zuplo 6.70.69 → 6.70.71

package/docs/dev-portal/zudoku/configuration/site.md

@@ -127,6 +127,44 @@ export const NotFound = () => (
 
 ## Layout
 
+### Collapsible Sidebar
+
+The navigation sidebar is collapsible by default. A small toggle button on the sidebar's right
+border lets users hide and reveal it. Configure the behavior under `site.sidebar`:
+
+```tsx title=zudoku.config.tsx
+{
+  site: {
+    sidebar: {
+      collapsible: true, // default: true. Set to false to disable the toggle entirely.
+      toggleVisibility: "always", // "always" (default) or "hover" — show button only when hovering the sidebar's right edge
+      togglePosition: "bottom", // "top", "center", or "bottom" (default)
+    },
+  }
+}
+```
+
+For finer vertical placement, override the `--sidebar-toggle-y` CSS variable in your stylesheet:
+
+```css
+:root {
+  --sidebar-toggle-y: 30%;
+}
+```
+
+The toggle button carries `aria-expanded="true"` when the sidebar is open and `"false"` when
+collapsed. Combine it with the `[data-sidebar-toggle]` selector to position the button differently
+per state:
+
+```css
+[data-sidebar-toggle][aria-expanded="true"] {
+  --sidebar-toggle-y: 20%;
+}
+[data-sidebar-toggle][aria-expanded="false"] {
+  --sidebar-toggle-y: 80%;
+}
+```
+
 ### Banner
 
 Add a banner message to the top of the page:

package/docs/dev-portal/zudoku/customization/colors-theme.mdx

@@ -164,29 +164,55 @@ const config = {
 };
 ```
 
-Alternatively, you can copy the CSS code and paste it into your `customCss` configuration:
+Alternatively, paste the copied CSS into a stylesheet and import it from your config:
+
+```css title=styles.css
+/* Copied CSS code */
+```
 
 ```ts title=zudoku.config.ts
-const config = {
-  theme: {
-    customCss: `
-      /* Copied CSS code */
-    `,
-  },
-};
+import "./styles.css";
 ```
 
 ## Custom CSS
 
-For advanced styling, you can add custom CSS either as a string or structured object:
+The recommended way to add custom styles is to write a `.css` file alongside your config and import
+it. This gives you HMR during development, syntax highlighting, autocompletion, and lets you split
+styles across files as your site grows.
 
-:::note
+```css title=styles.css
+.custom {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+```
 
-Changes to `customCss` require restarting the development server to take effect.
+```ts title=zudoku.config.ts
+import "./styles.css";
 
-:::
+const config = {
+  // ...
+};
+```
+
+If TypeScript reports `Cannot find module './styles.css'`, add `zudoku/client` to your tsconfig
+types so CSS side-effect imports are recognized:
+
+```json title=tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["zudoku/client"]
+  }
+}
+```
+
+Projects created with `create-zudoku` include this by default.
+
+### Inline alternatives (deprecated)
 
-### CSS String
+The `theme.customCss` option is deprecated and will be removed in a future release. It still accepts
+a CSS string or object for backwards compatibility, but every change requires restarting the dev
+server and you lose syntax highlighting, autocompletion, and HMR. Migrate to an imported `.css`
+file.
 
 ```ts title=zudoku.config.ts
 const config = {
@@ -200,37 +226,22 @@ const config = {
 };
 ```
 
-### CSS Object
-
-```ts title=zudoku.config.ts
-const config = {
-  theme: {
-    customCss: {
-      ".custom": {
-        background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
-      },
-    },
-  },
-};
-```
-
 ### Enabling Code Ligatures
 
 Dev Portal disables ligatures in code blocks by default to avoid unwanted glyph joining in fonts like
 Geist Mono (e.g. `---`, `###`, `|--|`). If you're using a coding font designed around ligatures
-(Fira Code, JetBrains Mono, etc.), re-enable them via `customCss`:
-
-```ts title=zudoku.config.ts
-const config = {
-  theme: {
-    customCss: `
-      code, pre, kbd, samp, .shiki, .shiki span {
-        font-variant-ligatures: normal;
-        font-feature-settings: normal;
-      }
-    `,
-  },
-};
+(Fira Code, JetBrains Mono, etc.), re-enable them in your CSS file:
+
+```css title=styles.css
+code,
+pre,
+kbd,
+samp,
+.shiki,
+.shiki span {
+  font-variant-ligatures: normal;
+  font-feature-settings: normal;
+}
 ```
 
 ## Default Theme

package/docs/errors/rate-limit-exceeded.mdx

@@ -4,6 +4,29 @@ title: Rate Limit Exceeded (RATE_LIMIT_EXCEEDED)
 
 The request was rejected because the client exceeded the configured rate limit.
 
+## Response format
+
+The 429 response uses the
+[Problem Details](../programmable-api/http-problems.mdx) format:
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/429",
+  "title": "Too Many Requests",
+  "status": 429,
+  "detail": "Rate limit exceeded",
+  "instance": "/your-route",
+  "trace": {
+    "requestId": "4d54e4ee-c003-4d75-aba9-e09a6d707b08",
+    "timestamp": "2026-04-14T12:00:00.000Z",
+    "buildId": "ec44e831-3a02-467e-a26c-7e401e4473bf"
+  }
+}
+```
+
+If `headerMode` is set to `"retry-after"` (the default), the response includes a
+`Retry-After` header with the number of seconds to wait before retrying.
+
 ## Common Causes
 
 - **Too many requests** — The client sent more requests than the rate limit
@@ -24,8 +47,12 @@ The request was rejected because the client exceeded the configured rate limit.
 
 ## For API Operators
 
-- Review the rate limiting policy configuration in the route settings.
+- Review the rate limiting policy configuration in the route settings. Check the
+  `requestsAllowed` and `timeWindowMinutes` values and verify that the
+  `rateLimitBy` identifier is resolving correctly.
 - Consider using
-  [dynamic rate limiting](../articles/step-5-dynamic-rate-limiting.mdx) to set
+  [dynamic rate limiting](../rate-limiting/dynamic-rate-limiting.mdx) to set
   different limits per customer tier.
-- Check the rate limit metrics to determine if limits need adjustment.
+- Use your [logging integration](../articles/logging.mdx) to filter for 429
+  responses and identify which consumers are being throttled. Break down by user
+  or IP to spot noisy neighbors.

package/docs/guides/canary-routing-for-employees.mdx

@@ -32,6 +32,10 @@ If any condition is met, the request routes to canary backends.
 
 ## Creating a Canary Routing Policy
 
+The policy doesn't set the backend URL directly. Instead, it stores the chosen
+backend on `context.custom`, and the route's handler reads that value to forward
+the request (see "Adding the Policy to Routes" below).
+
 Create a new policy file in your project:
 
 ```typescript
@@ -62,9 +66,9 @@ export const canaryRoutingPolicy: InboundPolicyHandler = async (
   const isCanary =
     stageParam === "canary" || stageHeader === "canary" || canaryUser;
 
-  // Route based on stage
+  // Store the backend URL for the route's handler to use
   if (isCanary) {
-    context.route.url = environment.API_URL_CANARY;
+    context.custom.backendUrl = environment.API_URL_CANARY;
 
     // Log canary routing for debugging
     context.log.info("Routing to canary backend", {
@@ -73,13 +77,19 @@ export const canaryRoutingPolicy: InboundPolicyHandler = async (
       stage: stageParam || stageHeader || "canary",
     });
   } else {
-    context.route.url = environment.API_URL_PRODUCTION;
+    context.custom.backendUrl = environment.API_URL_PRODUCTION;
   }
 
   // Remove stage query parameter to avoid passing it to backend
   if (stageParam) {
     url.searchParams.delete("stage");
-    return new ZuploRequest(url.toString(), request);
+    return new ZuploRequest(url.toString(), {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      user: request.user,
+      params: request.params,
+    });
   }
 
   return request;
@@ -139,24 +149,30 @@ export const multiServiceCanaryRoutingPolicy: InboundPolicyHandler = async (
   // Clean up query parameter
   if (stageParam) {
     url.searchParams.delete("stage");
-    return new ZuploRequest(url.toString(), request);
+    return new ZuploRequest(url.toString(), {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      user: request.user,
+      params: request.params,
+    });
   }
 
   return request;
 };
 ```
 
+Each service's route then reads the matching value in its handler options. For
+example, the user API route would use a URL Forward handler with
+`"baseUrl": "${context.custom.userApiUrl}"`.
+
 ## Percentage-Based Canary Routing
 
 Roll out canary deployments gradually with percentage-based routing:
 
 ```typescript
 // policies/percentage-canary-routing.ts
-import {
-  InboundPolicyHandler,
-  ZuploRequest,
-  environment,
-} from "@zuplo/runtime";
+import { InboundPolicyHandler, environment } from "@zuplo/runtime";
 
 export const percentageCanaryRoutingPolicy: InboundPolicyHandler = async (
   request,
@@ -168,7 +184,7 @@ export const percentageCanaryRoutingPolicy: InboundPolicyHandler = async (
     : [];
 
   if (request.user?.sub && CANARY_USERS.includes(request.user.sub)) {
-    context.route.url = environment.API_URL_CANARY;
+    context.custom.backendUrl = environment.API_URL_CANARY;
     return request;
   }
 
@@ -176,8 +192,12 @@ export const percentageCanaryRoutingPolicy: InboundPolicyHandler = async (
   const CANARY_PERCENTAGE = parseInt(environment.CANARY_PERCENTAGE || "0", 10);
 
   if (CANARY_PERCENTAGE > 0) {
-    // Use a consistent hash for sticky sessions
-    const sessionId = request.headers.get("x-session-id") || request.ip;
+    // Use a consistent hash for sticky sessions. The client IP is
+    // available on the true-client-ip header.
+    const sessionId =
+      request.headers.get("x-session-id") ??
+      request.headers.get("true-client-ip") ??
+      "unknown";
     const hash = await crypto.subtle.digest(
       "SHA-256",
       new TextEncoder().encode(sessionId),
@@ -186,13 +206,13 @@ export const percentageCanaryRoutingPolicy: InboundPolicyHandler = async (
     const hashValue = hashArray[0] / 255; // Value between 0 and 1
 
     if (hashValue * 100 < CANARY_PERCENTAGE) {
-      context.route.url = environment.API_URL_CANARY;
+      context.custom.backendUrl = environment.API_URL_CANARY;
       request.headers.set("X-Canary-Route", "percentage");
     } else {
-      context.route.url = environment.API_URL_PRODUCTION;
+      context.custom.backendUrl = environment.API_URL_PRODUCTION;
     }
   } else {
-    context.route.url = environment.API_URL_PRODUCTION;
+    context.custom.backendUrl = environment.API_URL_PRODUCTION;
   }
 
   return request;
@@ -221,7 +241,9 @@ CANARY_PERCENTAGE=10  # Route 10% of traffic to canary
 
 ### Adding the Policy to Routes
 
-Add the policy to your route configuration:
+Add the policy to your route configuration. Use the built-in
+[URL Forward handler](../handlers/url-forward.mdx) and reference the value the
+policy stored on `context.custom` in the `baseUrl` option:
 
 ```json
 {
@@ -231,14 +253,14 @@ Add the policy to your route configuration:
         "x-zuplo-route": {
           "corsPolicy": "anything-goes",
           "handler": {
-            "export": "urlRewriteHandler",
+            "export": "urlForwardHandler",
             "module": "$import(@zuplo/runtime)",
             "options": {
-              "rewritePattern": "https://api.company.com$1"
+              "baseUrl": "${context.custom.backendUrl}"
             }
           },
           "policies": {
-            "inbound": ["canary-routing", "auth-policy"]
+            "inbound": ["auth-policy", "canary-routing"]
           }
         }
       }
@@ -247,6 +269,9 @@ Add the policy to your route configuration:
 }
 ```
 
+The authentication policy runs first so that `request.user` is populated when
+the canary routing policy checks the allow list.
+
 ## Testing Your Policy
 
 ### 1. Using Query Parameters
@@ -289,7 +314,9 @@ curl https://your-api.zuplo.app/api/v1/users \
 
 ## Monitoring and Observability
 
-Add comprehensive logging to track canary routing:
+Add comprehensive logging to track canary routing. Inbound policies run before a
+response exists, so set debug response headers from a
+[response sending hook](../programmable-api/hooks.mdx):
 
 ```typescript
 export const canaryRoutingPolicy: InboundPolicyHandler = async (
@@ -298,20 +325,26 @@ export const canaryRoutingPolicy: InboundPolicyHandler = async (
 ) => {
   const startTime = Date.now();
 
+  const CANARY_USERS = environment.CANARY_USERS
+    ? environment.CANARY_USERS.split(",").map((user) => user.trim())
+    : [];
+
   // Check stage conditions
   const url = new URL(request.url);
   const stageParam = url.searchParams.get("stage");
   const stageHeader = request.headers.get("x-stage");
-  const canaryUser = /* ... check if user is in canary list ... */;
+  const canaryUser =
+    request.user?.sub && CANARY_USERS.includes(request.user.sub);
 
   const isCanary =
-    stageParam === "canary" ||
-    stageHeader === "canary" ||
-    canaryUser;
+    stageParam === "canary" || stageHeader === "canary" || canaryUser;
 
-  if (isCanary) {
-    context.route.url = environment.API_URL_CANARY;
+  const backendType = isCanary ? "canary" : "release";
+  context.custom.backendUrl = isCanary
+    ? environment.API_URL_CANARY
+    : environment.API_URL_PRODUCTION;
 
+  if (isCanary) {
     // Log canary routing metrics
     context.log.info("Canary route selected", {
       userId: request.user?.sub,
@@ -320,14 +353,14 @@ export const canaryRoutingPolicy: InboundPolicyHandler = async (
       stage: "canary",
       duration: Date.now() - startTime,
     });
-
-    // Add response header for debugging
-    context.response.headers.set("X-Backend-Type", "canary");
-  } else {
-    context.route.url = environment.API_URL_PRODUCTION;
-    context.response.headers.set("X-Backend-Type", "release");
   }
 
+  // Add a response header for debugging
+  context.addResponseSendingHook((response) => {
+    response.headers.set("X-Backend-Type", backendType);
+    return response;
+  });
+
   return request;
 };
 ```
@@ -359,14 +392,45 @@ if (isCanaryUser) {
 
 ### 3. Fallback Handling
 
-Implement fallback logic for canary backend failures:
+To fall back to production when the canary backend fails, replace the URL
+Forward handler with a [custom handler](../handlers/custom-handler.mdx) that
+retries against production on server errors:
 
 ```typescript
-// In your error handling policy
-if (context.response.status >= 500 && context.custom.isCanary) {
-  // Retry with production backend
-  context.route.url = environment.API_URL_PRODUCTION;
-  return context.retry();
+// modules/canary-fallback-handler.ts
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const url = new URL(request.url);
+  const backendUrl = context.custom.backendUrl;
+  const target = `${backendUrl}${url.pathname}${url.search}`;
+
+  // Buffer the body so the request can be retried
+  const body = request.body ? await request.arrayBuffer() : undefined;
+
+  const response = await fetch(target, {
+    method: request.method,
+    headers: request.headers,
+    body,
+  });
+
+  // Retry against production if the canary backend returns a server error
+  if (backendUrl === environment.API_URL_CANARY && response.status >= 500) {
+    context.log.warn("Canary backend failed, falling back to production", {
+      status: response.status,
+    });
+    const fallbackBase = environment.API_URL_PRODUCTION;
+    return fetch(`${fallbackBase}${url.pathname}${url.search}`, {
+      method: request.method,
+      headers: request.headers,
+      body,
+    });
+  }
+
+  return response;
 }
 ```
 

package/docs/guides/modify-openapi-paths.mdx

@@ -106,8 +106,8 @@ You can generate multiple versions as part of your build process:
 ```json title="package.json"
 {
   "scripts": {
-    "build:api:v1": "npx tsx add-path-prefix.ts /v1 openapi.json dist/openapi-v1.json",
-    "build:api:v2": "npx tsx add-path-prefix.ts /v2 openapi.json dist/openapi-v2.json",
+    "build:api:v1": "node add-path-prefix.mjs /v1 openapi.json dist/openapi-v1.json",
+    "build:api:v2": "node add-path-prefix.mjs /v2 openapi.json dist/openapi-v2.json",
     "build:api:all": "npm run build:api:v1 && npm run build:api:v2"
   }
 }
@@ -128,7 +128,7 @@ mkdir -p $OUTPUT_DIR
 for prefix in "${PREFIXES[@]}"; do
   echo "Building with prefix: /$prefix"
 
-  npx tsx add-path-prefix.ts \
+  node add-path-prefix.mjs \
     "/$prefix" \
     "$BASE_FILE" \
     "$OUTPUT_DIR/openapi-$prefix.json"

package/docs/handlers/legacy-dev-portal-handler.mdx

@@ -35,7 +35,7 @@ as it provides better performance and usability.
     "title": "Dev Portal Redirect"
   },
   "paths": {
-    "/docs{(.*)}": {
+    "/docs(.*)": {
       "x-zuplo-path": {
         "pathMode": "url-pattern"
       },

package/docs/handlers/mcp-server.mdx

@@ -35,14 +35,15 @@ Open the **Route Designer** by navigating to the **Code** tab, then click
 **routes.oas.json**. For any route definition, select **MCP Server** from the
 **Request Handlers** drop-down. Set the method to **POST**.
 
-Configure the handler with the following required options:
+Configure the handler with the following options:
 
-- **Server Name** - The name of the MCP server. AI MCP clients will read this
-  name when they initialize with the server.
-- **Server Version** - The version of your MCP server. AI MCP clients read this
-  version when they initialize with the server and may make autonomous decisions
-  based on the versioning of your MCP server and the instructions they've been
-  given.
+- **Server Name** (optional) - The name of the MCP server. AI MCP clients will
+  read this name when they initialize with the server. If not set, the server
+  advertises the default name `Zuplo MCP Server`.
+- **Server Version** (optional) - The version of your MCP server. AI MCP clients
+  read this version when they initialize with the server and may make autonomous
+  decisions based on the versioning of your MCP server and the instructions
+  they've been given. If not set, the version defaults to `0.0.0`.
 
 Next, configure your routes to be transformed into MCP tools or prompts (see
 Configuration section below).
@@ -65,7 +66,7 @@ with the following route configuration:
         "handler": {
 
           // The MCP Server Handler handler
-          // and required options
+          // and example options
 
           "export": "mcpServerHandler",
           "module": "$import(@zuplo/runtime)",
@@ -86,10 +87,11 @@ with the following route configuration:
 
 ## Configuration
 
-The MCP Server handler requires the following configurations:
+The MCP Server handler supports the following configuration options:
 
-- `name` (optional) - The name identifier of the MCP server.
-- `version` (optional) - The version of the MCP server.
+- `name` (optional, default `Zuplo MCP Server`) - The name identifier of the MCP
+  server.
+- `version` (optional, default `0.0.0`) - The version of the MCP server.
 - `debugMode` (optional, default `false`) - Verbose logs on server startup,
   initialization, tool listing, and tool calls. NOT recommended for production
   environments.

package/docs/handlers/url-forward.mdx

@@ -53,6 +53,8 @@ The following objects are available for substitution:
   `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`.
+- `method: string` - The HTTP method of the incoming request. For example, `GET`
+  or `POST`.
 - `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
@@ -62,6 +64,9 @@ The following objects are available for substitution:
 - `hostname: string` - The
   [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hostname)
   portion of the incoming URL
+- `origin: string` - The
+  [`origin`](https://developer.mozilla.org/en-US/docs/Web/API/URL/origin)
+  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
@@ -93,7 +98,6 @@ A few examples of the values of various substitutions.
 - `${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"`

package/docs/handlers/url-rewrite.mdx

@@ -43,6 +43,8 @@ The following objects are available for substitution:
   `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`.
+- `method: string` - The HTTP method of the incoming request. For example, `GET`
+  or `POST`.
 - `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
@@ -52,6 +54,9 @@ The following objects are available for substitution:
 - `hostname: string` - The
   [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hostname)
   portion of the incoming URL
+- `origin: string` - The
+  [`origin`](https://developer.mozilla.org/en-US/docs/Web/API/URL/origin)
+  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
@@ -83,7 +88,6 @@ A few examples of the values of various substitutions.
 - `${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"`
@@ -132,7 +136,8 @@ use-cases.
   - Type: `string`
   - Supports JavaScript template interpolation with request context
   - Available variables: `env`, `request`, `context`, `params`, `query`,
-    `headers`, `url`, `host`, `hostname`, `pathname`, `port`, `search`
+    `method`, `headers`, `url`, `host`, `hostname`, `origin`, `pathname`,
+    `port`, `search`
   - Example: `"https://api-${params.version}.example.com/users/${params.id}"`
 
 - **`forwardSearch`** (optional): Controls whether query parameters are

package/docs/handlers/websocket-handler.mdx

@@ -84,6 +84,8 @@ The following objects are available for substitution:
   `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`.
+- `method: string` - The HTTP method of the incoming request. For example, `GET`
+  or `POST`.
 - `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
@@ -93,6 +95,9 @@ The following objects are available for substitution:
 - `hostname: string` - The
   [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hostname)
   portion of the incoming URL
+- `origin: string` - The
+  [`origin`](https://developer.mozilla.org/en-US/docs/Web/API/URL/origin)
+  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
@@ -124,7 +129,6 @@ A few examples of the values of various substitutions.
 - `${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"`