Repository files navigation

websocket is a minimal and idiomatic WebSocket library for Go.

This library is not final and the API is subject to change.

If you have any feedback, please feel free to open an issue.

go get nhooyr.io/websocket@v0.2.0

• Minimal yet pragmatic API
• First class context.Context support
• Thoroughly tested, fully passes theautobahn-testsuite
• Concurrent writes
• Zero dependencies outside of the stdlib for the core library
• JSON and ProtoBuf helpers in the wsjson and wspb subpackages

• WebSockets over HTTP/2#4
• Deflate extension support#5

For a production quality example that shows off the full API, see theecho example on the godoc. On github, the example is atexample_echo_test.go.

http.HandlerFunc(func (w http.ResponseWriter,r*http.Request) {c,err:=websocket.Accept(w,r, websocket.AcceptOptions{})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", websocket.DialOptions{})iferr!=nil {// ...}deferc.Close(websocket.StatusInternalError,"the sky is falling")err=wsjson.Write(ctx,c,"hi")iferr!=nil {// ...}c.Close(websocket.StatusNormalClosure,"")

• Minimal API is easier to maintain and learn
• Context based cancellation is more ergonomic and robust than setting deadlines
• No ping support because TCP keep alives work fine for HTTP/1.1 and they do not makesense with HTTP/2 (see#1)
• net.Conn is never exposed as WebSocket over HTTP/2 will not have a net.Conn.
• Using net/http's Client for dialing means we do not have to reinvent dialing hooksand configurations like other WebSocket libraries

While I believe nhooyr/websocket has a better API than existing libraries,both gorilla/websocket and gobwas/ws were extremely useful in implementing theWebSocket protocol correctly sobig thanks to the authors of both. In particular,I made sure to go through the issue tracker of gorilla/websocket to make sureI implemented details correctly and understood how people were using the packagein production.

https://github.com/gorilla/websocket

This package is the community standard but it is 6 years old and over timehas accumulated cruft. Using is not clear as there are many ways to do thingsand there are some rough edges. Just compare the godoc ofnhooyr/websocket side by side withgorilla/websocket.

The API for nhooyr/websocket has been designed such that there is only one way to do thingswhich makes it easy to use correctly.

Furthermore, nhooyr/websocket has support for newer Go idioms such as context.Context andalso uses net/http's Client and ResponseWriter directly for WebSocket handshakes.gorilla/websocket writes its handshakes to the underlying net.Conn which meansit has to reinvent hooks for TLS and proxying and prevents support of HTTP/2.

Another advantage of nhooyr/websocket is that it supports concurrent writers out of the box.

https://godoc.org/golang.org/x/net/websocket

Unmaintained and the API does not reflect WebSocket semantics. Should never be used.

Seegolang/go#18152

https://github.com/gobwas/ws

This library has an extremely flexible API but that comes at the cost of usabilityand clarity.

This library is fantastic in terms of performance. The author put in significanteffort to ensure its speed and I have applied as many of its optimizations asI could into nhooyr/websocket. Definitely check out his fantasticblog postabout performant WebSocket servers.

If you want a library that gives you absolute control over everything, this is the library,but for most users, the API provided by nhooyr/websocket will fit better as it is nearly justas performant but much easier to use correctly and idiomatic.