@constructive-io/graphql-server 5.20.8 → 5.22.0

package/README.md

@@ -95,7 +95,7 @@ For the operational workflow, sampler output, and heap snapshot usage, see [docs
 - `GET /graphiql` -> GraphiQL UI
 - `GET /graphql` / `POST /graphql` -> GraphQL endpoint
 - `POST /graphql` (multipart) -> file uploads
-- `POST /flush` -> clears cached Graphile schema for the current API
+- `POST /flush` -> clears cached Graphile schema for the current API; mounted only when `API_FLUSH_TOKEN` is set, and requires `Authorization: Bearer $API_FLUSH_TOKEN`. Without the variable the route is not served (404) — operators deploying a schema-cache flush must set it on the server and on every caller. The `LISTEN/NOTIFY` invalidation path is unaffected.
 - `GET /debug/memory` -> memory/process/Graphile debug snapshot when observability is enabled
 - `GET /debug/db` -> PostgreSQL activity/locks/pool debug snapshot when observability is enabled
 
@@ -132,6 +132,8 @@ Configuration is merged from defaults, config files, and env vars via `@construc
 | `API_META_SCHEMAS`             | Meta schemas to query                 | `routing_public,metaschema_public,metaschema_modules_public` |
 | `API_ANON_ROLE`                | Anonymous role name                   | `administrator`                                               |
 | `API_ROLE_NAME`                | Authenticated role name               | `administrator`                                               |
+| `API_FLUSH_TOKEN`              | Bearer token required by `POST /flush`; route is not mounted when unset | empty                        |
+| `API_INTROSPECTION_ROLE`       | Role PostGraphile introspects as; unset means the pool's connecting role. Naming a role with fewer grants removes fields from the schema | empty |
 | `GRAPHQL_OBSERVABILITY_ENABLED` | Master switch for debug routes and sampler | `false`                                                  |
 | `GRAPHQL_DEBUG_SAMPLER_ENABLED` | Enables periodic NDJSON sampling when observability is on | `true`                                   |
 | `GRAPHQL_DEBUG_SAMPLER_INTERVAL_MS` | Sampler interval in milliseconds | `10000`                                                       |

package/diagnostics/debug-memory-snapshot.d.ts

@@ -1,6 +1,7 @@
 import v8 from 'node:v8';
 import { getCacheStats } from 'graphile-cache';
 import { getGraphileBuildStats } from '../middleware/observability/graphile-build-stats';
+import { getRefusalRecorderStats } from '../refusals/recorder';
 export interface DebugMemorySnapshot {
     pid: number;
     nodeEnv: string | undefined;
@@ -47,6 +48,8 @@ export interface DebugMemorySnapshot {
         keys: string[];
     };
     graphileBuilds: ReturnType<typeof getGraphileBuildStats>;
+    /** In-memory refusal counter + flusher state; null when no recorder is installed. */
+    refusals: ReturnType<typeof getRefusalRecorderStats>;
     uptimeMinutes: number;
     timestamp: string;
 }

package/diagnostics/debug-memory-snapshot.js

@@ -10,6 +10,7 @@ const server_utils_1 = require("@pgpmjs/server-utils");
 const graphile_cache_1 = require("graphile-cache");
 const graphile_1 = require("../middleware/graphile");
 const graphile_build_stats_1 = require("../middleware/observability/graphile-build-stats");
+const recorder_1 = require("../refusals/recorder");
 const toMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 const getDebugMemorySnapshot = () => {
     const mem = process.memoryUsage();
@@ -70,6 +71,7 @@ const getDebugMemorySnapshot = () => {
             keys: (0, graphile_1.getInFlightKeys)(),
         },
         graphileBuilds: (0, graphile_build_stats_1.getGraphileBuildStats)(),
+        refusals: (0, recorder_1.getRefusalRecorderStats)(),
         uptimeMinutes: process.uptime() / 60,
         timestamp: new Date().toISOString(),
     };

package/errors/graphql-response.d.ts

@@ -12,10 +12,24 @@
  */
 import type { ConstructiveError } from '@constructive-io/errors';
 import type { Response } from 'express';
+/** Transport-level overrides for a short-circuited response. */
+export interface GraphQLErrorResponseInit {
+    /**
+     * HTTP status to answer with, when 200 would hide the refusal from the
+     * machinery that has to act on it. Admission control is the case that needs
+     * it: the operation never reached the schema, and a client's backoff — and
+     * every proxy and load balancer between us — reads the status code, not a
+     * GraphQL error body.
+     */
+    status?: number;
+    /** Extra headers, e.g. `Retry-After` on a 429. */
+    headers?: Record<string, string>;
+}
 /**
  * Send a {@link ConstructiveError} as a GraphQL error response.
  *
- * Uses HTTP 200 per the GraphQL-over-HTTP convention: transport succeeded, the
- * operation did not. The error's own `http` hint travels in `extensions`.
+ * Defaults to HTTP 200 per the GraphQL-over-HTTP convention: transport
+ * succeeded, the operation did not. The error's own `http` hint travels in
+ * `extensions`.
  */
-export declare function respondWithGraphQLError(res: Response, error: ConstructiveError): void;
+export declare function respondWithGraphQLError(res: Response, error: ConstructiveError, init?: GraphQLErrorResponseInit): void;

package/errors/graphql-response.js

@@ -16,11 +16,14 @@ exports.respondWithGraphQLError = respondWithGraphQLError;
 /**
  * Send a {@link ConstructiveError} as a GraphQL error response.
  *
- * Uses HTTP 200 per the GraphQL-over-HTTP convention: transport succeeded, the
- * operation did not. The error's own `http` hint travels in `extensions`.
+ * Defaults to HTTP 200 per the GraphQL-over-HTTP convention: transport
+ * succeeded, the operation did not. The error's own `http` hint travels in
+ * `extensions`.
  */
-function respondWithGraphQLError(res, error) {
-    res.status(200).json({
+function respondWithGraphQLError(res, error, init = {}) {
+    if (init.headers)
+        res.set(init.headers);
+    res.status(init.status ?? 200).json({
         errors: [{ message: error.message, extensions: error.toExtensions() }],
     });
 }

package/esm/diagnostics/debug-memory-snapshot.js

@@ -4,6 +4,7 @@ import { SVC_CACHE_TTL_MS, svcCache } from '@pgpmjs/server-utils';
 import { getCacheStats } from 'graphile-cache';
 import { getInFlightCount, getInFlightKeys } from '../middleware/graphile';
 import { getGraphileBuildStats } from '../middleware/observability/graphile-build-stats';
+import { getRefusalRecorderStats } from '../refusals/recorder';
 const toMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 export const getDebugMemorySnapshot = () => {
     const mem = process.memoryUsage();
@@ -64,6 +65,7 @@ export const getDebugMemorySnapshot = () => {
             keys: getInFlightKeys(),
         },
         graphileBuilds: getGraphileBuildStats(),
+        refusals: getRefusalRecorderStats(),
         uptimeMinutes: process.uptime() / 60,
         timestamp: new Date().toISOString(),
     };

package/esm/errors/graphql-response.js

@@ -13,11 +13,14 @@
 /**
  * Send a {@link ConstructiveError} as a GraphQL error response.
  *
- * Uses HTTP 200 per the GraphQL-over-HTTP convention: transport succeeded, the
- * operation did not. The error's own `http` hint travels in `extensions`.
+ * Defaults to HTTP 200 per the GraphQL-over-HTTP convention: transport
+ * succeeded, the operation did not. The error's own `http` hint travels in
+ * `extensions`.
  */
-export function respondWithGraphQLError(res, error) {
-    res.status(200).json({
+export function respondWithGraphQLError(res, error, init = {}) {
+    if (init.headers)
+        res.set(init.headers);
+    res.status(init.status ?? 200).json({
         errors: [{ message: error.message, extensions: error.toExtensions() }],
     });
 }

package/esm/index.js

@@ -3,5 +3,5 @@ export * from './server';
 export { createApiMiddleware, getApiConfig, getSubdomain } from './middleware/api';
 export { createAuthenticateMiddleware } from './middleware/auth';
 export { cors } from './middleware/cors';
-export { flush, flushService } from './middleware/flush';
+export { createFlushMiddleware, flushService } from './middleware/flush';
 export { graphile } from './middleware/graphile';

package/esm/middleware/admission-control.js

@@ -0,0 +1,132 @@
+import './types'; // for Request type
+import { errors } from '@constructive-io/errors';
+import { clientIpFrom, ConcurrencyLimiter, DEFAULT_REQUEST_PROTECTION, RateWindow, trustedProxyHops } from '@constructive-io/express-context';
+import { Logger } from '@pgpmjs/logger';
+import { respondWithGraphQLError } from '../errors/graphql-response';
+import { recordRefusal } from '../refusals/recorder';
+const log = new Logger('admission');
+/**
+ * admission-control — the gate that decides whether a GraphQL request starts.
+ *
+ * The document gate rejects a *shape* and the timeout GUCs bound a *duration*;
+ * neither refuses a request that is individually reasonable. This does, on two
+ * axes:
+ *
+ *   1. **Concurrency**, per database. The thing being protected is this
+ *      process's PostgreSQL pool, so the counter is in-process and
+ *      `maxConcurrentRequests` is a per-replica budget — a cluster-wide number
+ *      would need shared state on the hot path to bound something that is not
+ *      shared. Over budget, a request waits up to `maxQueueWaitMs` for a slot
+ *      and is then refused; it never queues unbounded, because a queue that
+ *      outgrows the timeout is just latency with a memory cost.
+ *
+ *   2. **Rate**, per caller per route. Keyed on the client address rather than
+ *      the tenant, because a tenant-wide limit is spent *by* an anonymous
+ *      flood: exhausting it takes the tenant's own API down on the attacker's
+ *      behalf. This is abuse protection and fails closed, which is the opposite
+ *      of a billing quota (that serves and records overage) — the two must not
+ *      be conflated, and neither is a database write on the request path.
+ *
+ * @module middleware/admission-control
+ */
+/** Window the per-caller rate is counted over — `rateLimitRpm` is per minute. */
+const RATE_WINDOW_MS = 60_000;
+/** What a request is keyed by when it carries no resolved database. */
+const UNKNOWN_DATABASE = 'unknown';
+const protectionOf = (req) => req.requestProtection ?? DEFAULT_REQUEST_PROTECTION;
+/**
+ * The route half of the rate key.
+ *
+ * Per-route rather than per-request-line so a caller cannot spread a flood
+ * across query strings, and so a cheap route's traffic does not spend the
+ * budget an expensive one needs.
+ */
+const routeOf = (req) => `${req.method} ${req.baseUrl}${req.path}`;
+/** Seconds for a `Retry-After` header — the smallest honest whole number. */
+const retryAfterSeconds = (ms) => String(Math.max(Math.ceil(ms / 1000), 1));
+/**
+ * How far back through `X-Forwarded-For` to believe.
+ *
+ * `req.clientIp` and `req.ip` are both unusable as a limiter key here: this
+ * server sets `trust proxy` to a predicate that returns true unconditionally,
+ * and `request-ip` reads the *leftmost* forwarded entry regardless — so either
+ * one hands a caller a fresh key per request for the cost of a header. The
+ * fallback to 1 hop exists because the opposite failure is just as bad: behind
+ * an ingress with no hop count configured, every caller resolves to the
+ * ingress's address and one abuser throttles the whole tenant.
+ */
+const resolveHops = (req, configured) => {
+    if (typeof configured === 'number')
+        return configured;
+    const fromEnv = trustedProxyHops();
+    if (fromEnv > 0)
+        return fromEnv;
+    return req.app?.get('trust proxy') ? 1 : 0;
+};
+/**
+ * Rate-limit callers per route, then admit at most `maxConcurrentRequests` of
+ * them per database into the handler chain.
+ *
+ * Mount after `createRequestProtectionMiddleware` (which resolves the bounds
+ * this reads) and before the GraphQL handler. Order within the middleware
+ * matters: the rate check is O(1) and runs first, so a flood is refused
+ * without ever occupying a concurrency slot or waiting in its queue.
+ */
+export const createAdmissionControlMiddleware = (options = {}) => {
+    const concurrency = new ConcurrencyLimiter();
+    const rate = new RateWindow(RATE_WINDOW_MS);
+    return async (req, res, next) => {
+        const protection = protectionOf(req);
+        const databaseId = req.databaseId ?? UNKNOWN_DATABASE;
+        // ─── Per-caller rate ────────────────────────────────────────────────────
+        const hops = resolveHops(req, options.trustedProxyHops);
+        const ip = clientIpFrom(req, hops);
+        const rateKey = `${databaseId}\u0000${ip}\u0000${routeOf(req)}`;
+        if (!rate.admit(rateKey, protection.rateLimitRpm, protection.rateLimitBurst)) {
+            log.warn(`[admission] rate limit: database=${databaseId} ip=${ip} route=${routeOf(req)}`);
+            recordRefusal(req, 'rate_limited', { sourceIp: ip });
+            respondWithGraphQLError(res, errors.RATE_LIMITED(), {
+                status: 429,
+                headers: { 'Retry-After': retryAfterSeconds(rate.retryAfterMs(rateKey)) }
+            });
+            return;
+        }
+        // ─── Per-database concurrency ───────────────────────────────────────────
+        let lease;
+        try {
+            lease = await concurrency.acquire(databaseId, {
+                limit: protection.maxConcurrentRequests,
+                queueWaitMs: protection.maxQueueWaitMs
+            });
+        }
+        catch (e) {
+            next(e);
+            return;
+        }
+        if (!lease.granted) {
+            log.warn(`[admission] concurrency refused: database=${databaseId} ` +
+                `limit=${protection.maxConcurrentRequests} reason=${lease.refusal} waited=${lease.queuedMs}ms`);
+            recordRefusal(req, lease.refusal === 'queue_timeout' ? 'queue_timeout' : 'concurrency_saturated', {
+                sourceIp: ip
+            });
+            respondWithGraphQLError(res, errors.CONCURRENCY_LIMIT_REACHED({
+                limit: protection.maxConcurrentRequests,
+                waitedMs: lease.queuedMs
+            }), {
+                status: 429,
+                // The queue is the honest wait estimate: a slot freed sooner than
+                // this and the request would already have been admitted.
+                headers: { 'Retry-After': retryAfterSeconds(protection.maxQueueWaitMs) }
+            });
+            return;
+        }
+        // Release exactly once, whichever ends first. `close` covers the client
+        // that hangs up mid-flight — without it an aborted request holds its slot
+        // until the process restarts, and a client that retries on abort would
+        // drain the tenant's budget one leaked slot at a time. `release` is
+        // idempotent, so both listeners can fire.
+        res.on('close', () => lease.release());
+        res.on('finish', () => lease.release());
+        next();
+    };
+};

package/esm/middleware/api.js

@@ -6,7 +6,7 @@ import { svcCache } from '@pgpmjs/server-utils';
 import { getPgPool } from 'pg-cache';
 import errorPage50x from '../errors/50x';
 import errorPage404Message from '../errors/404-message';
-import { getRoutingSchema, isValidSchemaName, resolveRoute, routeToApiStructure } from './routing';
+import { getRoutingSchema, isValidSchemaName, requireApiRole, resolveRoute, routeToApiStructure } from './routing';
 const log = new Logger('api');
 // =============================================================================
 // Module Loader Registry (replaces inline SQL queries for per-db config)
@@ -141,8 +141,8 @@ export const getSvcKey = (opts, req) => {
 const toApiStructure = (row, opts, settings = {}) => ({
     apiId: row.api_id,
     dbname: row.dbname || opts.pg?.database || '',
-    anonRole: row.anon_role || 'anon',
-    roleName: row.role_name || 'authenticated',
+    anonRole: requireApiRole('anon_role', row.anon_role, row.api_id),
+    roleName: requireApiRole('role_name', row.role_name, row.api_id),
     schema: row.schemas || [],
     rlsModule: settings.rlsModule,
     domains: [],
@@ -345,6 +345,11 @@ export const createApiMiddleware = (opts) => {
                 res.status(404).send(errorPage404Message(err.message));
                 return;
             }
+            if (err.code === 'MISSING_API_ROLE') {
+                log.error('[api-middleware] resolved API row has no served role:', err.message);
+                res.status(500).send(errorPage50x);
+                return;
+            }
             if (err.code === 'NO_DATABASE_ID') {
                 log.error('[api-middleware] no database id resolved:', err.message);
                 res.status(500).send(errorPage50x);

package/esm/middleware/flush.js

@@ -1,19 +1,50 @@
 import './types'; // for Request type
 import { Logger } from '@pgpmjs/logger';
 import { svcCache } from '@pgpmjs/server-utils';
+import { createHash, timingSafeEqual } from 'crypto';
 import { graphileCache } from 'graphile-cache';
 import { getPgPool } from 'pg-cache';
 import { getRoutingSchema, isValidSchemaName } from './routing';
 const log = new Logger('flush');
-export const flush = async (req, res, next) => {
-    if (req.url === '/flush') {
-        // TODO: check bearer for a flush / special key
+const bearerToken = (req) => {
+    const header = req.get('authorization');
+    if (!header)
+        return null;
+    const [scheme, ...rest] = header.trim().split(/\s+/);
+    if (scheme.toLowerCase() !== 'bearer' || rest.length !== 1)
+        return null;
+    return rest[0];
+};
+// Compare digests rather than the tokens themselves: timingSafeEqual requires
+// equal lengths, and digests are equal-length whatever the caller presents.
+const tokensMatch = (presented, expected) => timingSafeEqual(createHash('sha256').update(presented).digest(), createHash('sha256').update(expected).digest());
+/**
+ * `/flush` drops the routing and schema caches for the request's service key,
+ * so it is a control-plane operation: it needs the flush secret, not a tenant
+ * session. Without a configured secret there is no way to authenticate the
+ * caller, so the route stays closed.
+ */
+export const createFlushMiddleware = (opts) => {
+    const expected = opts.api?.flushToken;
+    return async (req, res, next) => {
+        if (req.url !== '/flush') {
+            return next();
+        }
+        if (!expected) {
+            log.warn('[flush] rejected: no api.flushToken configured');
+            res.status(404).send('Not Found');
+            return;
+        }
+        const presented = bearerToken(req);
+        if (!presented || !tokensMatch(presented, expected)) {
+            log.warn('[flush] rejected: invalid or missing bearer token');
+            res.status(401).send('Unauthorized');
+            return;
+        }
         graphileCache.delete(req.svc_key);
         svcCache.delete(req.svc_key);
         res.status(200).send('OK');
-        return;
-    }
-    return next();
+    };
 };
 export const flushService = async (opts, databaseId) => {
     const pgPool = getPgPool(opts.pg);

package/esm/middleware/graphile.js

@@ -55,7 +55,7 @@ const reqLabel = (req) => (req.requestId ? `[${req.requestId}]` : '[req]');
  * plugin preset.  Without settings the default preset is used
  * (everything on except aggregates).
  */
-const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId, compute) => {
+const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, databaseSettings, apiId, compute) => {
     return {
         extends: [createConstructivePreset(databaseSettings)],
         plugins: [
@@ -84,7 +84,15 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
         pgServices: [
             makePgService({
                 pool,
-                schemas
+                schemas,
+                // Introspection runs outside any request, so it has no served role to
+                // inherit: unset, it reads the catalog as whatever role the pool
+                // connected as (a superuser in most deployments) and the schema
+                // advertises that role's reach. Naming the role keeps schema shape
+                // tied to a bounded role's grants.
+                ...(introspectionRole && {
+                    pgSettingsForIntrospection: { role: introspectionRole }
+                })
             })
         ],
         grafserv: {
@@ -139,6 +147,15 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                         if (req.token.session_id) {
                             pgSettings['jwt.claims.session_id'] = req.token.session_id;
                         }
+                        if (req.token.root_session_id) {
+                            pgSettings['jwt.claims.root_session_id'] = req.token.root_session_id;
+                        }
+                        if (req.token.parent_session_id) {
+                            pgSettings['jwt.claims.parent_session_id'] = req.token.parent_session_id;
+                        }
+                        if (req.token.intent) {
+                            pgSettings['jwt.claims.intent'] = req.token.intent;
+                        }
                         // Propagate credential metadata as JWT claims so PG functions
                         // can read them via current_setting('jwt.claims.access_level') etc.
                         if (req.token.access_level) {
@@ -287,7 +304,7 @@ export const graphile = (opts) => {
             const pool = getPgPool(pgConfig);
             // Create promise and store in in-flight map BEFORE try block
             const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
-            const preset = buildPreset(pool, schema || [], anonRole, roleName, api.databaseSettings, api.apiId, compute);
+            const preset = buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, api.databaseSettings, api.apiId, compute);
             const creationPromise = observeGraphileBuild({
                 cacheKey: key,
                 serviceKey: key,

package/esm/middleware/request-protection.js

@@ -2,6 +2,7 @@ import './types'; // for Request type
 import { errors } from '@constructive-io/errors';
 import { DEFAULT_REQUEST_PROTECTION } from '@constructive-io/express-context';
 import { respondWithGraphQLError } from '../errors/graphql-response';
+import { recordRefusal } from '../refusals/recorder';
 /**
  * Resolve the bounds this request runs under and attach them to it.
  *
@@ -51,6 +52,7 @@ export const createRequestProtectionMiddleware = () => {
         if (Number.isFinite(declaredLength) &&
             declaredLength > protection.maxRequestBytes &&
             !isMultipart(req)) {
+            recordRefusal(req, 'request_too_large');
             respondWithGraphQLError(res, errors.REQUEST_TOO_LARGE({ bytes: declaredLength, limit: protection.maxRequestBytes }));
             return;
         }

package/esm/middleware/routing.js

@@ -1,5 +1,33 @@
 import { Logger } from '@pgpmjs/logger';
 const log = new Logger('routing');
+// =============================================================================
+// Scoped routing plane (resolve_route contract)
+// =============================================================================
+//
+// One indexed call resolves an incoming request across scopes. The server's
+// projection is HOST-ONLY: Traefik/Ingress owns L7 path/method routing, so
+// the server always calls the frozen contract with the root path and no
+// method:
+//
+//   SELECT * FROM <schema>.resolve_route(request_host, '/', NULL)
+//
+// Contract (constructive-db docs/architecture/scoped-domain-routing.md):
+// a single row is always returned; no match → route_binding_id IS NULL.
+/**
+ * The role an API row names is the role the server will SET ROLE to; a row
+ * that leaves one blank is a broken surface, not a request for a default.
+ * Throws (code MISSING_API_ROLE) rather than substituting a role.
+ */
+export const requireApiRole = (column, value, apiId) => {
+    if (typeof value !== 'string' || value.trim() === '') {
+        const error = new Error(`API ${apiId ?? '<unknown>'} has no ${column}; a served role is required and there is no default.`);
+        error.code = 'MISSING_API_ROLE';
+        error.column = column;
+        error.apiId = apiId;
+        throw error;
+    }
+    return value;
+};
 const RESOLVER_FUNCTION = 'resolve_route';
 /** Published logical name of the database-scope routing plane. */
 export const DEFAULT_ROUTING_SCHEMA = 'routing_public';
@@ -52,13 +80,14 @@ export const routeToApiStructure = (route, opts) => {
         log.debug('[resolve-route] api target missing schemas in resolved_config; no match');
         return null;
     }
+    const apiId = config.api_id ?? route.target_source_id ?? undefined;
     return {
-        apiId: config.api_id ?? route.target_source_id ?? undefined,
+        apiId,
         // Scoped APIs leave dbname NULL when their schemas live in the serving
         // database; fall back to the server's own database in that case.
         dbname: config.dbname || opts.pg?.database || '',
-        anonRole: config.anon_role || 'anon',
-        roleName: config.role_name || 'authenticated',
+        anonRole: requireApiRole('anon_role', config.anon_role, apiId),
+        roleName: requireApiRole('role_name', config.role_name, apiId),
         schema: config.schemas,
         domains: [],
         databaseId: config.database_id,

package/esm/plugins/request-protection-plugin.js

@@ -1,6 +1,21 @@
 import '../middleware/types'; // for Request type
 import { DEFAULT_REQUEST_PROTECTION } from '@constructive-io/express-context';
+import { SafeError } from 'grafast';
 import { enforceDocumentProtection } from '../protection/document-gate';
+import { recordRefusal } from '../refusals/recorder';
+/** The document-gate error codes, as the refusal taxonomy names them. */
+const DOCUMENT_REFUSALS = {
+    QUERY_TOO_DEEP: 'query_too_deep',
+    QUERY_TOO_COSTLY: 'query_too_costly',
+    PAGE_SIZE_TOO_LARGE: 'page_size_too_large'
+};
+/** The refusal a gate rejection counts as, or undefined for any other error. */
+export const documentRefusalReason = (err) => {
+    if (!(err instanceof SafeError))
+        return undefined;
+    const code = err.extensions?.code;
+    return typeof code === 'string' ? DOCUMENT_REFUSALS[code] : undefined;
+};
 /**
  * Get the Express request from a grafserv request context.
  */
@@ -31,7 +46,17 @@ export const RequestProtectionPlugin = {
                 // the platform defaults still apply rather than nothing at all.
                 const protection = req?.requestProtection ?? DEFAULT_REQUEST_PROTECTION;
                 if (args.document && args.schema) {
-                    enforceDocumentProtection(args.schema, args.document, args.variableValues, protection, args.operationName);
+                    try {
+                        enforceDocumentProtection(args.schema, args.document, args.variableValues, protection, args.operationName);
+                    }
+                    catch (err) {
+                        // The rejection is still the client's `SafeError`; it is counted on
+                        // the way out, keyed by the tenant the request resolved.
+                        const reason = documentRefusalReason(err);
+                        if (reason && req)
+                            recordRefusal(req, reason);
+                        throw err;
+                    }
                 }
                 return next();
             }