zuplo 6.71.20 → 6.71.21

package/docs/handlers/websocket-handler.mdx

@@ -5,22 +5,35 @@ sidebar_label: WebSocket Handler
 
 :::note
 
-This is an Enterprise only feature at this time. Please contact us to trial this
-or sign up for an Enterprise account.
+WebSocket handlers are an Enterprise-only feature at this time. Please contact
+us to trial this or sign up for an Enterprise account.
 
 :::
 
-The WebSocket Handler enables you to manage WebSocket connections to your
-backend WebSocket APIs. It can be configured alongside other existing policies
-like [Rate Limiting](../policies/rate-limit-inbound.mdx),
-[API Keys](../policies/api-key-inbound.mdx), etc. and is available for use on
+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).
+
+Both handlers 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
 all environments.
 
-This handler is only configurable via the JSON View on a project's Route
+These handlers are only configurable via the JSON View on a project's Route
 Designer or directly in your project's `*.oas.json` file.
 
 ## Setup in `routes.oas.json`
 
+This section covers the passthrough `webSocketHandler`. To intercept messages,
+see the [WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx).
+
 Configuration of the WebSocket Handler is similar to other available handlers.
 Set the name of the path that your WebSocket API route will use, set the use of
 the `webSocketHandler` export from `@zuplo/runtime` module in the handler
@@ -62,6 +75,9 @@ 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
+  [WebSocket Pipeline Handler](./websocket-pipeline-handler.mdx).
 
 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

@@ -0,0 +1,189 @@
+---
+title: WebSocket Pipeline Handler
+sidebar_label: WebSocket Pipeline Handler
+---
+
+:::note
+
+The WebSocket Pipeline Handler is an Enterprise-only feature. Please contact us
+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.
+
+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.
+
+:::note
+
+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.
+
+:::
+
+## 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.
+
+```json
+"/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"
+  }
+}
+```
+
+:::caution{title="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](../policies/api-key-inbound.mdx)
+or [Rate Limiting](../policies/rate-limit-inbound.mdx) — that run once during
+the initial connection upgrade.
+
+:::
+
+The `rewritePattern` option behaves identically to the
+[WebSocket Handler](./websocket-handler.mdx#handler-options), including
+JavaScript string interpolation.
+
+## Writing a message policy
+
+A message policy is an exported function that matches the following signature:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+async function webSocketPolicy(
+  data: string,
+  target: WebSocket,
+  source: WebSocket,
+  request: ZuploRequest,
+  context: ZuploContext,
+): Promise<unknown>;
+```
+
+| Parameter | Description                                                                                                                                                                                                                                                             |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`    | The 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. |
+| `target`  | The destination socket the message is being forwarded to. For `inbound` this is the backend connection; for `outbound` it is the client connection.                                                                                                                     |
+| `source`  | The socket the message originated from. Call `source.send(...)` to send a message back to the originator, such as an acknowledgement or error.                                                                                                                          |
+| `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 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.
+
+```ts
+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.
+
+```ts
+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.

package/docs/mcp-gateway/cross-app-access/overview.mdx

@@ -10,9 +10,8 @@ description: |
 
 :::note{title="Beta"}
 
-Cross App Access support is in beta and builds on the
-[MCP Gateway](../introduction.mdx), which is also in beta. The configuration
-model and policy options may change before general availability.
+Cross App Access support is in beta. The configuration model and policy options
+may change before general availability.
 
 :::
 

package/docs/mcp-gateway/introduction.mdx

@@ -7,15 +7,6 @@ description:
   analytics.
 ---
 
-:::note{title="Beta"}
-
-The MCP Gateway is in beta. The configuration model and APIs may change before
-general availability. Build with it, share feedback — just pin a
-[compatibility date](./code-config/compatibility-dates.mdx) and expect the
-occasional rough edge.
-
-:::
-
 The Zuplo MCP Gateway fronts one or more remote
 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers with a
 single, OAuth-protected endpoint that AI clients connect to. Users sign in once

package/docs/policies/_index.md

@@ -99,6 +99,7 @@
 | sleep-inbound | Sleep / Delay | Add a delay to the incoming request. Useful for testing. | api-gateway |
 | stripe-webhook-verification-inbound | Stripe Webhook Auth | The Stripe Webhook policy validates the authenticity of an incoming Stripe webhook. | api-gateway |
 | supabase-jwt-auth-inbound | Supabase JWT Auth | The Supabase JWT Authentication policy supports user JWT tokens created by Supabase. | api-gateway |
+| traffic-splitting-inbound | Traffic Splitting | Splits traffic randomly across a set of weighted base paths. On each request one base path is selected (weighted by `weight`) and written to the request custom context at `customOutputProperty`. Reference it from a later URL Rewrite `rewritePattern` or URL Forward `baseUrl`, e.g. `${context.custom.trafficSplitting.basePath}`. | api-gateway |
 | transform-body-inbound | Transform Request Body | Transform the body of an incoming request. | api-gateway |
 | transform-body-outbound | Transform Response Body | Transform the body of an outgoing response. | api-gateway |
 | upstream-azure-ad-service-auth-inbound | Upstream Azure AD Service Auth | Uses Azure Active Directory to add an Authorization header to the request in order to authenticate requests using Azure identity. | api-gateway |

package/docs/policies/rate-limit-inbound/schema.json

@@ -96,14 +96,16 @@
             {
               "rateLimitBy": "ip",
               "requestsAllowed": 2,
-              "timeWindowMinutes": 1
+              "timeWindowMinutes": 1,
+              "mode": "async"
             },
             {
               "rateLimitBy": "function",
               "identifier": {
                 "export": "$import(./modules/my-module)",
                 "module": "default"
-              }
+              },
+              "mode": "async"
             }
           ]
         }
@@ -115,7 +117,8 @@
           "options": {
             "rateLimitBy": "ip",
             "requestsAllowed": 2,
-            "timeWindowMinutes": 1
+            "timeWindowMinutes": 1,
+            "mode": "async"
           }
         },
         {
@@ -126,7 +129,8 @@
             "identifier": {
               "export": "$import(./modules/my-module)",
               "module": "default"
-            }
+            },
+            "mode": "async"
           }
         }
       ]

package/docs/policies/traffic-splitting-inbound/doc.md

@@ -0,0 +1,67 @@
+On each request this policy selects one of the configured `basePaths` at random,
+weighted by each entry's `weight`. Weights are relative — they do not need to
+add up to 100. The selected URL is written to the request custom context at the
+path given by `customOutputProperty`.
+
+### Using the selected base path
+
+The selected URL is stored on `context.custom` and is intended to be consumed by
+a later handler on the same route. Reference it using the `customOutputProperty`
+path you configured. For example, with
+`"customOutputProperty": "trafficSplitting.basePath"`:
+
+```json
+// URL Rewrite handler
+{
+  "handler": {
+    "export": "urlRewriteHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rewritePattern": "${context.custom.trafficSplitting.basePath}/users/${params.id}"
+    }
+  }
+}
+```
+
+```json
+// URL Forward handler
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "${context.custom.trafficSplitting.basePath}"
+    }
+  }
+}
+```
+
+> The `redirect` handler's `location` is not interpolated — use the URL Rewrite
+> or URL Forward handler to route to the selected base path.
+
+### Only one value is in effect
+
+`customOutputProperty` resolves to a single value. If more than one Traffic
+Splitting policy on a route writes to the same property, the **last policy to
+run wins** — its selection is the one the handler sees. In practice you should
+configure a single Traffic Splitting policy per output property.
+
+### Environment variables
+
+Because each `url` is a string value, you can reference environment variables in
+it, including mixed strings:
+
+```json
+{
+  "basePaths": [
+    { "url": "$env(STABLE_BASE_URL)", "weight": 90 },
+    { "url": "$env(CANARY_BASE_URL)/v2", "weight": 10 }
+  ],
+  "customOutputProperty": "trafficSplitting.basePath"
+}
+```
+
+### Logging the selection
+
+Set `"logSelection": true` to log which base path was selected on each request.
+This is off by default.

package/docs/policies/traffic-splitting-inbound/intro.md

@@ -0,0 +1,5 @@
+The traffic splitting policy randomly distributes incoming requests across a set
+of weighted base paths. It selects one base path per request and writes it to
+the request custom context, where a URL Rewrite or URL Forward handler can use
+it to route the request. This is useful for blue/green rollouts, canary
+releases, or splitting traffic between backends.

package/docs/policies/traffic-splitting-inbound/schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/traffic-splitting-inbound.json",
+  "type": "object",
+  "title": "Traffic Splitting",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Splits traffic randomly across a set of weighted base paths. On each request one base path is selected (weighted by `weight`) and written to the request custom context at `customOutputProperty`. Reference it from a later URL Rewrite `rewritePattern` or URL Forward `baseUrl`, e.g. `${context.custom.trafficSplitting.basePath}`.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "TrafficSplittingInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "TrafficSplittingInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["basePaths", "customOutputProperty"],
+          "properties": {
+            "basePaths": {
+              "type": "array",
+              "description": "The set of base paths (URLs) to split traffic across. One entry is selected at random per request, weighted by its `weight`.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["url", "weight"],
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "examples": ["https://api-v1.example.com"],
+                    "description": "The base path (URL) to route to when this entry is selected. Supports environment variables, e.g. `$env(BASE_URL)/v2`."
+                  },
+                  "weight": {
+                    "type": "number",
+                    "minimum": 0,
+                    "examples": [80],
+                    "description": "The relative weight for this base path. Higher weights receive proportionally more traffic. Weights are relative and do not need to add up to 100."
+                  }
+                }
+              }
+            },
+            "customOutputProperty": {
+              "type": "string",
+              "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*(\\.[A-Za-z_$][A-Za-z0-9_$]*)*$",
+              "examples": ["trafficSplitting.basePath"],
+              "description": "A simple dotted property path under the request custom context where the selected URL is written (e.g. `trafficSplitting.basePath`). Reference it later in a URL Rewrite `rewritePattern` or URL Forward `baseUrl` as `${context.custom.trafficSplitting.basePath}`. Only one value is in effect; if multiple Traffic Splitting policies write the same property, the last one to run wins. Array indexes and brackets are not allowed."
+            },
+            "logSelection": {
+              "type": "boolean",
+              "default": false,
+              "x-show-example": false,
+              "description": "When `true`, logs which base path was selected for each request. Defaults to `false`."
+            }
+          },
+          "examples": [
+            {
+              "basePaths": [
+                {
+                  "url": "https://api-v1.example.com",
+                  "weight": 80
+                },
+                {
+                  "url": "https://api-v2.example.com",
+                  "weight": 15
+                },
+                {
+                  "url": "$env(CANARY_BASE_URL)",
+                  "weight": 5
+                }
+              ],
+              "customOutputProperty": "trafficSplitting.basePath",
+              "logSelection": true
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "export": "TrafficSplittingInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "basePaths": [
+              {
+                "url": "https://api-v1.example.com",
+                "weight": 80
+              },
+              {
+                "url": "https://api-v2.example.com",
+                "weight": 15
+              },
+              {
+                "url": "$env(CANARY_BASE_URL)",
+                "weight": 5
+              }
+            ],
+            "customOutputProperty": "trafficSplitting.basePath",
+            "logSelection": true
+          }
+        }
+      ]
+    }
+  }
+}

package/package.json

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