Handlers

WebSocket Pipeline Handler

Applies to
Gatewayruntime for API, AI, and MCP gateways
Hosting
Managed EdgeManaged DedicatedDiffersSelf-HostedDiffers
2 differences by hosting option
Managed Dedicated

The gateway opens the backend connection with the rewritePattern URL only. Headers from the client request and from route policies aren't sent to your backend, so pass any value the backend needs in the URL.

Self-Hosted

The gateway opens the backend connection with the rewritePattern URL only. Headers from the client request and from route policies aren't sent to your backend, so pass any value the backend needs in the URL.

The WebSocket Pipeline Handler is an Enterprise-only feature. Please contact us to trial this or sign up for an Enterprise account.

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 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 did, and it now resolves to this handler.

Messages are intercepted in both directions, configured independently:

  • inbound policies process messages traveling from the client to your backend.
  • outbound policies process messages traveling from your backend to the client.

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 the connection is torn down. There is no dedicated policy hook for close or error events — instead, use the onOpen hook to attach your own listeners to either socket.

Configuration

Use the webSocketPipelineHandler export and add an inbound and/or outbound array under options.policies. Each entry points to an exported function in one of your project's modules.

JSONCode
"/my-websocket": { "x-zuplo-path": { "pathMode": "open-api" }, "get": { "summary": "WebSocket route with message interception", "x-zuplo-route": { "corsPolicy": "none", "handler": { "export": "webSocketPipelineHandler", "module": "$import(@zuplo/runtime)", "options": { "rewritePattern": "https://myservice.com/websocket", "policies": { "inbound": [ { "module": "$import(./modules/websocket-policies)", "export": "redactInbound" } ], "outbound": [ { "module": "$import(./modules/websocket-policies)", "export": "filterOutbound" } ] } } }, "policies": { "inbound": [] } }, "operationId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e" } }

Two different policies blocks

The policies object inside handler.options configures the message policies that run on each WebSocket frame. This is separate from the route-level policies block (the inbound array next to handler), which configures the standard request policies — such as API Key or Rate Limiting — that run once during the initial connection upgrade.

The rewritePattern option behaves identically to the WebSocket Handler, including JavaScript string interpolation.

Writing a message policy

A message policy is an exported function that matches the following signature:

TypeScriptCode
import { ZuploContext, ZuploRequest } from "@zuplo/runtime"; async function webSocketPolicy( data: string, target: WebSocket, source: WebSocket, request: ZuploRequest, context: ZuploContext, ): Promise<unknown>;
ParameterDescription
dataThe message payload. For text protocols this is a string; binary frames arrive in the platform's binary form (for example, an ArrayBuffer). For an inbound policy this is the message from the client; for an outbound policy it is the message from the backend.
targetThe destination socket the message is being forwarded to. For inbound this is the backend connection; for outbound it is the client connection.
sourceThe socket the message originated from. Call source.send(...) to send a message back to the originator, such as an acknowledgement or error.
requestThe original ZuploRequest from the connection upgrade.
contextThe ZuploContext for the connection.

The return value controls what happens next:

  • Return the data (modified or unchanged) to forward it to target. When multiple policies are configured, the return value is passed as data to the next policy in the array.
  • Return undefined to drop the message. It is not forwarded, and no further policies run for that message.

Policies run in the order they appear in the inbound / outbound array, and each policy may be asynchronous. If a policy throws, Zuplo logs the error and drops the message.

Example: redact fields from inbound messages

This inbound policy parses each JSON message from the client, removes a sensitive field, and forwards the result to the backend.

TypeScriptCode
import { ZuploContext, ZuploRequest } from "@zuplo/runtime"; export async function redactInbound( data: string, target: WebSocket, source: WebSocket, request: ZuploRequest, context: ZuploContext, ) { let message: Record<string, unknown>; try { message = JSON.parse(data); } catch (err) { context.log.warn("Dropping non-JSON WebSocket message"); return undefined; // drop messages that aren't valid JSON } delete message.ssn; return JSON.stringify(message); }

Example: filter outbound messages

This outbound policy inspects messages from the backend and drops internal events so they never reach the client. Other messages pass through unchanged.

TypeScriptCode
import { ZuploContext, ZuploRequest } from "@zuplo/runtime"; export async function filterOutbound( data: string, target: WebSocket, source: WebSocket, request: ZuploRequest, context: ZuploContext, ) { const message = JSON.parse(data); if (message.type === "internal") { return undefined; // drop internal events; the client never sees them } return data; }

You can configure multiple policies in each direction to compose behavior — for 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.

Close the connection from a message policy

A message policy can end the session instead of forwarding a message. Call close() on the client socket and return undefined so the message isn't forwarded. When the client connection closes, the handler closes the backend connection too.

The client socket is source in an inbound policy and target in an outbound policy. Use a close code from 4000 to 4999, the range reserved for applications, or 1000 for a normal closure. Keep the reason to 123 bytes or fewer.

This inbound policy accepts only the message types it knows about and closes the connection on anything else:

TypeScriptCode
import { ZuploContext, ZuploRequest } from "@zuplo/runtime"; const ALLOWED_TYPES = new Set(["subscribe", "unsubscribe", "ping"]); export async function allowKnownMessages( data: string, target: WebSocket, source: WebSocket, request: ZuploRequest, context: ZuploContext, ) { let type: unknown; try { type = JSON.parse(data).type; } catch { type = undefined; } if (typeof type !== "string" || !ALLOWED_TYPES.has(type)) { context.log.warn("Closing WebSocket session", { type }); // `source` is the client in an inbound policy source.close(4003, "Message type not allowed"); return undefined; // don't forward the message } return data; }

To tell the client why before you close, call source.send(...) with an error message first.

Add headers to the backend connection

Applies to: Managed Edge only

The gateway opens the backend connection with the headers of the upgrade request after the route's inbound policies run. A policy that sets a header, such as the Set Headers policy, sets it on the backend connection. Use this to replace the client's credential with a backend credential that the client never sees.

For example, after an API Key policy authenticates the client, this Set Headers policy overwrites the client's Authorization header with a key stored in an environment variable:

JSONconfig/policies.json
{ "name": "set-backend-credential", "policyType": "set-headers-inbound", "handler": { "export": "SetHeadersInboundPolicy", "module": "$import(@zuplo/runtime)", "options": { "headers": [ { "name": "Authorization", "value": "Bearer $env(BACKEND_API_KEY)" } ] } } }

For a complete example, see Proxy the OpenAI Realtime API.

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:

JSONCode
"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:

TypeScriptCode
import { ZuploContext, ZuploRequest } from "@zuplo/runtime"; type WebSocketOnOpenHook = ( target: WebSocket, source: WebSocket, request: ZuploRequest, context: ZuploContext, ) => void | Promise<void>;
ParameterDescription
targetThe backend connection. Call target.send(...) to send a message to your backend.
sourceThe client connection. Call source.send(...) to send a message to the client.
requestThe original ZuploRequest from the connection upgrade.
contextThe ZuploContext 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.

TypeScriptCode
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.

TypeScriptCode
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.

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.

Last modified on