zuplo 7.7.9 → 7.7.11

package/docs/policies/ai-gateway-configuration-executor-v2-inbound/doc.md

@@ -355,34 +355,23 @@ have both actions, the `warn` value must be less than the `block` value. The
 policy does not treat entries whose `budgetBy` is `app` as expression budget
 rules.
 
-### Supported expressions
-
-Expressions read one string or safe integer from request-time data. Use these
-canonical forms when writing application configuration:
-
-| Source                      | Canonical expression example                |
-| --------------------------- | ------------------------------------------- |
-| Request URL or method       | `request.url`, `request.method`             |
-| One request header          | `request.headers.get("x-customer-id")`      |
-| Authenticated subject       | `request.user.sub`                          |
-| User data                   | `request.user.data.profile.organizationId`  |
-| Query parameter             | `request.query.customerId`                  |
-| Query parameter (map form)  | `request.searchParams.customerId`           |
-| Route parameter             | `request.params.productId`                  |
-| Custom context data         | `context.custom.account.id`                 |
-| Route data                  | `context.route.path`                        |
-| Incoming request data       | `context.incomingRequestProperties.country` |
-| Request or context identity | `request.user.sub`, `context.requestId`     |
-| A key requiring brackets    | `request.user.data["team-id"]`              |
-
-The `expression` field contains the complete expression. Do not wrap it in an
-interpolation marker such as `${...}`. Expressions use values from the request
-and context, including values set by earlier policies. Place policies that set
-these values before Semantic Cache. You can change an expression in the
+### Expressions
+
+An expression selects one value from the request or its context, such as
+`request.headers.get("x-user-id")` or `request.user.data["team-id"]`. Every
+distinct value gets its own budget.
+
+The expression grammar, the selectable properties, what a value must be, and
+what happens when an expression does not resolve are documented once, on the
+[AI Gateway Metering](/docs/policies/ai-gateway-metering-v2-inbound) policy
+page. The same grammar applies here.
+
+Two things are specific to application configuration. A policy that sets a value
+an expression reads must run before Semantic Cache, which can answer without
+reaching the rest of the chain. And you can change an expression in the
 application configuration without rebuilding or redeploying the gateway.
 
-JSON encoding and expression syntax are separate. When writing raw JSON, escape
-the double quotes required by a bracket segment:
+When writing raw JSON, escape the double quotes a bracket segment needs:
 
 ```json
 {
@@ -390,58 +379,14 @@ the double quotes required by a bracket segment:
 }
 ```
 
-After a JSON parser decodes this value, the expression is
+After a JSON parser decodes that value the expression is
 `request.user.data["team-id"]`; the backslashes are not part of its identity.
-Code that creates application configuration should build an ordinary string and
-let its JSON serializer handle the transport escaping:
+Code that builds application configuration should create an ordinary string and
+let its JSON serializer add the transport escaping.
 
-```ts
-const expression = 'request.user.data["team-id"]';
-const body = JSON.stringify({ expression });
-```
-
-Header expressions are terminal. Header names are case-insensitive; use
-lowercase in stored expressions. The parser accepts the canonical
-`request.headers.get("content-type")` form and the equivalent
-`request.headers.content-type` and `request.headers["content-type"]` forms. The
-canonical form keeps header access visually distinct from an ordinary object
-property.
-
-A dot property starts with an ASCII letter, `_`, or `$`, followed by those
-characters, ASCII digits, or hyphens. Canonical rendering uses quoted brackets
-for keys containing `$` or `-`, or any other non-identifier character. For
-example, `context.custom.team-id` is accepted and its canonical form is
-`context.custom["team-id"]`. Single- and double-quoted bracket properties are
-accepted. Whitespace immediately inside brackets is accepted but is not
-canonical.
-
-The selectable data model is:
-
-| Root      | Selectable properties                                                                                                                                                                                                                                           |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request` | `url`, `method`, `headers`, `user.sub`, `user.data`, `query`, `searchParams`, `params`, and the scalar Fetch request metadata `bodyUsed`, `cache`, `credentials`, `destination`, `integrity`, `keepalive`, `mode`, `redirect`, `referrer`, and `referrerPolicy` |
-| `context` | `contextId`, `requestId`, `custom`, `route`, and `incomingRequestProperties`                                                                                                                                                                                    |
-
-Expressions cannot read the request body, call logging or policy methods, or
-access properties outside this table.
-
-Expressions have these limits:
-
-- The expression is at most 1,024 UTF-8 bytes and contains well-formed Unicode.
-- Quoted keys are non-empty and do not contain double quotes, backslashes,
-  control characters, U+2028, or U+2029. String escapes are not supported.
-- Canonical expressions contain no syntax whitespace. Spaces inside a quoted key
-  are part of the key.
-- Wildcards, recursive descent, filters, numeric bracket indexes, calls other
-  than the terminal header `.get("name")`, function arguments, and roots other
-  than `request` and `context` are not supported. For example,
-  `request.url.substring(5, 1)` is not a supported expression.
-- Traversal reads own properties from plain objects and keys from declared Maps.
-  It does not traverse arrays, class instances, inherited properties, or the
-  property names `__proto__`, `constructor`, and `prototype`.
-
-An authentication policy can populate `request.user`. A custom policy earlier in
-the chain can derive a value and place it in a request header:
+An expression selects one value and cannot combine several. To budget by a
+composite value, compute it in a custom policy earlier in the chain and store it
+somewhere an expression can read:
 
 ```ts
 import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
@@ -463,19 +408,6 @@ The corresponding expression is `request.headers.get("x-budget-customer")`.
 Configuration code should create that ordinary string and pass the enclosing
 object to `JSON.stringify`; the serializer adds the JSON transport escaping.
 
-The expression chooses one value; it does not concatenate values, run
-JavaScript, or evaluate conditions. Compute composite values in an earlier
-policy and store the result in a supported request or context property.
-
-The selected value must be a string or a safe integer. The runtime converts the
-value to well-formed NFC Unicode and ignores it when it exceeds 256 UTF-8 bytes
-or contains control characters, U+2028, or U+2029. A missing or invalid value
-does not contribute to the rule for that request.
-
-Use consistent spelling for each expression. Different spellings, such as single
-quotes and double quotes, identify different budget rules even when they select
-the same value.
-
 Invalid budget rules and unsupported expressions are logged and skipped. Other
 valid rules continue to apply.
 

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

@@ -68,6 +68,162 @@ value of its expression. An action of `"warn"` notifies without blocking. An
 action of `"block"` activates the configured quota fallback or returns
 `429 Too Many Requests` when usage reaches the value.
 
+## Budget expressions
+
+A rule with `"budgetBy": "expression"` gives every distinct value of its
+expression its own budget. A daily cost budget of five dollars on
+`request.headers.get("x-user-id")` gives each user five dollars a day, rather
+than five dollars shared across all users.
+
+An expression selects one value from the request or its context. It is a
+selector, not code: there are no comparisons, arithmetic, string concatenation,
+or method calls other than the header accessor below.
+
+### Supported expressions
+
+| Expression                                 | Example                                     | Selects                                                         |
+| ------------------------------------------ | ------------------------------------------- | --------------------------------------------------------------- |
+| `request.headers.get("<name>")`            | `request.headers.get("x-user-id")`          | One request header. Header names are case-insensitive.          |
+| `request.query.<name>`                     | `request.query.tenant`                      | One query-string parameter.                                     |
+| `request.searchParams.<name>`              | `request.searchParams.tenant`               | One query-string parameter.                                     |
+| `request.params.<name>`                    | `request.params.customerId`                 | One path parameter from the matched route.                      |
+| `request.user.sub`                         | `request.user.sub`                          | The authenticated consumer's subject, such as the API key name. |
+| `request.user.data.<property>`             | `request.user.data.organizationId`          | A property of the consumer's metadata, including nested ones.   |
+| `request.<property>`                       | `request.method`                            | A scalar request property.                                      |
+| `context.custom.<property>`                | `context.custom.tenantId`                   | A value your own policies or handlers put on `context.custom`.  |
+| `context.route.<property>`                 | `context.route.path`                        | A property of the matched route, such as `path` or `label`.     |
+| `context.incomingRequestProperties.<name>` | `context.incomingRequestProperties.country` | A connection property, such as `country`, `city`, or `asn`.     |
+
+The selectable scalar request properties are `bodyUsed`, `cache`, `credentials`,
+`destination`, `integrity`, `keepalive`, `method`, `mode`, `redirect`,
+`referrer`, `referrerPolicy`, and `url`.
+
+Use quoted brackets for any key that is not a plain identifier:
+`request.query["team-id"]`, `context.custom["tenant.id"]`.
+
+`context.incomingRequestProperties` exposes connection data only: `country`,
+`city`, `region`, `regionCode`, `continent`, `colo`, `latitude`, `longitude`,
+`postalCode`, `metroCode`, `timezone`, `ip`, `asn`, `asOrganization`, and
+`httpProtocol`. Client-certificate and mTLS verification fields are not
+selectable. To budget per client certificate, run the mTLS Authentication policy
+first and select the metadata it attaches, such as
+`request.user.data.mtlsAuth.sha256Fingerprint`.
+
+An expression is limited to 1024 bytes and 32 property segments.
+
+### Examples
+
+Give every end user their own daily spend budget, keyed by a header your
+application sends:
+
+```json
+{
+  "budgetBy": "expression",
+  "expression": "request.headers.get(\"x-user-id\")",
+  "meters": [
+    { "meter": "cost", "period": "daily", "value": 5, "action": "block" }
+  ]
+}
+```
+
+Give every customer of yours their own monthly token budget, keyed by metadata
+on the API key that made the request:
+
+```json
+{
+  "budgetBy": "expression",
+  "expression": "request.user.data.organizationId",
+  "meters": [
+    {
+      "meter": "tokens",
+      "period": "monthly",
+      "value": 8000000,
+      "action": "warn"
+    },
+    {
+      "meter": "tokens",
+      "period": "monthly",
+      "value": 10000000,
+      "action": "block"
+    }
+  ]
+}
+```
+
+Cap requests per tenant per hour, keyed by a path parameter on a route such as
+`/tenants/:tenantId/chat`:
+
+```json
+{
+  "budgetBy": "expression",
+  "expression": "request.params.tenantId",
+  "meters": [
+    {
+      "meter": "requests",
+      "period": "hourly",
+      "value": 1000,
+      "action": "block"
+    }
+  ]
+}
+```
+
+### Values
+
+An expression must resolve to a string or a safe integer. The runtime converts
+the value to well-formed NFC Unicode, and ignores it when it exceeds 256 UTF-8
+bytes or contains control characters, U+2028, or U+2029. Values are
+case-sensitive, so `Acme` and `acme` get separate budgets, but two strings that
+normalize to the same NFC text share one budget.
+
+When an expression resolves to nothing, or to something else such as an object,
+an array, or a fractional number, that rule does not count or block the request.
+Other rules still apply. Pair a rule on a value you must enforce with a policy
+that rejects requests missing it, such as API key authentication or request
+validation.
+
+### Not supported
+
+| Not supported                                        | Use instead                                                         |
+| ---------------------------------------------------- | ------------------------------------------------------------------- |
+| Request body values, such as `request.body.userId`   | A header, a query parameter, a path parameter, or API key metadata. |
+| Whole objects, such as `request.headers`             | One value, such as `request.headers.get("x-user-id")`.              |
+| Comparisons, `&&`, ternaries, and literals           | One selector per rule. An application can have up to five rules.    |
+| String methods, such as `.toLowerCase()`             | The value as the client sends it.                                   |
+| Wildcards and multiple keys in one expression        | One rule per value you want to budget.                              |
+| Arrays, class instances, and inherited properties    | A plain value the gateway or your own policy sets.                  |
+| Per-request identifiers, such as `context.requestId` | A value shared by many requests, such as a user or tenant.          |
+
+An unsupported expression does not fail the request. The rule is skipped, and
+the request is not budgeted by it.
+
+### Keep the spelling stable
+
+Each expression is stored exactly as you write it, and its budgets are tracked
+under that exact text. `request.headers.get("x-user-id")` and
+`request.headers["x-user-id"]` read the same header but keep separate budgets,
+and editing a rule's expression starts its budgets over. Single quotes and
+double quotes likewise identify different rules. Use the spellings in the table
+above.
+
+Several forms parse, so prefer the canonical one. A header is written
+`request.headers.get("content-type")`, with a lowercase name; the equivalent
+`request.headers.content-type` and `request.headers["content-type"]` are
+accepted but keep separate budgets. A dot property starts with a letter, `_`, or
+`$`; a key containing anything else takes quoted brackets, so
+`context.custom.team-id` is canonically `context.custom["team-id"]`.
+
+In raw JSON, escape the double quotes a bracket segment needs:
+
+```json
+{
+  "expression": "request.user.data[\"team-id\"]"
+}
+```
+
+After a JSON parser decodes that value the expression is
+`request.user.data["team-id"]`; the backslashes are not part of its identity.
+
 ## Team limits
 
 Application budgets apply only to that application. Parent team and gateway

package/docs/policies/ai-gateway-metering-v2-inbound/intro.md

@@ -3,6 +3,10 @@ requests and enforces spend, token, and request budgets. When a limit is
 exceeded, it uses the model selection's quota fallback when one is configured or
 returns `429 Too Many Requests`.
 
+A budget rule covers the whole application, or gives every distinct value of an
+expression its own budget, such as one budget per user with
+`request.headers.get("x-user-id")`.
+
 Place it after Model Filtering and Fallback Model, and before policies such as
 Semantic Cache that may answer without calling a provider. Metering fails open
 by default when its service is unavailable; set `throwOnFailure` to `true` to

package/docs/policies/ai-gateway-metering-v2-inbound/schema.json

@@ -77,17 +77,19 @@
                 "properties": {
                   "budgetBy": {
                     "type": "string",
-                    "enum": ["app", "expression"]
+                    "enum": ["app", "expression"],
+                    "description": "Budget the application as a whole (\"app\"), or give every distinct value of an expression its own budget (\"expression\")."
                   },
                   "expression": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Required when budgetBy is \"expression\"; forbidden for \"app\". Each distinct value gets its own budget."
+                    "description": "Required when budgetBy is \"expression\"; forbidden for \"app\". Each distinct value gets its own budget. Select one value from the request or its context: request.headers.get(\"x-user-id\"), request.query.tenant, request.params.customerId, request.user.sub, request.user.data.organizationId, request.method, request.url, context.custom.tenantId, context.route.path, or context.incomingRequestProperties.country. Comparisons, arithmetic, string methods, and request body values are not supported."
                   },
                   "meters": {
                     "type": "array",
                     "minItems": 1,
                     "maxItems": 24,
+                    "description": "Thresholds this rule enforces. Add one entry per meter, period, and action you want.",
                     "items": {
                       "type": "object",
                       "additionalProperties": false,
@@ -95,19 +97,23 @@
                       "properties": {
                         "meter": {
                           "type": "string",
-                          "enum": ["cost", "requests", "tokens"]
+                          "enum": ["cost", "requests", "tokens"],
+                          "description": "What to measure: US dollars spent (\"cost\"), requests made (\"requests\"), or tokens used (\"tokens\")."
                         },
                         "period": {
                           "type": "string",
-                          "enum": ["hourly", "daily", "weekly", "monthly"]
+                          "enum": ["hourly", "daily", "weekly", "monthly"],
+                          "description": "How often usage resets."
                         },
                         "value": {
                           "type": "number",
-                          "exclusiveMinimum": 0
+                          "exclusiveMinimum": 0,
+                          "description": "The threshold for this meter and period. Cost is in US dollars."
                         },
                         "action": {
                           "type": "string",
-                          "enum": ["warn", "block"]
+                          "enum": ["warn", "block"],
+                          "description": "What happens at the threshold: \"warn\" notifies and lets the request through, \"block\" uses the configured quota fallback model or returns 429 Too Many Requests."
                         }
                       }
                     }

package/docs/self-hosted/install.md

@@ -168,4 +168,38 @@ Certificates can't be issued until these records resolve. cert-manager checks
 the challenge URL from inside the cluster before it contacts the certificate
 authority.
 
-Next, [verify your installation](./verify.md).
+## Verify your installation
+
+Use the [Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor)
+to check the installation. Doctor is a CLI that reads your installation through
+your kubeconfig and probes its DNS, TLS, and HTTP endpoints. It checks the Helm
+release, the `Configuration` resource, Deployment health, ingress reachability,
+certificate issuance, DNS records, the management API, and the builder
+configuration. It reads the installation and doesn't change it.
+
+Download the archive for your machine from the
+[releases page](https://github.com/zuplo/self-hosted-doctor/releases), verify
+its checksum, extract it, and run the full suite against your current kubeconfig
+context:
+
+```bash
+./zuplo-self-hosted-doctor verify
+```
+
+Doctor exits `0` when no check failed, `1` when a check failed, and `3` when it
+couldn't run. Each warning and failure names a diagnostic step and links to the
+matching entry in [Troubleshooting](./troubleshooting.md).
+
+To also check authenticated access to the management API, set `ZUPLO_API_KEY` in
+your shell before running `verify`. Without a key, Doctor checks only that
+unauthenticated requests are rejected.
+
+The repository's README covers selecting individual checks, comparing a local
+values file, private certificate authorities, and JSON output.
+
+:::note
+
+Doctor doesn't deploy a project. To confirm the full build-and-serve path, run
+`npx zuplo deploy` against your account after Doctor passes.
+
+:::

package/docs/self-hosted/overview.md

@@ -184,10 +184,10 @@ images, and the credentials to pull them.
 ## Get started
 
 1. Review the [requirements](./requirements.md) and run the preflight checks.
-2. [Install](./install.md) the Helm chart.
-3. [Verify the installation](./verify.md), including a complete deployment.
-4. [Upgrade](./upgrade.md) to later chart versions when needed.
-5. Use [troubleshooting](./troubleshooting.md) to resolve installation and
+2. [Install](./install.md) the Helm chart, then verify the installation with the
+   [Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor) CLI.
+3. [Upgrade](./upgrade.md) to later chart versions when needed.
+4. Use [troubleshooting](./troubleshooting.md) to resolve installation and
    deployment errors.
 
 To discuss your specific requirements,

package/docs/self-hosted/troubleshooting.md

@@ -202,8 +202,9 @@ to HTTPS.
 
 This redirect doesn't affect certificate issuance. cert-manager creates a
 separate challenge Ingress that continues to serve on port 80. To test the
-ingress, use a hostname with no Ingress, as described in
-[Verify your install](./verify.md).
+ingress, use a hostname with no Ingress. The
+[Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor) CLI does
+this for you in its `ingress-reachable` check.
 
 ## Failed to deploy the environment but the cluster shows the build succeeding
 

package/docs/self-hosted/upgrade.md

@@ -41,13 +41,13 @@ installed with `helm plugin install https://github.com/databus23/helm-diff`.
 
 ## Verify the upgrade
 
-Work through [Verify your install](./verify.md) again. The gateway deployments
-already in the cluster keep serving through the upgrade; they are rebuilt only
-when you deploy them.
+Run the [Zuplo self-hosted doctor](https://github.com/zuplo/self-hosted-doctor)
+CLI again and confirm the release history records the new revision. The gateway
+deployments already in the cluster keep serving through the upgrade; they are
+rebuilt only when you deploy them.
 
 ```bash
-kubectl wait --for=condition=Available deployment --all \
-  -n zuplo-system --timeout=5m
+./zuplo-self-hosted-doctor verify
 helm history zuplo -n zuplo
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.7.9",
+  "version": "7.7.11",
   "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.7.9",
-    "@zuplo/core": "7.7.9",
-    "@zuplo/runtime": "7.7.9",
-    "@zuplo/test": "7.7.9"
+    "@zuplo/cli": "7.7.11",
+    "@zuplo/core": "7.7.11",
+    "@zuplo/runtime": "7.7.11",
+    "@zuplo/test": "7.7.11"
   }
 }