Repository files navigation

websocket is a minimal and idiomatic WebSocket library for Go.

go get github.com/coder/websocket

• Minimal and idiomatic API
• First classcontext.Context support
• Fully passes the WebSocketautobahn-testsuite
• Zero dependencies
• JSON helpers in thewsjson 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 toWasm

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

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.CloseNow()// Set the context as needed. Use of r.Context() is not recommended// to avoid surprising behavior (see http.Hijacker).ctx,cancel:=context.WithTimeout(context.Background(),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.CloseNow()err=wsjson.Write(ctx,c,"hi")iferr!=nil {// ...}c.Close(websocket.StatusNormalClosure,"")

Advantages ofgorilla/websocket:

• Mature and widely used
• Prepared writes
• Configurablebuffer 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 withcontext.AfterFunc. See#411

Advantages of github.com/coder/websocket:

• Minimal and idiomatic API
  • Compare godoc ofgithub.com/coder/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 subpackage
• 1.75x faster WebSocket masking implementation in pure Go
  • Gorilla's implementation is slower and usesunsafe.Soon we'll have assembly and be 3x faster#326
• Fullpermessage-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 is deprecated.Seegolang/go/issues/18152.

Thenet.Conn can help in transitioningto github.com/coder/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 it is quite bloated. Seehttps://pkg.go.dev/github.com/gobwas/ws

When writing idiomatic Go, github.com/coder/websocket will be faster and easier to use.

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

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

When writing idiomatic Go, github.com/coder/websocket will be faster and easier to use.