Update docs and random little issues

Author: nhooyr

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
-      - name: make fmt
+      - name: Run make fmt
         uses: ./ci/image
         with:
           args: make fmt
@@ -27,7 +27,7 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
-      - name: make lint
+      - name: Run make lint
         uses: ./ci/image
         with:
           args: make lint
@@ -42,7 +42,7 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
-      - name: make test
+      - name: Run make test
         uses: ./ci/image
         with:
           args: make test

README.md

@@ -17,8 +17,8 @@ go get nhooyr.io/websocket
 
 - Minimal and idiomatic API
 - First class [context.Context](https://blog.golang.org/context) support
-- Thorough tests, fully passes the [autobahn-testsuite](https://github.com/crossbario/autobahn-testsuite)
-- [Zero dependencies](https://godoc.org/nhooyr.io/websocket?imports)
+- Thorough tests, fully passes the WebSocket [autobahn-testsuite](https://github.com/crossbario/autobahn-testsuite)
+- [Minimal dependencies](https://godoc.org/nhooyr.io/websocket?imports)
 - JSON and protobuf helpers in the [wsjson](https://godoc.org/nhooyr.io/websocket/wsjson) and [wspb](https://godoc.org/nhooyr.io/websocket/wspb) subpackages
 - Zero alloc reads and writes
 - Concurrent writes
@@ -34,7 +34,7 @@ go get nhooyr.io/websocket
 
 ## Examples
 
-For a production quality example that demonstrates the full API, see the [echo example](https://godoc.org/nhooyr.io/websocket#example-package--Echo).
+For a production quality example that demonstrates the complete API, see the [echo example](https://godoc.org/nhooyr.io/websocket#example-package--Echo).
 
 ### Server
 
@@ -111,6 +111,8 @@ Advantages of nhooyr.io/websocket:
   - Gorilla's implementation is slower and uses [unsafe](https://golang.org/pkg/unsafe/).
 - Full [permessage-deflate](https://tools.ietf.org/html/rfc7692) compression extension support
   - Gorilla only supports no context takeover mode
+  - Uses [klauspost/compress](https://github.com/klauspost/compress) for optimized compression
+  - See [gorilla/websocket#203](https://github.com/gorilla/websocket/issues/203)
 - [CloseRead](https://godoc.org/nhooyr.io/websocket#Conn.CloseRead) helper ([gorilla/websocket#492](https://github.com/gorilla/websocket/issues/492))
 - Actively maintained ([gorilla/websocket#370](https://github.com/gorilla/websocket/issues/370))
 

accept.go

@@ -37,9 +37,17 @@ type AcceptOptions struct {
 	// If used incorrectly your WebSocket server will be open to CSRF attacks.
 	InsecureSkipVerify bool
 
-	// CompressionOptions controls the compression options.
-	// See docs on the CompressionOptions type.
-	CompressionOptions *CompressionOptions
+	// CompressionMode controls the compression mode.
+	// Defaults to CompressionNoContextTakeover.
+	//
+	// See docs on CompressionMode for details.
+	CompressionMode CompressionMode
+
+	// CompressionThreshold controls the minimum size of a message before compression is applied.
+	//
+	// Defaults to 512 bytes for CompressionNoContextTakeover and 128 bytes
+	// for CompressionContextTakeover.
+	CompressionThreshold int
 }
 
 // Accept accepts a WebSocket handshake from a client and upgrades the
@@ -61,10 +69,6 @@ func accept(w http.ResponseWriter, r *http.Request, opts *AcceptOptions) (_ *Con
 	}
 	opts = &*opts
 
-	if opts.CompressionOptions == nil {
-		opts.CompressionOptions = &CompressionOptions{}
-	}
-
 	errCode, err := verifyClientRequest(w, r)
 	if err != nil {
 		http.Error(w, err.Error(), errCode)
@@ -97,7 +101,7 @@ func accept(w http.ResponseWriter, r *http.Request, opts *AcceptOptions) (_ *Con
 		w.Header().Set("Sec-WebSocket-Protocol", subproto)
 	}
 
-	copts, err := acceptCompression(r, w, opts.CompressionOptions.Mode)
+	copts, err := acceptCompression(r, w, opts.CompressionMode)
 	if err != nil {
 		return nil, err
 	}
@@ -120,7 +124,7 @@ func accept(w http.ResponseWriter, r *http.Request, opts *AcceptOptions) (_ *Con
 		rwc:            netConn,
 		client:         false,
 		copts:          copts,
-		flateThreshold: opts.CompressionOptions.Threshold,
+		flateThreshold: opts.CompressionThreshold,
 
 		br: brw.Reader,
 		bw: brw.Writer,

accept_js.go

@@ -8,9 +8,10 @@ import (
 
 // AcceptOptions represents Accept's options.
 type AcceptOptions struct {
-	Subprotocols       []string
-	InsecureSkipVerify bool
-	CompressionOptions *CompressionOptions
+	Subprotocols         []string
+	InsecureSkipVerify   bool
+	CompressionMode      CompressionMode
+	CompressionThreshold int
 }
 
 // Accept is stubbed out for Wasm.

close_notjs.go

@@ -35,7 +35,7 @@ func (c *Conn) closeHandshake(code StatusCode, reason string) (err error) {
 	defer errd.Wrap(&err, "failed to close WebSocket")
 
 	err = c.writeClose(code, reason)
-	if err != nil && CloseStatus(err) == -1 {
+	if err != nil && CloseStatus(err) == -1 && err != errAlreadyWroteClose {
 		return err
 	}
 
@@ -46,13 +46,15 @@ func (c *Conn) closeHandshake(code StatusCode, reason string) (err error) {
 	return nil
 }
 
+var errAlreadyWroteClose = xerrors.New("already wrote close")
+
 func (c *Conn) writeClose(code StatusCode, reason string) error {
 	c.closeMu.Lock()
 	closing := c.wroteClose
 	c.wroteClose = true
 	c.closeMu.Unlock()
 	if closing {
-		return xerrors.New("already wrote close")
+		return errAlreadyWroteClose
 	}
 
 	ce := CloseError{

compress.go

@@ -1,20 +1,5 @@
 package websocket
 
-// CompressionOptions represents the available deflate extension options.
-// See https://tools.ietf.org/html/rfc7692
-type CompressionOptions struct {
-	// Mode controls the compression mode.
-	//
-	// See docs on CompressionMode.
-	Mode CompressionMode
-
-	// Threshold controls the minimum size of a message before compression is applied.
-	//
-	// Defaults to 512 bytes for CompressionNoContextTakeover and 256 bytes
-	// for CompressionContextTakeover.
-	Threshold int
-}
-
 // CompressionMode represents the modes available to the deflate extension.
 // See https://tools.ietf.org/html/rfc7692
 //
@@ -38,7 +23,7 @@ const (
 	// CompressionContextTakeover uses a flate.Reader and flate.Writer per connection.
 	// This enables reusing the sliding window from previous messages.
 	// As most WebSocket protocols are repetitive, this can be very efficient.
-	// It carries an overhead of 64 kB for every connection compared to CompressionNoContextTakeover.
+	// It carries an overhead of 8 kB for every connection compared to CompressionNoContextTakeover.
 	//
 	// If the peer negotiates NoContextTakeover on the client or server side, it will be
 	// used instead as this is required by the RFC.

conn_notjs.go

@@ -101,7 +101,7 @@ func newConn(cfg connConfig) *Conn {
 	}
 
 	if c.flate() && c.flateThreshold == 0 {
-		c.flateThreshold = 256
+		c.flateThreshold = 128
 		if !c.msgWriterState.flateContextTakeover() {
 			c.flateThreshold = 512
 		}

conn_test.go

@@ -36,19 +36,18 @@ func TestConn(t *testing.T) {
 	t.Run("fuzzData", func(t *testing.T) {
 		t.Parallel()
 
-		copts := func() *websocket.CompressionOptions {
-			return &websocket.CompressionOptions{
-				Mode:      websocket.CompressionMode(xrand.Int(int(websocket.CompressionDisabled) + 1)),
-				Threshold: xrand.Int(9999),
-			}
+		compressionMode := func() websocket.CompressionMode {
+			return websocket.CompressionMode(xrand.Int(int(websocket.CompressionDisabled) + 1))
 		}
 
 		for i := 0; i < 5; i++ {
 			t.Run("", func(t *testing.T) {
 				tt, c1, c2 := newConnTest(t, &websocket.DialOptions{
-					CompressionOptions: copts(),
+					CompressionMode:      compressionMode(),
+					CompressionThreshold: xrand.Int(9999),
 				}, &websocket.AcceptOptions{
-					CompressionOptions: copts(),
+					CompressionMode:      compressionMode(),
+					CompressionThreshold: xrand.Int(9999),
 				})
 				defer tt.cleanup()
 
@@ -394,9 +393,9 @@ func BenchmarkConn(b *testing.B) {
 	for _, bc := range benchCases {
 		b.Run(bc.name, func(b *testing.B) {
 			bb, c1, c2 := newConnTest(b, &websocket.DialOptions{
-				CompressionOptions: &websocket.CompressionOptions{Mode: bc.mode},
+				CompressionMode: bc.mode,
 			}, &websocket.AcceptOptions{
-				CompressionOptions: &websocket.CompressionOptions{Mode: bc.mode},
+				CompressionMode: bc.mode,
 			})
 			defer bb.cleanup()
 

dial.go

@@ -33,9 +33,17 @@ type DialOptions struct {
 	// Subprotocols lists the WebSocket subprotocols to negotiate with the server.
 	Subprotocols []string
 
-	// CompressionOptions controls the compression options.
-	// See docs on the CompressionOptions type.
-	CompressionOptions *CompressionOptions
+	// CompressionMode controls the compression mode.
+	// Defaults to CompressionNoContextTakeover.
+	//
+	// See docs on CompressionMode for details.
+	CompressionMode CompressionMode
+
+	// CompressionThreshold controls the minimum size of a message before compression is applied.
+	//
+	// Defaults to 512 bytes for CompressionNoContextTakeover and 128 bytes
+	// for CompressionContextTakeover.
+	CompressionThreshold int
 }
 
 // Dial performs a WebSocket handshake on url.
@@ -67,9 +75,6 @@ func dial(ctx context.Context, urls string, opts *DialOptions, rand io.Reader) (
 	if opts.HTTPHeader == nil {
 		opts.HTTPHeader = http.Header{}
 	}
-	if opts.CompressionOptions == nil {
-		opts.CompressionOptions = &CompressionOptions{}
-	}
 
 	secWebSocketKey, err := secWebSocketKey(rand)
 	if err != nil {
@@ -107,7 +112,7 @@ func dial(ctx context.Context, urls string, opts *DialOptions, rand io.Reader) (
 		rwc:            rwc,
 		client:         true,
 		copts:          copts,
-		flateThreshold: opts.CompressionOptions.Threshold,
+		flateThreshold: opts.CompressionThreshold,
 		br:             getBufioReader(rwc),
 		bw:             getBufioWriter(rwc),
 	}), resp, nil
@@ -141,8 +146,8 @@ func handshakeRequest(ctx context.Context, urls string, opts *DialOptions, secWe
 	if len(opts.Subprotocols) > 0 {
 		req.Header.Set("Sec-WebSocket-Protocol", strings.Join(opts.Subprotocols, ","))
 	}
-	if opts.CompressionOptions.Mode != CompressionDisabled {
-		copts := opts.CompressionOptions.Mode.opts()
+	if opts.CompressionMode != CompressionDisabled {
+		copts := opts.CompressionMode.opts()
 		copts.setHeader(req.Header)
 	}
 

doc.go

@@ -6,7 +6,7 @@
 //
 // Use Dial to dial a WebSocket server.
 //
-// Accept to accept a WebSocket client.
+// Use Accept to accept a WebSocket client.
 //
 // Conn represents the resulting WebSocket connection.
 //
@@ -25,7 +25,8 @@
 //
 // Some important caveats to be aware of:
 //
+//  - Accept always errors out
 //  - Conn.Ping is no-op
 //  - HTTPClient, HTTPHeader and CompressionMode in DialOptions are no-op
-//  - *http.Response from Dial is &http.Response{} on success
+//  - *http.Response from Dial is &http.Response{} with a 101 status code on success
 package websocket // import "nhooyr.io/websocket"

ws_js.go

@@ -152,6 +152,11 @@ func (c *Conn) read(ctx context.Context) (MessageType, []byte, error) {
 	}
 }
 
+// Ping is mocked out for Wasm.
+func (c *Conn) Ping(ctx context.Context) error {
+	return nil
+}
+
 // Write writes a message of the given type to the connection.
 // Always non blocking.
 func (c *Conn) Write(ctx context.Context, typ MessageType, p []byte) error {