Merge pull request #31 from nhooyr/docs

Remove wscore and improve docs

Author: nhooyr

README.md

@@ -4,41 +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 are also confusing. 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. 
+
+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.
+
+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, "")

wscore/header.go renamed to header.go

@@ -1,17 +1,18 @@
-package wscore
+package ws
 
 import (
 	"io"
 )
 
-// Header represents a WebSocket frame header.
+// header represents a WebSocket frame header.
 // See https://tools.ietf.org/html/rfc6455#section-5.2
-type Header struct {
+// The fields are exported for easy printing for debugging.
+type header struct {
 	Fin    bool
 	Rsv1   bool
 	Rsv2   bool
 	Rsv3   bool
-	Opcode Opcode
+	Opcode opcode
 
 	PayloadLength int64
 
@@ -20,7 +21,7 @@ type Header struct {
 }
 
 // Bytes returns the bytes of the header.
-func (h Header) Bytes() []byte {
+func (h header) Bytes() []byte {
 	panic("TODO")
 }
 

wscore/mask.go renamed to mask.go

@@ -1,6 +1,6 @@
-package wscore
+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
@@ -10,6 +10,6 @@ package wscore
 //
 // For targets that do not support unsafe, please report an issue.
 // There is a mask by byte function below that will be used for such targets.
-func Mask(key [4]byte, pos int, p []byte) int {
+func mask(key [4]byte, pos int, p []byte) int {
 	panic("TODO")
 }

opcode.go

@@ -0,0 +1,17 @@
+package ws
+
+// opcode represents a WebSocket Opcode.
+//go:generate stringer -type=opcode
+type opcode int
+
+// opcode constants.
+const (
+	opContinuation opcode = iota
+	opText
+	opBinary
+	// 3 - 7 are reserved for further non-control frames.
+	opClose opcode = 8 + iota
+	opPing
+	opPong
+	// 11-16 are reserved for further control frames.
+)