Skip to content

Rework query complexity limits with merged fields and occurrence budgets - #4523

Merged
andimarek merged 20 commits into
masterfrom
codex/general-dos-protection
Nov 11, 2026
Merged

andimarek merged 20 commits into
masterfrom
codex/general-dos-protection

Conversation

@andimarek

@andimarek andimarek commented Nov 1, 2026 •

Copy link
Copy Markdown
Member

This PR reworks validation complexity protection to use merged fields, while retaining a separate budget for field occurrences after fragment expansion. It also replaces QueryComplexityLimits.newLimits() with newLimitsWithDefaults(), whose builders inherit the current JVM-wide configuration. This bounds merged response structure without allowing repeated selections to escape the expanded-field budget.

Breaking changes and migration

The following public APIs are removed without compatibility aliases. Update these references in application code and dependent libraries, then rebuild them against this version; the removed methods and enum member are also binary incompatible.

Removed API How to migrate
QueryComplexityLimits.newLimits() Rename to QueryComplexityLimits.newLimitsWithDefaults(). The new factory snapshots the current JVM-wide defaults; use NONE or explicit settings when the old unlimited builder behavior was intended.
QueryComplexityLimits.Builder.maxFieldsCount(int) Use maxFieldOccurrences(int) to retain the previous expanded-field metric, or choose maxMergedFieldCount(int) for a merged-field policy.
QueryComplexityLimits.getMaxFieldsCount() Use getMaxFieldOccurrences() for the previous metric; use getMaxMergedFieldCount() when reading the new merged-field budget.
QueryComplexityLimits.DEFAULT_MAX_FIELDS_COUNT Use DEFAULT_MAX_FIELD_OCCURRENCES for the previous 100,000-occurrence budget; DEFAULT_MAX_MERGED_FIELD_COUNT is the separate new 10,000-field budget.
GoodFaithIntrospection.GOOD_FAITH_MAX_FIELDS_COUNT Rename to GOOD_FAITH_MAX_MERGED_FIELD_COUNT; its value and merged-field meaning remain 500.
ValidationErrorType.MaxQueryFieldsExceeded Handle MaxQueryFieldOccurrencesExceeded for the previous metric and MaxQueryMergedFieldCountExceeded for the new metric.

Migrate the configured policy, not just the method names:

  • New default cap: the existing 100,000 expanded-field budget is retained, with an additional 10,000 merged-field cap; general depth remains 100. An operation with 10,001 distinct merged fields can now fail where master accepts it. To adopt the new defaults, use QueryComplexityLimits.DEFAULT, or omit request-specific limits to use the current JVM defaults. If existing operations exceed the merged cap, configure a suitable maxMergedFieldCount while retaining the depth/occurrence budgets. Reusing the old numeric limit for merged fields is not an equivalent policy; the counting examples below explain why.
  • Renamed factory and inherited limits: replace calls, static imports, and method references to newLimits with newLimitsWithDefaults. The old factory on master started with all limits disabled; newLimitsWithDefaults() snapshots getDefaultLimits() at creation, so overriding one setting preserves the others. For a configuration independent of JVM defaults, explicitly set all three limits. Set application-wide defaults before creating builders that should inherit them; recreate builders if they must pick up a subsequent global change. DEFAULT remains the fixed library configuration.
  • Previously unlimited builders: replace newLimits().build() with QueryComplexityLimits.NONE if the intent was to disable general limits. NONE does not disable Good Faith introspection; its existing switches remain separate.

For example, the old field-count-only policy newLimits().maxFieldsCount(N).build() becomes:

QueryComplexityLimits limits = QueryComplexityLimits.newLimitsWithDefaults()
    .maxFieldOccurrences(N)
    .maxMergedFieldCount(Integer.MAX_VALUE)
    .maxDepth(Integer.MAX_VALUE)
    .build();

If the old configuration also specified maxDepth(D), use D instead of the last Integer.MAX_VALUE. To retain the former default depth/occurrence budgets while removing the new 10,000-field cap, use N = 100_000 and D = 100, subject to the ceiling described below. Apply the instance per request under QueryComplexityLimits.KEY in GraphQLContext, or globally with QueryComplexityLimits.setDefaultLimits(limits).

In the current implementation, Integer.MAX_VALUE skips occurrence counting, while general merged/depth counting is skipped only when both those settings are Integer.MAX_VALUE. If a finite depth limit keeps merged counting active, Integer.MAX_VALUE remains a merged-field ceiling; long totals exceeding it are rejected. This is not a fully unlimited merged count with an independent finite depth bound.

Migrate error handling and assertions:

  • Update switches/comparisons on ValidationError.getValidationErrorType() to handle both replacement field-limit classifications. Occurrence failures now use ordinary validation errors even for introspection operations, where the old field-count failure used BadFaithIntrospection; handlers that only recognize BadFaithIntrospection must also recognize MaxQueryFieldOccurrencesExceeded.
  • Keep existing BadFaithIntrospection handling for Good Faith merged-field/depth and restricted-coordinate failures. MaxQueryDepthExceeded remains the ordinary depth-limit classification.
  • Update exact-message and QueryComplexityLimits.toString() assertions: merged-field messages identify that metric, occurrence failures have a separate message, and the configuration string includes both field settings. Earlier complexity checks can change which failure is reported first; for documents violating several limits, allow the applicable classifications rather than assuming the previous first error.

Counting and scope

Limits apply independently to every operation in the validated document, including unselected queries, mutations and subscriptions. Both object and leaf fields count:

Selection Merged fields Expanded field occurrences
{ node { name name } } 2 3
{ node { ...F ...F } }, where F selects name 2 3
{ a: node { name } b: node { name } } 4 4

All three have field depth 2. Fragment-spread and inline-fragment nodes do not themselves count as fields or increase field depth.

Merged counting reuses field-validation groups: selections with the same response name (alias, otherwise field name) and common parent type combine at each response position, including their children. Reusing a fragment at different response positions counts its fields again. Occurrences charge every field at every fragment use, without merging.

These are structural counts of the operation’s selections. All selections count regardless of @skip/@include, without coercing variables. Abstract selections can contribute to several concrete-parent groups, so merged counts can exceed occurrence counts. For example, with Query.node: I, implementations A/B, child returning I/A/B respectively, and name: String on each:

{
  node {
    child { a: name b: name c: name }
    ... on A { child { name } }
    ... on B { child { name } }
  }
}

This has 9 occurrences but 11 merged fields: node, plus one child and four names in each concrete-parent group.

Good Faith introspection

General and Good Faith checks now share merged-field/depth summaries. Good Faith retains its separate enable/disable settings, class, and special error handling:

  • Queries selecting root __schema or __type, including through aliases/fragments, retain caps of 500 merged fields and depth 20, or tighter configured general limits. The configured occurrence budget is preserved, including by goodFaithLimits(...).
  • These caps cover the whole mixed operation. Skipped introspection selections still activate them; __typename alone does not.
  • Each restricted coordinate remains limited to one merged occurrence: root __schema, root __type, and __Type.fields, inputFields, interfaces, possibleTypes. Different aliases or parent positions count separately.
  • NONE disables general limits only. Disabling Good Faith leaves general limits active; general limits remain independent of the validation-rule predicate.

Implementation and protection boundaries

  • Reuse document-wide field-merge state and per-operation summaries keyed by validation-state identity. Count leaf groups directly, cache non-leaf summaries, reuse traversal paths, and cache the validation-rule array to reduce allocation and repeated hashing.
  • Count occurrences in the existing iterative validation walk. Cache completed fragment totals across operations and add them at repeated spreads, while preserving per-operation variable validation. Do not cache incomplete cyclic/missing-fragment totals.
  • Check depth before collecting children, continue bounding conflicting selections, and use long field counters to prevent integer overflow. Adapt traversal-frame accounting and retain regression coverage for the fragment-stack fix already on master.

The fragment-doubling regression fixture has 886 characters, two raw AST fields and two merged fields, but 33,554,433 expanded occurrences; the default occurrence budget rejects it.

Occurrence counting follows initial merge validation, so it is not a preflight bound on all validation work. These limits do not measure list lengths, resolver cost, or response bytes. Parser defaults, the maximum-validation-error setting, and instrumentation APIs are unchanged; this PR does not consolidate all protection configuration or deprecate instrumentation.

Fixtures and verification

Adds the unchanged large-schema-6-query.graphql and matching 32,655,122-byte SDL, split into four definition-aligned parts under the repository file-size limit. Tests parse the parts separately and merge registries to reduce peak memory. The accompanying README documents parser limits, counting assumptions, and these measurements:

Measurement Query count
Characters / UTF-8 bytes (ASCII) 194,881
Grammar tokens, including EOF 22,480
Fragment definitions 663
Raw AST field nodes 5,687
Expanded field occurrences 91,515
Merged validation fields 4,311
Maximum field depth 15

The query has no root introspection selections. The validation counts include all selections regardless of @skip and @include; the stored query is unchanged. Its grammar-token count exceeds the default 15,000, so the fixture test raises that parser limit locally. Other parser measurements and exact/one-below boundaries are documented and tested.

Regression coverage includes default/custom/disabled limits, JVM-default snapshots, aliases/fragments, abstract types, directives, operation isolation, Good Faith, disabled rules, conflicting selections, cycles, integer overflow and the 1,501-fragment chain. FragmentExpansionComplexityTest adds readable F → G → J chains, repetition at every level, shared descendants through multiple branches, and reuse across operations in different operation/definition orders. Every case verifies exact merged-field, occurrence and depth limits, plus rejection when each limit is lowered by one. Two JMH benchmarks cover general complexity and fragment-expansion workloads.

Local verification: 686 validation/introspection tests passed, including the new fragment-expansion cases. The factory rename also passed Javadoc generation and JMH compilation. PR checks track the full CI matrix for the latest commit.

@github-actions

github-actions Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Test Report

Test Results

Java Version Total Passed Failed Errors Skipped
Java 17 6419 (+157 🟢) 6363 (+157 🟢) 0 (±0) 0 (±0) 56 (±0)
Java 21 6419 (+157 🟢) 6363 (+157 🟢) 0 (±0) 0 (±0) 56 (±0)
Java 25 6419 (+157 🟢) 6363 (+157 🟢) 0 (±0) 0 (±0) 56 (±0)
jcstress 32 (±0) 32 (±0) 0 (±0) 0 (±0) 0 (±0)
Total 19289 (+471 🟢) 19121 (+471 🟢) 0 (±0) 0 (±0) 168 (±0)

Code Coverage (Java 25)

Metric Covered Missed Coverage vs Master
Lines 30518 3032 91.0% +0.2% 🟢
Branches 9058 1498 85.8% +0.2% 🟢
Methods 8143 1168 87.5% +0.2% 🟢

Changed Class Coverage (26 classes)

Class Line Branch Method
g.e.FieldCollector +0.2% 🟢 +0.5% 🟢 ±0.0%
g.i.GoodFaithIntrospection +0.5% 🟢 ±0.0% ±0.0%
g.l.BooleanValue +8.0% 🟢 ±0.0% +7.1% 🟢
g.l.EnumValue +8.0% 🟢 ±0.0% +7.1% 🟢
g.l.IntValue +8.0% 🟢 ±0.0% +7.1% 🟢
g.l.ListType +20.0% 🟢 ±0.0% +21.4% 🟢
g.l.ListType
$Builder
+28.0% 🟢 ±0.0% +11.1% 🟢
g.l.NodeChildrenContainer +5.9% 🟢 ±0.0% +11.1% 🟢
g.l.NodeUtil +4.8% 🟢 +3.8% 🟢 +11.1% 🟢
g.l.NonNullType +20.0% 🟢 ±0.0% +21.4% 🟢
g.l.NonNullType
$Builder
+22.6% 🟢 ±0.0% +9.1% 🟢
g.l.StringValue +8.0% 🟢 ±0.0% +7.1% 🟢
g.l.TypeName +8.3% 🟢 ±0.0% +7.7% 🟢
g.l.VariableReference +8.3% 🟢 ±0.0% +7.7% 🟢
g.n.ENFMerger +0.9% 🟢 +2.6% 🟢 ±0.0%
g.s.i.MockedWiringFactory
$1
+5.9% 🟢 +10.0% 🟢 ±0.0%
g.u.SelectionSetTraversalFrame +100.0% 🟢 +100.0% 🟢 +100.0% 🟢
g.v.FragmentComplexityInfo removed removed removed
g.v.GoodFaithIntrospectionCounts removed removed removed
g.v.LanguageTraversal removed removed removed
g.v.MergedFieldComplexityCounts +100.0% 🟢 +100.0% 🟢 +100.0% 🟢
g.v.OperationValidationFrame +97.1% 🟢 +90.0% 🟢 +100.0% 🟢
g.v.OperationValidator +0.2% 🟢 +0.4% 🟢 +0.1% 🟢
g.v.OperationValidator
$1
removed removed removed
g.v.QueryComplexityLimits +7.1% 🟢 ±0.0% +12.5% 🟢
g.v.Validator +4.3% 🟢 ±0.0% +11.1% 🟢

Full HTML report: build artifact jacoco-html-report

Updated: 2026-11-11 16:38:10 UTC

@andimarek andimarek changed the title Use merged-field counting for general query complexity limits Use merged-field complexity limits with a separate occurrence budget Nov 2, 2026
@andimarek

andimarek commented Nov 7, 2026 •

Copy link
Copy Markdown
Member Author

Added the supplied query and matching SDL as large-schema-6-query.graphql and large-schema-6.graphqls.part1–.part4, with loading instructions and measurements. The files preserve the original bytes; the SDL is split at definition boundaries to satisfy the 10 MB file limit.

This query fits the PR’s default validation limits, but exceeds the default parser token limit. Its validation counts are 4,311 / 10,000 merged fields, 91,515 / 100,000 field occurrences, and depth 15 / 100. Parsing requires 22,480 grammar tokens, above the default 15,000.

I measured the PR against fetched origin/master at 96443c271. The document has one operation (mainIssueAggQuery), 146 variables, 663 reachable fragments, and 5,687 AST field nodes.

Measurement Count for this query Schema introspection selections
Raw AST field nodes (each field as written; fragment definitions counted once) 5,687 0
Current master’s AST-based validation count (maxFieldsCount; fields counted again at every fragment use) 91,515 0
PR’s AST field-occurrence counter (maxFieldOccurrences) 91,515 0
PR’s merged validation count (maxMergedFieldCount) 4,311 0
ENF factory field count (getOperationFieldCount(); before final ENF merging) 5,648 0
Fields reachable in the final ENF tree (after final ENF merging) 3,882 0

There are no __schema or __type selections, including inside fragments, so Good Faith introspection limits do not apply. There are 393 __typename AST nodes, representing 5,073 expanded occurrences; these contribute to the ordinary counts above.

The counts answer different questions:

  • Raw AST fields — 5,687: count each field node where it is written, including fragment definitions once. Object and leaf fields both count; fragment-spread and inline-fragment nodes are not fields.
  • Master and the occurrence counter — 91,515: count each field again at every fragment use, without merging duplicate selections. For this fixture the old and new counters agree exactly. For example, Row_fieldSets_4l5hCf spreads RowMaybeWithDragAndDrop_fieldSets_4l5hCf directly and also through RowWithSiblingCreate_fieldSets_4l5hCf; both uses contribute their fields again.
  • Merged validation fields — 4,311: combine selections with the same response name and common parent type at the same response position, then count their combined children. For example, the five root me selections contribute 37 occurrences but only 10 merged fields. Aliases and separate response positions remain separate.
  • ENF fields — 5,648 created, 3,882 in the final tree: executable normalization considers possible runtime object types. Its factory counter increments when ENFs are created; the later ENFMerger pass does not reduce that counter. At jira.issueByKey.fields.edges.node.id, normalization creates 108 type-specific entries, then retains one ENF covering 108 concrete types. Thus the final tree’s 3,882 nodes and the factory’s 5,648 are different measurements. The validator’s common-parent groups are also different from ENF runtime-type grouping.

All differences between the ENF and merged-validation totals are under jira: that root contributes 91,348 occurrences, 4,213 merged validation fields, 5,550 ENFs created, and 3,784 final ENF nodes. The other five roots contribute 98 merged fields and 98 ENFs.

Conditional-selection assumption: as agreed, this is a structural comparison retaining all selections. For ENF only, an in-memory copy changes @skip to false and @include to true, with stand-in coerced values satisfying field arguments. The stored fixture and the document used for validation remain unchanged. This includes mutually exclusive branches: issueSearch and childWorkItems use opposite conditions on $shouldUseNewChildWorkItemsDatafetcher. These counts therefore do not describe one particular runtime variable assignment. They also do not estimate list lengths, resolver calls, response bytes, or execution time.

The parser measurements are identical on master and this PR:

Parser measurement Query Default operation limit Reassembled SDL
UTF-8 bytes 194,881 No parser byte limit 32,655,122
UTF-16 units (maxCharacters) 194,881 1,048,576 32,501,785
Grammar tokens, including EOF (maxTokens) 22,480 15,000 1,591,375
Whitespace tokens (maxWhitespaceTokens) 7,414 200,000 1,806,512
Comment tokens (separate maxTokens budget) 0 15,000 0
All tokens, including EOF 29,894 No combined limit 3,397,887
Maximum grammar-rule nesting (maxRuleDepth) 47 500 24
Longest numeric literal (maxNumericLiteralCharacters) 5 100 6

maxCharacters counts Java Reader characters, i.e. UTF-16 units. The code-point count happens to equal that count in both files. The query is ASCII; the SDL contains non-ASCII text. SDL parser defaults use Integer.MAX_VALUE for character, token, whitespace and depth limits; its numeric-literal limit remains 100.

The query has 22,479 grammar tokens excluding EOF, but SafeTokenSource also charges EOF. Its whitespace channel contains 4,548 commas, 2,783 spaces and 83 line feeds. SDL descriptions are string tokens, not comments. Grammar-rule depth is syntactic and does not expand fragment spreads, so 47 parser-rule levels and 15 field levels are different measures.

Verification: the original query validates against the full SDL, using mocked wiring, on both versions once the local parser token limit is raised. Exact validation limits pass; lowering each by one rejects the query. The same boundary checks pass for all five query parser limits above. The committed Spock tests retain these checks and the ENF comparison. All 108 targeted tests passed on Java 25:

./gradlew test --tests graphql.validation.LargeSchemaQueryComplexityTest \
  --tests graphql.validation.MergedQueryComplexityTest \
  --tests graphql.validation.FieldOccurrencesTest

Preserve iterative validation and fragment expansion while recording occurrence totals in traversal frames. Update fragment stack-safety tests to check merged fields and expanded occurrences separately.
Parse the existing definition-aligned SDL parts separately and merge their registries. This retains the complete schema and all count assertions while avoiding the full-suite heap exhaustion during parsing.
Initialize new builders with the standard limits so changing one threshold does not disable other protections. Document explicit disabling and retain isolated occurrence-count benchmarks.
Snapshot the current defaults once when creating a builder. Preserve inherited limits through overrides and keep existing builders unchanged when global defaults change.
@andimarek andimarek changed the title Use merged-field complexity limits with a separate occurrence budget Rework query complexity limits with merged fields and occurrence budgets Nov 11, 2026
@andimarek andimarek added the breaking change requires a new major version to be relased label Nov 11, 2026
@andimarek
andimarek merged commit 2a54094 into master Nov 11, 2026
10 checks passed
@andimarek andimarek added this to the 27 milestone Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change requires a new major version to be relased

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants