Repository files navigation

websocket is a minimal and idiomatic WebSocket library for Go.

go get nhooyr.io/websocket

• Minimal and idiomatic API
• First classcontext.Context support
• Fully passes the WebSocketautobahn-testsuite
• Thorough tests with90% coverage
• Single dependency
• JSON and protobuf helpers in thewsjson andwspb subpackages
• Zero alloc reads and writes
• Concurrent writes
• Close handshake
• net.Conn wrapper
• Ping pong API
• RFC 7692 permessage-deflate compression
• Compile toWasm

• HTTP/2#4

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

For a full stack Chat example designed for chat rooms, see thechat example.It is designed for WSS so ensure your chat server is secured.

Here is an example command to get the chat server running locally on port 8080

go run. localhost:8080

http.HandlerFunc(func (w http.ResponseWriter,r*http.Request) {c,err:=websocket.Accept(w,r,nil)iferr!=nil {// ...}deferc.Close(websocket.StatusInternalError,"the sky is falling")ctx,cancel:=context.WithTimeout(r.Context(),time.Second*10)defercancel()varvinterface{}err=wsjson.Read(ctx,c,&v)iferr!=nil {// ...}log.Printf("received: %v",v)c.Close(websocket.StatusNormalClosure,"")})

ctx,cancel:=context.WithTimeout(context.Background(),time.Minute)defercancel()c,_,err:=websocket.Dial(ctx,"ws://localhost:8080",nil)iferr!=nil {// ...}deferc.Close(websocket.StatusInternalError,"the sky is falling")err=wsjson.Write(ctx,c,"hi")iferr!=nil {// ...}c.Close(websocket.StatusNormalClosure,"")

Advantages ofgorilla/websocket:

• Mature and widely used
• Prepared writes
• Configurablebuffer sizes

Advantages of nhooyr.io/websocket:

• Minimal and idiomatic API
  • Compare godoc ofnhooyr.io/websocket withgorilla/websocket side by side.
• net.Conn wrapper
• Zero alloc reads and writes (gorilla/websocket#535)
• Fullcontext.Context support
• Dial usesnet/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)
• Idiomaticping pong API
  • Gorilla requires registering a pong callback before sending a Ping
• Can target Wasm (gorilla/websocket#432)
• Transparent message buffer reuse withwsjson andwspb subpackages
• 1.75x faster WebSocket masking implementation in pure Go
  • Gorilla's implementation is slower and usesunsafe.
• Fullpermessage-deflate compression extension support
  • Gorilla only supports no context takeover mode
  • We use a vendoredklauspost/compress for much lower memory usage (gorilla/websocket#203)
• CloseRead helper (gorilla/websocket#492)
• Actively maintained (gorilla/websocket#370)

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

Thenet.Conn can help in transitioningto nhooyr.io/websocket.

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

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