From 1dbe13be300abcea781cd4d012c99a67750b80ec Mon Sep 17 00:00:00 2001 From: Valentin Cocaud Date: Thu, 6 Nov 2025 11:36:41 +0100 Subject: [PATCH 1/3] docs(proxy): warn about proxy usage with introspection and directives --- .../gateway/other-features/security/demand-control.mdx | 8 ++++++++ .../src/content/gateway/supergraph-proxy-source.mdx | 10 ++++++++++ 2 files changed, 18 insertions(+) diff --git a/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx b/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx index 8e6f8a35df4..8b4d383ca57 100644 --- a/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx +++ b/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx @@ -101,6 +101,14 @@ query BookQuery { Even if you can set defaults and customize the cost calculation programmatically in the gateway, it can also be customized on the subgraph level by using `@cost` and `@listSize` directives. + + +Customization using directives is not available when using the Gateway in `proxy` mode without providing the `schema` option. + +This limitation is due to the schema being loaded via introspection when it is not provided. But introspection result doesn't include directives. + + + ### `@cost` directive on the subgraph level If you want to override the default cost calculations, you can use `@cost` directive on the subgraph diff --git a/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx b/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx index 8645eb4c1f1..982416a5ec7 100644 --- a/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx +++ b/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx @@ -234,6 +234,16 @@ This allows you to add features such as [usage reporting](/docs/gateway/usage-re [persisted documents](/docs/gateway/persisted-documents) without modifying your existing GraphQL API. + + +When using introspection in proxy mode disallow schema directive usage, since directives are not +part of the introspection response. + +This means proxy mode with introspection is not compatible with directive driven cache, auth, demand +and control, or any other feature relying on directives. + + + {/* CLI */} From f6b0f4aa7396e04883eeb1ae19155b07d39d21d7 Mon Sep 17 00:00:00 2001 From: Valentin Cocaud Date: Thu, 6 Nov 2025 11:45:19 +0100 Subject: [PATCH 2/3] rephrase --- .../gateway/other-features/security/demand-control.mdx | 6 ++++-- .../docs/src/content/gateway/supergraph-proxy-source.mdx | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx b/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx index 8b4d383ca57..1f7b47bcfa4 100644 --- a/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx +++ b/packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx @@ -103,9 +103,11 @@ can also be customized on the subgraph level by using `@cost` and `@listSize` di -Customization using directives is not available when using the Gateway in `proxy` mode without providing the `schema` option. +Customization using directives is not available when using the Gateway in `proxy` mode without +providing the `schema` option. -This limitation is due to the schema being loaded via introspection when it is not provided. But introspection result doesn't include directives. +This is because the schema is loaded via introspection when it is not provided, and introspection +results do not include directives. diff --git a/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx b/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx index 982416a5ec7..fd58baa589e 100644 --- a/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx +++ b/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx @@ -236,8 +236,8 @@ API. -When using introspection in proxy mode disallow schema directive usage, since directives are not -part of the introspection response. +When using the Gateway `proxy` mode with a introspected remote schema, schema directives can't be +used, since directives are not part of the introspection response. This means proxy mode with introspection is not compatible with directive driven cache, auth, demand and control, or any other feature relying on directives. From 863a0da8b3d1e6af4fc92c4ed950f7e6fcf6b420 Mon Sep 17 00:00:00 2001 From: Valentin Cocaud Date: Thu, 6 Nov 2025 14:46:30 +0100 Subject: [PATCH 3/3] rephrase --- .../web/docs/src/content/gateway/supergraph-proxy-source.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx b/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx index fd58baa589e..e59d412a2eb 100644 --- a/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx +++ b/packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx @@ -236,8 +236,8 @@ API. -When using the Gateway `proxy` mode with a introspected remote schema, schema directives can't be -used, since directives are not part of the introspection response. +When using the Gateway in `proxy` mode with introspection of the source schema, schema directives +are not supported because they are not part of the introspection response. This means proxy mode with introspection is not compatible with directive driven cache, auth, demand and control, or any other feature relying on directives.