Polish further

Author: nhooyr

README.md

@@ -5,10 +5,6 @@
 
 websocket is a minimal and idiomatic WebSocket library for Go.
 
-This library is now production ready but some parts of the API are marked as experimental.
-
-Please feel free to open an issue for feedback.
-
 ## Install
 
 ```bash
@@ -23,8 +19,8 @@ go get nhooyr.io/websocket
 - Thorough tests, fully passes the [autobahn-testsuite](https://github.com/crossbario/autobahn-testsuite)
 - Zero dependencies outside of the stdlib for the core library
 - JSON and ProtoBuf helpers in the wsjson and wspb subpackages
-- High performance, memory reuse wherever possible
-- Concurrent reads and writes out of the box
+- High performance, memory reuse by default
+- Concurrent writes out of the box
 
 ## Roadmap
 
@@ -124,8 +120,8 @@ 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 proxies and prevents support of HTTP/2.
 
-Some more advantages of nhooyr/websocket are that it supports concurrent reads,
-writes and makes it very easy to close the connection with a status code and reason.
+Some more advantages of nhooyr/websocket are that it supports concurrent writes and
+makes it very easy to close the connection with a status code and reason.
 
 nhooyr/websocket also responds to pings, pongs and close frames in a separate goroutine so that
 your application doesn't always need to read from the connection unless it expects a data message.
@@ -134,11 +130,12 @@ even if you don't expect the peer to send any messages.
 
 In terms of performance, the differences depend on your application code. nhooyr/websocket
 reuses buffers efficiently out of the box whereas gorilla/websocket does not. As mentioned
-above, it also supports concurrent readers and writers out of the box.
+above, it also supports concurrent writers out of the box.
 
-The only performance downside to nhooyr/websocket is that uses two extra goroutines. One for
+The only performance con to nhooyr/websocket is that uses two extra goroutines. One for
 reading pings, pongs and close frames async to application code and another to support
-context.Context cancellation. This costs 4 KB of memory which is fairly cheap.
+context.Context cancellation. This costs 4 KB of memory which is cheap compared
+to the benefits.
 
 ### x/net/websocket
 

accept.go

@@ -76,12 +76,12 @@ func verifyClientRequest(w http.ResponseWriter, r *http.Request) error {
 }
 
 // Accept accepts a WebSocket handshake from a client and upgrades the
-// the connection to WebSocket.
+// the connection to a WebSocket.
 //
 // Accept will reject the handshake if the Origin domain is not the same as the Host unless
 // the InsecureSkipVerify option is set.
 //
-// The returned connection will be bound by r.Context(). Use c.Context() to change
+// The returned connection will be bound by r.Context(). Use conn.Context() to change
 // the bounding context.
 func Accept(w http.ResponseWriter, r *http.Request, opts AcceptOptions) (*Conn, error) {
 	c, err := accept(w, r, opts)
@@ -107,15 +107,15 @@ func accept(w http.ResponseWriter, r *http.Request, opts AcceptOptions) (*Conn,
 
 	hj, ok := w.(http.Hijacker)
 	if !ok {
-		err = xerrors.New("response writer must implement http.Hijacker")
+		err = xerrors.New("passed ResponseWriter does not implement http.Hijacker")
 		http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
 		return nil, err
 	}
 
 	w.Header().Set("Upgrade", "websocket")
 	w.Header().Set("Connection", "Upgrade")
 
-	handleKey(w, r)
+	handleSecWebSocketKey(w, r)
 
 	subproto := selectSubprotocol(r, opts.Subprotocols)
 	if subproto != "" {
@@ -163,7 +163,7 @@ func selectSubprotocol(r *http.Request, subprotocols []string) string {
 
 var keyGUID = []byte("258EAFA5-E914-47DA-95CA-C5AB0DC85B11")
 
-func handleKey(w http.ResponseWriter, r *http.Request) {
+func handleSecWebSocketKey(w http.ResponseWriter, r *http.Request) {
 	key := r.Header.Get("Sec-WebSocket-Key")
 	h := sha1.New()
 	h.Write([]byte(key))
@@ -185,5 +185,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 %q", origin, r.Host)
+	return xerrors.Errorf("request Origin %q is not authorized for Host %q", origin, r.Host)
 }

dial.go

@@ -18,9 +18,9 @@ import (
 // DialOptions represents the options available to pass to Dial.
 type DialOptions struct {
 	// HTTPClient is the http client used for the handshake.
-	// Its Transport must use HTTP/1.1 and return writable bodies
-	// for WebSocket handshakes. This was introduced in Go 1.12.
-	// http.Transport does this all correctly.
+	// Its Transport must return writable bodies
+	// for WebSocket handshakes.
+	// http.Transport does this correctly beginning with Go 1.12.
 	HTTPClient *http.Client
 
 	// HTTPHeader specifies the HTTP headers included in the handshake request.
@@ -30,7 +30,7 @@ type DialOptions struct {
 	Subprotocols []string
 }
 
-// We use this key for all client requests as the Sec-WebSocket-Key header is useless.
+// We use this key for all client requests as the Sec-WebSocket-Key header doesn't do anything.
 // See https://stackoverflow.com/a/37074398/4283659.
 // We also use the same mask key for every message as it too does not make a difference.
 var secWebSocketKey = base64.StdEncoding.EncodeToString(make([]byte, 16))
@@ -108,7 +108,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("response body is not a read write closer: %T", rwc)
+		return nil, resp, xerrors.Errorf("response body is not a io.ReadWriteCloser: %T", rwc)
 	}
 
 	c := &Conn{

example_echo_test.go

@@ -20,7 +20,7 @@ import (
 // dials the server and then sends 5 different messages
 // and prints out the server's responses.
 func Example_echo() {
-	// First we listen on port 0, that means the OS will
+	// First we listen on port 0 which 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")

messagetype.go

@@ -13,3 +13,5 @@ const (
 	// MessageBinary is for binary messages like Protobufs.
 	MessageBinary MessageType = MessageType(opBinary)
 )
+
+// Above I've explicitly included the types of the constants for stringer.

statuscode.go

@@ -60,7 +60,7 @@ func parseClosePayload(p []byte) (CloseError, error) {
 	}
 
 	if len(p) < 2 {
-		return CloseError{}, xerrors.Errorf("close payload too small, cannot even contain the 2 byte status code")
+		return CloseError{}, xerrors.Errorf("close payload %q too small, cannot even contain the 2 byte status code", p)
 	}
 
 	ce := CloseError{
@@ -78,13 +78,13 @@ func parseClosePayload(p []byte) (CloseError, error) {
 // See http://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number
 // and https://tools.ietf.org/html/rfc6455#section-7.4.1
 func validWireCloseCode(code StatusCode) bool {
-	if code >= StatusNormalClosure && code <= statusTLSHandshake {
-		switch code {
-		case 1004, StatusNoStatusRcvd, statusAbnormalClosure, statusTLSHandshake:
-			return false
-		default:
-			return true
-		}
+	switch code {
+	case 1004, StatusNoStatusRcvd, statusAbnormalClosure, statusTLSHandshake:
+		return false
+	}
+
+	if code >= StatusNormalClosure && code <= StatusBadGateway {
+		return true
 	}
 	if code >= 3000 && code <= 4999 {
 		return true