zuplo 6.70.70 → 6.71.0

package/docs/policies/data-loss-prevention-outbound/doc.md

@@ -0,0 +1,115 @@
+This policy inspects the body of each upstream response for sensitive data and
+applies a configurable action. It is the outbound counterpart to the
+[Data Loss Prevention - Inbound](/docs/policies/data-loss-prevention-inbound)
+policy, which inspects incoming requests.
+
+Detection happens entirely inside the gateway isolate — response bodies are
+never sent to a third-party service.
+
+## Actions
+
+- **`mask`** (default) — every detected value is replaced with the `mask` string
+  and the modified response is returned to the client. Overlapping matches are
+  merged and masked once.
+- **`block`** — the response is replaced with a `422 Unprocessable Content`. The
+  problem detail lists only the names of the detected entities, never the
+  matched values, so the policy never leaks the data it caught.
+- **`log`** — a structured warning is written (entity ids and counts only) and
+  the response is returned unchanged.
+
+## Built-in recognizers
+
+Enable entities individually or by **group selector** in the `entities` option,
+or omit it to use the full catalog. Entity ids follow a
+`{category}-{scope}-{name}` taxonomy, and any dash-aligned prefix of an id is a
+valid selector: `secret` enables every secret, `id-au` enables Australia's
+identifiers, `secret-aws` enables both AWS entities. Two named groups (`pii`,
+`region-eu`) bundle entities across categories.
+
+| Group       | Entities                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `secret`    | `secret-private-key`, `secret-jwt`, `secret-aws-access-key`, `secret-aws-bedrock`, `secret-github`, `secret-gitlab`, `secret-zuplo`, `secret-openai`, `secret-anthropic`, `secret-google-api-key`, `secret-stripe`, `secret-slack`, `secret-discord-webhook`, `secret-npm`, `secret-pypi`, `secret-sendgrid`, `secret-twilio`, `secret-hugging-face`, `secret-databricks`, `secret-shopify`, `secret-square`, `secret-mailchimp`, `secret-mailgun`, `secret-postman`, `secret-terraform`, `secret-sentry`, `secret-digitalocean`, `secret-heroku`, `secret-perplexity`, `secret-azure-client`, `secret-telegram-bot` |
+| `finance`   | `finance-credit-card` (Luhn), `finance-iban` (per-country length + mod-97), `finance-crypto-wallet`, `finance-us-aba-routing` (checksum), `finance-swift-bic`, `finance-us-bank-account`, `finance-cvv`                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `id`        | `id-us-ssn`, `id-us-itin`, `id-us-passport`, `id-uk-nino`, `id-uk-nhs` (mod-11), `id-ca-sin` (Luhn), `id-au-abn`, `id-au-acn`, `id-au-tfn`, `id-au-medicare` (all checksummed), `id-in-aadhaar` (Verhoeff), `id-in-pan`, `id-sg-nric` (checksum), `id-es-nif` (checksum), `id-it-fiscal-code` (checksum), `id-pl-pesel` (checksum), `id-nl-bsn` (11-proef), `id-br-cpf` (checksum), `id-fr-nir` (mod-97)                                                                                                                                                                                                             |
+| `contact`   | `contact-email`, `contact-phone`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `network`   | `network-ipv4`, `network-ipv6`, `network-mac`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `pii`       | `contact` + `id`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Prefixes    | `id-us`, `id-uk`, `id-au`, `id-ca`, `id-in`, `id-sg`, `id-es`, `id-it`, `id-pl`, `id-nl`, `id-br`, `id-fr`, `finance-us`, `secret-aws` — everything whose id starts with that prefix                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `region-eu` | `id-es-nif`, `id-it-fiscal-code`, `id-pl-pesel`, `id-nl-bsn`, `id-fr-nir`, `finance-iban`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+## Context-word scoring
+
+Every match gets a confidence score. Recognizers whose raw pattern is just "a
+run of digits" (bank accounts, routing numbers, NHS numbers, …) carry a low base
+confidence and a list of **context words**; when one of those words appears near
+the match — in prose, or in a JSON key, form field, or header-like label
+(`nhsNumber`, `routing_number`, `cvv:`) — the confidence is boosted above the
+detection threshold.
+
+For example, with the `id-uk-nhs` entity enabled, `{"nhsNumber": "9434765919"}`
+is masked while the same digits in `{"orderId": "9434765919"}` pass through
+untouched.
+
+The threshold is configurable via `minConfidence` (default `0.5`): lower it to
+detect context-dependent entities everywhere, raise it to keep only prefix- and
+checksum-validated matches.
+
+## Custom patterns
+
+Add your own recognizers with `customPatterns`. Each entry has a `name`, a
+JavaScript regular expression `pattern`, and optionally a `confidence` and
+`context` words to participate in context scoring. Invalid patterns are logged
+and skipped rather than failing the response. Remember to escape backslashes for
+JSON (for example `\\d` to match a digit).
+
+## Content types
+
+Only text-based bodies (JSON, XML, form-encoded, and `text/*`) are scanned;
+binary bodies pass through untouched. Override the allow-list with the
+`contentTypes` option if you need to scan a different set of content types.
+
+## Configuration
+
+- `engine`: The detection engine. Only `builtin` is available today.
+  **Default:** `builtin`
+- `entities`: Recognizer ids and/or group selectors (prefixes, `pii`,
+  `region-eu`) to enable. **Default:** all recognizers
+- `customPatterns`: Additional `{ name, pattern, confidence?, context? }` regex
+  recognizers
+- `action`: `mask`, `block`, or `log`. **Default:** `mask`
+- `mask`: Replacement string used when `action` is `mask`. **Default:**
+  `[REDACTED]`
+- `minConfidence`: Detection threshold (0-1). **Default:** `0.5`
+- `contentTypes`: Override the scannable content-type allow-list
+
+## Usage
+
+Apply this policy to outbound responses in your route configuration:
+
+```json
+{
+  "policies": [
+    {
+      "name": "data-loss-prevention-outbound",
+      "policyType": "data-loss-prevention-outbound",
+      "handler": {
+        "export": "DataLossPreventionOutboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "action": "mask",
+          "entities": ["secret", "finance", "id-us", "contact-email"],
+          "mask": "[REDACTED]",
+          "customPatterns": [
+            {
+              "name": "employee-id",
+              "pattern": "EMP-\\d{6}",
+              "confidence": 0.3,
+              "context": ["employee"]
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```

package/docs/policies/data-loss-prevention-outbound/intro.md

@@ -0,0 +1,18 @@
+The Data Loss Prevention (DLP) policy scans upstream response bodies for
+sensitive data — personally identifiable information (PII), secrets and API keys
+for dozens of vendors, payment and bank identifiers, and national IDs for many
+countries — using a catalog of 60+ built-in recognizers plus any custom patterns
+you add. When a match is found it takes a configurable action: mask the matches,
+block the response, or log a warning and let it through.
+
+Recognizers are selected individually or via entity groups (`secret`, `finance`,
+`pii`, `id-us`, `id-uk`, `region-eu`, …). Detection runs entirely in the gateway
+isolate using regular expressions, checksums (Luhn, mod-97, Verhoeff, and
+friends), and context-word scoring — no response data leaves the gateway. This
+is especially useful in front of APIs that interface with user-generated
+content, MCP servers, and AI consumers, where a response might otherwise leak
+data the client should never see.
+
+Pair with the
+[Data Loss Prevention - Inbound](/docs/policies/data-loss-prevention-inbound)
+policy to also scan incoming requests before they reach your handler.

package/docs/policies/data-loss-prevention-outbound/schema.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/data-loss-prevention-outbound.json",
+  "type": "object",
+  "title": "Data Loss Prevention",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Scans the upstream response body for sensitive data — PII, secrets, and financial identifiers — using an extensible catalog of built-in recognizers plus any custom patterns, and takes a configurable action when a match is found.\n\nThe action is one of `mask` (redact matches before returning the response), `block` (replace the response with a `422` listing the detected entity names only), or `log` (record a warning and return unchanged). Only text content types are inspected; binary bodies pass through untouched, and the body is read from a clone so the client still receives the original stream.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "DataLossPreventionOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "DataLossPreventionOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the Data Loss Prevention outbound policy. Scans the upstream response body for sensitive data and applies the configured action (mask, block, or log).",
+          "additionalProperties": false,
+          "required": [],
+          "examples": [
+            {
+              "action": "mask",
+              "entities": ["secret", "finance", "contact-email", "id-us-ssn"],
+              "mask": "[REDACTED]"
+            }
+          ],
+          "properties": {
+            "engine": {
+              "type": "string",
+              "enum": ["builtin"],
+              "default": "builtin",
+              "description": "The detection engine. Only `builtin` (in-isolate regex + checksum detection with context-word scoring) is available today. This is the extension point for a future hosted `presidio-service` mode; declaring it now keeps adding that mode an additive, non-breaking change."
+            },
+            "entities": {
+              "type": "array",
+              "description": "Built-in recognizer ids and/or group selectors to enable. Entity ids follow a {category}-{scope}-{name} taxonomy, and any dash-aligned id prefix acts as a selector (for example `secret` is every secret, `id-au` is Australia's identifiers, `secret-aws` is both AWS entities), plus the named groups `pii` and `region-eu`. Available selectors: `contact`, `finance`, `finance-us`, `id`, `id-au`, `id-br`, `id-ca`, `id-es`, `id-fr`, `id-in`, `id-it`, `id-nl`, `id-pl`, `id-sg`, `id-uk`, `id-us`, `network`, `pii`, `region-eu`, `secret`, `secret-aws`. When omitted, the full built-in catalog is used.",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "contact",
+                  "finance",
+                  "finance-us",
+                  "id",
+                  "id-au",
+                  "id-br",
+                  "id-ca",
+                  "id-es",
+                  "id-fr",
+                  "id-in",
+                  "id-it",
+                  "id-nl",
+                  "id-pl",
+                  "id-sg",
+                  "id-uk",
+                  "id-us",
+                  "network",
+                  "pii",
+                  "region-eu",
+                  "secret",
+                  "secret-aws",
+                  "contact-email",
+                  "contact-phone",
+                  "finance-credit-card",
+                  "finance-crypto-wallet",
+                  "finance-cvv",
+                  "finance-iban",
+                  "finance-swift-bic",
+                  "finance-us-aba-routing",
+                  "finance-us-bank-account",
+                  "id-au-abn",
+                  "id-au-acn",
+                  "id-au-medicare",
+                  "id-au-tfn",
+                  "id-br-cpf",
+                  "id-ca-sin",
+                  "id-es-nif",
+                  "id-fr-nir",
+                  "id-in-aadhaar",
+                  "id-in-pan",
+                  "id-it-fiscal-code",
+                  "id-nl-bsn",
+                  "id-pl-pesel",
+                  "id-sg-nric",
+                  "id-uk-nhs",
+                  "id-uk-nino",
+                  "id-us-itin",
+                  "id-us-passport",
+                  "id-us-ssn",
+                  "network-ipv4",
+                  "network-ipv6",
+                  "network-mac",
+                  "secret-anthropic",
+                  "secret-aws-access-key",
+                  "secret-aws-bedrock",
+                  "secret-azure-client",
+                  "secret-databricks",
+                  "secret-digitalocean",
+                  "secret-discord-webhook",
+                  "secret-github",
+                  "secret-gitlab",
+                  "secret-google-api-key",
+                  "secret-heroku",
+                  "secret-hugging-face",
+                  "secret-jwt",
+                  "secret-mailchimp",
+                  "secret-mailgun",
+                  "secret-npm",
+                  "secret-openai",
+                  "secret-perplexity",
+                  "secret-postman",
+                  "secret-private-key",
+                  "secret-pypi",
+                  "secret-sendgrid",
+                  "secret-sentry",
+                  "secret-shopify",
+                  "secret-slack",
+                  "secret-square",
+                  "secret-stripe",
+                  "secret-telegram-bot",
+                  "secret-terraform",
+                  "secret-twilio",
+                  "secret-zuplo"
+                ]
+              }
+            },
+            "customPatterns": {
+              "type": "array",
+              "description": "Additional customer-defined regex recognizers. Invalid patterns are logged and skipped rather than failing the response.",
+              "items": {
+                "type": "object",
+                "title": "DlpCustomPattern",
+                "additionalProperties": false,
+                "required": ["name", "pattern"],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Identifier reported in findings and block details for this pattern."
+                  },
+                  "pattern": {
+                    "type": "string",
+                    "description": "A JavaScript regular expression source string. Remember to escape backslashes for JSON (for example `\\\\d` for a digit)."
+                  },
+                  "confidence": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1,
+                    "default": 0.85,
+                    "description": "Base confidence (0-1) for matches of this pattern. The default of 0.85 is above the default detection threshold; combine a low value with `context` words for patterns that are only sensitive in context."
+                  },
+                  "context": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Context words that boost a match's confidence by 0.45 when one appears near the match (in the surrounding field, label, or key)."
+                  }
+                }
+              }
+            },
+            "action": {
+              "type": "string",
+              "enum": ["mask", "block", "log"],
+              "default": "mask",
+              "description": "What to do when sensitive data is detected. `mask` redacts matches before returning the response, `block` replaces the response with a 422 listing only the detected entity names, and `log` records a warning and returns the response unchanged."
+            },
+            "mask": {
+              "type": "string",
+              "default": "[REDACTED]",
+              "examples": ["[REDACTED]"],
+              "description": "The string that replaces detected values when `action` is `mask`."
+            },
+            "minConfidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.5,
+              "x-show-example": false,
+              "description": "Minimum confidence (0-1) a match must reach to count as a finding. Context-dependent recognizers (for example `finance-us-bank-account` or `finance-us-aba-routing`) sit below the default threshold of 0.5 until a context word near the match boosts them above it. Lower the threshold to surface them everywhere; raise it to keep only prefix- or checksum-validated matches."
+            },
+            "contentTypes": {
+              "type": "array",
+              "description": "Override the set of scannable content-type prefixes. When omitted, the built-in text content-type allow-list (JSON, XML, form-encoded, text/\\*) is used.",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "DataLossPreventionOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "action": "mask",
+            "entities": ["secret", "finance", "contact-email", "id-us-ssn"],
+            "mask": "[REDACTED]"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/graphql-analytics-outbound/doc.md

@@ -0,0 +1,93 @@
+This policy reads GraphQL `errors[]` from response bodies and reports them to
+Zuplo's GraphQL analytics, so operations that fail with the standard "`200 OK`
+with errors" pattern (Apollo Server, graphql-yoga, and most other GraphQL
+servers) show up as failures on the GraphQL dashboard instead of successes.
+
+The response always passes through to the client unchanged — the body is read
+from a clone, and any internal failure inside the policy is swallowed so error
+reporting can never break a request.
+
+## Requirements
+
+The route must be marked with `"x-graphql": true` in `routes.oas.json`. That
+marker is what enables GraphQL analytics for the route (one `graphql_operation`
+event per request); this policy enriches that event with the errors it finds in
+the response body. On a route without the marker the policy logs a warning and
+does nothing.
+
+## Error classification
+
+Each entry in the response's `errors[]` array counts as one error toward the
+operation's `errorCount`, and is classified into one of five classes from its
+`extensions.code`, following the Apollo Server conventions:
+
+| `extensions.code`                                                                                                                           | Class        |
+| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `GRAPHQL_PARSE_FAILED`                                                                                                                      | `syntax`     |
+| `GRAPHQL_VALIDATION_FAILED`, `BAD_USER_INPUT`, `PERSISTED_QUERY_NOT_FOUND`, `PERSISTED_QUERY_NOT_SUPPORTED`, `OPERATION_RESOLUTION_FAILURE` | `validation` |
+| `UNAUTHENTICATED`, `FORBIDDEN`                                                                                                              | `auth`       |
+| `REQUEST_TIMEOUT`, `TIMEOUT`, `GATEWAY_TIMEOUT`                                                                                             | `timeout`    |
+| `INTERNAL_SERVER_ERROR`, `DOWNSTREAM_SERVICE_ERROR`                                                                                         | `resolver`   |
+
+An error whose code is missing or unrecognized is classified as
+`defaultErrorClass` (`resolver` unless configured otherwise). Servers that emit
+their own codes can extend or override the table with `errorCodeClassification`;
+those entries are matched case-sensitively and win against the built-ins, which
+are matched case-insensitively.
+
+Batched (array) responses are supported — errors are collected across every
+result in the batch.
+
+## What is inspected
+
+Only responses with a JSON content type (`application/json` or any `+json` type
+such as `application/graphql-response+json`) are read, and bodies larger than
+`maxResponseBytes` (5 MiB by default) are skipped — by `Content-Length` when the
+header is present, or measured while reading when it is absent. Everything else
+passes through without the body being touched.
+
+## Logging
+
+Set `logErrors` to `true` to also write a structured warning to the request log
+whenever a response contains GraphQL errors. The entry carries the message,
+`extensions.code`, and path of each error (capped at the first 10) under a
+consistent `"GraphQL response contained errors"` message, so you can search or
+alert on it.
+
+## Configuration
+
+- `errorCodeClassification`: Additional `extensions.code` → class mappings,
+  merged over the built-in table. **Default:** none
+- `defaultErrorClass`: Class for errors with a missing or unrecognized code —
+  one of `syntax`, `validation`, `auth`, `timeout`, `resolver`. **Default:**
+  `resolver`
+- `logErrors`: Also log a structured warning per errored response. **Default:**
+  `false`
+- `maxResponseBytes`: Maximum response body size in bytes to inspect.
+  **Default:** `5242880` (5 MiB)
+
+## Usage
+
+Apply this policy to outbound responses on your GraphQL route:
+
+```json
+{
+  "policies": [
+    {
+      "name": "graphql-analytics",
+      "policyType": "graphql-analytics-outbound",
+      "handler": {
+        "export": "GraphqlAnalyticsOutboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "errorCodeClassification": {
+            "RATE_LIMITED": "resolver",
+            "NOT_LOGGED_IN": "auth"
+          },
+          "logErrors": true
+        }
+      }
+    }
+  ]
+}
+```

package/docs/policies/graphql-analytics-outbound/intro.md

@@ -0,0 +1,12 @@
+The GraphQL Analytics policy makes failed GraphQL operations visible on Zuplo's
+GraphQL analytics dashboard. GraphQL servers following the standard Apollo /
+graphql-yoga pattern return `200 OK` with an `errors[]` array in the response
+body when an operation fails — invisible to HTTP-level analytics, which would
+report every such operation as a success.
+
+Add this policy to a GraphQL route (marked `x-graphql: true`) and the gateway
+reads the response body, counts the GraphQL errors, and classifies each one by
+its `extensions.code` (syntax, validation, auth, timeout, or resolver) — no
+changes to your GraphQL server or client code required. The classification map
+is configurable for servers that emit custom error codes, and errors can
+optionally be written to the request log.

package/docs/policies/graphql-analytics-outbound/schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/graphql-analytics-outbound.json",
+  "type": "object",
+  "title": "GraphQL Analytics",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type.\n\nEach error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response. Bodies larger than `maxResponseBytes` (default 5 MiB) are not inspected.\n\nThe response always passes through unchanged — the body is read from a clone, and any internal failure is swallowed so reporting can never break the request. The route must be marked `x-graphql: true` in `routes.oas.json` (which enables GraphQL analytics for the route); without the marker the policy logs a warning and does nothing.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "GraphqlAnalyticsOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "GraphqlAnalyticsOutboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the GraphQL Analytics outbound policy. Reads GraphQL `errors[]` from the response body and reports them to Zuplo's GraphQL analytics.",
+          "additionalProperties": false,
+          "required": [],
+          "examples": [
+            {
+              "errorCodeClassification": {
+                "RATE_LIMITED": "resolver",
+                "NOT_LOGGED_IN": "auth"
+              },
+              "defaultErrorClass": "resolver",
+              "logErrors": false
+            }
+          ],
+          "properties": {
+            "errorCodeClassification": {
+              "type": "object",
+              "description": "Additional `extensions.code` → error-class mappings for codes your GraphQL server emits. Entries are merged over (and win against) the built-in Apollo-convention map (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` / `BAD_USER_INPUT` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`, `INTERNAL_SERVER_ERROR` → `resolver`). Keys are matched case-sensitively; built-in codes are matched case-insensitively.",
+              "additionalProperties": {
+                "type": "string",
+                "enum": ["syntax", "validation", "auth", "timeout", "resolver"]
+              }
+            },
+            "defaultErrorClass": {
+              "type": "string",
+              "enum": ["syntax", "validation", "auth", "timeout", "resolver"],
+              "default": "resolver",
+              "description": "The error class reported for a GraphQL error whose `extensions.code` is missing or not in the classification map."
+            },
+            "logErrors": {
+              "type": "boolean",
+              "default": false,
+              "description": "When `true`, also write a structured warning to the request log (message, `extensions.code`, and path of each error — capped at the first 10) whenever a response contains GraphQL errors."
+            },
+            "maxResponseBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 5242880,
+              "x-show-example": false,
+              "description": "Maximum response body size in bytes the policy will inspect. Larger bodies — by `Content-Length`, or measured while reading when the header is absent — pass through without being scanned, so their GraphQL errors (if any) go unreported. The default is 5 MiB."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "GraphqlAnalyticsOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "errorCodeClassification": {
+              "RATE_LIMITED": "resolver",
+              "NOT_LOGGED_IN": "auth"
+            },
+            "defaultErrorClass": "resolver",
+            "logErrors": false
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/programmable-api/background-dispatcher.mdx

@@ -13,7 +13,7 @@ groups entries and invokes your callback with batches at regular intervals.
 ```ts
 new BackgroundDispatcher<T>(
   dispatchFunction: (entries: T[]) => Promise<void>,
-  options: { msDelay: number }
+  options: { msDelay: number; name?: string }
 )
 ```
 
@@ -21,6 +21,7 @@ Creates a new background dispatcher instance.
 
 - `dispatchFunction` - Asynchronous function called with batched entries
 - `options.msDelay` - Milliseconds between dispatch calls (required, non-zero)
+- `options.name` - Optional name that identifies the dispatcher in error logs
 - `T` - The type of entries being batched
 
 ## Methods
@@ -30,7 +31,7 @@ Creates a new background dispatcher instance.
 Adds an entry to the batch queue for later dispatch.
 
 ```ts
-enqueue(entry: T, context: ZuploContext): void
+enqueue(entry: T): void
 ```
 
 ## Example
@@ -74,12 +75,9 @@ const backgroundDispatcher = new BackgroundDispatcher<ExampleEntry>(
 // This is an example Request Handler that used the component, a simple
 // "Hello World" handler.
 export default async function (request: ZuploRequest, context: ZuploContext) {
-  backgroundDispatcher.enqueue(
-    {
-      message: `new request on '${request.url}' with id ${context.requestId}`,
-    },
-    context,
-  );
+  backgroundDispatcher.enqueue({
+    message: `new request on '${request.url}' with id ${context.requestId}`,
+  });
 
   return "Hello World!";
 }

package/docs/programmable-api/zone-cache.mdx

@@ -18,7 +18,7 @@ time-to-live (TTL) after which it expires and is removed from the cache. Each
 cached object can be up to 512 MB in size.
 
 There's an demonstration of ZoneCache use in the
-[Per User Rate Limits Using a Database](../articles/per-user-rate-limits-using-db.mdx)
+[Per User Rate Limits Using a Database](../rate-limiting/per-user-rate-limits-using-db.mdx)
 example.
 
 ## Constructor

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

@@ -88,8 +88,9 @@ context.log.info({
 
 ### `log`
 
-A logger instance for debugging and monitoring. Logs appear in your log tail in
-the [Zuplo Portal](https://portal.zuplo.com/+/account/project/) and in your
+A logger instance for debugging and monitoring. Logs appear in the
+**Observability → Logs** view of your project in the
+[Zuplo Portal](https://portal.zuplo.com/+/account/project/) and in your
 integrated log solution (for example Datadog). Pre-production environments are
 typically set to **Info** log level, while production is set to **Error**.