@cacheControl support tests, fixes...

[ardatan]

Today if you @cacheControl directive in your subgraphs with Apollo Server, it sends cache control headers. And this is supported by http cache plugin. You don't need @composeDirective etc.

If you use those directives without ApolloServer, you can give the control to the gateway using Response Caching plugin but in order to have those directives in your gateway, you have to add the directive using @composeDirective so the supergraph can have it and response caching plugin can pick it up and use it.

This PR fixes the following issue when the directive definitions got lost while handling the supergraph using @graphql-tools/federation.
It also adds tests for both the cases mentioned above.

Needs to be documented on the website!!!

See the conversation below with @kamilkisiela to make sure to get what is documented!

After merging this PR, we need to update the docs with the two cases. And we need to mention http caching plugin can be used with the subgraph services returning cache control headers on its own and no @composeDirective.
If the subgraph is expected to control gateway's caching, response caching should be added and @composeDirective should be added for @cacheControl;

extend schema
  @link(
    url: "https://specs.apollo.dev/federation/v2.1"
    import: ["@composeDirective"]
  )
  @link(url: "https://the-guild.dev/mesh/v1.0", import: ["@cacheControl"])
  @composeDirective(name: "@cacheControl")

[theguild-bot]

🚀 Snapshot Release (alpha)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
@graphql-tools/federation	3.0.4-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd	npm ↗︎ unpkg ↗︎
@graphql-mesh/fusion-runtime	0.10.23-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd	npm ↗︎ unpkg ↗︎
@graphql-hive/gateway	1.7.2-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd	npm ↗︎ unpkg ↗︎
@graphql-mesh/plugin-opentelemetry	1.3.30-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd	npm ↗︎ unpkg ↗︎
@graphql-mesh/plugin-prometheus	1.3.18-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd	npm ↗︎ unpkg ↗︎
@graphql-hive/gateway-runtime	1.4.2-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd	npm ↗︎ unpkg ↗︎

[theguild-bot]

🚀 Snapshot Release (Binary for Linux-X64)

The latest changes of this PR are available for download (based on the declared changesets).

[theguild-bot]

🚀 Snapshot Release (Binary for macOS-ARM64)

The latest changes of this PR are available for download (based on the declared changesets).

[theguild-bot]

🚀 Snapshot Release (Bun Docker Image)

The latest changes of this PR are available as image on GitHub Container Registry (based on the declared changesets):

ghcr.io/graphql-hive/gateway:1.7.2-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd-bun

[theguild-bot]

🚀 Snapshot Release (Node Docker Image)

The latest changes of this PR are available as image on GitHub Container Registry (based on the declared changesets):

ghcr.io/graphql-hive/gateway:1.7.2-alpha-a700ce8ccd87f79236970cc1b9eb9826c65ccccd

[theguild-bot]

🚀 Snapshot Release (Binary for macOS-X64)

The latest changes of this PR are available for download (based on the declared changesets).

[theguild-bot]

🚀 Snapshot Release (Binary for Windows-X64)

The latest changes of this PR are available for download (based on the declared changesets).

[kamilkisiela]

When somebody runs hive schema:publish and points to a schema with @cacheControl directive then it won't be passed to supergraph SDL. Do I understand correctly that mesh-compose is needed to print the SDL of the subgraph?

[ardatan]

When somebody runs hive schema:publish and points to a schema with @CacheControl directive then it won't be passed to supergraph SDL.

You know @cacheControl is not part of federation spec. So @composeDirective should be used together with the directive definition like this;

extend schema
  @link(
    url: "https://specs.apollo.dev/federation/v2.1"
    import: ["@composeDirective"]
  )
  @link(url: "https://the-guild.dev/mesh/v1.0", import: ["@cacheControl"])
  @composeDirective(name: "@cacheControl")

If they use mesh-compose, it respects @cacheControl and automatically generates @composeDirective.
But if they don't use it, they have to add these composeDirective definition for cacheControl on their own.
Actually mesh compose would be a bit too much just to have composeDirective for cacheControl.

Is that what you asked or did I misunderstand it fully 😅 ?

[kamilkisiela]

Yeah, that's what I asked about. We need to make sure it's well documented

[Urigo]

@ardatan can you add documentation of this as part of this PR?

[Urigo]

also, how does Apollo's gateways handle this?

[ardatan]

also, how does Apollo's gateways handle this?

If I don't miss anything ( @kamilkisiela can correct me if I'm wrong ) , it respects cache-control headers as our http cache plugin does since @cacheControl is not available in the supergraph without @composeDirective;
This is my reference; https://www.apollographql.com/docs/apollo-server/performance/caching

[ardatan]

@ardatan can you add documentation of this as part of this PR?

I wanted to make everything clear first with this PR before starting a documentation PR on console repository.

[Urigo]

@ardatan I would like to review the docs and this together, as it will help me understand everything before I review

about Apollo, can you create an example and test how it actually behaves?
maybe a side by side example - one with Apollo Router and another with Hive Gateway?
Would also help me understand and might also help with docs

[kamilkisiela]

The "shortest" time from @cacheControl is turned into cache-control header by Apollo Server (via cache control plugin).
The gateway receives all cache-control headers and picks "shortest" for the entire response.

This is how it works in Apollo Server - gateway.

[kamilkisiela]

Apollo Router caches only the entity calls (to my knowledge) and it respects cache-control.
It supports global ttl (per subgraph) - as it obviously don't know the entity types it exposes.
It does not cache entire response emitted to the client.