Support multiple listSize directives

[morriswchris]

This is the final change on the router in the listSize enhancements. This PR allows the listSize directive to be used multiple times per field. The router aggregates the cost (e.g. takes the max expected_size) so cost stays safe across all usages. Single-directive behavior is unchanged.

Why

• One field, multiple usage patterns – e.g. pagination via first/last vs fetch-by-ids vs no args with a fallback size. Each pattern can have its own @listsize; cost reflects the worst case.
• Different nested fields – One directive can size by sizedFields: ["items"], another by sizedFields: ["totalCount"]. Aggregating avoids undercounting when different selections are used.
• Fallback + dynamic – Combine assumedSize (when no arg is provided) with slicingArguments (when the client sends a value). Cost uses the max so both cases are covered.

How (example)

products(first: Int, last: Int, ids: [ID!]): [Product!]!
  @listSize(slicingArguments: ["first", "last"], sizedFields: ["items"], requireOneSlicingArgument: false)
  @listSize(assumedSize: 20, sizedFields: ["totalCount"])

Cost is computed from all directives (e.g. max of their sizes), so limits and budgeting stay correct for every way the field is used.

A federation change will be needed to leverage this feature, which will come at a later date.

---

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

A subsequent PR will contain docs, and the PR to merge the feature branch into dev will contain the changeset

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 has no changes

The preview was not built because there were no changes.

Build ID: 701404ba0160469d2f37c2b1
Build Logs: View logs

[carodewig]

Same question RE having an Option - could this just be Vec<Arc> instead?

[carodewig]

Might be missing the business logic case here - but is there a situation where you'd want this to be a filter_map instead, because there are multiple descended values?

[morriswchris]

I looked more into this and you're right. I missed the case where we had 2 leaf nodes at the same level. filter_map is the correct approach. I've updated this section.

[morriswchris]

Since we removed Option, this means we no longer have the option for a None set of SizedFields when parsing

[dariuszkuc]

The changes look fine for now but once we make the change to repeatable we'll have to clean up the API (e.g. remove list_size_directive_from_field_definition and instead update the code to always process the list)

[dariuszkuc]

this is not a valid schema (as in this federation change still needs to happen) so unsure if this should be included in the PR

[morriswchris]

The changes look fine for now but once we make the change to repeatable we'll have to clean up the API (e.g. remove list_size_directive_from_field_definition and instead update the code to always process the list)

Thanks for the review. I agree with the cleanup of the API, which I would slot for the next router release after the federation change.