Add stubs

Closes #26

Author: nhooyr

.github/fmt/entrypoint.sh

@@ -2,25 +2,17 @@
 
 source .github/lib.sh
 
-if [[ $(gofmt -l -s .) != "" ]]; then
-	echo "files are not formatted correctly"
-	echo "please run:"
-	echo "gofmt -w -s ."
-	exit 1
-fi
+gofmt -w -s .
+go run go.coder.com/go-tools/cmd/goimports -w "-local=$(go list -m)" .
+go run mvdan.cc/sh/cmd/shfmt -w -s -sr .
 
-out=$(go run golang.org/x/tools/cmd/goimports -l -local=nhooyr.io/ws .)
-if [[ $out != "" ]]; then
-	echo "imports are not formatted correctly"
-	echo "please run:"
-	echo "goimports -w -local=nhooyr.io/ws ."
-	exit 1
-fi
-
-out=$(go run mvdan.cc/sh/cmd/shfmt -l -s -sr .)
-if [[ $out != "" ]]; then
-	echo "shell scripts are not formatted correctly"
+if [[ $CI ]] && unstaged_files; then
+	set +x
+	echo
+	echo "files are not formatted correctly"
 	echo "please run:"
-	echo "shfmt -w -s -sr ."
+	echo "./test.sh"
+	echo
+	git status
 	exit 1
 fi

.github/lib.sh

@@ -3,4 +3,17 @@
 set -euxo pipefail
 
 export GO111MODULE=on
-export GOFLAGS=-mod=readonly
+export PAGER=cat
+
+# shellcheck disable=SC2034
+# CI is used by the scripts that source this file.
+CI=${GITHUB_ACTION-}
+
+if [[ $CI ]]; then
+	export GOFLAGS=-mod=readonly
+fi
+
+function unstaged_files() {
+	[[ $(git ls-files --other --modified --exclude-standard) != "" ]]
+}
+

.github/test/entrypoint.sh

@@ -2,36 +2,38 @@
 
 source .github/lib.sh
 
-function gomod_help() {
+# Unfortunately, this is the only way to ensure go.mod and go.sum are correct.
+# See https://github.com/golang/go/issues/27005
+go list ./... > /dev/null
+go mod tidy
+
+go install golang.org/x/tools/cmd/stringer
+go generate ./...
+
+if [[ $CI ]] && unstaged_files; then
+	set +x
 	echo
-	echo "you may need to update go.mod/go.sum via:"
-	echo "go list all > /dev/null"
-	echo "go mod tidy"
+	echo "generated code needs an update"
+	echo "please run:"
+	echo "./test.sh"
 	echo
-	echo "or git add files to staging"
+	git status
 	exit 1
-}
-
-go list ./... > /dev/null || gomod_help
-go mod tidy
-
-# Until https://github.com/golang/go/issues/27005 the previous command can actually modify go.sum so we need to ensure its not changed.
-if [[ $(git diff --name-only) != "" ]]; then
-	git diff
-	gomod_help
 fi
 
-mapfile -t scripts <<< "$(find . -type f -name "*.sh")"
-shellcheck "${scripts[@]}"
+(
+	shopt -s globstar nullglob dotglob
+	shellcheck ./**/*.sh
+)
 
 go vet -composites=false ./...
 
-go test -race -v -coverprofile=coverage.out -vet=off ./...
+COVERAGE_PROFILE=$(mktemp)
+go test -race -v "-coverprofile=${COVERAGE_PROFILE}" -vet=off ./...
+go tool cover "-func=${COVERAGE_PROFILE}"
 
-if [[ -z ${GITHUB_ACTION-} ]]; then
-	go tool cover -html=coverage.out
-else
+if [[ $CI ]]; then
 	bash <(curl -s https://codecov.io/bash)
+else
+	go tool cover "-html=${COVERAGE_PROFILE}" -o=coverage.html
 fi
-
-rm coverage.out

.gitignore

@@ -0,0 +1 @@
+coverage.html

accept.go

@@ -0,0 +1,37 @@
+package ws
+
+import (
+	"fmt"
+	"net/http"
+)
+
+// AcceptOption is an option that can be passed to Accept.
+type AcceptOption interface {
+	acceptOption()
+	fmt.Stringer
+}
+
+// AcceptSubprotocols list the subprotocols that Accept will negotiate with a client.
+// The first protocol that a client supports will be negotiated.
+// Pass "" as a subprotocol if you would like to allow the default protocol.
+func AcceptSubprotocols(subprotocols ...string) AcceptOption {
+	panic("TODO")
+}
+
+// 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
+func AcceptOrigins(origins ...string) AcceptOption {
+	panic("TODO")
+}
+
+// Accept accepts a WebSocket handshake from a client and upgrades the
+// the connection to WebSocket.
+// Accept will reject the handshake if the Origin is not the same as the Host unless
+// InsecureAcceptOrigin is passed.
+func Accept(w http.ResponseWriter, r *http.Request, opts ...AcceptOption) (*Conn, error) {
+	panic("TODO")
+}

dataframe.go

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

dataframe_string.go

@@ -0,0 +1,41 @@
+package ws
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"net/http"
+)
+
+// DialOption represents a dial option that can be passed to Dial.
+type DialOption interface {
+	dialOption()
+	fmt.Stringer
+}
+
+// DialHTTPClient is the http client used for the handshake.
+// Its Transport must use HTTP/1.1 and must return writable bodies
+// for WebSocket handshakes.
+// http.Transport does this correctly.
+func DialHTTPClient(h *http.Client) DialOption {
+	panic("TODO")
+}
+
+// DialHeader are the HTTP headers included in the handshake request.
+func DialHeader(h http.Header) DialOption {
+	panic("TODO")
+}
+
+// DialSubprotocols accepts a slice of protcols to include in the Sec-WebSocket-Protocol header.
+func DialSubprotocols(subprotocols ...string) DialOption {
+	panic("TODO")
+}
+
+// We use this key for all client requests as the Sec-WebSocket-Key header is useless.
+// See https://stackoverflow.com/a/37074398/4283659.
+var secWebSocketKey = base64.StdEncoding.EncodeToString(make([]byte, 16))
+
+// 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")
+}

dial.go

@@ -0,0 +1,2 @@
+// Package ws implements the WebSocket protocol defined in RFC 6455.
+package ws

doc.go

@@ -0,0 +1,130 @@
+package ws_test
+
+import (
+	"context"
+	"io"
+	"log"
+	"net/http"
+	"time"
+
+	"golang.org/x/time/rate"
+	"nhooyr.io/ws"
+	"nhooyr.io/ws/wsjson"
+)
+
+func ExampleEcho() {
+	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 := context.Background()
+
+		echo := func() error {
+			ctx, cancel := context.WithTimeout(ctx, time.Minute)
+			defer cancel()
+
+			typ, r, err := c.ReadMessage(ctx)
+			if err != nil {
+				return err
+			}
+
+			ctx, cancel = context.WithTimeout(ctx, time.Second*10)
+			defer cancel()
+
+			r.SetContext(ctx)
+			r.Limit(32768)
+
+			w := c.MessageWriter(ctx, typ)
+			_, err = io.Copy(w, r)
+			if err != nil {
+				return err
+			}
+
+			err = w.Close()
+			if err != nil {
+				return err
+			}
+
+			return nil
+		}
+
+		l := rate.NewLimiter(rate.Every(time.Millisecond*100), 10)
+		for l.Allow() {
+			err := echo()
+			if err != nil {
+				log.Printf("failed to read message: %v", err)
+				return
+			}
+		}
+	})
+	// 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)
+	}
+}
+
+func ExampleAccept() {
+	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, "")
+
+		type myJsonStruct struct {
+			MyField string `json:"my_field"`
+		}
+		err = wsjson.Write(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)
+	}
+}
+
+func ExampleDial() {
+	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)
+		return
+	}
+	defer c.Close(ws.StatusInternalError, "")
+
+	type myJsonStruct struct {
+		MyField string `json:"my_field"`
+	}
+	err = wsjson.Write(c, myJsonStruct{
+		MyField: "foo",
+	})
+	if err != nil {
+		log.Fatalf("failed to write json struct: %v", err)
+		return
+	}
+
+	c.Close(ws.StatusNormalClosure, "")
+}