Update docs

nhooyr · nhooyr · commit 9d9c9718e1e1 · 2023-10-19T00:38:05.000-07:00
diff --git a/README.md b/README.md
@@ -5,15 +5,9 @@
 
 websocket is a minimal and idiomatic WebSocket library for Go.
 
-> **note**: I haven't been responsive for questions/reports on the issue tracker but I do
-> read through and there are no outstanding bugs. There are certainly some nice to haves
-> that I should merge in/figure out but nothing critical. I haven't given up on adding new
-> features and cleaning up the code further, just been busy. Should anything critical
-> arise, I will fix it.
-
 ## Install
 
-```bash
+```sh
 go get nhooyr.io/websocket
 ```
 
@@ -23,18 +17,23 @@ go get nhooyr.io/websocket
 - First class [context.Context](https://blog.golang.org/context) support
 - Fully passes the WebSocket [autobahn-testsuite](https://github.com/crossbario/autobahn-testsuite)
 - [Zero dependencies](https://pkg.go.dev/nhooyr.io/websocket?tab=imports)
-- JSON and protobuf helpers in the [wsjson](https://pkg.go.dev/nhooyr.io/websocket/wsjson) and [wspb](https://pkg.go.dev/nhooyr.io/websocket/wspb) subpackages
+- JSON helpers in the [wsjson](https://pkg.go.dev/nhooyr.io/websocket/wsjson) subpackage
 - Zero alloc reads and writes
 - Concurrent writes
 - [Close handshake](https://pkg.go.dev/nhooyr.io/websocket#Conn.Close)
 - [net.Conn](https://pkg.go.dev/nhooyr.io/websocket#NetConn) wrapper
 - [Ping pong](https://pkg.go.dev/nhooyr.io/websocket#Conn.Ping) API
 - [RFC 7692](https://tools.ietf.org/html/rfc7692) permessage-deflate compression
+- [CloseRead](https://pkg.go.dev/nhooyr.io/websocket#Conn.CloseRead) helper for write only connections
 - Compile to [Wasm](https://pkg.go.dev/nhooyr.io/websocket#hdr-Wasm)
 
 ## Roadmap
 
+- [ ] Ping pong heartbeat helper [#267](https://github.com/nhooyr/websocket/issues/267)
+- [ ] Graceful shutdown helper [#209](https://github.com/nhooyr/websocket/issues/209)
+- [ ] Assembly for WebSocket masking [#16](https://github.com/nhooyr/websocket/issues/16)
 - [ ] HTTP/2 [#4](https://github.com/nhooyr/websocket/issues/4)
+- [ ] The holy grail [#402](https://github.com/nhooyr/websocket/issues/402)
 
 ## Examples
 
@@ -51,7 +50,7 @@ http.HandlerFunc(func (w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		// ...
 	}
-	defer c.Close(websocket.StatusInternalError, "the sky is falling")
+	defer c.CloseNow()
 
 	ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
 	defer cancel()
@@ -78,7 +77,7 @@ c, _, err := websocket.Dial(ctx, "ws://localhost:8080", nil)
 if err != nil {
 	// ...
 }
-defer c.Close(websocket.StatusInternalError, "the sky is falling")
+defer c.CloseNow()
 
 err = wsjson.Write(ctx, c, "hi")
 if err != nil {
@@ -110,12 +109,14 @@ Advantages of nhooyr.io/websocket:
   - Gorilla writes directly to a net.Conn and so duplicates features of net/http.Client.
 - Concurrent writes
 - Close handshake ([gorilla/websocket#448](https://github.com/gorilla/websocket/issues/448))
+- [CloseRead](https://pkg.go.dev/nhooyr.io/websocket#Conn.CloseRead) helper for write only connections
 - Idiomatic [ping pong](https://pkg.go.dev/nhooyr.io/websocket#Conn.Ping) API
   - Gorilla requires registering a pong callback before sending a Ping
 - Can target Wasm ([gorilla/websocket#432](https://github.com/gorilla/websocket/issues/432))
-- Transparent message buffer reuse with [wsjson](https://pkg.go.dev/nhooyr.io/websocket/wsjson) and [wspb](https://pkg.go.dev/nhooyr.io/websocket/wspb) subpackages
+- Transparent message buffer reuse with [wsjson](https://pkg.go.dev/nhooyr.io/websocket/wsjson) subpackage
 - [1.75x](https://github.com/nhooyr/websocket/releases/tag/v1.7.4) faster WebSocket masking implementation in pure Go
   - Gorilla's implementation is slower and uses [unsafe](https://golang.org/pkg/unsafe/).
+    Soon we'll have assembly and be 4.5x faster [#326](https://github.com/nhooyr/websocket/pull/326)
 - Full [permessage-deflate](https://tools.ietf.org/html/rfc7692) compression extension support
   - Gorilla only supports no context takeover mode
 - [CloseRead](https://pkg.go.dev/nhooyr.io/websocket#Conn.CloseRead) helper ([gorilla/websocket#492](https://github.com/gorilla/websocket/issues/492))
diff --git a/doc.go b/doc.go
@@ -13,7 +13,7 @@
 //
 // The examples are the best way to understand how to correctly use the library.
 //
-// The wsjson and wspb subpackages contain helpers for JSON and protobuf messages.
+// The wsjson subpackage contain helpers for JSON and protobuf messages.
 //
 // More documentation at https://nhooyr.io/websocket.
 //
diff --git a/example_test.go b/example_test.go
@@ -20,7 +20,7 @@ func ExampleAccept() {
 			log.Println(err)
 			return
 		}
-		defer c.Close(websocket.StatusInternalError, "the sky is falling")
+		defer c.CloseNow()
 
 		ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
 		defer cancel()
@@ -50,7 +50,7 @@ func ExampleDial() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer c.Close(websocket.StatusInternalError, "the sky is falling")
+	defer c.CloseNow()
 
 	err = wsjson.Write(ctx, c, "hi")
 	if err != nil {
@@ -71,7 +71,7 @@ func ExampleCloseStatus() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer c.Close(websocket.StatusInternalError, "the sky is falling")
+	defer c.CloseNow()
 
 	_, _, err = c.Reader(ctx)
 	if websocket.CloseStatus(err) != websocket.StatusNormalClosure {
@@ -88,7 +88,7 @@ func Example_writeOnly() {
 			log.Println(err)
 			return
 		}
-		defer c.Close(websocket.StatusInternalError, "the sky is falling")
+		defer c.CloseNow()
 
 		ctx, cancel := context.WithTimeout(r.Context(), time.Minute*10)
 		defer cancel()
@@ -145,7 +145,7 @@ func ExampleConn_Ping() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer c.Close(websocket.StatusInternalError, "the sky is falling")
+	defer c.CloseNow()
 
 	// Required to read the Pongs from the server.
 	ctx = c.CloseRead(ctx)
@@ -162,10 +162,10 @@ func ExampleConn_Ping() {
 
 // This example demonstrates full stack chat with an automated test.
 func Example_fullStackChat() {
-	// https://github.com/nhooyr/websocket/tree/master/examples/chat
+	// https://github.com/nhooyr/websocket/tree/master/internal/examples/chat
 }
 
 // This example demonstrates a echo server.
 func Example_echo() {
-	// https://github.com/nhooyr/websocket/tree/master/examples/echo
+	// https://github.com/nhooyr/websocket/tree/master/internal/examples/echo
 }
diff --git a/internal/examples/chat/chat.go b/internal/examples/chat/chat.go
@@ -74,7 +74,7 @@ func (cs *chatServer) subscribeHandler(w http.ResponseWriter, r *http.Request) {
 		cs.logf("%v", err)
 		return
 	}
-	defer c.Close(websocket.StatusInternalError, "")
+	defer c.CloseNow()
 
 	err = cs.subscribe(r.Context(), c)
 	if errors.Is(err, context.Canceled) {
diff --git a/internal/examples/echo/server.go b/internal/examples/echo/server.go
@@ -28,7 +28,7 @@ func (s echoServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		s.logf("%v", err)
 		return
 	}
-	defer c.Close(websocket.StatusInternalError, "the sky is falling")
+	defer c.CloseNow()
 
 	if c.Subprotocol() != "echo" {
 		c.Close(websocket.StatusPolicyViolation, "client must speak the echo subprotocol")

Original file line number	Diff line number	Diff line change
`@@ -74,7 +74,7 @@ func (cs chatServer) subscribeHandler(w http.ResponseWriter, r http.Request) {`
`74`	`74`	`cs.logf("%v", err)`
`75`	`75`	`return`
`76`	`76`	`}`
`77`		`- defer c.Close(websocket.StatusInternalError, "")`
	`77`	`+ defer c.CloseNow()`
`78`	`78`
`79`	`79`	`err = cs.subscribe(r.Context(), c)`
`80`	`80`	`if errors.Is(err, context.Canceled) {`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ func (s echoServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {`
`28`	`28`	`s.logf("%v", err)`
`29`	`29`	`return`
`30`	`30`	`}`
`31`		`- defer c.Close(websocket.StatusInternalError, "the sky is falling")`
	`31`	`+ defer c.CloseNow()`
`32`	`32`
`33`	`33`	`if c.Subprotocol() != "echo" {`
`34`	`34`	`c.Close(websocket.StatusPolicyViolation, "client must speak the echo subprotocol")`