Skip to content

docs(proxy): warn about proxy usage with introspection and directives #7229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(proxy): warn about proxy usage with introspection and directives #7229

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1dbe13b
docs(proxy): warn about proxy usage with introspection and directives
EmrysMyrddin Nov 6, 2025
f6b0f4a
rephrase
EmrysMyrddin Nov 6, 2025
863a0da
rephrase
EmrysMyrddin Nov 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions packages/web/docs/src/content/gateway/other-features/security/demand-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Callout type="warning">

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.
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrasing of this sentence can be improved for clarity and a more professional tone. The use of 'But' is a bit informal for documentation.

This is because the schema is loaded via introspection when it is not provided, and introspection results do not include directives.


</Callout>

### `@cost` directive on the subgraph level

If you want to override the default cost calculations, you can use `@cost` directive on the subgraph
Expand Down
10 changes: 10 additions & 0 deletions packages/web/docs/src/content/gateway/supergraph-proxy-source.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Callout>

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.

</Callout>
Comment on lines 237 to 245
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This callout explains an important limitation and should probably be a warning type for better visibility and consistency with the other warning added in this PR. The phrasing can also be improved for clarity, as the first sentence currently reads like an instruction.

<Callout type="warning">

When using the Gateway in `proxy` mode with introspection, 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 features such as cache, auth, demand and control, or any other feature relying on directives.

</Callout>

Copy link
Collaborator Author

@EmrysMyrddin EmrysMyrddin Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rephrase the first sentence so that it's clear that it's the source schema that is introspected.

Copy link
Collaborator Author

@EmrysMyrddin EmrysMyrddin Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😔

Copy link
Member

@ardatan ardatan Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to tag it @gemini-code-assist

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apologies for the back and forth on this. You're right, clarifying the source of introspection is important. How about this revised phrasing for the callout?

It maintains the warning type for better visibility and explicitly mentions the "source schema" as requested.

Suggested change
<Callout>
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.
</Callout>
<Callout type="warning">
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 features such as cache, auth, demand and control, or any other feature relying on directives.
</Callout>

Copy link
Collaborator Author

@EmrysMyrddin EmrysMyrddin Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gemini-code-assist Rephrase the first sentence so that it's clear that it's the source schema that is introspected.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification, EmrysMyrddin! My previous suggestion in message 5 already incorporated this change by adding "of the source schema" to the sentence. Here it is again for your convenience:

<Callout type="warning">

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 features such as cache, auth, demand and control, or any other feature relying on directives.

</Callout>
Suggested change
<Callout>
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.
</Callout>
<Callout type="warning">
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 features such as cache, auth, demand and control, or any other feature relying on directives.
</Callout>


<Tabs items={['CLI', 'Configuration File']}>

{/* CLI */}
Expand Down
Loading