@zuplo/cli 6.73.21 → 6.73.22

package/node_modules/@zuplo/runtime/out/types/index.d.ts

@@ -15687,65 +15687,92 @@ declare interface WebSearchTool {
 }
 
 /**
- * Handler that proxies WebSocket connections to a different URL.
- * Enables WebSocket support in your API gateway for real-time communication.
+ * Proxies WebSocket connections to an upstream URL.
  *
- * @param request - The incoming ZuploRequest with WebSocket upgrade headers
- * @param context - The ZuploContext
- * @returns A WebSocket upgrade Response (101 Switching Protocols)
+ * @deprecated Use {@link webSocketPipelineHandler} instead. `webSocketHandler`
+ * is retained as a backwards-compatible alias and resolves to the exact same
+ * handler — with no inbound/outbound message policies configured it is a
+ * transparent passthrough, so existing routes keep working unchanged. Because
+ * it is the same function, routes using this name report
+ * `zuplo.handler.type = "websocket-pipeline"`.
+ * @public
+ */
+export declare const webSocketHandler: typeof webSocketPipelineHandler;
+
+/**
+ * A WebSocket connection-level hook, invoked once when the connection opens.
  *
- * @beta
- * @example
- * ```json
- * // routes.oas.json - WebSocket endpoint
- * {
- *   "paths": {
- *     "/ws/chat": {
- *       "x-zuplo-route": {
- *         "handler": {
- *           "export": "webSocketHandler",
- *           "module": "$import(@zuplo/runtime)",
- *           "options": {
- *             "rewritePattern": "wss://chat-backend.example.com/ws"
- *           }
- *         }
- *       }
- *     }
- *   }
- * }
- * ```
+ * Mirrors {@link WebSocketPolicyFunction} without the per-message `data`
+ * argument. It runs after both the client and upstream legs are established and
+ * before any frame is relayed. Throwing (or returning a rejected promise)
+ * aborts the connection: both sockets are closed and no `101 Switching
+ * Protocols` response is returned to the caller.
+ *
+ * @param target - The upstream socket (gateway to origin).
+ * @param source - The client-facing socket (gateway to caller).
+ * @param request - The {@link ZuploRequest} that initiated the upgrade.
+ * @param context - The {@link ZuploContext}.
+ *
+ * @remarks
+ * Configuring `onOpen` opts the connection out of the zero-overhead Cloudflare
+ * passthrough splice: the worker stays in the data path so the hook has both
+ * live sockets to act on. If you need connection-level `close`/`error`/`message`
+ * handling, attach your own listeners to either socket from within the hook.
+ *
+ * @public
+ */
+export declare type WebSocketOnOpenHook = (
+  target: WebSocket,
+  source: WebSocket,
+  request: ZuploRequest,
+  context: ZuploContext
+) => void | Promise<void>;
+
+/**
+ * Handle WebSocket requests by proxying them to a different URL, optionally
+ * running inbound/outbound message policies and/or a connection-level `onOpen`
+ * hook.
+ *
+ * When no intercept policies are configured the handler behaves like the plain
+ * `webSocketHandler`: messages are forwarded verbatim and, on Cloudflare,
+ * the upstream socket is spliced directly to the client so the worker stays out
+ * of the per-message data path. The worker only sits in the message path (and
+ * policies are only wired up) when at least one inbound or outbound policy is
+ * configured.
+ *
+ * The optional `onOpen` hook (see {@link WebSocketOnOpenHook}) runs once after
+ * both legs are established and before any frame is relayed. Because it needs
+ * both live sockets, configuring it keeps the worker in the data path (the
+ * Cloudflare splice is skipped). Throwing from the hook aborts the connection.
  *
  * @example
+ * A route that runs an `onOpen` hook and an inbound message policy. `onOpen`
+ * is declared at the `options` level, a sibling of `policies`:
  * ```json
- * // Dynamic WebSocket routing based on path parameters
  * {
- *   "paths": {
- *     "/ws/{room}": {
- *       "x-zuplo-route": {
- *         "handler": {
- *           "export": "webSocketHandler",
- *           "module": "$import(@zuplo/runtime)",
- *           "options": {
- *             "rewritePattern": "wss://chat.example.com/rooms/${params.room}"
- *           }
- *         }
+ *   "handler": {
+ *     "export": "webSocketPipelineHandler",
+ *     "module": "$import(@zuplo/runtime)",
+ *     "options": {
+ *       "rewritePattern": "https://example.com/socket",
+ *       "onOpen": {
+ *         "export": "onWebSocketOpen",
+ *         "module": "$import(./modules/ws-onopen)"
+ *       },
+ *       "policies": {
+ *         "inbound": [
+ *           { "export": "authFrame", "module": "$import(./modules/ws-auth)" }
+ *         ]
  *       }
  *     }
  *   }
  * }
  * ```
- */
-export declare function webSocketHandler(
-  request: ZuploRequest,
-  context: ZuploContext
-): Promise<Response>;
-
-/**
- * Handle websocket requests to a different url
+ *
  * @param request - The ZuploRequest
  * @param context - The ZuploContext
- * @returns
- * @beta
+ * @returns A WebSocket upgrade Response (101 Switching Protocols)
+ * @public
  */
 export declare function webSocketPipelineHandler(
   request: ZuploRequest,

package/node_modules/@zuplo/runtime/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zuplo/runtime",
   "type": "module",
-  "version": "6.73.21",
+  "version": "6.73.22",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuplo/cli",
-  "version": "6.73.21",
+  "version": "6.73.22",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "type": "module",
@@ -27,10 +27,10 @@
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/api-logs": "0.220.0",
     "@swc/core": "1.10.18",
-    "@zuplo/core": "6.73.21",
+    "@zuplo/core": "6.73.22",
     "@zuplo/editor": "1.0.29844086763",
-    "@zuplo/openapi-tools": "6.73.21",
-    "@zuplo/runtime": "6.73.21",
+    "@zuplo/openapi-tools": "6.73.22",
+    "@zuplo/runtime": "6.73.22",
     "chalk": "5.4.1",
     "chokidar": "3.5.3",
     "cookie": "1.0.2",
@@ -61,8 +61,8 @@
     "workerd": "1.20241230.0",
     "yargs": "17.7.2",
     "zod": "3.25.76",
-    "@zuplo/graphql": "6.73.21",
-    "@zuplo/otel": "6.73.21"
+    "@zuplo/graphql": "6.73.22",
+    "@zuplo/otel": "6.73.22"
   },
   "bundleDependencies": [
     "@inquirer/prompts",