zuplo 6.73.30 → 6.74.2

package/docs/ai-gateway/integrations/ai-sdk.mdx

@@ -76,17 +76,24 @@ const { text } = await generateText({
 
 ### Google
 
+The `@ai-sdk/google` provider speaks Gemini's native protocol: it sends requests
+to `/models/{model}:generateContent` and authenticates with the `x-goog-api-key`
+header, neither of which the AI Gateway serves. Use the
+[OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers)
+instead — the AI Gateway translates OpenAI-format requests to Google upstream.
+
 ```typescript
-import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { generateText } from "ai";
 
-const google = createGoogleGenerativeAI({
+const gateway = createOpenAICompatible({
+  name: "zuplo-ai-gateway",
   apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
   baseURL: "https://my-ai-gateway.zuplo.app/v1",
 });
 
 const { text } = await generateText({
-  model: google("gemini-2.5-flash"),
+  model: gateway("gemini-2.5-flash"),
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```

package/docs/articles/check-ip-address.mdx

@@ -2,16 +2,175 @@
 title: How to check an incoming IP address
 sidebar_label: "Check IP Address"
 description:
-  Learn how to access the true client IP address of requests using the
-  true-client-ip header.
+  Read the client IP address of an incoming request, and understand when that
+  address can be trusted on each deployment type.
 tags:
   - request-handling
   - deployment
 ---
 
-Sometimes you want to access the true IP address of the gateway's client making
-the current request. To do this you can read the `true-client-ip` header:
+To get the IP address of the client that made the current request, read it from
+the request context:
 
 ```ts
-const ip = request.headers.get("true-client-ip");
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const ip = context.incomingRequestProperties.ip;
+  return new Response(ip ?? "unknown");
+}
 ```
+
+This is the official way to read the client IP. Zuplo resolves the address from
+the layer in front of your gateway, so you get the same property regardless of
+where the gateway runs.
+
+## Handle an unknown address
+
+The value is `undefined` when nothing identified the caller. Handle that case
+explicitly:
+
+```ts
+const ip = context.incomingRequestProperties.ip;
+if (!ip) {
+  return HttpProblems.badRequest(request, context, {
+    detail: "Could not determine the client IP address",
+  });
+}
+```
+
+Don't substitute a placeholder such as `"unknown"` or `0.0.0.0` and then key on
+it. Every unidentified caller collapses into that single value, so a rate limit
+keyed on it throttles them as one client, and an allow list keyed on it either
+admits all of them or none.
+
+## When the address can be trusted
+
+An IP address is only as trustworthy as the layer that determined it. Zuplo
+reports an address only where that layer establishes it, so the value is either
+trustworthy or `undefined` — never one the caller chose.
+
+| Deployment        | Determined by                         | Trustworthy                              |
+| ----------------- | ------------------------------------- | ---------------------------------------- |
+| Zuplo Cloud       | The Zuplo edge                        | Yes                                      |
+| Zuplo Dedicated   | Your environment, configured by Zuplo | Yes                                      |
+| Self-hosted       | The proxy you run                     | Only if that proxy overwrites the header |
+| Local development | Nothing — the caller is loopback      | Reports `127.0.0.1`                      |
+
+Zuplo Cloud and Zuplo Dedicated need no configuration. Self-hosted deployments
+depend on the proxy you run, covered in
+[Self-hosted deployments](#self-hosted-deployments).
+
+:::caution
+
+Don't read an IP header from `request.headers` yourself. Which header carries
+the caller's address depends on where the gateway runs, so a header that holds
+it on one deployment may be absent on another — or may hold whatever the caller
+put there. Use `context.incomingRequestProperties.ip`, which resolves the right
+one for the deployment.
+
+:::
+
+## The `x-forwarded-for` header
+
+`x-forwarded-for` carries a client address through a chain of proxies. Each
+proxy appends the address it received the request from, producing a list:
+
+```
+X-Forwarded-For: 203.0.113.7, 198.51.100.4
+```
+
+The header reaches your code and your backend unchanged, so you can read it
+directly:
+
+```ts
+const chain = (request.headers.get("x-forwarded-for") ?? "")
+  .split(",")
+  .map((entry) => entry.trim())
+  .filter(Boolean);
+```
+
+To use it correctly, understand what the list contains. A caller can send an
+`X-Forwarded-For` of its own, and every proxy after that appends to whatever
+arrived. So the front of the list is whatever the caller wrote, and only entries
+added by a hop you operate mean anything.
+
+That leads to a few rules:
+
+- Count positions from the **end**. The last entry was added by the hop nearest
+  your gateway; the first came from the caller.
+- Decide in advance how many hops you operate, and ignore anything beyond them.
+  A caller can pad the front with as many entries as it likes.
+- Don't search the list for an address you recognize — a caller can put one
+  there.
+- Expect IPv6 entries, which may be bracketed and carry a port, such as
+  `[2001:db8::1]:8080`.
+
+:::danger
+
+An address is only as reliable as the hop that established it. If you key a rate
+limit on a value the caller can choose, they escape the limit by rotating it.
+The same value in an allow list can be used to impersonate an allowed client,
+and in an audit record it produces entries that didn't happen.
+
+:::
+
+If you only need the caller's address, `context.incomingRequestProperties.ip`
+already gives it to you without any of this.
+
+## Running your own CDN or proxy in front of Zuplo
+
+If your own CDN, load balancer, or WAF sits in front of your gateway, then that
+hop — not the end user — is the client Zuplo sees.
+`incomingRequestProperties.ip` returns its address.
+
+To identify the end user, have your CDN write the address into a header of your
+own and read that header in your code:
+
+```ts
+const endUserIp = request.headers.get("x-acme-client-ip");
+```
+
+This works only if your CDN **overwrites** that header on every request. If it
+merely adds the header when absent, a caller can supply their own value and it
+passes straight through to your code.
+
+## Zuplo Dedicated
+
+Zuplo configures your Dedicated environment to determine the client address, so
+there's nothing for you to set up. `context.incomingRequestProperties.ip`
+returns the caller's address the same way it does on Zuplo Cloud.
+
+Dedicated environments aren't identical to one another — they differ by cloud,
+region, and what sits in front of the gateway, such as a CDN or WAF you already
+operate. If you need to know exactly how the address is determined for your
+environment, or you're adding a network layer in front of it, contact your
+account team or [support](mailto:support@zuplo.com). Adding a hop in front of
+the gateway changes which address the gateway sees, as described in
+[Running your own CDN or proxy in front of Zuplo](#running-your-own-cdn-or-proxy-in-front-of-zuplo).
+
+## Self-hosted deployments
+
+On a self-hosted deployment you run the proxy in front of the gateway, so
+determining the client address is yours to configure. The gateway reads it from
+the `x-real-ip` request header.
+
+Your proxy must **overwrite** that header rather than pass one through. If a
+client-supplied `x-real-ip` reaches the gateway untouched, any caller can choose
+its own address by sending it. NGINX's `real_ip` module does this correctly by
+default. Confirm the behavior against your own configuration before relying on
+the address for anything security-sensitive.
+
+:::warning
+
+A gateway reachable directly, with no proxy in front of it, has nothing
+determining the client address. Don't expose a self-hosted gateway to the
+internet directly if you rely on the client IP.
+
+:::
+
+## Geolocation
+
+To act on where a caller is rather than their address,
+`incomingRequestProperties` already carries resolved geolocation — `country`,
+`city`, `region`, `latitude`, `longitude`, `asn`, and more. There's no need to
+geolocate the IP address yourself. See
+[ZuploContext](../programmable-api/zuplo-context.mdx#incomingrequestproperties).

package/docs/policies/ai-gateway-model-filtering-v2-inbound/doc.md

@@ -1,9 +1,73 @@
 # AI Gateway Model Filtering (v2) Policy
 
-Use this policy to control which models clients may select on AI Gateway routes.
-Model references use `providerName/model`; the first slash separates the
-Provider Name configured in the Zuplo Portal from the provider-specific model
-ID.
+Use this policy when an AI Gateway route must restrict which models clients may
+select. The policy is optional.
+
+Choose the setup that matches the route:
+
+- Omit Model Filtering to let each request select any available model. Every
+  request must provide `model` as `providerName/model`.
+- Use an `allowList` to expose a curated set of models and provide a default
+  model.
+- Use a `blockList` to permit available models except for specific exclusions.
+- Use a custom routing policy when model selection depends on request data or
+  application logic that an allow list or block list cannot express.
+
+`providerName` is the Provider Name configured in the Zuplo Portal. The text
+after the first slash is the provider-specific model ID, so model IDs may
+contain additional slashes.
+
+## Routing without Model Filtering
+
+When neither Model Filtering nor a custom routing policy selects a model, the AI
+Gateway handler reads the request body's `model` and uses it as the primary
+routing target:
+
+```json
+{
+  "model": "openai/gpt-4o-mini",
+  "messages": [{ "role": "user", "content": "Hello" }]
+}
+```
+
+The handler validates that:
+
+- `model` is a string in `providerName/model` form;
+- the Provider Name is configured;
+- the model is available for the route's capability;
+- the Provider Assignment has usable credentials.
+
+Missing, bare, non-string, or malformed model values receive an
+OpenAI-compatible 400 `invalid_request_error`. A validly formatted target that
+cannot be fulfilled is reported as a routing configuration error with a
+suggested fix.
+
+When Semantic Cache is attached, a cache hit also validates request-derived
+routing before returning the cached response. A removed, deprecated, or
+otherwise unavailable target therefore follows the same routing configuration
+error path instead of bypassing validation with a cached response. Native route
+requirements are checked too, so an Anthropic Messages cache hit cannot be
+served by an OpenAI-backed Provider Name.
+
+Attach Model Filtering only when the gateway must enforce model-selection rules.
+An attached policy must always have a valid, non-empty `models` configuration.
+
+### Responses management operations
+
+These Responses API operations do not have a request body:
+
+- `GET /v1/responses/:responseId`
+- `GET /v1/responses/:responseId/input_items`
+- `DELETE /v1/responses/:responseId`
+
+Because they cannot supply `model`, they require routing to be selected before
+the handler runs. Configure a `completions.allowList` in Model Filtering so its
+first entry supplies the default, or use a custom inbound policy that calls
+`AIGatewayModelRouting.set(context, { completions: "providerName/model" })`.
+Without preselected routing, the handler returns an OpenAI-compatible 400
+`invalid_request_error` with this configuration guidance.
+
+## Policy order
 
 Place Model Filtering before Fallback Model in the inbound policy chain:
 
@@ -13,7 +77,8 @@ Model Filtering -> Fallback Model -> AI Gateway handler
 
 Model Filtering accepts or rejects the request and creates the primary model
 selection. Fallback Model can then enrich that allowed selection without
-bypassing the filter.
+bypassing the filter. Fallback Model does not create a primary selection by
+itself.
 
 ## Options
 
@@ -25,9 +90,17 @@ chooses exactly one mode:
 - `blockList` leaves the catalog open except for named models. Every request
   must include `model`.
 
-Every list entry is a plain `providerName/model` string. Matching is
-case-insensitive, while configured casing is preserved for the upstream request.
-Route-target objects and fallback fields belong in the Fallback Model policy.
+Each configured list must contain at least one entry. A capability cannot define
+both `allowList` and `blockList`, and unsupported fields are rejected. Every
+list entry is a plain `providerName/model` string. Matching is case-insensitive,
+while configured casing is preserved for the upstream request. Route-target
+objects and fallback fields belong in the Fallback Model policy.
+
+Configure every capability served by a route using this policy. A route using
+`/v1/embeddings` needs `embeddings`; Chat Completions, Responses, and Anthropic
+Messages routes need `completions`. If the policy is attached but the active
+capability has no rules, the request receives a 403 response explaining which
+capability to add.
 
 ## Allow-list example
 
@@ -70,14 +143,30 @@ reported as warnings because they cannot match a request.
 
 ## Request behavior
 
-`/v1/embeddings` uses `embeddings`; Chat Completions, Responses, and Anthropic
-Messages use `completions`. Native routes also enforce their provider type:
-`/v1/responses` requires an OpenAI-backed Provider Name and `/v1/messages`
-requires an Anthropic-backed Provider Name.
+| Situation                                           | Result                                                 |
+| --------------------------------------------------- | ------------------------------------------------------ |
+| Allow list, request omits `model`                   | The first allow-list entry is selected.                |
+| Allow list, request names a listed model            | The matching configured entry is selected.             |
+| Allow list, request names an unlisted model         | 403 response listing the allowed models.               |
+| Block list, request omits `model`                   | 400 response asking for `providerName/model`.          |
+| Block list, request names a blocked model           | 403 response.                                          |
+| Either mode, request uses a bare or malformed model | 400 response explaining the required format.           |
+| Policy has no rules for the route capability        | 403 response explaining which capability to configure. |
+| Another inbound policy already selected routing     | Model Filtering leaves that selection unchanged.       |
 
-A bare model name receives a 400 response. An unlisted allow-list model or a
-blocked model receives a 403 response. If another policy has already selected a
-model, Model Filtering leaves that selection unchanged.
+Native routes also enforce provider type. `/v1/responses` requires a Provider
+Name backed by OpenAI, and `/v1/messages` requires a Provider Name backed by
+Anthropic. Provider Names may be custom labels; validation uses the provider
+type configured for that Provider Assignment.
+
+For example, this embedding request is evaluated against `models.embeddings`:
+
+```json
+{
+  "model": "openai/text-embedding-3-small",
+  "input": "Search text"
+}
+```
 
 ## Adding fallbacks
 
@@ -143,6 +232,18 @@ Attach the module as an ordinary inbound policy instead of Model Filtering:
 
 `AIGatewayModelRouting.get(context)` returns the sanitized, normalized routing
 for the current request and never returns credentials. The AI Gateway handler
-consumes a custom selection even when Model Filtering is not attached. Prefer
-one policy that creates the primary selection: Model Filtering preserves an
-existing selection, while a later custom policy can replace it.
+consumes a custom selection even when Model Filtering is not attached. If
+neither kind of policy creates a selection, the handler derives one from the
+request's required `providerName/model`.
+
+Policy order determines precedence:
+
+1. Routing selected before Model Filtering remains authoritative because Model
+   Filtering leaves an existing selection unchanged.
+2. Model Filtering creates routing when no earlier policy selected it.
+3. A custom policy placed after Model Filtering may deliberately replace that
+   selection.
+4. If no policy selects routing, the handler derives it from the request.
+
+Prefer one policy as the primary selector so the route's intent is easy to
+understand.

package/docs/programmable-api/zuplo-context.mdx

@@ -48,9 +48,15 @@ const elapsed = Date.now() - context.custom.startTime;
 
 ### `incomingRequestProperties`
 
-Information about the incoming request such as geolocation data. This is a
-read-only object with the following properties:
-
+Information about the incoming request such as the client IP address and
+geolocation data. This is a read-only object with the following properties:
+
+- `ip` - The IP address of the client that made the request, for example,
+  "203.0.113.7". This is the only supported way to read the client IP; don't
+  read an IP header from `request.headers` yourself. The value is `undefined`
+  when nothing identified the caller. See
+  [how to check an incoming IP address](../articles/check-ip-address.mdx) for
+  when the address can be trusted on each deployment type.
 - `asn` - ASN of the incoming request, for example, 395747.
 - `asOrganization` - The organization which owns the ASN of the incoming
   request, for example, Google Cloud.

package/package.json

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