Add optional maxDepth and maxAliases execution options

[eddieran]

Summary

Fixes #4662 — the execution engine has no built-in depth or complexity limits, allowing deep recursive queries and alias-bombing to cause denial-of-service via resolver amplification.

This PR adds two opt-in execution options:

• maxDepth — limits the field nesting depth during execution. When a field at depth > maxDepth is encountered, a GraphQLError is raised and the parent field resolves to null (standard nullable error handling). List indices do not count toward depth.

• maxAliases — limits the number of response keys (including aliases) per selection set. This prevents alias-bombing attacks where thousands of aliases for the same field bypass depth-based defenses. When exceeded, a GraphQLError is raised before the selection set executes.

Both options are undefined by default — no limits are applied and existing behavior is fully preserved. They are passed via ExecutionArgs.options alongside the existing maxCoercionErrors:

const result = await execute({
  schema,
  document,
  options: {
    maxDepth: 10,
    maxAliases: 50,
  },
});

Implementation details

• Depth checking happens in executeField by walking the Path linked list (only counting string keys, not list indices)
• Alias counting happens in executeOperation (root fields) and completeObjectValue (sub-selections) after field collection
• Errors follow standard GraphQL error propagation — nullable parent fields are nulled, non-null fields propagate upward
• 12 new tests covering: within-limit queries, exceeded limits, no-op when unset, list index handling, nested alias limits, combined usage

Test plan

• All 12 new tests pass
• Full test suite (1972 tests) passes with no regressions
• TypeScript compilation clean
• ESLint clean

[linux-foundation-easycla]

• ❌ - login: @eddieran / name: eddie . The commit (43e0e57) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please submit a support request ticket.
• ❌ - login: @eddieran / name: Ran . The commit (f9d67dc) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please submit a support request ticket.

[vercel]

@eddieran is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[yaacovCR]

Maybe we could consider adding a fieldDepth property to FieldDetails of type number? Then we wouldn't have to keep recalculating the path length?

[eddieran]

Thanks for the review, @yaacovCR! Since FieldDetails doesn't exist in the 16.x.x branch this PR targets (collected fields are plain Map<string, ReadonlyArray<FieldNode>>), I took the equivalent approach: thread a depth: number parameter through executeFields/executeField/completeValue and its helpers. completeObjectValue increments depth when descending into sub-selections; list items and abstract-type resolution keep the same depth as their parent field.

This turns the depth check into O(1) per field resolution instead of O(depth) walk of the Path linked list, while preserving identical semantics (list indices still don't count).

All 12 new tests and the full 1972-test suite still pass. Pushed in f9d67dc. Happy to take further suggestions, e.g. if you'd prefer a different naming or placement.

stale

[yaacovCR]

This looks great to me, comments/suggestions inline.

Looping in @benjie with regards to naming as he is driving the Golden Path initiative (graphql/graphql-wg#1887 https://github.com/graphql/golden-path-wg).

Gentle nudge also about the CLA!

(CI also notes there is a prettier issue).

From benchmarking on my machine ran from the 17.x.x branch:

npm run benchmark -- benchmark/introspectionFromSchema-benchmark.js benchmark/list-sync-benchmark.js benchmark/list-async-benchmark.js benchmark/object-async-benchmark.js --revs pr/4666 v16.13.2

[yaacovCR]

If the depth limit check was in completeObjectValue (and at the root) rather than at the field, right after field collection, we could return all the collected fields/subfields. We could also with this change allow for setting a limit of 0 which should fail everything, not be so useful, but would protects us in that edge case from an error message in that edge case of uncertain use that would read "Query depth limit of 0 exceeded, found depth: 2." when it might be expected to read: "Query depth limit of 0 exceeded, found depth: 1."

[yaacovCR]

We could consider calling this option maxResultDepth as we may later wish to introduce a separate maximum inline/named fragment depth with respect to field collection.

[yaacovCR]

Suggested change

	maxAliases?: number;
	maxResponseNames?: number;

The idea is that we want a maximum breadth at an object level, whether or not aliases are used.

I think "response name" would be the official erm => https://spec.graphql.org/draft/#sec-Field-Alias

(This would need to be renamed throughout the code/comments.)

[yaacovCR]

Not sure, but I think we would want to include all nodes, not just those above the maximum, it's not the fault of a later node if a new node is added to a operation prior to it and causes it to fail? And we would not be able to tell which is the real offending node. Alternatively, we could just list the parent with too many sub-response names. Not sure how much value we actually add by including all of the nodes causing the response names limit to be breached, it may be more helpful to highlight the offending parent (considering the list of nodes would be expected to be quite long).

[yaacovCR]

If we include all the offending response names, for consistency, I would assume we would need to include all of the fieldNodes, not just the first. This array is the set of overlapping fieldNodes that have been coalesced into one response name, but if we think we're helping by pointing out all the nodes within the operation that cause this limit to be breached, I think we would just confuse things by not listing all the nodes that are part of the problem. If we include just the first, the removal of that node would not cause the error to be avoided if there were other nodes with that response name.

(As above, not sure if we actually need to include all of the offending nodes rather than just the parent.)

[benjie]

Is there a reason for doing this at resolve-time rather than validation-time?

Returning null for data past a given depth is unsafe; a client might update their normalized cache thinking null is the true data for this. An error must be throw instead.

I'd recommend doing this as a validation rule instead.

I'd strongly recommend that you factor in list depth, it's much more significant a concern than selection set depth - selection sets grow cost linearly, lists grow cost exponentially.