pq: include operation name in "PQ not found" error

[glasser]

We have found that during migrations to PQ-based safelisting, it is helpful to have a bit more information about what operation the client is trying to run than just the hashed PQ ID, to help find the client app that is being blocked. While the client name can be found in the context, the operation name (if provided explicitly in the body's operationName field by the client) is helpful. We now provide this as an extension on the error.

(It is both directly helpful in that it is available in the JSON error response if you're looking at individual failures, and it also makes it easy for a router_service-level Rust or Rhai plugin that's trying to provide more observability into PQ errors to look at the error for the extra data. This error occurs before supergraph_service runs, which means that the operation name is not in an easily accessible place for plugins.)

---

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, 1 changed, 0 removed

* (developer-tools)/apollo-mcp-server/(latest)/best-practices.mdx

Build ID: 548084269000d84f260ab156

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

[glasser]

This is in some sense a workaround for #3642 (though not just for Rhai), but I think it is likely to be helpful in other circumstances. Another more plugin-focused design could be to add this to the context instead of the error, though then we'd have to choose a name that indicates "this is the explicit operation name found in the request" as opposed to the existing context entry (added later by query analysis) that means "this is the resolved operation name we are using".