Improve docs and CONTRIBUTING.md

Author: nhooyr

accept.go

@@ -41,31 +41,31 @@ type AcceptOptions struct {
 
 func verifyClientRequest(w http.ResponseWriter, r *http.Request) error {
 	if !headerValuesContainsToken(r.Header, "Connection", "Upgrade") {
-		err := xerrors.Errorf("websocket: protocol violation: Connection header %q does not contain Upgrade", r.Header.Get("Connection"))
+		err := xerrors.Errorf("websocket protocol violation: Connection header %q does not contain Upgrade", r.Header.Get("Connection"))
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return err
 	}
 
 	if !headerValuesContainsToken(r.Header, "Upgrade", "WebSocket") {
-		err := xerrors.Errorf("websocket: protocol violation: Upgrade header %q does not contain websocket", r.Header.Get("Upgrade"))
+		err := xerrors.Errorf("websocket protocol violation: Upgrade header %q does not contain websocket", r.Header.Get("Upgrade"))
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return err
 	}
 
 	if r.Method != "GET" {
-		err := xerrors.Errorf("websocket: protocol violation: handshake request method %q is not GET", r.Method)
+		err := xerrors.Errorf("websocket protocol violation: handshake request method %q is not GET", r.Method)
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return err
 	}
 
 	if r.Header.Get("Sec-WebSocket-Version") != "13" {
-		err := xerrors.Errorf("websocket: unsupported protocol version: %q", r.Header.Get("Sec-WebSocket-Version"))
+		err := xerrors.Errorf("unsupported websocket protocol version: %q", r.Header.Get("Sec-WebSocket-Version"))
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return err
 	}
 
 	if r.Header.Get("Sec-WebSocket-Key") == "" {
-		err := xerrors.New("websocket: protocol violation: missing Sec-WebSocket-Key")
+		err := xerrors.New("websocket protocol violation: missing Sec-WebSocket-Key")
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return err
 	}
@@ -78,6 +78,14 @@ func verifyClientRequest(w http.ResponseWriter, r *http.Request) error {
 // Accept will reject the handshake if the Origin is not the same as the Host unless
 // the InsecureSkipVerify option is set.
 func Accept(w http.ResponseWriter, r *http.Request, opts AcceptOptions) (*Conn, error) {
+	c, err := accept(w, r, opts)
+	if err != nil {
+		return nil, xerrors.Errorf("failed to accept websocket connection: %w", err)
+	}
+	return c, nil
+}
+
+func accept(w http.ResponseWriter, r *http.Request, opts AcceptOptions) (*Conn, error) {
 	err := verifyClientRequest(w, r)
 	if err != nil {
 		return nil, err
@@ -93,7 +101,7 @@ func Accept(w http.ResponseWriter, r *http.Request, opts AcceptOptions) (*Conn,
 
 	hj, ok := w.(http.Hijacker)
 	if !ok {
-		err = xerrors.New("websocket: response writer does not implement http.Hijacker")
+		err = xerrors.New("response writer must implement http.Hijacker")
 		http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
 		return nil, err
 	}
@@ -112,7 +120,7 @@ func Accept(w http.ResponseWriter, r *http.Request, opts AcceptOptions) (*Conn,
 
 	netConn, brw, err := hj.Hijack()
 	if err != nil {
-		err = xerrors.Errorf("websocket: failed to hijack connection: %w", err)
+		err = xerrors.Errorf("failed to hijack connection: %w", err)
 		http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
 		return nil, err
 	}
@@ -166,5 +174,5 @@ func authenticateOrigin(r *http.Request) error {
 	if strings.EqualFold(u.Host, r.Host) {
 		return nil
 	}
-	return xerrors.Errorf("request origin %q is not authorized for host %v", origin, r.Host)
+	return xerrors.Errorf("request origin %q is not authorized for host %q", origin, r.Host)
 }

bench_test.go

@@ -28,7 +28,7 @@ func benchConn(b *testing.B, stream bool) {
 			if stream {
 				streamEchoLoop(r.Context(), c)
 			} else {
-				bufferedEchoLoop(r.Context(), c)
+				streamEchoLoop(r.Context(), c)
 			}
 
 		}))

ci/bench/entrypoint.sh

@@ -12,5 +12,6 @@ go test --vet=off --run=^$ -bench=. \
 	./...
 
 set +x
+echo
 echo "profiles are in ./profs
 keep in mind that every profiler Go provides is enabled so that may skew the benchmarks"

dial.go

@@ -35,7 +35,15 @@ type DialOptions struct {
 var secWebSocketKey = base64.StdEncoding.EncodeToString(make([]byte, 16))
 
 // Dial performs a WebSocket handshake on the given url with the given options.
-func Dial(ctx context.Context, u string, opts DialOptions) (_ *Conn, _ *http.Response, err error) {
+func Dial(ctx context.Context, u string, opts DialOptions) (*Conn, *http.Response, error) {
+	c, r, err := dial(ctx, u, opts)
+	if err != nil {
+		return nil, r, xerrors.Errorf("failed to websocket dial: %w", err)
+	}
+	return c, r, nil
+}
+
+func dial(ctx context.Context, u string, opts DialOptions) (_ *Conn, _ *http.Response, err error) {
 	if opts.HTTPClient == nil {
 		opts.HTTPClient = http.DefaultClient
 	}
@@ -45,7 +53,7 @@ func Dial(ctx context.Context, u string, opts DialOptions) (_ *Conn, _ *http.Res
 
 	parsedURL, err := url.Parse(u)
 	if err != nil {
-		return nil, nil, xerrors.Errorf("failed to parse websocket url: %w", err)
+		return nil, nil, xerrors.Errorf("failed to parse url: %w", err)
 	}
 
 	switch parsedURL.Scheme {
@@ -54,7 +62,7 @@ func Dial(ctx context.Context, u string, opts DialOptions) (_ *Conn, _ *http.Res
 	case "wss":
 		parsedURL.Scheme = "https"
 	default:
-		return nil, nil, xerrors.Errorf("unknown scheme in url: %q", parsedURL.Scheme)
+		return nil, nil, xerrors.Errorf("unexpected url scheme scheme: %q", parsedURL.Scheme)
 	}
 
 	req, _ := http.NewRequest("GET", parsedURL.String(), nil)
@@ -70,7 +78,7 @@ func Dial(ctx context.Context, u string, opts DialOptions) (_ *Conn, _ *http.Res
 
 	resp, err := opts.HTTPClient.Do(req)
 	if err != nil {
-		return nil, nil, err
+		return nil, nil, xerrors.Errorf("failed to send handshake request: %w", err)
 	}
 	defer func() {
 		respBody := resp.Body
@@ -90,7 +98,7 @@ func Dial(ctx context.Context, u string, opts DialOptions) (_ *Conn, _ *http.Res
 
 	rwc, ok := resp.Body.(io.ReadWriteCloser)
 	if !ok {
-		return nil, resp, xerrors.Errorf("websocket: body is not a read write closer but should be: %T", rwc)
+		return nil, resp, xerrors.Errorf("response body is not a read write closer: %T", rwc)
 	}
 
 	// TODO pool bufio
@@ -108,15 +116,15 @@ func Dial(ctx context.Context, u string, opts DialOptions) (_ *Conn, _ *http.Res
 
 func verifyServerResponse(resp *http.Response) error {
 	if resp.StatusCode != http.StatusSwitchingProtocols {
-		return xerrors.Errorf("websocket: expected status code %v but got %v", http.StatusSwitchingProtocols, resp.StatusCode)
+		return xerrors.Errorf("expected handshake response status code %v but got %v", http.StatusSwitchingProtocols, resp.StatusCode)
 	}
 
 	if !headerValuesContainsToken(resp.Header, "Connection", "Upgrade") {
-		return xerrors.Errorf("websocket: protocol violation: Connection header does not contain Upgrade: %q", resp.Header.Get("Connection"))
+		return xerrors.Errorf("websocket protocol violation: Connection header does not contain Upgrade: %q", resp.Header.Get("Connection"))
 	}
 
 	if !headerValuesContainsToken(resp.Header, "Upgrade", "WebSocket") {
-		return xerrors.Errorf("websocket: protocol violation: Upgrade header does not contain websocket: %q", resp.Header.Get("Upgrade"))
+		return xerrors.Errorf("websocket protocol violation: Upgrade header does not contain websocket: %q", resp.Header.Get("Upgrade"))
 	}
 
 	// We do not care about Sec-WebSocket-Accept because it does not matter.

docs/CONTRIBUTING.md

@@ -13,4 +13,4 @@ Be sure to link to an existing issue if one exists. In general, try creating an
 before making a PR to get some discussion going and to make sure you do not spend time
 on a PR that may be rejected.
 
-Run `test/run.sh` to test your changes. You only need docker and bash to run the tests.
+Run `ci/run.sh` to test your changes. You only need docker and bash to run the tests.

export_test.go

@@ -12,7 +12,7 @@ import (
 // to write an additional fin frame when Close is called on the writer which
 // can result in worse performance if the full message exceeds the buffer size
 // which is 4096 right now as then two syscalls will be necessary to complete the message.
-// TODO this is no good as we cannot write daata frame msg in between other ones
+// TODO this is no good as we cannot write data frame msg in between other ones
 func (c *Conn) Write(ctx context.Context, typ MessageType, p []byte) error {
 	return c.writeControl(ctx, opcode(typ), p)
 }

header.go

@@ -128,7 +128,7 @@ func readHeader(r io.Reader) (header, error) {
 	case payloadLength == 127:
 		h.payloadLength = int64(binary.BigEndian.Uint64(b))
 		if h.payloadLength < 0 {
-			return header{}, xerrors.Errorf("websocket: header has negative payload length: %v", h.payloadLength)
+			return header{}, xerrors.Errorf("header with negative payload length: %v", h.payloadLength)
 		}
 		b = b[8:]
 	}

json.go

@@ -39,7 +39,7 @@ func (jc JSONConn) read(ctx context.Context, v interface{}) error {
 	}
 
 	if typ != MessageText {
-		return xerrors.Errorf("unexpected frame type for json (expected DataText): %v", typ)
+		return xerrors.Errorf("unexpected frame type for json (expected %v): %v", MessageText, typ)
 	}
 
 	r = io.LimitReader(r, 131072)
@@ -65,7 +65,7 @@ func (jc JSONConn) Write(ctx context.Context, v interface{}) error {
 func (jc JSONConn) write(ctx context.Context, v interface{}) error {
 	w, err := jc.Conn.Writer(ctx, MessageText)
 	if err != nil {
-		return xerrors.Errorf("failed to get message writer: %w", err)
+		return err
 	}
 
 	e := json.NewEncoder(w)

statuscode.go

@@ -43,7 +43,7 @@ const (
 )
 
 // CloseError represents an error from a WebSocket close frame.
-// It is returned by a Conn's method when the Connection was closed with a WebSocket close frame.
+// It is returned by Conn's methods when the Connection is closed with a WebSocket close frame.
 type CloseError struct {
 	Code   StatusCode
 	Reason string

websocket.go

@@ -60,7 +60,7 @@ type Conn struct {
 }
 
 func (c *Conn) close(err error) {
-	err = xerrors.Errorf("websocket: connection broken: %w", err)
+	err = xerrors.Errorf("connection broken: %w", err)
 
 	c.closeOnce.Do(func() {
 		runtime.SetFinalizer(c, nil)
@@ -96,7 +96,7 @@ func (c *Conn) init() {
 	c.readDone = make(chan int)
 
 	runtime.SetFinalizer(c, func(c *Conn) {
-		c.Close(StatusInternalError, "websocket: connection ended up being garbage collected")
+		c.Close(StatusInternalError, "connection garbage collected")
 	})
 
 	go c.writeLoop()