zuplo 6.71.0 → 6.71.2

package/docs/articles/graphql.mdx

@@ -8,29 +8,27 @@ tags:
   - backends
 ---
 
-Zuplo fronts GraphQL APIs the same way it fronts REST: requests pass through a
-gateway route — with whatever authentication, rate limiting, and
-GraphQL-specific policies you attach — and your Dev Portal documents the schema.
-This guide covers both halves: adding a GraphQL endpoint to your gateway routes,
-then rendering a schema reference and playground in the Dev Portal with
-`@zudoku/plugin-graphql`.
-
-## Prerequisites
-
-- A Zuplo project
-- An upstream GraphQL API to proxy
-- For the Dev Portal section: your project's
-  [Dev Portal](../dev-portal/introduction.mdx) lives in its `docs/` folder. The
-  plugin requires the `zudoku` package version `0.80.1` or newer — check the
-  version in `docs/package.json` and
-  [update the Dev Portal](../dev-portal/updating.mdx) if yours is older.
+Zuplo fronts a GraphQL API like any other backend: requests pass through a
+gateway route with the policies you attach, and your Dev Portal documents the
+schema. This guide proxies the endpoint, reports failed operations to analytics,
+and publishes a schema reference and playground.
+
+:::tip{title="TL;DR"}
+
+- [ ] Proxy your GraphQL endpoint through a route with the URL Rewrite handler
+- [ ] Tag the route with the `x-graphql` extension so the Portal recognizes it
+- [ ] Surface failed operations with the `graphql-analytics-outbound` policy
+- [ ] Publish a schema reference and playground with the `graphqlPlugin` for the
+      Developer Portal
+
+:::
 
 ## Add a GraphQL endpoint to your gateway
 
-A GraphQL API serves every query and mutation from a single endpoint, so the
-gateway route uses the [URL Rewrite handler](../handlers/url-rewrite.mdx) —
-every request goes to exactly the upstream URL — rather than URL Forward, which
-appends the incoming path.
+Because GraphQL uses a single endpoint, the route uses the
+[URL Rewrite handler](../handlers/url-rewrite.mdx) — every request goes to
+exactly the upstream URL — rather than URL Forward, which appends the incoming
+path.
 
 ### Add a new GraphQL route
 
@@ -45,10 +43,11 @@ appends the incoming path.
 2. **Add the endpoint**
 
    Click **Add** and select **GraphQL Endpoint**. This creates a `POST /graphql`
-   route preconfigured with the URL Rewrite handler and a demo upstream. If
-   `/graphql` is already taken, the Portal appends a short suffix (for example
-   `/graphql-b891`) — edit the path to whatever you prefer. GraphQL routes show
-   a **GraphQL** badge in the route list instead of an HTTP method.
+   route preconfigured with the URL Rewrite handler, a demo upstream, and the
+   [GraphQL Analytics policy](#report-failed-operations-to-analytics) for error
+   reporting. If `/graphql` is already taken, the Portal appends a short suffix
+   (for example `/graphql-b891`) — edit the path to whatever you prefer. GraphQL
+   routes show a **GraphQL** badge in the route list instead of an HTTP method.
 
 3. **Point it at your upstream**
 
@@ -106,44 +105,100 @@ set:
 
 :::tip{title="Secure the endpoint"}
 
-GraphQL has its own attack surface — deeply nested queries, expensive
-operations, and schema introspection. Zuplo ships policies for all three. See
+Zuplo ships policies for query depth, complexity, and introspection. See
 [Secure your GraphQL API](./graphql-security.mdx) to add complexity limits and
 disable introspection in production.
 
 :::
 
-## Document the API in your Dev Portal
+## Report failed operations to analytics
+
+Failed GraphQL operations return `200 OK` with an `errors[]` array in the body
+(the Apollo Server and graphql-yoga convention). HTTP-level analytics read that
+`200` as a success, so those failures never show up on the
+[GraphQL analytics dashboard](../analytics/tabs/graphql.md).
 
-The `@zudoku/plugin-graphql` package renders GraphQL APIs in your Dev Portal
-from a schema. Each plugin instance produces a browsable type reference
-(queries, mutations, objects, enums, and so on) plus a playground, generated
-straight from your schema.
+The **GraphQL Analytics** policy closes that gap. It reads each response body,
+counts the GraphQL errors, and classifies every one by its `extensions.code` —
+`syntax`, `validation`, `auth`, `timeout`, or `resolver` — so failed operations
+appear on the dashboard as failures, broken down by error class. The response
+passes through to the client unchanged.
 
 :::caution{title="Beta"}
 
-The GraphQL plugin is in beta. During the beta it isn't available in your
-project's working copy — it only works in projects
-[connected to source control](./source-control.mdx).
+The GraphQL Analytics policy is in beta. You can use it today, but it may change
+in non-backward compatible ways before the final release.
 
 :::
 
-<Stepper>
+New GraphQL endpoints include this policy automatically — the
+[Add a new GraphQL route](#add-a-new-graphql-route) flow attaches a
+`graphql-analytics-outbound` policy to the route's `outbound` chain, so error
+reporting works out of the box. If you instead
+[marked an existing route as GraphQL](#mark-an-existing-route-as-graphql), add a
+`graphql-analytics-outbound` policy and reference it in that route's `outbound`
+list.
+
+Tune the policy by editing its `options` in `config/policies.json`. Out of the
+box it classifies the standard Apollo error codes — for example, it reports
+`GRAPHQL_VALIDATION_FAILED` as `validation` and `UNAUTHENTICATED` as `auth` —
+and falls back to `resolver` for anything it doesn't recognize:
+
+```json title="config/policies.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"
+          },
+          "defaultErrorClass": "resolver",
+          "logErrors": true
+        }
+      }
+    }
+  ]
+}
+```
 
-1. **Install the plugin**
+- `errorCodeClassification` — Maps custom `extensions.code` values your server
+  emits to an error class. Entries merge over, and win against, the built-in
+  Apollo code map. Defaults to none.
+- `defaultErrorClass` — The class for an error whose code is missing or
+  unrecognized. One of `syntax`, `validation`, `auth`, `timeout`, or `resolver`.
+  Defaults to `resolver`.
+- `logErrors` — When `true`, also writes a structured warning to the request log
+  — the message, code, and path of each error, capped at the first 10 — for
+  every errored response. Defaults to `false`.
+- `maxResponseBytes` — The largest response body, in bytes, the policy inspects.
+  Larger responses pass through unscanned, so any errors they carry go
+  unreported. Defaults to `5242880` (5 MiB).
+
+See the
+[GraphQL Analytics policy reference](../policies/graphql-analytics-outbound.mdx)
+for the full classification table and schema.
 
-   Check `docs/package.json` first — new projects ship with
-   `@zudoku/plugin-graphql` already listed in `dependencies`, so there's nothing
-   to install. Only older projects need to add it. In your project's `docs/`
-   folder (where `zudoku.config.tsx` lives), install the plugin:
+## Document the API in your Dev Portal
 
-   ```bash
-   npm install @zudoku/plugin-graphql
-   ```
+The `@zudoku/plugin-graphql` package renders a browsable type reference and a
+playground in your Dev Portal, generated from your schema. Register one instance
+per API.
 
-   The plugin requires `zudoku` `0.80.1` or newer.
+:::caution{title="Beta"}
+
+The GraphQL plugin is in beta.
 
-2. **Register the plugin**
+:::
+
+<Stepper>
+
+1. **Register the plugin**
 
    Import `graphqlPlugin` and add an instance per API. The `path` is where the
    docs mount, and `input` points at your GraphQL endpoint:
@@ -168,11 +223,11 @@ project's working copy — it only works in projects
    export default config;
    ```
 
-   With `type: "url"`, the schema is fetched via introspection when the portal
-   builds, and the playground sends operations to that same URL by default.
-   Point `input` at the gateway route from the first half of this guide so
-   readers run real queries through your gateway — or keep the playground
-   separate from the schema source with `options.playground.endpoint`.
+   With `type: "url"`, the portal fetches the schema via introspection at build
+   time, and the playground sends operations to that same URL by default. Point
+   `input` at the gateway route from the first half of this guide so readers run
+   real queries through your gateway — or keep the playground separate from the
+   schema source with `options.playground.endpoint`.
 
    Have a GraphQL schema definition language (SDL) file instead of a live
    endpoint? Use `type: "file"` and set `input` to the file's path (for example
@@ -184,7 +239,17 @@ project's working copy — it only works in projects
    You can register the plugin more than once to document several schemas, each
    with its own `path`.
 
-3. **Link it in the navigation**
+   :::note
+
+   New projects ship with `@zudoku/plugin-graphql` in `dependencies` already.
+   Older projects might need to add it to `docs/package.json`. The plugin
+   requires `zudoku` version `0.80.1` or newer.
+   [Update the Dev Portal](../dev-portal/updating.mdx) to get the latest
+   version.
+
+   :::
+
+2. **Link it in the navigation**
 
    Point a navigation link at the instance's `path`. Set `stack: true` so the
    API's own pages render as a stacked sub-navigation instead of expanding
@@ -254,6 +319,8 @@ playground runs operations against your configured endpoint.
   introspection policies
 - [Testing GraphQL queries](./testing-graphql.mdx) — test the endpoint from the
   Zuplo Portal or external tools
+- [GraphQL analytics](../analytics/tabs/graphql.md) — monitor operation volume,
+  latency, and error classes once traffic flows
 - [URL Rewrite handler](../handlers/url-rewrite.mdx) — full reference for the
   handler GraphQL routes use
 - [MCP Server GraphQL endpoints](../mcp-server/graphql.mdx) — expose GraphQL

package/package.json

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