websocket

websocket is a minimal and idiomatic WebSocket library for Go.

Install

go get github.com/coder/websocket

[!NOTE] Coder now maintains this project as explained in this blog post. We're grateful to nhooyr for authoring and maintaining this project from 2019 to 2024.

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 github.com/coder/websocket 2 KB of memory per connection.

- Will be removed soon with context.AfterFunc. See #411

Advantages of github.com/coder/websocket:

Minimal and idiomatic API

- Compare godoc of github.com/coder/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 github.com/coder/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, github.com/coder/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