zuplo 6.67.32 → 6.68.0

package/docs/handlers/websocket-handler.mdx

@@ -0,0 +1,154 @@
+---
+title: WebSocket Handler
+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.
+
+:::
+
+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
+all environments.
+
+This handler is currently in beta and 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`
+
+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
+configuration and use the `rewritePattern` property inside of `options` to point
+to your service's WebSocket API endpoint.
+
+Your configuration will look like below:
+
+```json
+"/my-websocket": {
+  "x-zuplo-path": {
+  "pathMode": "open-api"
+  },
+  "get": {
+  "summary": "Zuplo websocket route to internal API",
+  "description": "Zuplo websocket route to internal API",
+  "x-zuplo-route": {
+    "corsPolicy": "none",
+    "handler": {
+      "export": "webSocketHandler",
+      "module": "$import(@zuplo/runtime)",
+      "options": {
+        "rewritePattern": "https://myservice.com/websocket",
+      }
+    },
+    "policies": {
+      "inbound": []
+    }
+  },
+  "operationId": "8115f88e-b561-4248-b317-0e256e9d6b6a"
+  }
+},
+```
+
+## Handler Options
+
+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.
+
+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
+incoming request and environment variables defined in the project.
+
+```txt
+https://${env.BASE_HOST_NAME}/${method}/${params.productId}
+```
+
+The following objects are available for substitution:
+
+- `env` - the environment object, to access
+  [Environment Variables](../articles/environment-variables.mdx)
+- `request: ZuploRequest` - the full
+  [`ZuploRequest`](../programmable-api/zuplo-request.mdx) object
+- `context: ZuploContext` - the
+  [`ZuploContext`](../programmable-api/zuplo-context.mdx) object without
+  functions.
+- `params: Record<string, string>` - The parameters of the route. For example,
+  `params.productId` would be the value of `:productId` in a route.
+- `query: Record<string, string>` - The query parameters of the route. For
+  example, `query.filterBy` would be the value of `?filterBy=VALUE`.
+- `headers: Headers` - the incoming request's
+  [headers object](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+- `url: string` - The full incoming request as a string
+- `host: string` - The
+  [`host`](https://developer.mozilla.org/en-US/docs/Web/API/URL/host) portion of
+  the incoming URL
+- `hostname: string` - The
+  [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hostname)
+  portion of the incoming URL
+- `pathname: string` - The
+  [`pathname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname)
+  portion of the incoming URL
+- `port: string` - The
+  [`port`](https://developer.mozilla.org/en-US/docs/Web/API/URL/port) portion of
+  the incoming URL
+- `search` - The
+  [`search`](https://developer.mozilla.org/en-US/docs/Web/API/URL/search)
+  portion of the incoming URL
+
+Use the following methods to encode portions of the URL:
+
+- `encodeURIComponent`: The
+  [`encodeURIComponent()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
+  function encodes a URI by replacing each instance of certain characters with
+  escape sequences.
+- `e`: An alias to `encodeURIComponent` to help keep URLs more readable. Can be
+  used like `${e(params.productId)}`
+
+### Example Values
+
+A few examples of the values of various substitutions.
+
+- `${headers.get("content-type")}` - `"application/json"`
+- `${host}` - `"example.com:8080"`
+- `${hostname}` - `"example.com"`
+- `${method}` - `"GET"`
+- `${origin}` - `"https://example.com"`
+- `${params.productId}` - `":productId"`
+- `${pathname}` - `"/v1/products/:productId"`
+- `${port}` - `"8080"`
+- `${protocol}` - `"https:"`
+- `${query.category}` - `"cars"`
+- `${search}` - `"?category=cars"`
+- `${url}` - `"https://example.com:8080/v1/products/:productId?category=cars"`
+- `${env.BASE_URL}` - `"https://example.com"`
+
+## Different Backends per Environment
+
+It's common to want to use different backends for your production, staging and
+preview environments. This can be achieved by using
+[environment variables](../articles/environment-variables.mdx) to specify the
+origin of the backend.
+
+For example,
+
+```js
+${env.BASE_PATH}
+```
+
+Using the `rewritePattern` in `options` you can combine the `BASE_PATH`
+environment variable, say `https://example.com` to achieve this.
+
+```txt
+https://${env.BASE_PATH}/foo/bar
+
+// Runtime value is
+https://example.com/foo/bar
+```

package/docs/home.mdx

@@ -0,0 +1,6 @@
+---
+title: Zuplo Documentation
+sidebar_label: Home
+---
+
+<DocsHome />

package/docs/managed-edge/overview.md

@@ -0,0 +1,78 @@
+---
+title: Zuplo Managed Edge
+sidebar_label: Overview
+---
+
+Zuplo Managed Edge is a serverless deployment model where your Zuplo projects
+run at the edge across 300+ data centers worldwide. This is the most popular
+hosting option and the default choice for all Zuplo projects. Managed Edge
+provides automatic scaling, global distribution, and enterprise-grade
+performance without requiring any infrastructure management.
+
+Managed Edge hosting is the right choice for you if you:
+
+- Want the simplest deployment experience with zero infrastructure management
+- Need global distribution and low-latency performance for users worldwide
+- Require automatic scaling to handle traffic spikes and high request volumes
+- Are using Zuplo's self-serve product or need a fully-managed solution
+- Want deployments that go live globally in under 20 seconds
+
+## Features
+
+The managed edge hosting model provides all of Zuplo's standard features and
+capabilities. You can use all the same policies, integrations, and features as
+you would with other deployment models.
+
+### Global Edge Network
+
+Zuplo's edge-first architecture provides:
+
+- **Built-in redundancy and high availability** - Your API is automatically
+  distributed across hundreds of data centers worldwide
+- **Low-latency performance** - Requests are typically served within 50ms of
+  most users, thanks to edge locations close to your customers
+- **Automatic failover** - If one edge location experiences issues, traffic is
+  automatically routed to the nearest available location
+
+### Performance and Scale
+
+Managed Edge hosting is designed to handle:
+
+- **Billions of requests per month** - Proven at enterprise scale with some of
+  the world's largest API deployments
+- **Millions of requests per second** - Automatic scaling handles traffic spikes
+  effortlessly
+- **Serverless architecture** - No need to provision or manage servers; Zuplo
+  handles all infrastructure automatically
+
+### Security
+
+Enterprise customers on managed edge deployments can leverage:
+
+- **Zuplo Managed WAF** - Enterprise-grade protection with OWASP Core Ruleset,
+  OFAC sanctions compliance, DDoS protection, and custom rule capabilities
+- **Edge-deployed security** - Security rules run at the same edge locations as
+  your API, ensuring no additional latency
+- **Automatic updates** - Protection rules are continuously updated without
+  requiring deployments
+
+### Developer Experience
+
+- **Fast deployments** - Changes go live globally in under 20 seconds
+- **GitOps workflows** - Everything is defined through code and stored in source
+  control
+- **Unlimited environments** - Create as many environments as you need for
+  development, staging, and production
+- **Working Copy environments** - Develop and test changes directly in the Zuplo
+  portal before deploying
+
+## Getting Started
+
+Managed Edge is the default hosting option for all Zuplo projects. When you
+create a new project, it will automatically be configured for managed edge
+deployment. You can start building your API immediately—no additional
+configuration is required.
+
+For more information about getting started with Zuplo, see the
+[API Management introduction](/docs/api-management/introduction) or
+[sign up](https://portal.zuplo.com/signup?utm_source=docs) for free.

package/docs/mcp-server/configuration-migration-guide.mdx

@@ -0,0 +1,344 @@
+---
+title: MCP Server Configuration Migration Guide
+sidebar_label: Configuration Migration Guide
+---
+
+This guide explains how to migrate from the deprecated MCP server configuration
+syntax to the new consolidated format introduced in November 2025.
+
+## What Changed
+
+The new configuration consolidates and simplifies MCP server setup:
+
+**Handler Options:**
+
+- ✅ **New**: `operations` array with simple `{ file, id }` references
+- ❌ **Deprecated**: `files`, `tools`, `prompts`, `resources` arrays
+
+**Operation Extensions:**
+
+- ✅ **New**: Single `x-zuplo-route.mcp` extension with `type` field
+- ❌ **Deprecated**: Separate `x-zuplo-mcp-tool`, `x-zuplo-mcp-prompt`,
+  `x-zuplo-mcp-resource`, `x-zuplo-mcp-graphql` extensions
+
+## Migration Steps
+
+### Step 1: Update Handler Options
+
+**Old Syntax:**
+
+```json
+{
+  "handler": {
+    "export": "mcpServerHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "name": "my MCP server",
+      "version": "0.0.0",
+      "files": [
+        {
+          "path": "./config/routes.oas.json",
+          "operationIds": ["list-users", "create-user"]
+        }
+      ],
+      "prompts": [
+        {
+          "path": "./config/routes.oas.json",
+          "operationIds": ["greeting"]
+        }
+      ],
+      "resources": [
+        {
+          "path": "./config/routes.oas.json",
+          "operationIds": ["html"]
+        }
+      ]
+    }
+  }
+}
+```
+
+**New Syntax:**
+
+```json
+{
+  "handler": {
+    "export": "mcpServerHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "name": "my MCP server",
+      "version": "0.0.0",
+      "operations": [
+        { "file": "./config/routes.oas.json", "id": "list-users" },
+        { "file": "./config/routes.oas.json", "id": "create-user" },
+        { "file": "./config/routes.oas.json", "id": "greeting" },
+        { "file": "./config/routes.oas.json", "id": "html" }
+      ]
+    }
+  }
+}
+```
+
+:::note
+
+All operations (tools, prompts, resources) now go into a single `operations`
+array. The type is determined by the `x-zuplo-route.mcp.type` field on each
+operation.
+
+:::
+
+### Step 2: Update Operation Extensions
+
+### Tools
+
+**Old Syntax:**
+
+```json
+{
+  "paths": {
+    "/users": {
+      "get": {
+        "operationId": "list-users",
+        "summary": "List all users",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)"
+          }
+        },
+        "x-zuplo-mcp-tool": {
+          "name": "get_all_users",
+          "description": "Use this tool to retrieve a list of all registered users"
+        }
+      }
+    }
+  }
+}
+```
+
+**New Syntax:**
+
+```json
+{
+  "paths": {
+    "/users": {
+      "get": {
+        "operationId": "list-users",
+        "summary": "List all users",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)"
+          },
+          "mcp": {
+            "type": "tool",
+            "name": "get_all_users",
+            "description": "Use this tool to retrieve a list of all registered users"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Prompts
+
+**Old Syntax:**
+
+```json
+{
+  "paths": {
+    "/greeting": {
+      "post": {
+        "operationId": "greeting",
+        "summary": "Generate a greeting message",
+        "x-zuplo-mcp-prompt": {
+          "name": "greeting_generator",
+          "description": "Generate a personalized greeting message"
+        }
+      }
+    }
+  }
+}
+```
+
+**New Syntax:**
+
+```json
+{
+  "paths": {
+    "/greeting": {
+      "post": {
+        "operationId": "greeting",
+        "summary": "Generate a greeting message",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)"
+          },
+          "mcp": {
+            "type": "prompt",
+            "name": "greeting_generator",
+            "description": "Generate a personalized greeting message"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Resources
+
+**Old Syntax:**
+
+```json
+{
+  "paths": {
+    "/html": {
+      "get": {
+        "operationId": "html",
+        "summary": "HTML document",
+        "x-zuplo-mcp-resource": {
+          "name": "html_doc",
+          "description": "An HTML document resource",
+          "uri": "ui://html",
+          "mimeType": "text/html"
+        }
+      }
+    }
+  }
+}
+```
+
+**New Syntax:**
+
+```json
+{
+  "paths": {
+    "/html": {
+      "get": {
+        "operationId": "html",
+        "summary": "HTML document",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)"
+          },
+          "mcp": {
+            "type": "resource",
+            "name": "html_doc",
+            "description": "An HTML document resource",
+            "uri": "ui://html",
+            "mimeType": "text/html"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### GraphQL
+
+**Old Syntax:**
+
+```json
+{
+  "paths": {
+    "/graphql": {
+      "post": {
+        "operationId": "graphql-api",
+        "summary": "GraphQL API endpoint",
+        "x-zuplo-mcp-graphql": {
+          "enabled": true,
+          "introspectionToolName": "graphql_introspect",
+          "executeToolName": "graphql_execute"
+        }
+      }
+    }
+  }
+}
+```
+
+**New Syntax:**
+
+```json
+{
+  "paths": {
+    "/graphql": {
+      "post": {
+        "operationId": "graphql-api",
+        "summary": "GraphQL API endpoint",
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)"
+          },
+          "mcp": {
+            "type": "graphql",
+            "enabled": true,
+            "introspectionTool": {
+              "name": "graphql_introspect",
+              "description": "Introspect the GraphQL schema"
+            },
+            "executeTool": {
+              "name": "graphql_execute",
+              "description": "Execute a GraphQL query"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## New Features
+
+### Enabled Flag
+
+The new syntax supports an `enabled` flag on all types to conditionally include
+operations:
+
+```json
+{
+  "x-zuplo-route": {
+    "mcp": {
+      "type": "tool",
+      "name": "disabled_tool",
+      "enabled": false
+    }
+  }
+}
+```
+
+When `enabled: false`, the operation is skipped during registration without
+needing to remove it from the configuration.
+
+### Improved Validation
+
+The new format includes OpenAPI schema validation via `oneOf` constraints,
+providing better IDE support and error messages.
+
+## Quick Migration Checklist
+
+- [ ] Replace `files`, `tools`, `prompts`, `resources` arrays with single
+      `operations` array
+- [ ] Change `path` to `file` and `operationIds` to individual `{ file, id }`
+      objects
+- [ ] Move `x-zuplo-mcp-tool` into `x-zuplo-route.mcp` with `type: "tool"`
+- [ ] Move `x-zuplo-mcp-prompt` into `x-zuplo-route.mcp` with `type: "prompt"`
+- [ ] Move `x-zuplo-mcp-resource` into `x-zuplo-route.mcp` with
+      `type: "resource"`
+- [ ] Move `x-zuplo-mcp-graphql` into `x-zuplo-route.mcp` with `type: "graphql"`
+- [ ] Update GraphQL field names: `introspectionToolName` →
+      `introspectionTool.name`, `executeToolName` → `executeTool.name`
+- [ ] Test your MCP server to ensure all operations are registered correctly
+
+## Backward Compatibility
+
+The old syntax is currently marked as deprecated but still functional. However,
+it will be removed in a future release, so migration is recommended as soon as
+possible.