chore: propose @openfed__queryCache rfc

[Aenimus]

Summary by CodeRabbit

• New Features

  • Added support for a new query-response caching directive.
  • Introduced options to control cache duration, header-based cache variation, and a shadow mode for safer rollout.
  • Clarified how cache keys are generated for queries with and without arguments.

• Bug Fixes

  • Added validation to prevent invalid directive use on non-query fields.
  • Prevented conflicting cache directives from being applied to the same query field.
  • Rejected non-positive cache duration values.

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• If applicable, I have provided instructions for reviewers for manually validating my changes.
• Documentation has been updated on https://github.com/wundergraph/docs-website.
• I have read the Contributors Guide.

Open Source AI Manifesto

This project follows the principles of the Open Source AI Manifesto. Please ensure your contribution aligns with its principles.

[coderabbitai]

Walkthrough

This PR adds a new RFC markdown document proposing an @openfed__queryCache directive for caching query root field responses. It specifies directive arguments, cache key derivation rules, relationship to entity caching, and composition-time validation errors.

Changes

RFC: queryCache directive

Layer / File(s)	Summary
Directive intent and cache key rules rfc/openfed__queryCache-v1.md	Introduces the @openfed__queryCache directive's arguments (maxAge, includeHeaders, shadowMode) and defines cache key derivation for fields with and without arguments, requiring deterministic ordering for equivalent inputs.
Entity cache relationship and validation errors rfc/openfed__queryCache-v1.md	Documents the relationship to @openfed__entityCache and lists composition-time errors: invalid directive placement, directive conflicts, and invalid maxAge values.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Related Issues: None specified.

Related PRs: None specified.

Suggested labels: rfc, documentation

Suggested reviewers: None specified.

🐰 A whisker twitch, a cache key spun,
Query fields remembered, one by one,
No args? Just the name will do,
With args? Order them true and through,
An RFC hops in, docs alone, all done!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: proposing an RFC for @openfed__queryCache.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@rfc/openfed__queryCache-v1.md`:
- Around line 84-94: Clarify the query-cache contract in the RFC so it matches
the composer’s existing type-aware normalization: update the
`@openfed__queryCache` section to explicitly state whether `QueryCache` is
allowed on any query return type or only on entity-backed fields, and align that
with `entityCacheConfigByTypeName` and future entity-cache validation
expectations. If the intent is still type agnostic, say so and note that entity
type tracking in the composer is reserved for other directives; if not, revise
the wording and errors section to require entity-backed returns.
- Around line 8-19: The RFC for `@openfed__queryCache` introduces includeHeaders
and shadowMode without defining their behavior. Update the directive spec in
openfed__queryCache-v1 to explicitly state which request headers are part of the
cache key when includeHeaders is enabled, and define exactly what shadowMode
does versus normal caching. Use the directive name and its option fields
includeHeaders and shadowMode to keep the wording unambiguous and
implementation-ready.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f05b0154-9840-4a57-a4e2-19db4c320790

📥 Commits

Reviewing files that changed from the base of the PR and between 1d3b30e and 800e342.

📒 Files selected for processing (1)

• rfc/openfed__queryCache-v1.md