websocket

README

websocket

websocket is a minimal and idiomatic WebSocket library for Go.

Install

go get nhooyr.io/websocket@v1.0.0

Features

• Minimal and idiomatic API
• Tiny codebase at 1700 lines
• First class context.Context support
• Thorough tests, fully passes the autobahn-testsuite
• Zero dependencies outside of the stdlib for the core library
• JSON and ProtoBuf helpers in the wsjson and wspb subpackages
• Highly optimized by default
• Concurrent writes out of the box

Roadmap

• WebSockets over 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.

Server

http.HandlerFunc(func (w http.ResponseWriter, r *http.Request) {
	c, err := websocket.Accept(w, r, websocket.AcceptOptions{})
	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

The client side of this library requires at minimum Go 1.12 as it uses a new feature in net/http to perform WebSocket handshakes.

ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()

c, _, err := websocket.Dial(ctx, "ws://localhost:8080", websocket.DialOptions{})
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
• We do not support the deflate compression extension because Go's compress/flate library is very memory intensive and browsers do not handle WebSocket compression intelligently. See #5

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

This package is the community standard but it is 6 years old and over time has accumulated cruft. There are too many ways to do the same thing. Just compare the godoc of nhooyr/websocket side by side with gorilla/websocket.

The API for nhooyr/websocket has been designed such that there is only one way to do things which makes it easy to use correctly. Not only is the API simpler, the implementation is only 1700 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.

The future of gorilla/websocket is also uncertain. See gorilla/websocket#370.

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

Some more advantages of nhooyr/websocket are that it supports concurrent writes and makes it very easy to close the connection with a status code and reason.

nhooyr/websocket also responds to pings, pongs and close frames in a separate goroutine so that your application doesn't always need to read from the connection unless it expects a data message. gorilla/websocket requires you to constantly read from the connection to respond to control frames even if you don't expect the peer to send any messages.

In terms of performance, the differences depend on your application code. nhooyr/websocket reuses buffers efficiently out of the box if you use the wsjson and wspb subpackages whereas gorilla/websocket does not. As mentioned above, nhooyr/websocket also supports concurrent writers out of the box.

The only performance con to nhooyr/websocket is that uses two extra goroutines. One for reading pings, pongs and close frames async to application code and another to support context.Context cancellation. This costs 4 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 nhooyr/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 most users, the API provided by nhooyr/websocket will fit better as it is nearly just as performant but much easier to use correctly and idiomatic.

Documentation

Overview

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

See 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.

Please see https://nhooyr.io/websocket for more overview docs and a comparison with existing implementations.

Please be sure to use the https://golang.org/x/xerrors package when inspecting returned errors.

Example (Echo)

This example starts a WebSocket echo server, dials the server and then sends 5 different messages and prints out the server's responses.

package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net"
	"net/http"
	"time"

	"golang.org/x/time/rate"
	"golang.org/x/xerrors"

	"nhooyr.io/websocket"
	"nhooyr.io/websocket/wsjson"
)

// This example starts a WebSocket echo server,
// dials the server and then sends 5 different messages
// and prints out the server's responses.
func main() {
	// First we listen on port 0 which means the OS will
	// assign us a random free port. This is the listener
	// the server will serve on and the client will connect to.
	l, err := net.Listen("tcp", "localhost:0")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}
	defer l.Close()

	s := &http.Server{
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			err := echoServer(w, r)
			if err != nil {
				log.Printf("echo server: %v", err)
			}
		}),
		ReadTimeout:  time.Second * 15,
		WriteTimeout: time.Second * 15,
	}
	defer s.Close()

	// This starts the echo server on the listener.
	go func() {
		err := s.Serve(l)
		if err != http.ErrServerClosed {
			log.Fatalf("failed to listen and serve: %v", err)
		}
	}()

	// Now we dial the server, send the messages and echo the responses.
	err = client("ws://" + l.Addr().String())
	if err != nil {
		log.Fatalf("client failed: %v", err)
	}
}

// echoServer is the WebSocket echo server implementation.
// It ensures the client speaks the echo subprotocol and
// only allows one message every 100ms with a 10 message burst.
func echoServer(w http.ResponseWriter, r *http.Request) error {
	log.Printf("serving %v", r.RemoteAddr)

	c, err := websocket.Accept(w, r, websocket.AcceptOptions{
		Subprotocols: []string{"echo"},
	})
	if err != nil {
		return err
	}
	defer c.Close(websocket.StatusInternalError, "the sky is falling")

	if c.Subprotocol() != "echo" {
		c.Close(websocket.StatusPolicyViolation, "client must speak the echo subprotocol")
		return xerrors.Errorf("client does not speak echo sub protocol")
	}

	l := rate.NewLimiter(rate.Every(time.Millisecond*100), 10)
	for {
		err = echo(r.Context(), c, l)
		if err != nil {
			return xerrors.Errorf("failed to echo with %v: %w", r.RemoteAddr, err)
		}
	}
}

// echo reads from the websocket connection and then writes
// the received message back to it.
// The entire function has 10s to complete.
func echo(ctx context.Context, c *websocket.Conn, l *rate.Limiter) error {
	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	err := l.Wait(ctx)
	if err != nil {
		return err
	}

	typ, r, err := c.Reader(ctx)
	if err != nil {
		return err
	}

	w, err := c.Writer(ctx, typ)
	if err != nil {
		return err
	}

	_, err = io.Copy(w, r)
	if err != nil {
		return xerrors.Errorf("failed to io.Copy: %w", err)
	}

	err = w.Close()
	return err
}

// client dials the WebSocket echo server at the given url.
// It then sends it 5 different messages and echo's the server's
// response to each.
func client(url string) error {
	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	c, _, err := websocket.Dial(ctx, url, websocket.DialOptions{
		Subprotocols: []string{"echo"},
	})
	if err != nil {
		return err
	}
	defer c.Close(websocket.StatusInternalError, "the sky is falling")

	for i := 0; i < 5; i++ {
		err = wsjson.Write(ctx, c, map[string]int{
			"i": i,
		})
		if err != nil {
			return err
		}

		v := map[string]int{}
		err = wsjson.Read(ctx, c, &v)
		if err != nil {
			return err
		}

		fmt.Printf("received: %v\n", v)
	}

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

Output:

received: map[i:0]
received: map[i:1]
received: map[i:2]
received: map[i:3]
received: map[i:4]

Index

• 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) Context(parent 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 (i StatusCode) String() string

Examples

• Package (Echo)
• Accept
• Dial

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.
	// Please 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 the Connection is closed with a WebSocket close frame. You will need to use https://golang.org/x/xerrors to check for this error.

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, Read and SetReadLimit.

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

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.

The returned connection will be bound by r.Context(). Use conn.Context() to change the bounding context.

Example

This example accepts a WebSocket connection, reads a single JSON message from the client and then closes the connection.

package main

import (
	"context"
	"log"
	"net/http"
	"time"

	"nhooyr.io/websocket"
	"nhooyr.io/websocket/wsjson"
)

func main() {
	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		c, err := websocket.Accept(w, r, websocket.AcceptOptions{})
		if err != nil {
			log.Println(err)
			return
		}
		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.Println(err)
			return
		}

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

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

	err := http.ListenAndServe("localhost:8080", fn)
	log.Fatal(err)
}

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.

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

Example

This example dials a server, writes a single JSON message and then closes the connection.

package main

import (
	"context"
	"log"
	"time"

	"nhooyr.io/websocket"
	"nhooyr.io/websocket/wsjson"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	c, _, err := websocket.Dial(ctx, "ws://localhost:8080", websocket.DialOptions{})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close(websocket.StatusInternalError, "the sky is falling")

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

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

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 5 seconds. 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.

func (*Conn) Context

func (c *Conn) Context(parent context.Context) context.Context

Context returns a context derived from parent that will be cancelled when the connection is closed or broken. If the parent context is cancelled, the connection will be closed.

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. 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.

Control (ping, pong, close) frames will be handled automatically in a separate goroutine so if you do not expect any data messages, you do not need to read from the connection. However, if the peer sends a data message, further pings, pongs and close frames will not be read if you do not read the message from the connection.

Only one Reader may be open at a time.

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 StatusPolicyViolation.

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. The docs on Writer regarding concurrency also apply to this method.

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 = MessageType(opText)
	// MessageBinary is for binary messages like Protobufs.
	MessageBinary MessageType = MessageType(opBinary)
)

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 + iota
	StatusGoingAway
	StatusProtocolError
	StatusUnsupportedData

	StatusNoStatusRcvd

	StatusInvalidFramePayloadData
	StatusPolicyViolation
	StatusMessageTooBig
	StatusMandatoryExtension
	StatusInternalError
	StatusServiceRestart
	StatusTryAgainLater
	StatusBadGateway
)

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

func (StatusCode) String

func (i StatusCode) String() string