GraphQL / Advanced: bounded and distributed execution / Lesson 13

Demand control, cost and trusted documents

Bound operation work using complementary controls and distinguish persisted storage from a trusted allowlist.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Estimate nested list growth and explain why depth alone is insufficient.
Combine document, argument, execution and principal budgets.

Budget the work rather than the endpoint count

A single GraphQL endpoint can execute operations with radically different cost. One card lookup and a deeply nested collection traversal should not receive identical resource assumptions merely because each is one HTTP request. Bound body size, operation count, aliases, list arguments, depth, estimated cost, execution time and source concurrency according to actual application needs. No universal numeric limit fits every schema. Derive thresholds from approved workload evidence and business requirements, and reject excessive operations before expensive source work whenever practical.

Expose multiplicative fanout

This model counts the upper bound on leaf course cards when a query asks for twenty departments, ten authors per department and five courses per author. It intentionally ignores shared records, batching and early filtering so the multiplication is visible. The result is not a measured runtime cost or a complete complexity algorithm. A practical estimator should understand field weights, list bounds, fragments, aliases and variables. A shallow query with many aliases or a single expensive aggregation can still be costly even when its nesting depth is small.

javascript Offline list-fanout arithmetic

const bounds = {departments:20, authors:10, courses:5};
const leafCards = bounds.departments * bounds.authors * bounds.courses;
console.assert(leafCards === 1000);
const capped = {...bounds, courses:2};
console.assert(capped.departments * capped.authors * capped.courses === 400);

The declared upper bounds produce 1000 and 400 leaf positions. This does not measure database rows, deduplication or execution latency.

Persisted does not automatically mean trusted

Persisted documents replace repeated document text with an identifier, commonly a hash. An automatic registration mechanism that accepts any new document is not the same as an allowlist of reviewed operations. For a first-party application, a trusted registry can restrict execution to approved documents and known variable bounds. Public clients that compose arbitrary operations require another policy. Even an approved document can become expensive with a huge pagination argument, so enforce input limits and principal budgets after lookup rather than assuming document identity alone controls cost.

Write a reviewable policy record

The JSON below names complementary checks rather than prescribing arbitrary production limits. Its values are synthetic review categories, not configuration accepted by a particular server. Implementation should fail closed when a trusted identifier is unknown if that is the chosen deployment policy, while preserving a controlled development registration workflow. Keep registry updates compatible with client rollout and rollback. A document hash should identify the exact canonical artifact agreed by the toolchain; different whitespace normalization assumptions can otherwise cause lookup misses without any schema problem.

json Synthetic demand policy checklist

{
  "mode": "reviewed-first-party-documents",
  "unknownDocument": "reject",
  "checks": ["body-bound", "single-selected-operation", "variable-bounds", "expanded-cost", "principal-budget", "source-deadline"],
  "registryChange": "review-with-client-artifact"
}

This is a local design record. It neither configures a gateway nor claims measured safe thresholds.

Keep runtime enforcement and cancellation

Pre-execution estimates can be wrong when source behavior changes or a field hides expensive work. Use bounded source concurrency, deadlines and cancellation propagation where the chosen implementation and driver support them. A client timeout alone may leave server work running, so observe actual cleanup. Apply per-principal rate and resource policies alongside global protection; one user should not consume the entire shared budget. Test rejection with synthetic operations and counters rather than sending hostile or high-load traffic to a real endpoint during authoring.

Common errors and fixes

A shallow query exhausts source resources

Why it happens: Only nesting depth was limited.
How to fix it: Consider breadth, field weights, arguments and concurrency.
Prevent it next time: Keep representative expensive shallow fixtures.

A persisted hash accepts arbitrary new operations

Why it happens: Automatic registration was called a trusted allowlist.
How to fix it: Separate approved registration from runtime lookup policy.
Prevent it next time: Test unknown documents under the intended mode.

A timed-out client leaves expensive work running

Why it happens: Cancellation did not reach source tasks.
How to fix it: Propagate supported cancellation and release resources.
Prevent it next time: Observe cleanup in isolated integration tests.

Check your understanding

1. Why does an approved document still need variable limits?

Show worked solution

The same selection can request two or two million items if the schema and resolver allow that argument. Document review controls structure, not every runtime value. Enforce pagination and domain bounds, include coerced variables in cost estimation where appropriate, and keep runtime deadlines because source work can exceed an estimate even within an approved structure.

2. What does the fanout multiplication fail to model?