feat: support subgraph-level demand control

[carodewig]

This allows users to configure a maximum cost (and list size) per subgraph, rather than relying solely on a whole-query cost limit.

The new configuration looks something like:

demand_control:
  enabled: true
  mode: enforce
  strategy:
    static_estimated:
      max: 10
      list_size: 10
      subgraphs: # <---- everything from here down is new (all fields optional)
        all:
          max: 8
          list_size: 10
        subgraphs:
          products:
            max: 6
            list_size: 100
          users:
            max: 2
            # list_size omitted, 10 implied because of all.list_size
          reviews:
            list_size: 50
            # max omitted, 8 implied because of all.max

Consider a topProducts query, which fetches a list of products from a products subgraph and then performs an entity lookup for each product in a reviews subgraph. Assume that the products cost is 10 and the reviews cost is 5, leading to a total estimated cost of 15 (10 + 5).

Previously, you would only be able to restrict that query via demand_control.static_estimated.max:

• If you set it <= 15, the query would execute
• If you set it >15, the query would be rejected

This feature allows much more granular control. In addition to demand_control.static_estimated.max, which operates as before, there are also per subgraph maxes.

For example, if you set max 20 and reviews.max as 2, the query will 'pass' the aggregate check (15 < 20) and will execute on the products subgraph (no limit specified), but will not execute against the reviews subgraph (5 > 2). The result will be composed as if the reviews subgraph had returned null.

TODOs:

• move new feature to a new strategy, rather than overloading static_estimated. this is required to support the following item
• correctly compute per-subgraph actual costs; right now entity fetches do not contribute to the cost metrics
• make the actual cost be the sum of the per-subgraph actual costs, rather than computing it separately.
  right now, the actual computation seems to mostly reflect the shape of the output, not how much work had to be done to get there. as an example, if you have two subgraphs A B and a query path that goes query(A) -> entities fetch(B) -> entities fetch(A), the actual cost doesn't include the 'hidden' fields from A/B that made that query path possible (ie ids).
• documentation
• more tests

---

Checklist

Complete the checklist (and note appropriate exceptions) before the PR is marked ready-for-review.

• PR description explains the motivation for the change and relevant context for reviewing
• PR description links appropriate GitHub/Jira tickets (creating when necessary)
• Changeset is included for user-facing changes
• Changes are compatible¹
• Documentation² completed
• Performance impact assessed and acceptable
• Metrics and logs are added³ and documented
• Tests added and passing⁴
  • Unit tests
  • Integration tests
  • Manual tests, as necessary

Exceptions

Note any exceptions here

Notes

Footnotes

1. It may be appropriate to bring upcoming changes to the attention of other (impacted) groups. Please endeavour to do this before seeking PR approval. The mechanism for doing this will vary considerably, so use your judgement as to how and when to do this. ↩

2. Configuration is an important part of many changes. Where applicable please try to document configuration examples. ↩

3. A lot of (if not most) features benefit from built-in observability and debug-level logs. Please read this guidance on metrics best-practices. ↩

4. Tick whichever testing boxes are applicable. If you are adding Manual Tests, please document the manual testing (extensively) in the Exceptions. ↩

[apollo-librarian]

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 2 changed, 0 removed

* graphos/routing/(latest)/performance/caching/response-caching/faq.mdx
* graphos/routing/(latest)/performance/caching/response-caching/quickstart.mdx

Build ID: b52304f001e34e72e4689a10
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/b52304f001e34e72e4689a10

[github-actions]

@carodewig, please consider creating a changeset entry in /.changesets/. These instructions describe the process and tooling.

[carodewig]

Superseded by #8829