Skip to content

Consolidate Good Faith settings in QueryComplexityLimits - #4550

Merged
andimarek merged 2 commits into
masterfrom
codex/consolidate-good-faith-limits
Nov 12, 2026
Merged

andimarek merged 2 commits into
masterfrom
codex/consolidate-good-faith-limits

Conversation

@andimarek

@andimarek andimarek commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Good Faith introspection settings currently live outside QueryComplexityLimits, and its enablement is applied differently by execution and direct validation. This PR puts all of those settings in the same immutable configuration while preserving the special introspection exception and GraphQL error handling.

Changes

Adds three builder settings, matching getters, and default constants:

Setting Default
introspectionLimitsEnabled(boolean) true
maxIntrospectionMergedFieldCount(int) 500
maxIntrospectionDepth(int) 20
  • newLimitsWithDefaults() snapshots all six general/introspection settings from the current JVM defaults. transform(...) copies an existing instance independently of those defaults. Toggling introspection preserves its configured thresholds; thresholds must be positive. The diagnostic string includes the new settings.
  • Queries selecting root __schema or __type keep the smaller of their general and introspection-specific merged-field/depth caps, applied to the whole mixed operation. General occurrence limits remain unchanged. Root detection through fragments/aliases and structural counting of conditional selections are unchanged; __typename alone does not activate introspection limits.
  • The existing six restricted-coordinate rules remain fixed and are controlled by the enable flag. Disabling introspection removes these restrictions and its additional caps while retaining general limits.
  • Validation reads the configuration directly, reusing existing merge groups and traversal. The ParseAndValidate.parseAndValidate(schema, input) convenience entry point now also reads request-specific limits; it previously ignored them. GoodFaithIntrospectionExceeded and its conversion during execution are preserved. The returned error retains its messages and BadFaithIntrospection classification; occurrence failures remain ordinary validation errors.
  • Removes GoodFaithIntrospection.java, the separate JVM/context enablement mechanism, and its unusual-configuration façade. Parser settings and the maximum-validation-error setting are unchanged.

Breaking changes and migration

GoodFaithIntrospection and its configuration APIs are removed without compatibility aliases. Update references and rebuild callers. The default protections remain enabled at 500 merged fields and depth 20. The changes below matter when configuring limits, filtering validation rules, or referring to the old Java error type.

1. Move JVM-wide configuration to QueryComplexityLimits.

// Before
GoodFaithIntrospection.enabledJvmWide(false);
// Or: GraphQL.unusualConfiguration().goodFaithIntrospection().enabledJvmWide(false);

// After: disable only the additional introspection protections
QueryComplexityLimits.setDefaultLimits(
    QueryComplexityLimits.getDefaultLimits()
        .transform(b -> b.introspectionLimitsEnabled(false)));

Replace isEnabledJvmWide() with QueryComplexityLimits.getDefaultLimits().isIntrospectionLimitsEnabled(). The unusual-configuration façade and its GoodFaithIntrospectionConfig type are removed. The new setter returns no previous value; read the current configuration before changing it if needed.

2. Replace the request context flag with a limits instance.

// Before
executionInput.getGraphQLContext().put(
    GoodFaithIntrospection.GOOD_FAITH_INTROSPECTION_DISABLED, true);

// After
QueryComplexityLimits limits = QueryComplexityLimits.newLimitsWithDefaults()
    .introspectionLimitsEnabled(false)
    .build();
executionInput.getGraphQLContext().put(QueryComplexityLimits.KEY, limits);

The boolean meaning is reversed: old DISABLED = true becomes introspectionLimitsEnabled(false). The old context key is no longer read, including when supplied as a string literal. Replace GoodFaithIntrospection.isEnabled(context) by reading isIntrospectionLimitsEnabled() from the context's limits instance, falling back to JVM defaults when absent.

Request settings now override JVM defaults in either direction: .introspectionLimitsEnabled(true) can re-enable protections disabled globally. Builders snapshot defaults at creation; set JVM defaults before creating builders that should inherit them. To preserve an existing request's other settings, use its transform(...) method.

3. Review every use of QueryComplexityLimits.NONE.

Previously, NONE disabled general limits but retained Good Faith protection. It now disables both general and introspection protections, including the restricted-coordinate checks. To preserve the previous policy:

QueryComplexityLimits limits = QueryComplexityLimits.NONE
    .transform(b -> b.introspectionLimitsEnabled(true));

This retains the default introspection thresholds of 500/20 while leaving general limits disabled. Disabling only introspection, as in steps 1–2, leaves general limits active.

4. Configure protections instead of filtering their validation rule.

OperationValidationRule.GOOD_FAITH_INTROSPECTION is removed. Remove references to that enum member and use .introspectionLimitsEnabled(false) where disabling the protections is intended. Even a predicate that deselects every validation rule now leaves configured introspection protections active.

Direct validation reads the same limits as execution. ParseAndValidate.parseAndValidate(schema, input) now also honors all request-context complexity settings, including general limits it previously ignored. Pass the intended limits and update tests that relied on those settings being ignored. Direct validation still throws GoodFaithIntrospectionExceeded; execution still converts it to the special GraphQL error.

5. Update imports and type checks for the relocated error.

Replace graphql.introspection.GoodFaithIntrospection.BadFaithIntrospectionError with graphql.introspection.BadFaithIntrospectionError. Its messages, serialized representation and BadFaithIntrospection classification are unchanged. Occurrence-limit failures remain ordinary validation errors.

6. Migrate constants and the old limit helper.

Removed member of GoodFaithIntrospection Replacement
GOOD_FAITH_MAX_MERGED_FIELD_COUNT QueryComplexityLimits.DEFAULT_MAX_INTROSPECTION_MERGED_FIELD_COUNT (500)
GOOD_FAITH_MAX_DEPTH_COUNT QueryComplexityLimits.DEFAULT_MAX_INTROSPECTION_DEPTH (20)
goodFaithLimits(existing) Supply the limits directly to validation; it combines general and introspection caps for introspection operations. There is no pre-clamped replacement object.

To customize thresholds, use .maxIntrospectionMergedFieldCount(n) and .maxIntrospectionDepth(n). Read configured values through the matching getters; the effective caps remain the smaller general/introspection values. Update exact toString() assertions to include the three new settings.

Verification

Existing alias, fragment, mixed-operation, directive, restricted-coordinate and general-limit coverage is retained. New tests cover configurable caps above and below defaults, JVM snapshots, request overrides in both directions, NONE, toggling without losing thresholds, rule-predicate independence, and exact special-error messages/classification/serialization through execution and direct validation.

  • Targeted validation, introspection and configuration tests passed, including the request-limit entry-point regression. A dedicated test preserves JVM configuration chaining coverage after removing the old Good Faith façade test; BaseConfig has 100% line and method coverage locally. PR checks show the full Java 17/21/25 matrix and coverage-guard results for the latest commit.
  • Local Java 25 / Apple M1 Pro JMH, three forks with 3 × 1 s warmup and 5 × 1 s measurement: ordinary tiny query 0.652 ± 0.013 → 0.637 ± 0.020 µs/op; ordinary fragment query 4.109 ± 0.081 → 4.093 ± 0.090 µs/op. The intervals overlap; no regression was detected in these two samples. Parsing/schema setup are outside the timed validation.

@andimarek andimarek added the breaking change requires a new major version to be relased label Nov 11, 2026
@andimarek andimarek added this to the 27 milestone Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Test Report

Test Results

Java Version Total Passed Failed Errors Skipped
Java 17 6448 (+29 🟢) 6392 (+29 🟢) 0 (±0) 0 (±0) 56 (±0)
Java 21 6448 (+29 🟢) 6392 (+29 🟢) 0 (±0) 0 (±0) 56 (±0)
Java 25 6448 (+29 🟢) 6392 (+29 🟢) 0 (±0) 0 (±0) 56 (±0)
jcstress 32 (±0) 32 (±0) 0 (±0) 0 (±0) 0 (±0)
Total 19376 (+87 🟢) 19208 (+87 🟢) 0 (±0) 0 (±0) 168 (±0)

Code Coverage (Java 25)

Metric Covered Missed Coverage vs Master
Lines 30534 3029 91.0% ±0.0%
Branches 9052 1498 85.8% ±0.0%
Methods 8144 1165 87.5% ±0.0%

Changed Class Coverage (5 classes)

Class Line Branch Method
g.GraphQLUnusualConfiguration
$GoodFaithIntrospectionConfig
removed removed removed
g.i.BadFaithIntrospectionError +88.9% 🟢 ±0.0% +85.7% 🟢
g.i.GoodFaithIntrospection removed removed removed
g.i.GoodFaithIntrospection
$BadFaithIntrospectionError
removed removed removed
g.ParseAndValidate +0.8% 🟢 ±0.0% +1.3% 🟢

Full HTML report: build artifact jacoco-html-report

Updated: 2026-11-11 22:31:28 UTC

@andimarek
andimarek merged commit 7163ee7 into master Nov 12, 2026
10 checks passed
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.

1 participant