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
• 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 example, see thechat example.

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 useklauspost/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.