websocket

README

websocket

websocket is a minimal and idiomatic WebSocket library for Go.

Go 1.12 is required as it uses a new feature in net/http to perform WebSocket handshakes.

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

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

Install

go get nhooyr.io/websocket@v0.2.0

Features

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

Roadmap

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

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

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 considerations

• 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 make sense 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 hooks and configurations like other WebSocket libraries

Comparison

While I believe nhooyr/websocket has a better API than existing libraries, 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 make sure I implemented details correctly and understood how people were using the package 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. Using is not clear as there are many ways to do things and there are some rough edges. 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.

Furthermore, 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 proxying and prevents support of HTTP/2.

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

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, that 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 {
	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: %w", err)
		}
	}
}

// echo reads from the websocket connection and then writes
// the received message back to it.
// The entire function has 10s to complete.
// The received message is limited to 32768 bytes.
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
	}
	r = io.LimitReader(r, 32768)

	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) Reader(ctx context.Context) (MessageType, io.Reader, error)
  • func (c *Conn) Subprotocol() string
  • 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 except Reader can be used concurrently. Please be sure to call Close on the connection when you are finished with it to release 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 WebSocket. Accept will reject the handshake if the Origin domain is not the same as the Host unless the InsecureSkipVerify option is set.

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.

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.

func (*Conn) Reader

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

Reader will wait 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.

Your application must keep reading messages for the Conn to automatically respond to ping and close frames and not become stuck waiting for a data message to be read. Please ensure to read the full message from io.Reader. If you do not read till io.EOF, the connection will break unless the next read would have yielded io.EOF.

You can only read a single message at a time so do not call this method concurrently.

func (*Conn) Subprotocol

func (c *Conn) Subprotocol() string

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

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.

Ensure you close the writer once you have written the entire message. Concurrent calls to Writer are ok. Only one writer can be open at a time so Writer will block if there is another goroutine with an open writer until that writer is closed.

type DialOptions

type DialOptions struct {
	// HTTPClient is the http client used for the handshake.
	// Its Transport must use HTTP/1.1 and must return writable bodies
	// for WebSocket handshakes. This was introduced in Go 1.12.
	// http.Transport does this all correctly.
	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