websocket

README

websocket

websocket is a minimal and idiomatic WebSocket library for Go.

Install

go get github.com/schollz/websocket

Features

• Minimal and idiomatic API
• Tiny codebase at 2200 lines
• First class context.Context support
• Thorough tests, fully passes the autobahn-testsuite
• Zero dependencies
• JSON and ProtoBuf helpers in the wsjson and wspb subpackages
• Highly optimized by default
• Concurrent writes out of the box
• Complete Wasm support
• Close handshake

Roadmap

• Compression Extensions #163
• HTTP/2 #4

Examples

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

Use the errors.As function new in Go 1.13 to check for websocket.CloseError. There is also websocket.CloseStatus to quickly grab the close status code out of a websocket.CloseError. See the CloseStatus godoc example.

Server

http.HandlerFunc(func (w http.ResponseWriter, r *http.Request) {
	c, err := websocket.Accept(w, r, nil)
	if err != nil {
		// ...
	}
	defer c.Close(websocket.StatusInternalError, "the sky is falling")

	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.Close(websocket.StatusInternalError, "the sky is falling")

err = wsjson.Write(ctx, c, "hi")
if err != nil {
	// ...
}

c.Close(websocket.StatusNormalClosure, "")

Design justifications

• A minimal API is easier to maintain due to less docs, tests and bugs
• A minimal API is also easier to use and learn
• Context based cancellation is more ergonomic and robust than setting deadlines
• 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 hooks and configurations like other WebSocket libraries

Comparison

Before the comparison, I want to point out that both gorilla/websocket and gobwas/ws were extremely useful in implementing the WebSocket protocol correctly so big thanks to the authors of both. In particular, I made sure to go through the issue tracker of gorilla/websocket to ensure I implemented details correctly and understood how people were using WebSockets in production.

gorilla/websocket

https://github.com/gorilla/websocket

The implementation of gorilla/websocket is 6 years old. As such, it is widely used and very mature compared to github.com/schollz/websocket.

On the other hand, it has grown organically and now there are too many ways to do the same thing. Compare the godoc of nhooyr/websocket with gorilla/websocket side by side.

The API for github.com/schollz/websocket has been designed such that there is only one way to do things. This makes it easy to use correctly. Not only is the API simpler, the implementation is only 2200 lines whereas gorilla/websocket is at 3500 lines. That's more code to maintain, more code to test, more code to document and more surface area for bugs.

Moreover, github.com/schollz/websocket supports newer Go idioms such as context.Context. It also uses net/http's Client and ResponseWriter directly for WebSocket handshakes. gorilla/websocket writes its handshakes to the underlying net.Conn. Thus it has to reinvent hooks for TLS and proxies and prevents support of HTTP/2.

Some more advantages of github.com/schollz/websocket are that it supports concurrent writes and makes it very easy to close the connection with a status code and reason. In fact, github.com/schollz/websocket even implements the complete WebSocket close handshake for you whereas with gorilla/websocket you have to perform it manually. See gorilla/websocket#448.

The ping API is also nicer. gorilla/websocket requires registering a pong handler on the Conn which results in awkward control flow. With github.com/schollz/websocket you use the Ping method on the Conn that sends a ping and also waits for the pong.

Additionally, github.com/schollz/websocket can compile to Wasm for the browser.

In terms of performance, the differences mostly depend on your application code. github.com/schollz/websocket reuses message buffers out of the box if you use the wsjson and wspb subpackages. As mentioned above, github.com/schollz/websocket also supports concurrent writers.

The WebSocket masking algorithm used by this package is also 1.75x faster than gorilla/websocket or gobwas/ws while using only pure safe Go.

The only performance con to github.com/schollz/websocket is that it uses one extra goroutine to support cancellation with context.Context. This costs 2 KB of memory which is cheap compared to the benefits.

x/net/websocket

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

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

See https://github.com/golang/go/issues/18152

gobwas/ws

https://github.com/gobwas/ws

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

This library is fantastic in terms of performance. The author put in significant effort to ensure its speed and I have applied as many of its optimizations as I could into github.com/schollz/websocket. Definitely check out his fantastic blog post about performant WebSocket servers.

If you want a library that gives you absolute control over everything, this is the library. But for 99.9% of use cases, github.com/schollz/websocket will fit better. It's nearly as performant but much easier to use.

Contributing

See .github/CONTRIBUTING.md.

Users

If your company or project is using this library, feel free to open an issue or PR to amend this list.

• Coder
• Tatsu Works - Ingresses 20 TB in websocket data every month on their Discord bot.

Documentation

Overview

Package websocket is a minimal and idiomatic implementation of the WebSocket protocol.

https://tools.ietf.org/html/rfc6455

Conn, Dial, and Accept are the main entrypoints into this package. Use Dial to dial a WebSocket server, Accept to accept a WebSocket client dial and then Conn to interact with the resulting WebSocket connections.

The examples are the best way to understand how to correctly use the library.

The wsjson and wspb subpackages contain helpers for JSON and ProtoBuf messages.

See https://github.com/schollz/websocket for more overview docs and a comparison with existing implementations.

Use the errors.As function new in Go 1.13 to check for websocket.CloseError. Or use the CloseStatus function to grab the StatusCode out of a websocket.CloseError See the CloseStatus example.

Wasm

The client side fully supports compiling to Wasm. It wraps the WebSocket browser API.

See https://developer.mozilla.org/en-US/docs/Web/API/WebSocket

Thus the unsupported features (not compiled in) for Wasm are:

• Accept and AcceptOptions
• Conn.Ping
• HTTPClient and HTTPHeader fields in DialOptions

The *http.Response returned by Dial will always either be nil or &http.Response{} as we do not have access to the handshake response in the browser.

The Writer method on the Conn buffers everything in memory and then sends it as a message when the writer is closed.

The Reader method also reads the entire response and then returns a reader that reads from the byte slice.

SetReadLimit cannot actually limit the number of bytes read from the connection so instead when a message beyond the limit is fully read, it throws an error.

Writes are also always async so the passed context is no-op.

Everything else is fully supported. This includes the wsjson and wspb helper packages.

Once https://github.com/gopherjs/gopherjs/issues/929 is closed, GopherJS should be supported as well.

Index

• func NetConn(ctx context.Context, c *Conn, msgType MessageType) net.Conn
• type AcceptOptions
• type CloseError
  • func (ce CloseError) Error() string
• type Conn
  • func Accept(w http.ResponseWriter, r *http.Request, opts *AcceptOptions) (*Conn, error)
  • func Dial(ctx context.Context, u string, opts *DialOptions) (*Conn, *http.Response, error)
  • func (c *Conn) Close(code StatusCode, reason string) error
  • func (c *Conn) CloseRead(ctx context.Context) context.Context
  • func (c *Conn) Ping(ctx context.Context) error
  • func (c *Conn) Read(ctx context.Context) (MessageType, []byte, error)
  • func (c *Conn) Reader(ctx context.Context) (MessageType, io.Reader, error)
  • func (c *Conn) SetReadLimit(n int64)
  • func (c *Conn) Subprotocol() string
  • func (c *Conn) Write(ctx context.Context, typ MessageType, p []byte) error
  • func (c *Conn) Writer(ctx context.Context, typ MessageType) (io.WriteCloser, error)
• type DialOptions
• type MessageType
  • func (i MessageType) String() string
• type StatusCode
  • func CloseStatus(err error) StatusCode
  • func (i StatusCode) String() string

Functions

func NetConn

func NetConn(ctx context.Context, c *Conn, msgType MessageType) net.Conn

NetConn converts a *websocket.Conn into a net.Conn.

It's for tunneling arbitrary protocols over WebSockets. Few users of the library will need this but it's tricky to implement correctly and so provided in the library. See https://github.com/nhooyr/websocket/issues/100.

Every Write to the net.Conn will correspond to a message write of the given type on *websocket.Conn.

The passed ctx bounds the lifetime of the net.Conn. If cancelled, all reads and writes on the net.Conn will be cancelled.

If a message is read that is not of the correct type, the connection will be closed with StatusUnsupportedData and an error will be returned.

Close will close the *websocket.Conn with StatusNormalClosure.

When a deadline is hit, the connection will be closed. This is different from most net.Conn implementations where only the reading/writing goroutines are interrupted but the connection is kept alive.

The Addr methods will return a mock net.Addr that returns "websocket" for Network and "websocket/unknown-addr" for String.

A received StatusNormalClosure or StatusGoingAway close frame will be translated to io.EOF when reading.

Types

type AcceptOptions

type AcceptOptions struct {
	// Subprotocols lists the websocket subprotocols that Accept will negotiate with a client.
	// The empty subprotocol will always be negotiated as per RFC 6455. If you would like to
	// reject it, close the connection if c.Subprotocol() == "".
	Subprotocols []string

	// InsecureSkipVerify disables Accept's origin verification
	// behaviour. By default Accept only allows the handshake to
	// succeed if the javascript that is initiating the handshake
	// is on the same domain as the server. This is to prevent CSRF
	// attacks when secure data is stored in a cookie as there is no same
	// origin policy for WebSockets. In other words, javascript from
	// any domain can perform a WebSocket dial on an arbitrary server.
	// This dial will include cookies which means the arbitrary javascript
	// can perform actions as the authenticated user.
	//
	// See https://stackoverflow.com/a/37837709/4283659
	//
	// The only time you need this is if your javascript is running on a different domain
	// than your WebSocket server.
	// Think carefully about whether you really need this option before you use it.
	// If you do, remember that if you store secure data in cookies, you wil need to verify the
	// Origin header yourself otherwise you are exposing yourself to a CSRF attack.
	InsecureSkipVerify bool
}

AcceptOptions represents the options available to pass to Accept.

type CloseError

type CloseError struct {
	Code   StatusCode
	Reason string
}

CloseError represents a WebSocket close frame. It is returned by Conn's methods when a WebSocket close frame is received from the peer. You will need to use the https://golang.org/pkg/errors/#As function, new in Go 1.13, to check for this error. See the CloseError example.

func (CloseError) Error

func (ce CloseError) Error() string

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn represents a WebSocket connection. All methods may be called concurrently except for Reader and Read.

You must always read from the connection. Otherwise control frames will not be handled. See the docs on Reader and CloseRead.

Be sure to call Close on the connection when you are finished with it to release the associated resources.

Every error from Read or Reader will cause the connection to be closed so you do not need to write your own error message. This applies to the Read methods in the wsjson/wspb subpackages as well.

func Accept

func Accept(w http.ResponseWriter, r *http.Request, opts *AcceptOptions) (*Conn, error)

Accept accepts a WebSocket handshake from a client and upgrades the the connection to a WebSocket.

Accept will reject the handshake if the Origin domain is not the same as the Host unless the InsecureSkipVerify option is set. In other words, by default it does not allow cross origin requests.

If an error occurs, Accept will always write an appropriate response so you do not have to.

func Dial

func Dial(ctx context.Context, u string, opts *DialOptions) (*Conn, *http.Response, error)

Dial performs a WebSocket handshake on the given url with the given options. The response is the WebSocket handshake response from the server. If an error occurs, the returned response may be non nil. However, you can only read the first 1024 bytes of its body.

You never need to close the resp.Body yourself.

This function requires at least Go 1.12 to succeed as it uses a new feature in net/http to perform WebSocket handshakes and get a writable body from the transport. See https://github.com/golang/go/issues/26937#issuecomment-415855861

func (*Conn) Close

func (c *Conn) Close(code StatusCode, reason string) error

Close closes the WebSocket connection with the given status code and reason.

It will write a WebSocket close frame with a timeout of 5s and then wait 5s for the peer to send a close frame. Thus, it implements the full WebSocket close handshake. All data messages received from the peer during the close handshake will be discarded.

The connection can only be closed once. Additional calls to Close are no-ops.

The maximum length of reason must be 125 bytes otherwise an internal error will be sent to the peer. For this reason, you should avoid sending a dynamic reason.

Close will unblock all goroutines interacting with the connection once complete.

func (*Conn) CloseRead

func (c *Conn) CloseRead(ctx context.Context) context.Context

CloseRead will start a goroutine to read from the connection until it is closed or a data message is received. If a data message is received, the connection will be closed with StatusPolicyViolation. Since CloseRead reads from the connection, it will respond to ping, pong and close frames. After calling this method, you cannot read any data messages from the connection. The returned context will be cancelled when the connection is closed.

Use this when you do not want to read data messages from the connection anymore but will want to write messages to it.

func (*Conn) Ping

func (c *Conn) Ping(ctx context.Context) error

Ping sends a ping to the peer and waits for a pong. Use this to measure latency or ensure the peer is responsive. Ping must be called concurrently with Reader as it does not read from the connection but instead waits for a Reader call to read the pong.

TCP Keepalives should suffice for most use cases.

func (*Conn) Read

func (c *Conn) Read(ctx context.Context) (MessageType, []byte, error)

Read is a convenience method to read a single message from the connection.

See the Reader method if you want to be able to reuse buffers or want to stream a message. The docs on Reader apply to this method as well.

func (*Conn) Reader

func (c *Conn) Reader(ctx context.Context) (MessageType, io.Reader, error)

Reader waits until there is a WebSocket data message to read from the connection. It returns the type of the message and a reader to read it. The passed context will also bound the reader. Ensure you read to EOF otherwise the connection will hang.

All returned errors will cause the connection to be closed so you do not need to write your own error message. This applies to the Read methods in the wsjson/wspb subpackages as well.

You must read from the connection for control frames to be handled. Thus if you expect messages to take a long time to be responded to, you should handle such messages async to reading from the connection to ensure control frames are promptly handled.

If you do not expect any data messages from the peer, call CloseRead.

Only one Reader may be open at a time.

If you need a separate timeout on the Reader call and then the message Read, use time.AfterFunc to cancel the context passed in early. See https://github.com/nhooyr/websocket/issues/87#issue-451703332 Most users should not need this.

func (*Conn) SetReadLimit

func (c *Conn) SetReadLimit(n int64)

SetReadLimit sets the max number of bytes to read for a single message. It applies to the Reader and Read methods.

By default, the connection has a message read limit of 32768 bytes.

When the limit is hit, the connection will be closed with StatusMessageTooBig.

func (*Conn) Subprotocol

func (c *Conn) Subprotocol() string

Subprotocol returns the negotiated subprotocol. An empty string means the default protocol.

func (*Conn) Write

func (c *Conn) Write(ctx context.Context, typ MessageType, p []byte) error

Write is a convenience method to write a message to the connection.

See the Writer method if you want to stream a message.

func (*Conn) Writer

func (c *Conn) Writer(ctx context.Context, typ MessageType) (io.WriteCloser, error)

Writer returns a writer bounded by the context that will write a WebSocket message of type dataType to the connection.

You must close the writer once you have written the entire message.

Only one writer can be open at a time, multiple calls will block until the previous writer is closed.

type DialOptions

type DialOptions struct {
	// HTTPClient is the http client used for the handshake.
	// Its Transport must return writable bodies
	// for WebSocket handshakes.
	// http.Transport does this correctly beginning with Go 1.12.
	HTTPClient *http.Client

	// HTTPHeader specifies the HTTP headers included in the handshake request.
	HTTPHeader http.Header

	// Subprotocols lists the subprotocols to negotiate with the server.
	Subprotocols []string
}

DialOptions represents the options available to pass to Dial.

type MessageType

type MessageType int

MessageType represents the type of a WebSocket message. See https://tools.ietf.org/html/rfc6455#section-5.6

const (
	// MessageText is for UTF-8 encoded text messages like JSON.
	MessageText MessageType = iota + 1
	// MessageBinary is for binary messages like Protobufs.
	MessageBinary
)

MessageType constants.

func (MessageType) String

func (i MessageType) String() string

type StatusCode

type StatusCode int

StatusCode represents a WebSocket status code. https://tools.ietf.org/html/rfc6455#section-7.4

const (
	StatusNormalClosure   StatusCode = 1000
	StatusGoingAway       StatusCode = 1001
	StatusProtocolError   StatusCode = 1002
	StatusUnsupportedData StatusCode = 1003

	// StatusNoStatusRcvd cannot be sent in a close message.
	// It is reserved for when a close message is received without
	// an explicit status.
	StatusNoStatusRcvd StatusCode = 1005

	// StatusAbnormalClosure is only exported for use with Wasm.
	// In non Wasm Go, the returned error will indicate whether the connection was closed or not or what happened.
	StatusAbnormalClosure StatusCode = 1006

	StatusInvalidFramePayloadData StatusCode = 1007
	StatusPolicyViolation         StatusCode = 1008
	StatusMessageTooBig           StatusCode = 1009
	StatusMandatoryExtension      StatusCode = 1010
	StatusInternalError           StatusCode = 1011
	StatusServiceRestart          StatusCode = 1012
	StatusTryAgainLater           StatusCode = 1013
	StatusBadGateway              StatusCode = 1014

	// StatusTLSHandshake is only exported for use with Wasm.
	// In non Wasm Go, the returned error will indicate whether there was a TLS handshake failure.
	StatusTLSHandshake StatusCode = 1015
)

These codes were retrieved from: https://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number

The defined constants only represent the status codes registered with IANA. The 4000-4999 range of status codes is reserved for arbitrary use by applications.

func CloseStatus

func CloseStatus(err error) StatusCode

CloseStatus is a convenience wrapper around errors.As to grab the status code from a *CloseError. If the passed error is nil or not a *CloseError, the returned StatusCode will be -1.

func (StatusCode) String

func (i StatusCode) String() string