README.md

websocket

websocket is a minimal and idiomatic WebSocket library for Go.

Install

go get nhooyr.io/websocket

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: