websocket

websocket is a minimal and idiomatic WebSocket library for Go.

Install

go get nhooyr.io/websocket

Highlights

Minimal and idiomatic API
First class context.Context support
Fully passes the WebSocket autobahn-testsuite
Zero dependencies
JSON helpers in the wsjson subpackage
Zero alloc reads and writes
Concurrent writes
Close handshake
net.Conn wrapper
Ping pong API
RFC 7692 permessage-deflate compression
CloseRead helper for write only connections
Compile to Wasm

Roadmap

See GitHub issues for minor issues but the major future enhancements are:

Perfect examples #217
wstest.Pipe for in memory testing #340
Ping pong heartbeat helper #267
Ping pong instrumentation callbacks #246
Graceful shutdown helpers #209
Assembly for WebSocket masking #16
- WIP at #326, about 3x faster
HTTP/2 #4
The holy grail #402

Examples

For a production quality example that demonstrates the complete API, see the echo example.

For a full stack example, see the chat example.

Server

http.HandlerFunc(func (w http.ResponseWriter, r *http.Request) {
	c, err := websocket.Accept(w, r, nil)
	if err != nil {
		// ...
	}
	defer c.CloseNow()

	ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
	defer cancel()

	var v interface{}
	err = wsjson.Read(ctx, c, &v)
	if err != nil {
		// ...
	}

	log.Printf("received: %v", v)

	c.Close(websocket.StatusNormalClosure, "")
})

Client

ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()

c, _, err := websocket.Dial(ctx, "ws://localhost:8080", nil)
if err != nil {
	// ...
}
defer c.CloseNow()

err = wsjson.Write(ctx, c, "hi")
if err != nil {
	// ...
}

c.Close(websocket.StatusNormalClosure, "")

Comparison

gorilla/websocket

Advantages of gorilla/websocket:

Mature and widely used
Prepared writes
Configurable buffer sizes
No extra goroutine per connection to support cancellation with context.Context. This costs nhooyr.io/websocket 2 KB of memory per connection.
- Will be removed soon with context.AfterFunc. See #411

Advantages of nhooyr.io/websocket:

Minimal and idiomatic API
- Compare godoc of nhooyr.io/websocket with gorilla/websocket side by side.
net.Conn wrapper
Zero alloc reads and writes (gorilla/websocket#535)
Full context.Context support
Dial uses net/http.Client
- Will enable easy HTTP/2 support in the future
- Gorilla writes directly to a net.Conn and so duplicates features of net/http.Client.
Concurrent writes
Close handshake (gorilla/websocket#448)
Idiomatic ping pong API
- Gorilla requires registering a pong callback before sending a Ping
Can target Wasm (gorilla/websocket#432)
Transparent message buffer reuse with wsjson subpackage
1.75x faster WebSocket masking implementation in pure Go
- Gorilla's implementation is slower and uses unsafe. Soon we'll have assembly and be 3x faster #326
Full permessage-deflate compression extension support
- Gorilla only supports no context takeover mode
CloseRead helper for write only connections (gorilla/websocket#492)

golang.org/x/net/websocket

golang.org/x/net/websocket is deprecated. See golang/go/issues/18152.

The net.Conn can help in transitioning to nhooyr.io/websocket.

gobwas/ws

gobwas/ws has an extremely flexible API that allows it to be used in an event driven style for performance. See the author's blog post.

However it is quite bloated. See https://pkg.go.dev/github.com/gobwas/ws

When writing idiomatic Go, nhooyr.io/websocket will be faster and easier to use.

lesismal/nbio

lesismal/nbio is similar to gobwas/ws in that the API is event driven for performance reasons.

However it is quite bloated. See https://pkg.go.dev/github.com/lesismal/nbio