Merge pull request #37 from nhooyr/name-change

Rename ws to websocket and clean up API

Author: nhooyr

README.md

@@ -1,17 +1,17 @@
-# ws
+# websocket
 
-[![GoDoc](https://godoc.org/nhooyr.io/ws?status.svg)](https://godoc.org/nhooyr.io/ws)
-[![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)
+[![GoDoc](https://godoc.org/nhooyr.io/websocket?status.svg)](https://godoc.org/nhooyr.io/websocket)
+[![Codecov](https://img.shields.io/codecov/c/github/nhooyr/websocket.svg)](https://codecov.io/gh/nhooyr/websocket)
+[![GitHub release](https://img.shields.io/github/release/nhooyr/websocket.svg)](https://github.com/nhooyr/websocket/releases)
 
-ws is a minimal and idiomatic WebSocket library for Go.
+websocket is a minimal and idiomatic WebSocket library for Go.
 
 This library is in heavy development.
 
 ## Install
 
 ```bash
-go get nhooyr.io/ws@master
+go get nhooyr.io/websocket@master
 ```
 
 ## Features
@@ -20,10 +20,9 @@ go get nhooyr.io/ws@master
 - 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
+- Compression of text frames larger than 1024 bytes by default
 - Highly optimized
-- API will be ready for WebSockets over HTTP/2
+- API will transparently work with WebSockets over HTTP/2
 - WASM support
 
 ## Example
@@ -33,57 +32,65 @@ go get nhooyr.io/ws@master
 ```go
 func main() {
 	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		c, err := ws.Accept(w, r)
+		c, err := websocket.Accept(w, r,
+			websocket.AcceptSubprotocols("test"),
+		)
 		if err != nil {
 			log.Printf("server handshake failed: %v", err)
 			return
 		}
-		defer c.Close(ws.StatusInternalError, "")
+		defer c.Close(websocket.StatusInternalError, "")
 
 		ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
 		defer cancel()
 
-		err = wsjson.Write(ctx, c, map[string]interface{}{
+		v := map[string]interface{}{
 			"my_field": "foo",
-		})
+		}
+		err = websocket.WriteJSON(ctx, c, v)
 		if err != nil {
-			log.Printf("failed to write json struct: %v", err)
+			log.Printf("failed to write json: %v", err)
 			return
 		}
 
-		c.Close(ws.StatusNormalClosure, "")
+		log.Printf("wrote %v", v)
+
+		c.Close(websocket.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)
 	}
  }
 ```
 
+For a production quality example that shows off the low level API, see the [echo example](https://godoc.org/nhooyr.io/websocket#ex-Accept--Echo).
+
 ### Client
 
 ```go
 func main() {
 	ctx := context.Background()
-	ctx, cancel := context.WithTimeout(ctx, time.Minute)
+	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
 	defer cancel()
 
-	c, _, err := ws.Dial(ctx, "ws://localhost:8080")
+	c, _, err := websocket.Dial(ctx, "ws://localhost:8080",
+		websocket.DialSubprotocols("test"),
+	)
 	if err != nil {
 		log.Fatalf("failed to ws dial: %v", err)
 	}
-	defer c.Close(ws.StatusInternalError, "")
+	defer c.Close(websocket.StatusInternalError, "")
 
-	err = wsjson.Write(ctx, c, map[string]interface{}{
-		"my_field": "foo",
-	})
+	var v interface{}
+	err = websocket.ReadJSON(ctx, c, v)
 	if err != nil {
-		log.Fatalf("failed to write json struct: %v", err)
+		log.Fatalf("failed to read json: %v", err)
 	}
 
-	c.Close(ws.StatusNormalClosure, "")
+	log.Printf("received %v", v)
+
+	c.Close(websocket.StatusNormalClosure, "")
 }
 ```
 
@@ -111,10 +118,10 @@ https://github.com/gorilla/websocket
 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. Just compare the godoc of
-[nhooyr/ws](godoc.org/github.com/nhooyr/ws) side by side with
+[nhooyr/websocket](godoc.org/github.com/nhooyr/websocket) side by side with
 [gorilla/websocket](godoc.org/github.com/gorilla/websocket).
 
-The API for nhooyr/ws has been designed such that there is only one way to do things
+The API for nhooyr/websocket 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.
 
 ### x/net/websocket
@@ -134,8 +141,8 @@ 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.
+I could into nhooyr/websocket.
 
 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
+but for most users, the API provided by nhooyr/websocket will definitely fit better as it will
 be just as performant but much easier to use.

accept.go

@@ -1,4 +1,4 @@
-package ws
+package websocket
 
 import (
 	"fmt"
@@ -21,10 +21,11 @@ func AcceptSubprotocols(subprotocols ...string) AcceptOption {
 // AcceptOrigins lists the origins that Accept will accept.
 // Accept will always accept r.Host as the origin so you do not need to
 // specify that with this option.
+//
 // 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.
+// You can use a * to specify wildcards.
 func AcceptOrigins(origins ...string) AcceptOption {
 	panic("TODO")
 }
@@ -33,6 +34,7 @@ func AcceptOrigins(origins ...string) AcceptOption {
 // the connection to WebSocket.
 // Accept will reject the handshake if the Origin is not the same as the Host unless
 // InsecureAcceptOrigin is passed.
+// Accept uses w to write the handshake response so the timeouts on the http.Server apply.
 func Accept(w http.ResponseWriter, r *http.Request, opts ...AcceptOption) (*Conn, error) {
 	panic("TODO")
 }

datatype.go

@@ -1,4 +1,4 @@
-package ws
+package websocket
 
 // DataType represents the Opcode of a WebSocket data frame.
 //go:generate stringer -type=DataType

datatype_string.go

@@ -1,4 +1,4 @@
-package ws
+package websocket
 
 import (
 	"context"

dial.go

@@ -1,4 +1,4 @@
-// Package ws is a minimal and idiomatic implementation of the WebSocket protocol.
+// Package websocket 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
+// For now the docs are at https://github.com/nhooyr/websocket#websocket. I will move them here later.
+package websocket

doc.go

@@ -1,4 +1,4 @@
-package ws_test
+package websocket_test
 
 import (
 	"context"
@@ -9,20 +9,19 @@ import (
 
 	"golang.org/x/time/rate"
 
-	"nhooyr.io/ws"
-	"nhooyr.io/ws/wsjson"
+	"nhooyr.io/websocket"
 )
 
 func ExampleAccept_echo() {
 	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		c, err := ws.Accept(w, r,
-			ws.AcceptSubprotocols("echo"),
+		c, err := websocket.Accept(w, r,
+			websocket.AcceptSubprotocols("echo"),
 		)
 		if err != nil {
 			log.Printf("server handshake failed: %v", err)
 			return
 		}
-		defer c.Close(ws.StatusInternalError, "")
+		defer c.Close(websocket.StatusInternalError, "")
 
 		ctx := context.Background()
 
@@ -65,38 +64,46 @@ func ExampleAccept_echo() {
 			}
 		}
 	})
-	// For production deployments, use a net/http.Server configured
-	// with the appropriate timeouts.
-	err := http.ListenAndServe("localhost:8080", fn)
+
+	s := &http.Server{
+		Addr:         "localhost:8080",
+		Handler:      fn,
+		ReadTimeout:  time.Second * 15,
+		WriteTimeout: time.Second * 15,
+	}
+	err := s.ListenAndServe()
 	if err != nil {
 		log.Fatalf("failed to listen and serve: %v", err)
 	}
 }
 
 func ExampleAccept() {
 	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		c, err := ws.Accept(w, r)
+		c, err := websocket.Accept(w, r,
+			websocket.AcceptSubprotocols("test"),
+		)
 		if err != nil {
 			log.Printf("server handshake failed: %v", err)
 			return
 		}
-		defer c.Close(ws.StatusInternalError, "")
+		defer c.Close(websocket.StatusInternalError, "")
 
 		ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
 		defer cancel()
 
-		err = wsjson.Write(ctx, c, map[string]interface{}{
+		v := map[string]interface{}{
 			"my_field": "foo",
-		})
+		}
+		err = websocket.WriteJSON(ctx, c, v)
 		if err != nil {
-			log.Printf("failed to write json struct: %v", err)
+			log.Printf("failed to write json: %v", err)
 			return
 		}
 
-		c.Close(ws.StatusNormalClosure, "")
+		log.Printf("wrote %v", v)
+
+		c.Close(websocket.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)
@@ -108,18 +115,21 @@ func ExampleDial() {
 	ctx, cancel := context.WithTimeout(ctx, time.Minute)
 	defer cancel()
 
-	c, _, err := ws.Dial(ctx, "ws://localhost:8080")
+	c, _, err := websocket.Dial(ctx, "ws://localhost:8080",
+		websocket.DialSubprotocols("test"),
+	)
 	if err != nil {
 		log.Fatalf("failed to ws dial: %v", err)
 	}
-	defer c.Close(ws.StatusInternalError, "")
+	defer c.Close(websocket.StatusInternalError, "")
 
-	err = wsjson.Write(ctx, c, map[string]interface{}{
-		"my_field": "foo",
-	})
+	var v interface{}
+	err = websocket.ReadJSON(ctx, c, v)
 	if err != nil {
-		log.Fatalf("failed to write json struct: %v", err)
+		log.Fatalf("failed to read json: %v", err)
 	}
 
-	c.Close(ws.StatusNormalClosure, "")
+	log.Printf("received %v", v)
+
+	c.Close(websocket.StatusNormalClosure, "")
 }

example_test.go

@@ -1,9 +1,8 @@
-module nhooyr.io/ws
+module nhooyr.io/websocket
 
 go 1.12
 
 require (
-	github.com/golang/protobuf v1.3.1
 	github.com/kr/pretty v0.1.0 // indirect
 	go.coder.com/go-tools v0.0.0-20190317003359-0c6a35b74a16
 	golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3

go.mod

@@ -1,5 +1,3 @@
-github.com/golang/protobuf v1.3.1 h1:YF8+flBXS5eO826T4nzqPrxfhQThhXl0YzfuUPu4SBg=
-github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=

go.sum

@@ -1,4 +1,4 @@
-package ws
+package websocket
 
 import (
 	"io"