[glen-84]

Summary

• The routes that MapGraphQLPersistedOperations maps answer a method they do not map the way the GraphQL endpoint does. Under Draft20260903 that is 405 with Allow: GET, OPTIONS, POST (plus QUERY when EnableQueryRequests is on) and Accept-Query, or 204 for OPTIONS; under the older transport versions it is 404. The answer no longer depends on whether a MapGraphQL endpoint is mapped above the persisted path, which used to give 404 with the default paths and ASP.NET Core routing's 405 otherwise.
• A method-agnostic endpoint on both route patterns of the persisted route group receives every method the GET, POST, and QUERY routes do not match, since routing prefers the method-specific endpoints on the same pattern. ASP0022 reports that layout as a route conflict, so MapPersistedOperationMiddleware suppresses it (ASP0022 false positive for Map beside MapGet on the same route pattern dotnet/aspnetcore#69972).
• The HTTP transport and endpoints docs describe the new answers, and both 16.6 to 16.7 migration guides note that persisted routes mapped without MapGraphQL, or at their own path, answer 404 instead of routing's 405 under the older versions.

Test plan

• PersistedOperationMiddlewareTests covers PUT, DELETE, HEAD, QUERY while disabled, and OPTIONS on both route patterns across the transport versions, Allow and Accept-Query with QUERY enabled, persisted routes mapped without MapGraphQL, and a CORS preflight that the CORS middleware still answers.
• The gateway's PersistedOperationTests covers PUT and OPTIONS on a gateway that maps only the persisted routes.
• PersistedOperationMiddlewareTests, PersistedOperationTests, GraphQLOverHttpSpecTests, and HttpQueryMiddlewareTests pass in HotChocolate.AspNetCore.Tests, and the gateway's PersistedOperationTests and FusionActivityServerDiagnosticListenerTests pass.
• HotChocolate.AspNetCore.Pipeline builds for net8.0 through net11.0 without warnings.

[Copilot]

🟢 Approval recommended

No unresolved review issues were identified, and the supplied assessments unanimously find it ready for approval.

No open issues 🎉

What changed in this PR

This pull request updates persisted-operation routes to return transport-version-appropriate responses for unsupported HTTP methods, aligning them with GraphQL endpoint behavior while preserving CORS preflight handling.

Changes:

• Added fallback handling for unsupported methods, including 404, 405, and 204 OPTIONS responses with appropriate headers.
• Added ASP.NET Core and Fusion tests for unsupported methods, query negotiation, standalone routes, and CORS.
• Updated HTTP transport, endpoint, and migration documentation.

File	Summary
website/​content/​docs/​hotchocolate/​server/​http-transport.md	Documents persisted-route status codes and headers.
website/​content/​docs/​hotchocolate/​server/​endpoints.md	Documents unsupported-method behavior for persisted endpoints.
website/​content/​docs/​hotchocolate/​migrating/​migrate-from-16-6-to-16-7.md	Describes the persisted-route behavior change for Hot Chocolate migrations.
website/​content/​docs/​fusion/​migration/​migrate-from-16-6-to-16-7.md	Describes the persisted-route behavior change for Fusion migrations.
src/​HotChocolate/​Fusion/​test/​Fusion.AspNetCore.Tests/​PersistedOperationTests.cs	Tests unsupported methods and OPTIONS on gateway persisted routes.
src/​HotChocolate/​AspNetCore/​test/​AspNetCore.Tests/​PersistedOperationMiddlewareTests.cs	Tests transport-version behavior, allowed methods, QUERY support, standalone routes, and CORS.
src/​HotChocolate/​AspNetCore/​src/​AspNetCore.Pipeline/​PersistedOperationMiddleware.cs	Adds fallback handling for methods not mapped by persisted-operation routes.

_{Review effort: Lite}

[github-actions]

Patch coverage

100.0% of changed lines covered (21/21)

File	Covered	Changed	Patch %
…/src/AspNetCore.Pipeline/PersistedOperationMiddleware.cs	21	21	100.0% 🟢

---

Project coverage: 59.3% (314820/531228 lines)