websocket

A zero-dependency Golang implementation of the websocket protocol (RFC 6455), originally extracted from mccutchen/go-httpbin.

Warning

Not production ready!

Do not use this library in a production application. It is not particularly optimized and many breaking API changes are likely for the forseeable future.

Consider one of these libraries instead:

• https://github.com/coder/websocket
• https://github.com/gobwas/ws
• https://github.com/lxzan/gws

Usage

For now, see

• Go package docs on pkg.go.dev
• Example servers in the examples dir

More useful usage and example docs TK.

Testing

Unit tests

This project's unit tests are relatively quick to run and provide decent coverage of the implementation:

make test

Or generate code coverage:

make testcover

Autobahn integration tests

The crossbario/autobahn-testsuite project's "fuzzing client" is also used for integration/conformance/fuzz testing.

Note

The most recent Autobahn test reports may be viewed at https://mccutchen.github.io/websocket/

Because these tests a) require docker and b) take 40-60s to run, they are disabled by default.

To run the autobahn fuzzing client in its default configuration, use:

make testautobahn

There are a variety of options that can be enabled individually or together, which are useful for viewing the generated HTML test report, narrowing the set of test cases to debug a particular issue, or to enable more detailed debug logging.

• AUTOBAHN=1 is required to enable the Autobahn fuzzing client test suite, set automatically by the make testautobahn target.

• CASES narrows the set of test cases to execute (note the wildcards):

  make testautobahn CASES='5.7,6.12.*,9.*'

• REPORT_DIR={path} specifies the output dir for autobahn test results (defaults to .ingegrationtests/autobahn-test-${timestamp})

• REPORT=1 automatically opens the resulting HTML test resport:

  make testautobahn REPORT=1

• TARGET={url} runs autobanh against an external server instead of an ephemeral httptest server, which can be useful for, e.g., capturing pprof info or running tcpdump:

  make testautobahn TARGET=http://localhost:8080/

• DEBUG=1 enables fairly detailed debug logging via the server's built-in websocket lifecycle hooks:

  make testautobahn DEBUG=1

Putting it all together, a command like this might be used to debug a a particular failing test case:

make testautobahn DEBUG=1 CASES=9.1.6 REPORT=1

Benchmarks

🚧 Accurate, useful benchmarks are very much a work in progress. 🚧

Go benchmarks

Standard Go benchmarks may be run like so:

make bench

nstd/webocket-benchmarks

Basic, manual support for running the ntsd/websocket-benchmarks suite of benchmarks is documented in the examples/benchserver dir.