Skip to content

A zero-dependency Golang implementation of the websocket protocol (RFC 6455)

License

Notifications You must be signed in to change notification settings

mccutchen/websocket

Folders and files

NameName
Last commit message
Last commit date
Feb 20, 2025
Feb 20, 2025
Feb 12, 2025
Feb 22, 2025
Feb 18, 2025
Nov 26, 2024
Feb 18, 2025
Feb 18, 2025
Feb 20, 2025
Nov 26, 2024
Nov 26, 2024
Feb 12, 2025
Feb 6, 2025
Feb 15, 2025
Feb 15, 2025
Feb 22, 2025

Repository files navigation

websocket

Documentation Build status Code coverage Go report card

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:

Usage

For now, see

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.