websocket

Gorilla WebSocket is a Go implementation of the WebSocket protocol (RFC 6455) providing both server-side (Upgrader) and client-side (Dialer) connection types built directly on net/http and net.Conn. Instead of hiding the protocol behind a high-level abstraction, it exposes byte-level control over frame masking, per-message compression, and control-frame (ping/pong/close) handling, while still offering convenience methods like ReadJSON/WriteJSON for the common structured-message case.

The package has near-zero dependencies, passes the Autobahn Test Suite’s protocol-conformance tests, and ships runnable examples for chat servers, remote command execution, echo clients, and file-watch notifications. It is one of the most widely used low-level WebSocket libraries in the Go ecosystem, commonly reached for by projects that need direct control over connection lifecycle and framing rather than a batteries-included realtime framework.

What You Get

• An Upgrader type for turning an *http.Request into a WebSocket *Conn on the server side, with origin-checking and subprotocol negotiation built in.
• A Dialer type for opening outbound WebSocket connections as a client, including TLS, proxy, and custom net.Conn dial support.
• Streaming NextReader/NextWriter APIs plus convenience ReadMessage/WriteMessage/ReadJSON/WriteJSON methods.
• Optional permessage-deflate compression negotiation with per-connection compression level control.
• Runnable examples covering chat servers, command execution over WebSockets, echo clients/servers, and file-watch notifications.

Common Use Cases

• Building chat and messaging backends that need a persistent, bidirectional connection to browser or mobile clients.
• Streaming live server-side data such as logs, metrics, or prices to a JavaScript frontend without polling.
• Building custom realtime protocols on top of raw WebSocket frames where a full framework would be overkill.
• Proxying or relaying WebSocket traffic between a Go client and an upstream WebSocket server.

Under The Hood

Architecture

Gorilla WebSocket centers on the *Conn type defined in conn.go, which wraps a net.Conn together with read/write frame buffers, deadlines, and pluggable close/ping/pong handlers; server.go’s Upgrader.Upgrade hijacks an *http.Request/http.ResponseWriter pair (via http.Hijacker) to produce a *Conn after validating the Sec-WebSocket-Key handshake and negotiating subprotocols/origin checks, while client.go’s Dialer.Dial and DialContext perform the mirrored client-side handshake over a net.Conn obtained from netDialFn (with TLS and HTTP/SOCKS proxy support in proxy.go). Frame masking is isolated behind a maskBytes function with two implementations selected by build tag — mask.go’s unsafe, word-aligned XOR loop and mask_safe.go’s byte-at-a-time App Engine-safe fallback — and permessage-deflate compression is factored into compression.go behind pooled flate.Reader/Writer instances so Conn stays framing-agnostic. Changing the core Conn read/write buffering would ripple through every public method (ReadMessage, NextReader, WriteJSON, and others) since they all funnel through the same frame-header parsing state machine.

Tech Stack

The library targets a recent Go toolchain and has exactly one external dependency, golang.org/x/net, used only for proxy- and test-related helpers rather than the core protocol code, keeping the module close to a pure standard-library implementation built on net, net/http, crypto/tls, and compress/flate. There is no additional build system beyond the standard Go toolchain; CI runs through CircleCI per the project’s badge, and the bundled examples directory (chat, command, echo, filewatch, autobahn) doubles as integration coverage and demonstrates the library wired directly into net/http handlers with no additional framework involved, since this is a transport-layer library rather than an application framework.

Code Quality

The repository carries a large body of test files alongside its implementation files, giving close to one-to-one test-to-source coverage including a dedicated Autobahn protocol-conformance suite run against the reference test client. Error handling is explicit and typed rather than swallowed: sentinel errors and a dedicated CloseError/HandshakeError pair carry protocol-level detail back to callers instead of generic error strings everywhere. Naming follows standard Go conventions with exported PascalCase types/methods and unexported lowercase internals, and CI is wired through CircleCI rather than GitHub Actions.

API Design The public API favors small, composable primitives over a monolithic client: NextReader/NextWriter expose io.Reader/io.WriteCloser instead of forcing full-message buffering, letting callers stream arbitrarily large messages with constant memory, while ReadJSON/WriteJSON layer on top for the common structured-message case without requiring a separate helper package. Getting started requires little boilerplate beyond declaring an Upgrader and calling Upgrade from an existing net/http handler — there is no required framework, config file, or code generation step. Documentation is unusually thorough for a low-level library, with a multi-section package-level doc comment covering concurrency rules, origin considerations, and buffering behavior that is directly consumable via pkg.go.dev in place of a separate docs site. The one rough edge is concurrency: the API requires callers to manage their own single-reader/single-writer discipline, documented but not enforced by the type system, which is a deliberate performance trade-off rather than an oversight.