[magnusnordlander]

Gives this subgraph Apollo Server's cache-hint semantics: @cacheControl annotations in the schema become a Cache-Control response header, and @cacheTag is passed through to the federated SDL for the router to use for invalidation.

Previously the bundle emitted no cache headers at all — GraphController always returned a bare JsonResponse and the only header it ever set was CORS — so a router in front of it could cache nothing.

Apollo splits the two directives between the parties, and so does this:

Directive	Interpreted by	Effect
@cacheControl	this subgraph	produces the Cache-Control response header
@cacheTag	the router	tags data for invalidation; the subgraph only publishes it

Scope

SDL and YAML only (no PHP attributes/annotations), static directives only (no setCacheHint() equivalent). Ships opt-in behind redeye_graphql.cache_control.enabled, because switching it on gives a header to responses that previously had none — including no-store for anything unannotated.

redeye_graphql:
    cache_control:
        enabled: true
        default_max_age: 0
        calculate_http_headers: always   # always | if-cacheable | never

How it works

The per-field hint is collected in TracingReferenceExecutor::resolveFieldValueOrError, which graphql-php calls once per field per parent object — the direct equivalent of Apollo's willResolveField. The recorder travels in the GraphQL context value rather than being injected, since graphql-php builds the executor through a static factory with no container access; that also makes it reachable from the _entities resolver.

The response policy is the smallest maxAge among fields that decided one, private if any of them said so. A field that never decides contributes nothing — which is exactly how inheritance works, since non-root scalar fields stay undecided.

_entities

Query._entities is a root field, so the default rule would pin every federated entity fetch at maxAge: 0 and no entity response could ever be cached — defeating the point of the feature for a subgraph. It is exempt from the root default and instead takes the hint from the concrete type of each representation, matching Apollo.

Published SDL

The @link moves from federation v2.0 to v2.12, which is where @cacheTag is defined. @cacheTag arrives through that import and gets no local definition (having both is a composition error); @cacheControl is not a federation directive, so it is declared locally together with its CacheControlScope argument type.

Verification

• 801 tests, up from 697. The only failures are 5 pre-existing GetUserTest errors, caused by Symfony\Component\Security\Core\Security being removed in Symfony 7 — they should not appear on the CI matrix, which pins 5.4–6.4.
• Real HTTP responses asserted in tests/Functional/CacheControl/: cacheable, type-level hint, private scope, unannotated, errored, batch min, if-cacheable, and disabled.
• rover supergraph compose succeeds on Federation 2.12, with @cacheTag surviving into the supergraph as @join__directive(graphs: [POSTS], name: "federation__cacheTag", args: {format: "post-{$key.id}"}). @cacheControl correctly does not survive — the router learns the TTL from the header. One cosmetic hint: CacheControlScope is "defined but unused".

Incidental fixes

Three pre-existing bugs in code this change makes load-bearing:

• DirectiveNode broke out of its loop after @deprecated, silently dropping every directive written after it on the same field. Regression test included.
• TracingReferenceExecutor called ->startChild() on a span that SentrySdk::getCurrentHub()->getSpan() may legitimately return as null.
• A dead Webmozart\Assert import for a package the bundle never required.

Notes for review

• no-store, private, not bare no-store. Symfony's ResponseHeaderBag appends , private to any Cache-Control naming neither public, private nor s-maxage. Not reachable through Symfony's Response API (setCache() goes the same route) and means the same thing to every cache.
• phpunit.xml.dist gets an explicit memory_limit. The suite boots a kernel per functional test case and already sat at ~124M of the 128M default before this branch.
• PHPStan could not be run locally — 0.12.100 fails to parse Symfony 7 syntax (386 parse errors on a clean checkout, all in vendor/symfony/*). No findings in the new code and phpstan-baseline.neon is unchanged, but CI is the first real run.

Docs: docs/definitions/cache-control.md.