@nxgt/graphql-validation 0.4.1 → 0.6.0

package/docs/guide/query-limits.md

@@ -0,0 +1,206 @@
+# Limiting the depth and cost of a query
+
+`maxDepth` and `maxListCost` are graphql-js validation rules. They refuse an
+operation before any resolver runs, so a hostile query costs a walk of its
+document and nothing more. For `@constraint`, see
+[Constraints](constraints.md).
+
+## Why
+
+A schema with a list cycle lets a client multiply a cost at each level:
+
+```graphql
+type Folder { id: ID! items(first: Int = 100): [Item!]! }
+type Item { id: ID! folder: Folder! }
+type Query { folder(id: ID!): Folder }
+```
+
+```graphql
+query {
+  folder(id: "1") {
+    items { folder { items { folder { items { folder { items { id } } } } } } }
+  }
+}
+```
+
+Four `items` levels of 100 each can ask for 100 million nodes in a query nine
+levels deep (`folder`, four `items`, three `folder`, `id`). `maxDepth` bounds the nesting; `maxListCost` bounds the work.
+
+## Use
+
+With graphql-js, add the rules to the ones `validate` already runs:
+
+```ts
+import { maxDepth, maxListCost } from '@nxgt/graphql-validation';
+import { parse, specifiedRules, validate } from 'graphql';
+
+const errors = validate(schema, parse(query), [
+  ...specifiedRules,
+  maxDepth({ depth: 8 }),
+  maxListCost({ budget: 10_000, defaultFirst: 50 }),
+]);
+```
+
+With graphql-yoga, in a plugin:
+
+```ts
+import { maxDepth, maxListCost } from '@nxgt/graphql-validation';
+import { createYoga } from 'graphql-yoga';
+
+createYoga({
+  schema,
+  plugins: [
+    {
+      onValidate: ({ addValidationRule }) => {
+        addValidationRule(maxDepth({ depth: 8 }));
+        addValidationRule(maxListCost({ budget: 10_000, defaultFirst: 50 }));
+      },
+    },
+  ],
+});
+```
+
+Each rule reports **one** `GraphQLError` per operation, whose `nodes` is the
+operation. An invalid option (`depth: 0`, a fractional `budget`) throws a
+`RangeError` when the rule is created.
+
+## `maxDepth({ depth, ignoreIntrospection? })`
+
+The depth of an operation is the nesting of its field selections: a top-level
+field is depth 1.
+
+- Named fragments are followed, each measured once. A fragment cycle adds
+  nothing (`NoFragmentCyclesRule` reports it).
+- Inline fragments add no depth.
+- `__typename` does not count. `__schema` and `__type` count like any field:
+  the standard introspection query (`getIntrospectionQuery()`) is **15 levels
+  deep**, so `maxDepth({ depth: 8 })` refuses it. Where introspection is
+  disabled, or the client is trusted (GraphiQL in development), pass
+  `ignoreIntrospection: true`: `__schema` and `__type` and everything under
+  them are then left out.
+
+```ts
+maxDepth({ depth: 8, ignoreIntrospection: process.env.NODE_ENV !== 'production' });
+```
+
+The refusal:
+
+```json
+{
+  "message": "Operation \"Deep\" is 9 levels deep, more than the 8 allowed",
+  "extensions": { "code": "QUERY_TOO_DEEP", "depth": 9, "limit": 8 }
+}
+```
+
+`depth` is the operation's real depth. An anonymous operation reads
+`Operation is 9 levels deep, ...`.
+
+## `maxListCost({ budget, defaultFirst, sizeArguments?, ignoreIntrospection? })`
+
+### How cost is counted
+
+A field costs 1, times the sizes of the list fields enclosing it. A list field
+multiplies the cost of its sub-selection by its size; a field that is not a list
+multiplies by 1. A list field that selects nothing below it (`tags: [String!]!`)
+costs 1.
+
+```graphql
+{ folder(id: "1") { id items(first: 5) { id } } }
+# folder 1 + id 1 + items 1 + 5 * id 1 = 8
+```
+
+A type that is a list once unwrapped from non-null is one list, nested
+`[[X]]` included. `__typename` costs nothing.
+
+`__schema` and `__type` are costed like any field, their lists sized by the
+schema itself: `__Schema.types` is the number of types of the schema, and
+`fields`, `inputFields`, `enumValues`, `args`, `interfaces`, `possibleTypes`,
+`directives` and `locations` are the longest such list anywhere in the schema.
+A query repeating `a1: __schema { ... }` hundreds of times is refused like any
+other. The standard introspection query costs on the order of 200,000 even on a
+schema of one field, so it is refused by a budget
+of 10,000: pass `ignoreIntrospection: true` where introspection is disabled or
+the client is trusted, such as GraphiQL in development.
+
+### How a list is sized
+
+A list field is sized by its **size arguments**, `['first', 'last', 'limit']`
+unless `sizeArguments` says otherwise:
+
+```ts
+maxListCost({ budget: 10_000, defaultFirst: 50, sizeArguments: ['first', 'pageSize'] });
+```
+
+Each size argument the field gives or declares a default for says a size, and
+the **largest** wins: `items(first: 0, limit: 1000000)` is a million items. An
+argument says:
+
+| Argument | Size |
+| --- | --- |
+| a literal Int, 0 or more (`first: 5`) | that number |
+| a string literal holding a canonical integer (`limit: "100000000"`, for a `Long`-like scalar) | that number: digits only, no sign, no leading zero |
+| a bigint (an SDL default held by a code-first schema, or after graphql-tools' `mapSchema`) | that number |
+| an integral Float literal (`first: 1000.0`, `first: 1e3`) | that number; `1.5` and `-1000.0` are unusable |
+| a negative literal (`first: -1000`), another string | as if unusable, see below |
+| a variable (`first: $n`) | as if unusable: validation has no variable values |
+| not given | its SDL default, when it has one; else nothing |
+
+An SDL default is read the same way: `limit: String = "1000"` and `first:
+Float = 1000.0` are sizes of 1000. Every size is held at most
+`Number.MAX_SAFE_INTEGER`.
+
+An argument given but unusable counts for its SDL default when it has one in
+any accepted form (`items(first: Int = 100)`), and `defaultFirst` otherwise. On
+an abstract parent that is the largest default, or `defaultFirst` when it is
+larger and some possible type has no default. A
+field where no size argument says anything is sized `defaultFirst`.
+
+On an interface or a union, the default is the **largest** over the interface's
+field and the field of every possible type (`Node.kids(first: Int = 1)` next to
+`Folder.kids(first: Int = 100000)` is sized 100,000), since the query cannot
+say which object comes back.
+
+A negative number is therefore never taken as a size: no subtree costs less than
+nothing, and `items(first: -1000)` next to an expensive sibling cannot cancel
+the sibling's cost.
+
+Pick `defaultFirst` knowing a variable counts for it: a client using
+`first: $n` is charged the default whatever it sends. If your server caps a size
+argument, set `defaultFirst` (or the SDL default) at that cap.
+
+### Fragments and abstract types
+
+Named fragments are followed, each costed once (a fragment's type condition fixes
+its parent type). A fragment spread twice counts twice. Inline fragments and
+fragments on an interface or a union are **summed branch by branch**: a
+selection `... on A { ... } ... on B { ... }` costs A's plus B's, although an
+object is one of them. The cost of a query on an abstract type is overestimated,
+never underestimated.
+
+### The refusal
+
+```json
+{
+  "message": "Operation \"Big\" costs 5002, more than the 1000 allowed",
+  "extensions": { "code": "QUERY_TOO_COSTLY", "cost": 5002, "limit": 1000 }
+}
+```
+
+`budget` and `defaultFirst` must be integers below `Number.MAX_SAFE_INTEGER`
+(a cost never exceeds it, so a budget at or over it would refuse nothing); the
+rule throws a `RangeError` otherwise.
+
+Costs are plain numbers, computed from memoized fragments (no exponential work
+on a hostile query) and held at `Number.MAX_SAFE_INTEGER`: `cost` is exact below
+it and never `Infinity`.
+
+## Not covered
+
+- A size carried inside an input object (`items(page: { first: 1000 })`) is not
+  read: the field has no size argument, so it is sized `defaultFirst`. Name the
+  size as an argument, or raise `defaultFirst`.
+- A nested list `[[X]]` is sized **once**: the inner lists are not multiplied. A
+  schema returning a list of lists should size it with its own argument.
+- The rules read the document, not its variables' values, and not what a
+  resolver does: a resolver can still return more than `first` items. They
+  complement a page-size cap in the resolver; they do not replace it.

package/docs/roadmap.md

@@ -8,8 +8,7 @@ Nothing in progress.
 
 ## Next
 
-- **Schemas that read the context**, `(args, context) => schema`, for checks
-  that need the request (uniqueness in a database, permissions).
+Nothing planned yet.
 
 ## Later
 
@@ -19,6 +18,18 @@ Nothing in progress.
 
 ## Shipped
 
+- **Query depth and cost limits** — `maxDepth` and `maxListCost` are graphql-js
+  validation rules (also for graphql-yoga's `addValidationRule`) that refuse a
+  query nested too deep or too costly for a schema with list cycles, with the
+  stable codes `QUERY_TOO_DEEP` and `QUERY_TOO_COSTLY`.
+- **Schemas that read the context** — 0.5.0. `validated((context, info) =>
+  schema, resolver)` builds the schema on each call from the request's context
+  and the field's `info`, for checks that need the request (a uniqueness query
+  in the request's database, a rule depending on the viewer). Its result is
+  parsed like a fixed schema; what it throws reaches the client as it is. The
+  function does not receive the arguments: the schema it returns checks them,
+  and a `refine` sees them. A shape's arguments are now typed in the resolver (they
+  were `unknown`).
 - **Answering invalid input as one error** — 0.4.0.
   `invalidInputError(issues, { translate })` builds one 400 error whose
   `extensions.fields` lists every field at fault with your own codes,

package/docs/troubleshooting.md

@@ -8,6 +8,7 @@ is the one a client sees.
 - [Startup](#startup)
 - [Silent traps](#silent-traps)
 - [Runtime](#runtime)
+- [Query limits](#query-limits)
 - [The bin](#the-bin)
 
 ## Install
@@ -405,6 +406,58 @@ every issue. The resolver did not run.
 | `Too small: expected number to be >=18` | `min: 18` |
 | `Invalid string: must match pattern /.../` | `pattern` |
 
+## Query limits
+
+### `Operation "Name" is 9 levels deep, more than the 8 allowed`
+
+**When:** an operation is validated with `maxDepth({ depth: 8 })`.
+**Why:** `extensions` is `{ code: 'QUERY_TOO_DEEP', depth: 9, limit: 8 }`. A
+top-level field is depth 1; named fragments are followed, inline fragments add
+nothing, `__typename` does not count. `__schema` and `__type` do: the standard
+introspection query is 15 levels deep (pass `ignoreIntrospection: true` where
+it is trusted). An anonymous operation
+reads `Operation is 9 levels deep, ...`.
+**Fix:** flatten the query, or raise `depth`. See
+[Limiting the depth and cost of a query](guide/query-limits.md).
+
+### `Operation "Name" costs 5002, more than the 1000 allowed`
+
+**When:** an operation is validated with `maxListCost({ budget: 1000, ... })`.
+**Why:** `extensions` is `{ code: 'QUERY_TOO_COSTLY', cost: 5002, limit: 1000 }`.
+Each field costs 1, times the sizes of the lists enclosing it. A list without a
+usable `first` (a variable, a negative number, nothing) counts for its SDL
+default, else `defaultFirst`, so a query that is cheap with the variable's real
+value can still be refused.
+**Fix:** ask for fewer items with a literal `first`, or raise `budget`. A query
+on an interface or a union is overestimated (every branch is summed).
+
+### `maxDepth: depth must be an integer from 1 to 9007199254740990.`
+
+**When:** `maxDepth` is called with `0`, a negative or a fractional `depth`.
+**Fix:** pass an integer in range.
+
+### `maxListCost: budget must be an integer from 0 to 9007199254740990.`
+
+**When:** `maxListCost` is called with a negative, fractional or too large
+`budget`. A cost never exceeds `Number.MAX_SAFE_INTEGER` (9007199254740991), so a
+budget at or over it would refuse nothing.
+**Fix:** pass an integer in range.
+
+### `maxListCost: defaultFirst must be an integer from 0 to 9007199254740990.`
+
+**When:** `defaultFirst` is negative, fractional or too large.
+**Fix:** pass the size to assume for a list with no usable size argument.
+
+### A query refused although its `first` is small, or an introspection query refused
+
+**When:** `QUERY_TOO_COSTLY` or `QUERY_TOO_DEEP` for GraphiQL's schema fetch or
+a codegen's introspection query.
+**Why:** `__schema` is counted: the standard introspection query is 15 levels
+deep and costs on the order of 200,000 on a one-field schema.
+**Fix:** `ignoreIntrospection: true` on the rule where introspection is
+disabled or the client is trusted. A `first: $n` variable counts for the SDL
+default, not for the value sent.
+
 ## The bin
 
 ### `typedefs failed: <message>`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/graphql-validation",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"description": "Validate GraphQL arguments and input fields with @constraint directives, checked by Zod schemas, for graphql 16 and 17",
 	"license": "MIT",
 	"type": "module",