Improve README.md

Closes #30

Author: nhooyr

README.md

@@ -4,47 +4,139 @@
 [![Codecov](https://img.shields.io/codecov/c/github/nhooyr/ws.svg)](https://codecov.io/gh/nhooyr/ws)
 [![GitHub release](https://img.shields.io/github/release/nhooyr/ws.svg)](https://github.com/nhooyr/ws/releases)
 
-ws is a clean and idiomatic WebSocket library for Go.
+ws is a minimal and idiomatic WebSocket library for Go.
 
 This library is in heavy development.
 
 ## Install
 
 ```bash
-go get nhooyr.io/ws
+go get nhooyr.io/ws@master
 ```
 
-## Why
+## Example
+
+### Server
+
+```go
+func main() {
+	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		c, err := ws.Accept(w, r,
+			ws.AcceptSubprotocols("echo"),
+		)
+		if err != nil {
+			log.Printf("server handshake failed: %v", err)
+			return
+		}
+		defer c.Close(ws.StatusInternalError, "")
+
+		ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
+		defer cancel()
+
+		type myJsonStruct struct {
+			MyField string `json:"my_field"`
+		}
+		err = wsjson.Write(ctx, c, myJsonStruct{
+			MyField: "foo",
+		})
+		if err != nil {
+			log.Printf("failed to write json struct: %v", err)
+			return
+		}
+
+		c.Close(ws.StatusNormalClosure, "")
+	})
+	// For production deployments, use a net/http.Server configured
+	// with the appropriate timeouts.
+	err := http.ListenAndServe("localhost:8080", fn)
+	if err != nil {
+		log.Fatalf("failed to listen and serve: %v", err)
+	}
+}
+```
 
-There is no other Go WebSocket library with a clean API.
+### Client
+
+```go
+func main() {
+	ctx := context.Background()
+	ctx, cancel := context.WithTimeout(ctx, time.Minute)
+	defer cancel()
+
+	c, _, err := ws.Dial(ctx, "ws://localhost:8080")
+	if err != nil {
+		log.Fatalf("failed to ws dial: %v", err)
+	}
+	defer c.Close(ws.StatusInternalError, "")
+
+	type myJsonStruct struct {
+		MyField string `json:"my_field"`
+	}
+	err = wsjson.Write(ctx, c, myJsonStruct{
+		MyField: "foo",
+	})
+	if err != nil {
+		log.Fatalf("failed to write json struct: %v", err)
+	}
+
+	c.Close(ws.StatusNormalClosure, "")
+}
+```
 
-Comparisons with existing WebSocket libraries below.
+See [example_test.go](example_test.go) for more examples.
 
-### [x/net/websocket](https://godoc.org/golang.org/x/net/websocket)
+## Features
 
+- Full support of the WebSocket protocol
+- Simple to use because of the minimal API
+- Uses the context package for cancellation
+- Uses net/http's Client to do WebSocket dials
+- JSON and Protobuf helpers in wsjson and wspb subpackages
+- Compression extension is supported
+- Highly optimized
+- API will be ready for WebSockets over HTTP/2
 
-Unmaintained and the API does not reflect WebSocket semantics.
+## Design considerations
 
-See https://github.com/golang/go/issues/18152
+- Minimal API is easier to maintain and for others to learn
+- Context based cancellation is more ergonomic and robust than setting deadlines
+- No pings or pongs because TCP keep alives work fine for HTTP/1.1 and they do not make
+  sense with HTTP/2
+- net.Conn is never exposed as WebSocket's over HTTP/2 will not have a net.Conn.
+- Functional options make the API very clean and easy to extend
+- Compression is very useful for JSON payloads
+- Protobuf and JSON helpers make code terse
+- Using net/http's Client for dialing means we do not have to reinvent dialing hooks
+  and configurations. Just pass in a custom net/http client if you want custom dialing.
+
+## Comparison
 
 ### [gorilla/websocket](https://github.com/gorilla/websocket)
 
-This package is the community standard but it is very old and over time
+This package is the community standard but it is very old and over timennn
 has accumulated cruft. There are many ways to do the same thing and the API
-overall is just not very clear. 
+overall is just not very clear. Just compare the godoc of
+[nhooyr/ws](godoc.org/github.com/nhooyr/ws) side by side with
+[gorilla/websocket](godoc.org/github.com/gorilla/websocket).
 
-The callback hooks . The API for this library has been designed
-such that there is only one way to do things and callbacks have been avoided.
+The API for nhooyr/ws has been designed such that there is only one way to do things
+and with HTTP/2 in mind which makes using it correctly and safely much easier.
 
-Performance sensitive applications should use ws/wscore directly.
+### [x/net/websocket](https://godoc.org/golang.org/x/net/websocket)
+
+Unmaintained and the API does not reflect WebSocket semantics. Should never be used.
+
+See https://github.com/golang/go/issues/18152
 
 ### [gobwas/ws](https://github.com/gobwas/ws)
 
-This library has an extremely flexible API but that comes at a cost of usability
-and clarity. Its just not clear and simple how to do things in a safe manner. 
+This library has an extremely flexible API but that comes at the cost of usability
+and clarity. Its just not clear how to do things in a safe manner. 
 
-## TODO
+This library is fantastic in terms of performance though. The author put in significant
+effort to ensure its speed and I have tried to apply as many of its teachings as
+I could into nhooyr/ws.
 
-- [ ] Fully implement.
-- [ ] Decide whether we want to do WebSocket pings by default maybe every 30s?
-- [ ] 
+If you want a library that gives you absolute control over everything, this is the library,
+but for most users, the API provided by nhooyr/ws will definitely fit better as it will
+be just as performant but much easier to use.

accept.go

@@ -24,6 +24,7 @@ func AcceptSubprotocols(subprotocols ...string) AcceptOption {
 // Use this option with caution to avoid exposing your WebSocket
 // server to a CSRF attack.
 // See https://stackoverflow.com/a/37837709/4283659
+// You can use a * to specify wildcards in domain names.
 func AcceptOrigins(origins ...string) AcceptOption {
 	panic("TODO")
 }

datatype.go

@@ -1,15 +1,11 @@
 package ws
 
-import (
-	"nhooyr.io/ws/wscore"
-)
-
 // DataType represents the Opcode of a WebSocket data frame.
 //go:generate stringer -type=DataType
 type DataType int
 
 // DataType constants.
 const (
-	Text   DataType = DataType(wscore.OpText)
-	Binary DataType = DataType(wscore.OpBinary)
+	Text   DataType = DataType(opText)
+	Binary DataType = DataType(opBinary)
 )

dial.go

@@ -33,9 +33,10 @@ func DialSubprotocols(subprotocols ...string) DialOption {
 
 // We use this key for all client requests as the Sec-WebSocket-Key header is useless.
 // 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))
 
-// Dial performs a websocket handshake on the given url with the given options.
+// Dial performs a WebSocket handshake on the given url with the given options.
 func Dial(ctx context.Context, u string, opts ...DialOption) (*Conn, *http.Response, error) {
 	panic("TODO")
 }

doc.go

@@ -1,2 +1,4 @@
-// Package ws implements the WebSocket protocol defined in RFC 6455.
+// Package ws is a minimal and idiomatic implementation of the WebSocket protocol.
+//
+// For now the docs are at https://github.com/nhooyr/ws#ws. I will move them here later.
 package ws

example_test.go

@@ -41,7 +41,8 @@ func ExampleAccept_echo() {
 			r.SetContext(ctx)
 			r.Limit(32768)
 
-			w := c.MessageWriter(ctx, typ)
+			w := c.MessageWriter(typ)
+			w.SetContext(ctx)
 			_, err = io.Copy(w, r)
 			if err != nil {
 				return err
@@ -83,10 +84,13 @@ func ExampleAccept() {
 		}
 		defer c.Close(ws.StatusInternalError, "")
 
+		ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
+		defer cancel()
+
 		type myJsonStruct struct {
 			MyField string `json:"my_field"`
 		}
-		err = wsjson.Write(r.Context(), c, myJsonStruct{
+		err = wsjson.Write(ctx, c, myJsonStruct{
 			MyField: "foo",
 		})
 		if err != nil {
@@ -112,7 +116,6 @@ func ExampleDial() {
 	c, _, err := ws.Dial(ctx, "ws://localhost:8080")
 	if err != nil {
 		log.Fatalf("failed to ws dial: %v", err)
-		return
 	}
 	defer c.Close(ws.StatusInternalError, "")
 
@@ -124,7 +127,6 @@ func ExampleDial() {
 	})
 	if err != nil {
 		log.Fatalf("failed to write json struct: %v", err)
-		return
 	}
 
 	c.Close(ws.StatusNormalClosure, "")

mask.go

@@ -1,6 +1,6 @@
 package ws
 
-// Mask applies the websocket masking algorithm to p
+// Mask applies the WebSocket masking algorithm to p
 // with the given key where the first 3 bits of pos
 // are the starting position in the key.
 // See https://tools.ietf.org/html/rfc6455#section-5.3

opcode_string.go

@@ -2,7 +2,6 @@ package ws
 
 import (
 	"context"
-	"net"
 )
 
 const (
@@ -18,16 +17,11 @@ func (c *Conn) Subprotocol() string {
 	panic("TODO")
 }
 
-// NetConn returns the net.Conn underlying the Conn.
-func (c *Conn) NetConn() net.Conn {
-	panic("TODO")
-}
-
 // MessageWriter returns a writer bounded by the context that will write
 // a WebSocket data frame of type dataType to the connection.
 // Ensure you close the MessageWriter once you have written to entire message.
 // Concurrent calls to MessageWriter are ok.
-func (c *Conn) MessageWriter(ctx context.Context, dataType DataType) *MessageWriter {
+func (c *Conn) MessageWriter(dataType DataType) *MessageWriter {
 	panic("TODO")
 }
 
@@ -41,6 +35,9 @@ func (c *Conn) ReadMessage(ctx context.Context) (DataType, *MessageReader, error
 // Close closes the WebSocket connection with the given status code and reason.
 // It will write a WebSocket close frame with a timeout of 5 seconds.
 func (c *Conn) Close(code StatusCode, reason string) error {
+	// This function also will not wait for a close frame from the peer like the RFC
+	// wants because that makes no sense and I don't think anyone actually follows that.
+	// Definitely worth seeing what popular browsers do later.
 	panic("TODO")
 }
 
@@ -56,6 +53,18 @@ func (w *MessageWriter) Write(p []byte) (n int, err error) {
 	panic("TODO")
 }
 
+// SetContext bounds the writer to the context.
+// This must be called before any write.
+func (w *MessageWriter) SetContext(ctx context.Context) {
+	panic("TODO")
+}
+
+// Compress marks the message to be compressed.
+// This must be called before any write.
+func (w *MessageWriter) Compress() {
+	panic("TODO")
+}
+
 // Close flushes the frame to the connection.
 // This must be called for every MessageWriter.
 func (w *MessageWriter) Close() error {
@@ -68,11 +77,13 @@ type MessageReader struct{}
 // SetContext bounds the read operation to the ctx.
 // By default, the context is the one passed to conn.ReadMessage.
 // You still almost always want a separate context for reading the message though.
+// Must be called before any read.
 func (r *MessageReader) SetContext(ctx context.Context) {
 	panic("TODO")
 }
 
 // Limit limits the number of bytes read by the reader.
+// Must be called before any read.
 func (r *MessageReader) Limit(bytes int) {
 	panic("TODO")
 }