websocket
websocket is a minimal and idiomatic WebSocket library for Go.
Install
go get nhooyr.io/websocketHighlights
- 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
- WebSocket masking implemented in assembly for amd64 and arm64 #326
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
- 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
-
4x faster WebSocket masking implementation in assembly for amd64 and arm64 and 2x faster implementation in pure Go
- Gorilla's implementation is slower and uses unsafe.
- 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
When writing idiomatic Go, nhooyr.io/websocket will be faster and easier to use.