zuplo 6.73.21 → 6.73.23

package/docs/handlers/websocket-handler.mdx

@@ -10,20 +10,25 @@ us to trial this or sign up for an Enterprise account.
 
 :::
 
-Zuplo provides two handlers for proxying WebSocket connections to your backend
-WebSocket APIs:
-
-- **`webSocketHandler`** proxies WebSocket traffic straight through to your
-  backend without inspecting the messages. Use this when you only need to
-  authenticate, rate limit, or route the connection.
-- **`webSocketPipelineHandler`** does everything `webSocketHandler` does and
-  additionally runs every message through a policy pipeline, so you can inspect,
-  transform, or drop individual messages in either direction. See the
-  [WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx).
+:::caution{title="Deprecated"}
+
+`webSocketHandler` is deprecated. It's now an alias of
+[`webSocketPipelineHandler`](./websocket-pipeline-handler.mdx), which does
+everything this handler does — with no message policies configured it's the same
+transparent passthrough. Existing routes keep working unchanged; switch the
+handler `export` name to `webSocketPipelineHandler` when convenient.
+
+:::
+
+The WebSocket Handler proxies WebSocket traffic straight through to your backend
+without inspecting the messages. Use the
+[WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx) when you also
+want to intercept individual messages or run an
+[`onOpen` connection hook](./websocket-pipeline-handler.mdx#the-onopen-connection-hook).
 
-Both handlers can be configured alongside other existing policies like
+The handler can be configured alongside other existing policies like
 [Rate Limiting](../policies/rate-limit-inbound.mdx),
-[API Keys](../policies/api-key-inbound.mdx), etc. and are available for use on
+[API Keys](../policies/api-key-inbound.mdx), etc. and is available for use on
 all environments.
 
 These handlers are only configurable via the JSON View on a project's Route
@@ -75,9 +80,12 @@ The WebSocket Handler accepts the following options in the `options` property:
 - **`rewritePattern`** (required): The URL pattern for the backend WebSocket
   endpoint. Supports JavaScript string interpolation syntax for dynamic URL
   construction based on request data and environment variables.
-- **`policies`** (optional, `webSocketPipelineHandler` only): Configures the
-  message-interception policies that run on each WebSocket frame. See the
+- **`policies`** (optional): Configures the message-interception policies that
+  run on each WebSocket frame. See the
   [WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx).
+- **`onOpen`** (optional): Configures a connection hook that runs once per
+  connection, before any message is relayed. See
+  [the `onOpen` connection hook](./websocket-pipeline-handler.mdx#the-onopen-connection-hook).
 
 Similar to other handlers using `rewritePattern`, it supports JavaScript string
 interpolation syntax and can be used to shape the URL based on data from the

package/docs/handlers/websocket-pipeline-handler.mdx

@@ -10,12 +10,24 @@ to trial this or sign up for an Enterprise account.
 
 :::
 
-The `webSocketPipelineHandler` proxies WebSocket connections exactly like the
-[WebSocket Handler](./websocket-handler.mdx), but additionally passes every
-WebSocket message through a pipeline of **policy functions** before forwarding
-it. Each policy can inspect, transform, or drop the message. Use this to redact
-sensitive fields, enforce a message schema, filter events, or add observability
-to real-time traffic.
+The `webSocketPipelineHandler` is Zuplo's WebSocket handler. It proxies
+WebSocket connections to your backend and optionally lets you run code at two
+points in the connection's life:
+
+- **Message policies** pass every WebSocket message through a pipeline of
+  **policy functions** before forwarding it. Each policy can inspect, transform,
+  or drop the message. Use this to redact sensitive fields, enforce a message
+  schema, filter events, or add observability to real-time traffic.
+- **The [`onOpen` connection hook](#the-onopen-connection-hook)** runs once per
+  connection, after the connection to your backend is established and before any
+  message is relayed. Use it to gate connections, send a handshake message to
+  your backend, or attach your own connection lifecycle listeners (such as
+  `close`).
+
+With no policies and no `onOpen` hook configured, the handler is a transparent
+passthrough — this is what the deprecated
+[`webSocketHandler`](./websocket-handler.mdx) did, and it now resolves to this
+handler.
 
 Messages are intercepted in both directions, configured independently:
 
@@ -28,8 +40,10 @@ Messages are intercepted in both directions, configured independently:
 
 The pipeline only intercepts **message** events. Connection lifecycle events are
 handled automatically: when either side closes, the other side is closed, and
-socket errors are logged and forwarded. There is no policy hook for `close` or
-`error` events.
+socket errors are logged and the connection is torn down. There is no dedicated
+policy hook for `close` or `error` events — instead, use the
+[`onOpen` hook](#the-onopen-connection-hook) to attach your own listeners to
+either socket.
 
 :::
 
@@ -187,3 +201,126 @@ You can configure multiple policies in each direction to compose behavior — fo
 example, one policy to validate a message against a schema and a second to
 redact fields. Because each policy receives the previous policy's output, order
 matters.
+
+## The `onOpen` connection hook
+
+The `onOpen` option configures a function that runs **once per connection**,
+after both the client and backend connections are established and **before any
+message is relayed**. Unlike message policies, it isn't tied to a direction — it
+receives both sockets.
+
+Configure it at the `options` level, as a sibling of `rewritePattern` and
+`policies`. It works with or without message policies:
+
+```json
+"handler": {
+  "export": "webSocketPipelineHandler",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "rewritePattern": "https://myservice.com/websocket",
+    "onOpen": {
+      "module": "$import(./modules/websocket-hooks)",
+      "export": "onWebSocketOpen"
+    }
+  }
+}
+```
+
+The hook matches the `WebSocketOnOpenHook` type exported from `@zuplo/runtime` —
+the same parameters as a message policy, minus the message data:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+type WebSocketOnOpenHook = (
+  target: WebSocket,
+  source: WebSocket,
+  request: ZuploRequest,
+  context: ZuploContext,
+) => void | Promise<void>;
+```
+
+| Parameter | Description                                                                                       |
+| --------- | ------------------------------------------------------------------------------------------------- |
+| `target`  | The backend connection. Call `target.send(...)` to send a message to your backend.                |
+| `source`  | The client connection. Call `source.send(...)` to send a message to the client.                   |
+| `request` | The original [`ZuploRequest`](../programmable-api/zuplo-request.mdx) from the connection upgrade. |
+| `context` | The [`ZuploContext`](../programmable-api/zuplo-context.mdx) for the connection.                   |
+
+The hook is awaited, and its outcome controls the connection:
+
+- **Return (or resolve)** to accept the connection. Message relaying begins only
+  after the hook completes — messages that arrive while it runs are buffered and
+  delivered afterward, in order.
+- **Throw (or reject)** to abort the connection. Both sockets are closed and the
+  client never receives the `101 Switching Protocols` upgrade response.
+
+### Example: gate connections and greet the backend
+
+This hook rejects unauthenticated connections, then sends a handshake message to
+the backend before any client traffic flows.
+
+```ts
+import { WebSocketOnOpenHook } from "@zuplo/runtime";
+
+export const onWebSocketOpen: WebSocketOnOpenHook = async (
+  target,
+  source,
+  request,
+  context,
+) => {
+  if (!request.user) {
+    // Aborts the upgrade: both sockets close and no 101 is returned
+    throw new Error("Unauthenticated WebSocket connection");
+  }
+
+  // Runs before any client message is relayed to the backend
+  target.send(
+    JSON.stringify({ type: "session.start", user: request.user.sub }),
+  );
+};
+```
+
+### Example: react to the connection closing
+
+There is no separate `onClose` option — because `onOpen` hands you both raw
+sockets, attach a standard `close` event listener to either one. Listeners
+attached here live for the duration of the connection; there's no need to remove
+them.
+
+```ts
+import { WebSocketOnOpenHook } from "@zuplo/runtime";
+
+export const trackConnection: WebSocketOnOpenHook = (
+  target,
+  source,
+  request,
+  context,
+) => {
+  const connectedAt = Date.now();
+
+  // Fires when the client disconnects
+  source.addEventListener("close", () => {
+    const seconds = Math.round((Date.now() - connectedAt) / 1000);
+    context.log.info(`Client disconnected after ${seconds}s`);
+  });
+
+  // Fires when your backend closes the connection
+  target.addEventListener("close", () => {
+    context.log.warn("Backend closed the WebSocket connection");
+  });
+};
+```
+
+The same pattern works for `error` and `message` events. For a listener that
+should fire only once — such as waiting for a single handshake reply from your
+backend — pass `{ once: true }` as the third argument to `addEventListener`.
+
+:::tip{title="Performance"}
+
+With no message policies and no `onOpen` hook, the gateway hands the connection
+straight through to your backend and stays out of the per-message data path
+entirely. Configuring `onOpen` (or any message policy) keeps the gateway in the
+data path for that route, since the hook needs both live sockets to act on.
+
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.73.21",
+  "version": "6.73.23",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.73.21",
-    "@zuplo/core": "6.73.21",
-    "@zuplo/runtime": "6.73.21",
+    "@zuplo/cli": "6.73.23",
+    "@zuplo/core": "6.73.23",
+    "@zuplo/runtime": "6.73.23",
     "@zuplo/test": "1.4.0"
   }
 }