zuplo 6.70.71 → 6.71.1

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

@@ -1,15 +1,15 @@
 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.
+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
+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.
 

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/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**.
 

package/package.json

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