refactor: rename Serve → Handle (#69)

A quick rename, because this high level API could be used for either the
client or the server end of a websocket connection.

Author: mccutchen

autobahn_test.go

@@ -97,7 +97,7 @@ func TestAutobahn(t *testing.T) {
 				http.Error(w, err.Error(), http.StatusBadRequest)
 				return
 			}
-			_ = ws.Serve(r.Context(), websocket.EchoHandler)
+			_ = ws.Handle(r.Context(), websocket.EchoHandler)
 		}))
 		defer srv.Close()
 		targetURL = srv.URL

examples/benchserver/main.go

@@ -61,7 +61,7 @@ func main() {
 			logger.ErrorContext(r.Context(), "websocket handshake failed", "err", err)
 			return
 		}
-		ws.Serve(r.Context(), websocket.EchoHandler)
+		ws.Handle(r.Context(), websocket.EchoHandler)
 	})
 
 	// 3. JSON message test
@@ -82,7 +82,7 @@ func main() {
 			logger.ErrorContext(r.Context(), "websocket handshake failed", "err", err)
 			return
 		}
-		ws.Serve(r.Context(), func(_ context.Context, msg *websocket.Message) (*websocket.Message, error) {
+		ws.Handle(r.Context(), func(_ context.Context, msg *websocket.Message) (*websocket.Message, error) {
 			var m jsonMessage
 			if err := json.Unmarshal(msg.Payload, &m); err != nil {
 				return nil, err
@@ -111,7 +111,7 @@ func main() {
 			logger.ErrorContext(r.Context(), "websocket handshake failed", "err", err)
 			return
 		}
-		ws.Serve(r.Context(), func(_ context.Context, msg *websocket.Message) (*websocket.Message, error) {
+		ws.Handle(r.Context(), func(_ context.Context, msg *websocket.Message) (*websocket.Message, error) {
 			if len(msg.Payload) != 4 {
 				return nil, fmt.Errorf("invalid payload length: %d", len(msg.Payload))
 			}

examples/echoserver/main.go

@@ -49,7 +49,7 @@ func main() {
 			return
 		}
 		logger.InfoContext(r.Context(), "websocket handshake completed, starting echo handler", "client-key", ws.ClientKey())
-		ws.Serve(r.Context(), websocket.EchoHandler)
+		ws.Handle(r.Context(), websocket.EchoHandler)
 	})
 
 	if pprof {

websocket.go

@@ -291,27 +291,27 @@ func (ws *Websocket) writeFrame(frame *Frame) error {
 	return nil
 }
 
-// Serve is a high-level convienience method for request-response style
+// Handle is a high-level convienience method for request-response style
 // websocket connections, where the given [Handler] is called for each
 // incoming message read from the peer.
 //
 // If the handler returns a non-nil message, that message is written back
-// to the peer. Nil messages indicate that there is no reply and are skipped.
+// to the peer. A nil message indicates that there is no reply to send.
 //
 // If the handler returns a non-nil error, its message will be sent to the
 // client as the start of the two-way closing handshake with a status of
-// internal error. NOTE: This means errors returned by the handler should not
+// Internal Error. NOTE: This means errors returned by the handler should not
 // contain sensitive information that should not be exposed to peers.
 //
 // If there is an error reading from or writing to the underlying connection,
 // the connection is assumed to be unrecoverable and is closed immediately,
 // without waiting for the full two-way handshake. For more control over
 // error handling and closing behavior, use [ReadMessage], [WriteMessage], and
-// [Close] directly.
+// [CloseWithStatus] directly.
 //
 // See also [EchoHandler], a minimal handler that echoes each incoming message
 // verbatim.
-func (ws *Websocket) Serve(ctx context.Context, handler Handler) error {
+func (ws *Websocket) Handle(ctx context.Context, handler Handler) error {
 	for {
 		msg, err := ws.ReadMessage(ctx)
 		if err != nil {
@@ -497,7 +497,7 @@ func (ws *Websocket) ClientKey() ClientKey {
 }
 
 // Handler handles a single websocket [Message] as part of the high level
-// [Serve] request-response API.
+// [Handle] request-response API.
 //
 // If the returned message is non-nil, it will be sent to the client. If an
 // error is returned, the connection will be closed.

websocket_test.go

@@ -128,7 +128,7 @@ func TestHandshake(t *testing.T) {
 					http.Error(w, err.Error(), http.StatusBadRequest)
 					return
 				}
-				_ = ws.Serve(r.Context(), websocket.EchoHandler)
+				_ = ws.Handle(r.Context(), websocket.EchoHandler)
 			}))
 			defer srv.Close()
 
@@ -229,7 +229,7 @@ func TestConnectionLimits(t *testing.T) {
 			},
 			serverTest: func(t testing.TB, ws *websocket.Websocket, _ net.Conn) {
 				start := time.Now()
-				err := ws.Serve(t.Context(), websocket.EchoHandler)
+				err := ws.Handle(t.Context(), websocket.EchoHandler)
 				elapsed := time.Since(start)
 				assert.Equal(t, elapsed >= maxDuration, true, "not enough time passed")
 				assert.Error(t, err, os.ErrDeadlineExceeded)
@@ -374,7 +374,7 @@ func TestProtocolOkay(t *testing.T) {
 
 			// server just runs EchoHandler to reply to client
 			serverTest: func(t testing.TB, ws *websocket.Websocket, _ net.Conn) {
-				assert.NilError(t, ws.Serve(t.Context(), websocket.EchoHandler))
+				assert.NilError(t, ws.Handle(t.Context(), websocket.EchoHandler))
 			},
 		}.Run(t)
 	})
@@ -459,7 +459,7 @@ func TestProtocolOkay(t *testing.T) {
 
 			// server just echoes messages from the client
 			serverTest: func(t testing.TB, ws *websocket.Websocket, _ net.Conn) {
-				assert.NilError(t, ws.Serve(t.Context(), websocket.EchoHandler))
+				assert.NilError(t, ws.Handle(t.Context(), websocket.EchoHandler))
 			},
 		}.Run(t)
 	})
@@ -482,7 +482,7 @@ func TestProtocolOkay(t *testing.T) {
 			},
 			// server just echoes messages from the client
 			serverTest: func(t testing.TB, ws *websocket.Websocket, _ net.Conn) {
-				assert.NilError(t, ws.Serve(t.Context(), websocket.EchoHandler))
+				assert.NilError(t, ws.Handle(t.Context(), websocket.EchoHandler))
 			},
 		}.Run(t)
 	})
@@ -606,7 +606,7 @@ func TestProtocolErrors(t *testing.T) {
 				// protocol errors automatically
 				serverOpts: newOpts(t),
 				serverTest: func(t testing.TB, ws *websocket.Websocket, conn net.Conn) {
-					assert.Error(t, ws.Serve(t.Context(), websocket.EchoHandler), tc.wantCloseReason)
+					assert.Error(t, ws.Handle(t.Context(), websocket.EchoHandler), tc.wantCloseReason)
 				},
 			}.Run(t)
 		})
@@ -675,7 +675,7 @@ func TestCloseFrameValidation(t *testing.T) {
 				// server just runs echo handler, which should process all
 				// protocol errors automatically
 				serverTest: func(t testing.TB, ws *websocket.Websocket, conn net.Conn) {
-					assert.Error(t, ws.Serve(t.Context(), websocket.EchoHandler), tc.wantErr)
+					assert.Error(t, ws.Handle(t.Context(), websocket.EchoHandler), tc.wantErr)
 				},
 			}.Run(t)
 		})
@@ -916,7 +916,7 @@ func TestErrorHandling(t *testing.T) {
 				}
 			},
 			serverTest: func(t testing.TB, ws *websocket.Websocket, _ net.Conn) {
-				err := ws.Serve(t.Context(), websocket.EchoHandler)
+				err := ws.Handle(t.Context(), websocket.EchoHandler)
 				assert.Error(t, err, writeErr)
 			},
 		}.Run(t)
@@ -941,7 +941,7 @@ func TestErrorHandling(t *testing.T) {
 			// server tries to read message with the cancelable context, which
 			// should be canceled while waiting for the continuation frame.
 			serverTest: func(t testing.TB, ws *websocket.Websocket, _ net.Conn) {
-				assert.Error(t, ws.Serve(ctx, websocket.EchoHandler), context.Canceled)
+				assert.Error(t, ws.Handle(ctx, websocket.EchoHandler), context.Canceled)
 			},
 		}.Run(t)
 	})
@@ -1143,7 +1143,7 @@ func TestServeLoop(t *testing.T) {
 			// server runs Serve with a custom handler that returns an error
 			// when it receives a "fail" message
 			serverTest: func(t testing.TB, ws *websocket.Websocket, _ net.Conn) {
-				err := ws.Serve(t.Context(), func(ctx context.Context, msg *websocket.Message) (*websocket.Message, error) {
+				err := ws.Handle(t.Context(), func(ctx context.Context, msg *websocket.Message) (*websocket.Message, error) {
 					if bytes.Equal(msg.Payload, []byte("fail")) {
 						return nil, wantErr
 					}
@@ -1179,7 +1179,7 @@ func TestServeLoop(t *testing.T) {
 				}
 			},
 			serverTest: func(t testing.TB, ws *websocket.Websocket, conn net.Conn) {
-				err := ws.Serve(t.Context(), func(ctx context.Context, msg *websocket.Message) (*websocket.Message, error) {
+				err := ws.Handle(t.Context(), func(ctx context.Context, msg *websocket.Message) (*websocket.Message, error) {
 					return nil, appErr
 				})
 				// the error returned wraps both the application-level error
@@ -1566,7 +1566,7 @@ var (
 // ============================================================================
 // Examples
 // ============================================================================
-func ExampleServe() {
+func ExampleHandle() {
 	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		ws, err := websocket.Accept(w, r, websocket.Options{
 			ReadTimeout:    500 * time.Millisecond,
@@ -1578,10 +1578,10 @@ func ExampleServe() {
 			http.Error(w, err.Error(), http.StatusBadRequest)
 			return
 		}
-		if err := ws.Serve(r.Context(), websocket.EchoHandler); err != nil {
-			// an error returned by Serve is strictly informational; the
+		if err := ws.Handle(r.Context(), websocket.EchoHandler); err != nil {
+			// an error returned by Handle is strictly informational; the
 			// connection will already be closed at this point.
-			log.Printf("error serving websocket connection: %s", err)
+			log.Printf("error handling websocket connection: %s", err)
 		}
 	})
 	if err := http.ListenAndServe(":8080", handler); err != nil {