coder /websocket

Minimal and idiomatic WebSocket library for Go

★ 5,575⑂ 390👁 48⑃ 248● 335▤ 41
GoISCCreated 2018-08-13
More from this author
Download: v1.8.15v1.8.15 ↓1.8.152026-06-15
+1
Daily
5,575
stars
390
forks
48
watchers
248
prs
335
issues
41
releases

README

websocket




websocket is a minimal and idiomatic WebSocket library for Go.

 Install

sh
go get github.com/coder/websocket


 [!NOTE]
 Coder now maintains this project as explained in this blog post.
 We're grateful to nhooyr for authoring and maintaining this project from
 2019 to 2024.

 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

go
http.HandlerFunc(func (w http.ResponseWriter, r http.Request) {
	c, err := websocket.Accept(w, r, nil)
	if err != nil {
		// ...
	}
	defer c.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.Second10)
	defer cancel()

	var v any
	err = wsjson.Read(ctx, c, &v)
	if err != nil {
		// ...
	}

	log.Printf("received: %v", v)

	c.Close(websocket.StatusNormalClosure, "")
})


 Client

go
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

Advantages of github.com/coder/websocket:

- Minimal and idiomatic API
  - Compare godoc of github.com/coder/websocket with gorilla/websocket side by side.
- net.Conn wrapper
- Zero alloc reads and writes (gorilla/websocket535)
- 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/websocket448)
- Idiomatic ping pong API
  - Gorilla requires registering a pong callback before sending a Ping
- Can target Wasm (gorilla/websocket432)
- Transparent message buffer reuse with wsjson subpackage
- 1.75x faster WebSocket masking implementation in pure Go
  - Gorilla's implementation is slower and uses u

Top issues

Latest release

v1.8.15 v1.8.15 2026-06-15
Changes

 chore: fix typo in Accept function by @IgorSilvestre in https://github.com/coder/websocket/pull/544
 fix: transmit in single frame when compression enabled by @DanielleMaywood in https://github.com/coder/websocket/pull/552
 docs: add document for AI agents (AGENTS.md) by @mafredri in https://github.com/coder/websocket/pull/547
 docs: remove mention of resolved issue in README by @tamird in https://github.com/coder/websocket/pull/556
 docs: fix lint issue by @mafredri in https://github.com/coder/websocket/pull/557
 docs: fix roadmap links after repo transfer by @GeObts in https://gith

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON