+1
日增长
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 uTop issues
#265Documentation Request about Ping Pong28 comments · 2020-11-25#4WebSockets over HTTP/228 comments · 2018-09-06#402meta: Status update and v2.0.0 holy grail requests24 comments · 2023-08-16#391Add protection against concurrent Readers20 comments · 2023-05-12#445Update docs and mention explicit close required change in v1.8.1116 comments · 2024-04-10#373WASM: support DialOptions.HTTPClient16 comments · 2023-02-28#474failed to close writer: context canceled12 comments · 2024-08-30#217Add example demonstrating a basic WebSocket protocol with message types12 comments · 2020-03-26
Latest release
v1.8.15 v1.8.15 2026-06-15Changes 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