Significantly better examples and godoc

Author: nhooyr

README.md

@@ -25,7 +25,7 @@ go get nhooyr.io/websocket
 - context.Context is first class
 - net/http is used for WebSocket dials and upgrades
 - Thoroughly tested, fully passes the [autobahn-testsuite](https://github.com/crossbario/autobahn-testsuite)
-- JSON helpers
+- All returned errors include detailed context
 
 ## Roadmap
 
@@ -34,45 +34,37 @@ go get nhooyr.io/websocket
 
 ## Example
 
+For a production quality example that shows off the full API, see the echo example on the godoc.
+
 ### Server
 
 ```go
-fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-	c, err := websocket.Accept(w, r)
+http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	c, err := websocket.Accept(w, r, websocket.AcceptOptions{})
 	if err != nil {
-		log.Printf("server handshake failed: %v", err)
-		return
+		// ...
 	}
 	defer c.Close(websocket.StatusInternalError, "")
 
-	jc := websocket.JSONConn{
-		Conn: c,
-	}
-
 	ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
 	defer cancel()
 
-	v := map[string]interface{}{
-		"my_field": "foo",
+	_, r, err := c.Reader(ctx)
+	if err != nil {
+		// ...
 	}
-	err = jc.Write(ctx, v)
+	
+	b, err := ioutil.ReadAll(r)
 	if err != nil {
-		log.Printf("failed to write json: %v", err)
-		return
+		// ...
 	}
-
-	log.Printf("wrote %v", v)
-
+	
+	fmt.Printf("received %q\n", b)
+	
 	c.Close(websocket.StatusNormalClosure, "")
 })
-err := http.ListenAndServe("localhost:8080", fn)
-if err != nil {
-	log.Fatalf("failed to listen and serve: %v", err)
-}
 ```
 
-For a production quality example that shows off the low level API, see the [echo server example](https://github.com/nhooyr/websocket/blob/master/example_test.go#L15).
-
 ### Client
 
 ```go
@@ -85,17 +77,20 @@ if err != nil {
 }
 defer c.Close(websocket.StatusInternalError, "")
 
-jc := websocket.JSONConn{
-	Conn: c,
+ww, err := c.Writer(ctx)
+if err != nil {
+	// ...
 }
 
-var v interface{}
-err = jc.Read(ctx, &v)
+_, err = ww.Write([]byte("hi"))
 if err != nil {
-	return err
+	// ...
 }
 
-log.Printf("received %v", v)
+err = ww.Close()
+if err != nil {
+	// ...
+}
 
 c.Close(websocket.StatusNormalClosure, "")
 ```

bench_test.go

@@ -28,7 +28,7 @@ func benchConn(b *testing.B, stream bool) {
 			if stream {
 				streamEchoLoop(r.Context(), c)
 			} else {
-				streamEchoLoop(r.Context(), c)
+				bufferedEchoLoop(r.Context(), c)
 			}
 
 		}))
@@ -46,11 +46,10 @@ func benchConn(b *testing.B, stream bool) {
 		defer c.Close(websocket.StatusInternalError, "")
 
 		runN := func(n int) {
+			msg := []byte(strings.Repeat("2", n))
+			buf := make([]byte, len(msg))
 			b.Run(strconv.Itoa(n), func(b *testing.B) {
-				msg := []byte(strings.Repeat("2", n))
-				buf := make([]byte, len(msg))
 				b.SetBytes(int64(len(msg)))
-				b.ResetTimer()
 				for i := 0; i < b.N; i++ {
 					if stream {
 						w, err := c.Writer(ctx, websocket.MessageText)
@@ -83,18 +82,17 @@ func benchConn(b *testing.B, stream bool) {
 						b.Fatal(err)
 					}
 				}
-				b.StopTimer()
 			})
 		}
 
-		runN(32)
-		runN(128)
-		runN(512)
-		runN(1024)
+		// runN(32)
+		// runN(128)
+		// runN(512)
+		// runN(1024)
 		runN(4096)
 		runN(16384)
-		runN(65536)
-		runN(131072)
+		// runN(65536)
+		// runN(131072)
 
 		c.Close(websocket.StatusNormalClosure, "")
 	})

example_echo_test.go

@@ -0,0 +1,164 @@
+package websocket_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/ioutil"
+	"log"
+	"net"
+	"net/http"
+	"time"
+
+	"golang.org/x/time/rate"
+	"golang.org/x/xerrors"
+
+	"nhooyr.io/websocket"
+)
+
+func Example_echo() {
+	l, err := net.Listen("tcp", "localhost:0")
+	if err != nil {
+		log.Fatalf("failed to listen: %v", err)
+		return
+	}
+	defer l.Close()
+
+	s := &http.Server{
+		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			err := echoServer(w, r)
+			if err != nil {
+				log.Printf("echo server: %v", err)
+			}
+		}),
+		ReadTimeout:  time.Second * 15,
+		WriteTimeout: time.Second * 15,
+	}
+	defer s.Close()
+
+	go func() {
+		err := s.Serve(l)
+		if err != http.ErrServerClosed {
+			log.Fatalf("failed to listen and serve: %v", err)
+		}
+	}()
+
+	err = client("ws://" + l.Addr().String())
+	if err != nil {
+		log.Fatalf("client failed: %v", err)
+	}
+
+	// Output:
+	// {"i":0}
+	// {"i":1}
+	// {"i":2}
+	// {"i":3}
+	// {"i":4}
+}
+
+func echoServer(w http.ResponseWriter, r *http.Request) error {
+	c, err := websocket.Accept(w, r, websocket.AcceptOptions{
+		Subprotocols: []string{"echo"},
+	})
+	if err != nil {
+		return err
+	}
+	defer c.Close(websocket.StatusInternalError, "")
+
+	if c.Subprotocol() == "" {
+		c.Close(websocket.StatusPolicyViolation, "cannot communicate with the default protocol")
+		return xerrors.Errorf("client does not speak echo sub protocol")
+	}
+
+	ctx := r.Context()
+	l := rate.NewLimiter(rate.Every(time.Millisecond*100), 10)
+
+	for {
+		err = echo(ctx, c, l)
+		if err != nil {
+			return xerrors.Errorf("failed to echo: %w", err)
+		}
+	}
+}
+
+func echo(ctx context.Context, c *websocket.Conn, l *rate.Limiter) error {
+	ctx, cancel := context.WithTimeout(ctx, time.Minute)
+	defer cancel()
+
+	err := l.Wait(ctx)
+	if err != nil {
+		return err
+	}
+
+	typ, r, err := c.Reader(ctx)
+	if err != nil {
+		return err
+	}
+	r = io.LimitReader(r, 32768)
+
+	w, err := c.Writer(ctx, typ)
+	if err != nil {
+		return err
+	}
+
+	_, err = io.Copy(w, r)
+	if err != nil {
+		return err
+	}
+
+	err = w.Close()
+	return err
+}
+
+func client(url string) error {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+
+	c, _, err := websocket.Dial(ctx, url, websocket.DialOptions{
+		Subprotocols: []string{"echo"},
+	})
+	if err != nil {
+		return err
+	}
+	defer c.Close(websocket.StatusInternalError, "")
+
+	for i := 0; i < 5; i++ {
+		w, err := c.Writer(ctx, websocket.MessageText)
+		if err != nil {
+			return err
+		}
+
+		e := json.NewEncoder(w)
+		err = e.Encode(map[string]int{
+			"i": i,
+		})
+		if err != nil {
+			return err
+		}
+
+		err = w.Close()
+		if err != nil {
+			return err
+		}
+
+		typ, r, err := c.Reader(ctx)
+		if err != nil {
+			return err
+		}
+
+		if typ != websocket.MessageText {
+			return xerrors.Errorf("expected text message but got %v", typ)
+		}
+
+		msg2, err := ioutil.ReadAll(r)
+		if err != nil {
+			return err
+		}
+
+		fmt.Printf("%s", msg2)
+	}
+
+	c.Close(websocket.StatusNormalClosure, "")
+	return nil
+}