zuplo 7.9.13 → 7.9.15

package/docs/programmable-api/environment.mdx

@@ -1,26 +1,42 @@
 ---
-title: Environment Variables API
+title: Gateway Environment Variables
 sidebar_label: Environment Variables
 ---
 
-The `environment` object provides access to environment variables in your Zuplo
-Gateway. It returns a record of environment variable names to their values.
+Your API gateway can read every environment variable set for its environment,
+including secrets. This page covers how to read variables in code, configuration
+files, and URL handlers, and which variables Zuplo sets for you.
 
 :::info{title="Configuration Guide"}
 
-For information on how to set and manage environment variables in the Zuplo
-Portal, see
+To set and manage environment variables, and to learn how gateway variables
+differ from Developer Portal variables, see
 [Configuring Environment Variables](../articles/environment-variables.mdx).
 
 :::
 
-## Interface
+## Where to Use Variables
+
+Each location in your project has its own syntax:
+
+| Location                                              | Syntax                 | Resolved              |
+| ----------------------------------------------------- | ---------------------- | --------------------- |
+| Custom code (handlers, policies, hooks)               | `environment.VAR_NAME` | Runtime               |
+| Configuration files (`policies.json`, OpenAPI routes) | `$env(VAR_NAME)`       | Build time            |
+| URL Rewrite, URL Forward, and WebSocket handlers      | `${env.VAR_NAME}`      | Runtime (per request) |
+
+## In Code
+
+The `environment` object from `@zuplo/runtime` returns a record of environment
+variable names to their values.
+
+### Interface
 
 ```ts
 const environment: Record<string, string | undefined>;
 ```
 
-## Usage
+### Usage
 
 Access environment variables using the `environment` object:
 
@@ -49,7 +65,7 @@ export default async function handler(
 }
 ```
 
-## Type Safety
+### Type Safety
 
 Since environment variables might not be defined, they return
 `string | undefined`:
@@ -70,6 +86,185 @@ if (value) {
 const port = environment.PORT || "3000";
 ```
 
+## In Configuration Files
+
+Inside policy options, route handler options, and CORS policy options,
+environment variables can be referenced with the `$env(VAR_NAME)` pattern.
+Substitutions happen at build time — the build replaces each `$env()` expression
+with a reference to the runtime `environment` object before the project is
+deployed.
+
+### Where `$env()` is allowed
+
+- `config/policies.json` — any property under `policies[].handler.options`,
+  including nested objects and array elements
+- `config/policies.json` — any direct property of a `corsPolicies[]` entry, such
+  as `allowedOrigins`, `allowedHeaders`, `allowedMethods`, `exposeHeaders`, and
+  `maxAge`
+- `config/routes.oas.json` (and other OpenAPI route files) — any property under
+  a route's `x-zuplo-route.handler.options`, including nested objects and array
+  elements
+
+`$env()` is **not** allowed in other locations such as policy `name`,
+`policyType`, `module`, route paths, or top-level OpenAPI fields. Using it
+elsewhere produces a build error:
+
+```text
+An $env() statement is not expected at this location.
+```
+
+### Standalone substitution
+
+When the value is _only_ an `$env()` expression, the variable's value is
+inserted directly. The runtime type matches the type of the environment variable
+(always a string when set, `undefined` when not).
+
+```json
+{
+  "name": "my-custom-code-inbound-policy",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/YOUR_MODULE)",
+    "options": {
+      "apiKey": "$env(BACKEND_API_KEY)",
+      "config2": true
+    }
+  }
+}
+```
+
+### String interpolation
+
+You can mix `$env()` with literal text to compose a value. The build wraps the
+result in a JavaScript template literal that's evaluated at runtime, so each
+request gets the current value of the variable.
+
+```json
+{
+  "options": {
+    "endpoint": "https://$env(API_HOST)/v1",
+    "userAgent": "MyGateway/$env(APP_VERSION) ($env(ENVIRONMENT_NAME))"
+  }
+}
+```
+
+:::note
+
+If the variable isn't set, the interpolated portion resolves to an empty string.
+For example, with `API_HOST` unset, `"https://$env(API_HOST)/v1"` becomes
+`"https:///v1"`. Use a standalone `$env()` (no surrounding text) if you need to
+detect an unset variable in your handler or policy code.
+
+:::
+
+### In arrays
+
+`$env()` works inside string array elements, including mixed arrays where some
+elements are static and others are interpolated:
+
+```json
+{
+  "options": {
+    "allowedKeys": ["$env(PRIMARY_KEY)", "$env(SECONDARY_KEY)"],
+    "tags": ["public", "$env(REGION)", "tier-$env(SERVICE_TIER)"]
+  }
+}
+```
+
+### In nested objects
+
+`$env()` works at any depth within a handler or policy `options` object:
+
+```json
+{
+  "options": {
+    "database": {
+      "host": "$env(DB_HOST)",
+      "credentials": {
+        "username": "$env(DB_USER)",
+        "password": "$env(DB_PASSWORD)"
+      }
+    }
+  }
+}
+```
+
+### Variable name rules
+
+The name inside `$env(...)` is matched literally up to the first closing
+parenthesis. Use only letters, digits, and underscores in the name — matching
+what the
+[Zuplo Portal](../articles/environment-variables.mdx#environment-variable-editor)
+accepts when you create the variable.
+
+## Rewrite, Forwarding, and WebSocket Handlers
+
+The URL Rewrite handler's `rewritePattern`, the URL Forward handler's `baseUrl`,
+and the WebSocket handler's `rewritePattern` use a different syntax. These
+options are evaluated as JavaScript template literals at request time, so you
+reference variables with `${env.VAR_NAME}`:
+
+```json
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "https://${env.BACKEND_HOST}"
+    }
+  }
+}
+```
+
+Because `rewritePattern` and `baseUrl` run as code, they also have access to the
+request, URL parts, route params, and query string. See the
+[URL Rewrite Handler](../handlers/url-rewrite.mdx) docs for the full list of
+available variables.
+
+:::caution
+
+Using `$env(VAR_NAME)` inside `rewritePattern` or `baseUrl` is the most common
+mistake. The build will warn you when it detects this, but the value will be
+passed through to the handler as a literal string and the rewrite will fail at
+runtime. Always use `${env.VAR_NAME}` in these two options.
+
+:::
+
+## System Environment Variables
+
+Zuplo sets the following variables for your gateway. You can't create variables
+with these names.
+
+| Variable                   | Value                                                                                                                                                                                     |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ZUPLO_ENVIRONMENT_STAGE`  | The environment stage: `production`, `preview`, `working-copy`, or `local`. Use this variable to check which environment the gateway runs in.                                             |
+| `ZUPLO_ENVIRONMENT_TYPE`   | The kind of host that runs the gateway, such as `edge` or `local`.                                                                                                                        |
+| `ZUPLO_ENVIRONMENT_NAME`   | The globally unique name of the environment, as used in its default URL. For example, `my-project-main-1235` in `my-project-main-1235.zuplo.app`. Custom domains don't change this value. |
+| `ZUPLO_ACCOUNT_NAME`       | The name of the Zuplo account that owns the environment.                                                                                                                                  |
+| `ZUPLO_PROJECT_NAME`       | The name of the project that owns the environment.                                                                                                                                        |
+| `ZUPLO_BUILD_ID`           | A unique ID (UUID) for the build of the environment.                                                                                                                                      |
+| `ZUPLO_COMPATIBILITY_DATE` | The [compatibility date](./compatibility-dates.mdx) of the runtime environment.                                                                                                           |
+
+:::note
+
+Your Developer Portal gets a different set of system variables, and its
+`ZUPLO_ENVIRONMENT_TYPE` has different values. See
+[Dev Portal environment variables](../dev-portal/zudoku/guides/environment-variables.md).
+
+:::
+
+## Environment Detection
+
+Zuplo doesn't set `NODE_ENV`, because the gateway runs on a V8 runtime, not
+Node.js. Use `ZUPLO_ENVIRONMENT_STAGE` instead:
+
+```ts
+import { environment } from "@zuplo/runtime";
+
+const isProduction = environment.ZUPLO_ENVIRONMENT_STAGE === "production";
+```
+
 ## Common Patterns
 
 ### Required Environment Variables
@@ -158,28 +353,19 @@ export default async function handler(
 
 ### Environment-Specific Configuration
 
-To handle environment-specific logic, use environment variables that you define:
+Use `ZUPLO_ENVIRONMENT_STAGE` to change behavior between production, preview,
+and development environments:
 
 ```ts
-import { environment } from "@zuplo/runtime";
+import { environment, ZuploContext, ZuploRequest } from "@zuplo/runtime";
 
-// Define your own environment variable to identify the environment
-const isProduction = environment.ENVIRONMENT === "production";
-const isStaging = environment.ENVIRONMENT === "staging";
-const isDevelopment = environment.ENVIRONMENT === "development";
+const isProduction = environment.ZUPLO_ENVIRONMENT_STAGE === "production";
 
 export default async function handler(
   request: ZuploRequest,
   context: ZuploContext,
 ) {
-  // Use different endpoints based on environment
-  const apiUrl = isProduction
-    ? "https://api.example.com"
-    : isStaging
-      ? "https://staging-api.example.com"
-      : "https://dev-api.example.com";
-
-  // Enable debug logging in non-production
+  // Enable debug logging outside production
   if (!isProduction) {
     context.log.debug("Incoming request", {
       headers: Object.fromEntries(request.headers),
@@ -187,19 +373,15 @@ export default async function handler(
     });
   }
 
-  // Use stricter security in production
-  const headers: HeadersInit = {
-    "Content-Type": "application/json",
-  };
-
-  if (isProduction) {
-    headers["Strict-Transport-Security"] = "max-age=31536000";
-  }
-
-  return new Response("OK", { headers });
+  return new Response("OK");
 }
 ```
 
+To use different values per environment, such as a backend URL, set the same
+variable with a different value for each
+[environment](../articles/environment-variables.mdx#environments) instead of
+branching in code.
+
 ### Secret Management
 
 ```ts
@@ -242,13 +424,6 @@ function validateSecrets() {
 validateSecrets();
 ```
 
-## Environment Detection
-
-Zuplo doesn't provide a built-in `NODE_ENV` variable since it runs on a custom
-V8 runtime, not Node.js. To implement environment-specific logic, define your
-own environment variables (for example, `ENVIRONMENT`, `STAGE`, or `ENV_TYPE`)
-and set them appropriately for each environment in your project settings.
-
 ## Best Practices
 
 ### 1. Use Descriptive Names
@@ -313,17 +488,14 @@ context.log.info("Config loaded", {
 
 ## Setting Environment Variables
 
-Set environment variables in the Zuplo Portal:
-
-1. Open the
-   [**Environments**](https://portal.zuplo.com/+/account/project/environments)
-   tab of your project.
-2. Select an environment and add variables under **Environment Variables**.
-3. Zuplo encrypts variables at rest and in transit.
+Set environment variables in the Zuplo Portal under **Settings** >
+[**Environment Variables**](https://portal.zuplo.com/+/account/project/settings/environment-variables).
+For local development, use a `.env` file. See
+[Configuring Environment Variables Locally](../articles/local-development-env-variables.mdx).
 
 ## See Also
 
-- [Environment Variables](../articles/environment-variables.mdx) - Setting up
-  environment variables
+- [Configuring Environment Variables](../articles/environment-variables.mdx) -
+  Setting up environment variables
 - [ConfigurationError](./runtime-errors.mdx#configurationerror) - Error handling
   for configuration issues

package/docs/programmable-api/hooks.mdx

@@ -307,6 +307,30 @@ Hooks can be registered in two ways:
 2. **Globally via Runtime Extensions** - Register hooks that apply to all
    requests using [Runtime Extensions](./runtime-extensions.mdx)
 
+## Internal route invocations
+
+Global runtime hooks also run when
+[`context.invokeRoute`](./zuplo-context.mdx#invokeroute) invokes another route
+in the same gateway. This includes API routes invoked by the MCP Server handler
+for tool calls. The hooks receive the internal route's request and a new context
+whose `parentContext` points to the calling context.
+
+In request and response hooks, use `context.parentContext === undefined` to
+select only client requests, or check for a parent context to select internal
+invocations. Pre-routing hooks receive only a request, so they can't use this
+context check.
+
+By default, an internal invocation inherits the parent's `requestId`, while each
+context has a distinct `contextId`. Group related analytics events by
+`requestId` and distinguish executions by `contextId`.
+
+For a complete MCP example, including how to identify the tool and avoid
+counting both the client request and its internal invocation, see
+[Track tool calls with runtime hooks](../mcp-server/tools.mdx#track-tool-calls-with-runtime-hooks).
+Use an [`addResponseSendingFinalHook`](#hook-onresponsesendingfinal) when your
+event needs the response status. For an internal invocation, that status belongs
+to the API route response; the outer `/mcp` response contains the MCP result.
+
 ## Complete Hook Pipeline Example
 
 This example demonstrates how all hooks work together in a request/response

package/docs/programmable-api/mcp-sdk.mdx

@@ -177,6 +177,28 @@ export default async function (request: ZuploRequest, context: ZuploContext) {
 Unlike `setRawCallToolResult`, this method can be called any number of times —
 the request object is not consumed.
 
+#### MCP metadata in runtime hooks
+
+The MCP Server handler stores the original `tools/call` request when it starts
+processing the request. Availability therefore depends on where the hook runs:
+
+| Hook location                                     | `getRawCallToolRequest()` result                                            |
+| ------------------------------------------------- | --------------------------------------------------------------------------- |
+| Global request hook on the initial `/mcp` request | `null`: the MCP handler hasn't run yet                                      |
+| Request or response hook on the tool's API route  | The original tool call, read from the parent context                        |
+| Response hook on the outer `/mcp` request         | The original tool call, if the MCP handler processed a `tools/call` request |
+
+Use `context.parentContext` to distinguish an internal invocation from the
+initial client request. The presence of a tool call alone doesn't distinguish
+them in a response hook. See
+[Track tool calls with runtime hooks](../mcp-server/tools.mdx#track-tool-calls-with-runtime-hooks)
+for an analytics example.
+
+The helper checks only the current context and its immediate parent. If your
+tool's API route invokes another route, the deeper invocation can't read the
+original tool call through this helper unless your code passes the metadata
+along. Calls such as `tools/list` don't populate tool-call metadata.
+
 ## Output schema enforcement
 
 When a tool advertises an `outputSchema` (via `includeOutputSchema` on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.9.13",
+  "version": "7.9.15",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.9.13",
-    "@zuplo/core": "7.9.13",
-    "@zuplo/runtime": "7.9.13",
-    "@zuplo/test": "7.9.13"
+    "@zuplo/cli": "7.9.15",
+    "@zuplo/core": "7.9.15",
+    "@zuplo/runtime": "7.9.15",
+    "@zuplo/test": "7.9.15"
   }
 }

package/docs/policies/ai-gateway-internal-only-inbound/doc.md

@@ -1,102 +0,0 @@
-## How it works
-
-`context.invokeRoute` runs a route on this gateway without leaving the process,
-and the runtime marks the request it creates by setting `context.parentContext`
-to the calling request's context. Nothing else sets that property. A request
-that arrives over the network never has one, whatever headers, URL, or body it
-carries. This policy passes a request when `context.parentContext` is present
-and rejects it otherwise.
-
-| Request origin                                                                 | Result |
-| ------------------------------------------------------------------------------ | ------ |
-| Any HTTP client, with or without an API key                                    | `403`  |
-| `context.invokeRoute` from a policy, handler, or custom module on this gateway | Passes |
-| The MCP server handler calling the route as a tool                             | Passes |
-| An internal application calling another internal application                   | Passes |
-
-The rejection is a `403 Forbidden` problem response. On AWS Bedrock Runtime
-routes it uses the AWS error envelope (`AccessDeniedException`) so the AWS SDKs
-surface the message.
-
-The policy does not authenticate the caller and does not set `request.user`.
-Metering records the request against the application with no consumer, and a
-budget rule keyed on `request.user` has no value to accumulate for these
-requests. Attach per-consumer budgets to the calling application instead.
-
-## Add the policy
-
-Declare the policy in `config/policies.json`:
-
-```json
-{
-  "policies": [
-    {
-      "name": "ai-gateway-internal-only-inbound",
-      "policyType": "ai-gateway-internal-only",
-      "handler": {
-        "export": "AIGatewayInternalOnlyInboundPolicy",
-        "module": "$import(@zuplo/runtime)",
-        "options": {}
-      }
-    }
-  ]
-}
-```
-
-Then select it in the application's `inboundPolicyChain` in place of
-`ai-gateway-auth-inbound`. Put it first so nothing else runs for a rejected
-request:
-
-```json
-{
-  "inboundPolicyChain": [
-    { "name": "ai-gateway-internal-only-inbound" },
-    { "name": "ai-gateway-model-filtering-inbound" },
-    { "name": "ai-gateway-metering-inbound" }
-  ]
-}
-```
-
-The policy also works as a route-level inbound policy on any route that should
-be reachable only through `context.invokeRoute`.
-
-## Call the application
-
-Call the application from a policy or handler on the same gateway. No
-`Authorization` header is needed:
-
-```ts
-const response = await context.invokeRoute(
-  `/${classifierAppId}/v1/chat/completions`,
-  {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ model: "openai/gpt-5-mini", messages }),
-  }
-);
-```
-
-The Smart Router and Prompt Injection Protection policies already call their
-classifier applications this way.
-
-A direct call from outside the gateway is rejected:
-
-```bash
-curl https://gateway.example.com/my-classifier-app/v1/chat/completions \
-  --header "Content-Type: application/json" \
-  --data '{
-    "model": "openai/gpt-5-mini",
-    "messages": [{ "role": "user", "content": "Hello" }]
-  }'
-```
-
-The response is `403 Forbidden`, and its `detail` explains that the application
-only accepts requests made from inside the gateway with `context.invokeRoute`.
-
-## What it does not check
-
-This policy asserts that a request originated inside this gateway deployment,
-not that the caller is trusted. Any route on the same gateway that forwards
-requests through `context.invokeRoute`, including an MCP server that exposes the
-application as a tool, reaches the application. Protect such routes with their
-own authentication, exactly as you would an internal URL.

package/docs/policies/ai-gateway-internal-only-inbound/intro.md

@@ -1,11 +0,0 @@
-The Ensure Gateway Internal Invocation Only policy admits a request only when
-this gateway made it with `context.invokeRoute`, and answers every request that
-arrived over the network with `403 Forbidden`.
-
-Add it to an application's `inboundPolicyChain` in place of AI Gateway
-Authentication when the application is only ever called by other routes and
-policies on the same gateway, such as the classifier application behind the
-Smart Router or Prompt Injection Protection policies. Those calls never leave
-the gateway, so an API key on them protects nothing; this policy checks the one
-thing that matters. It has no options, makes no network calls, and never reads
-the request body.

package/docs/policies/ai-gateway-internal-only-inbound/schema.json

@@ -1,50 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-internal-only-inbound.json",
-  "type": "object",
-  "title": "Ensure Gateway Internal Invocation Only",
-  "isDeprecated": false,
-  "isPaidAddOn": false,
-  "isEnterprise": false,
-  "isInternal": false,
-  "isBeta": false,
-  "isHidden": false,
-  "requiresAI": true,
-  "policyType": "ai-gateway-internal-only",
-  "products": ["ai-gateway"],
-  "description": "Accepts only requests that this gateway made itself with `context.invokeRoute`, and rejects every request that arrived over the network with `403 Forbidden`.\n\nUse it in place of AI Gateway Authentication on an application that is only ever called by other routes and policies on the same gateway, such as the classifier application behind the Smart Router or Prompt Injection Protection policies. Those calls never leave the gateway, so an API key on them protects nothing. This policy asserts the one thing that matters: the request originated inside the deployment.\n\nThe check reads `context.parentContext`, which the runtime sets only on the child context that `context.invokeRoute` creates. A client cannot supply it through a header, the URL, or the body. The policy has no options, makes no network calls, reads no body, and leaves `request.user` unset.",
-  "deprecatedMessage": "",
-  "required": ["handler"],
-  "properties": {
-    "handler": {
-      "type": "object",
-      "default": {},
-      "required": ["export", "module", "options"],
-      "properties": {
-        "export": {
-          "const": "AIGatewayInternalOnlyInboundPolicy",
-          "description": "The name of the exported type"
-        },
-        "module": {
-          "const": "$import(@zuplo/runtime)",
-          "description": "The module containing the policy"
-        },
-        "options": {
-          "title": "AIGatewayInternalOnlyInboundPolicyOptions",
-          "type": "object",
-          "description": "The options for this policy. It has none.",
-          "additionalProperties": false,
-          "required": [],
-          "properties": {}
-        }
-      },
-      "examples": [
-        {
-          "export": "AIGatewayInternalOnlyInboundPolicy",
-          "module": "$import(@zuplo/runtime)",
-          "options": {}
-        }
-      ]
-    }
-  }
-}