refactor(services): add content negotiation layer and integrate into HTTP pipeline

[BrynCooke]

Add content negotiation layer and integrate into HTTP pipeline

Task

Create and integrate a dedicated content negotiation layer to standardize HTTP content type handling across all federated subgraph communications, improving code organization and consistency.

Why

Content type validation logic was scattered across the codebase with some duplication. The router needed a centralized, reusable approach to content negotiation that follows the Tower service architecture pattern and provides consistent behavior across all subgraph communications.

Benefits:

• Centralized content type validation and response processing
• Elimination of code duplication
• Consistent content negotiation behavior across all subgraph requests
• Better foundation for supporting additional content types in the future

How

Phase 1: Content Negotiation Layer Creation

• Created apollo-router/src/services/layers/content_negotiation.rs with:
  • validate_content_type() function for standardized content type validation
  • http_response_to_graphql() function for response conversion
  • Support for application/json and application/graphql-response+json
  • Comprehensive error handling with backward-compatible error messages

Phase 2: HTTP Pipeline Integration

• Integrated layer into HttpClientServiceFactory.create() method
• Automatically adds appropriate Accept headers to all subgraph HTTP requests
• Positioned after plugins to preserve existing ordering and behavior
• Added comprehensive integration tests

Technical Details

• Zero behavioral changes: All existing content negotiation behavior preserved
• Tower service pattern: Uses standard Tower layer architecture for clean composition
• Accept header management: Automatically adds application/json, application/graphql-response+json to requests
• Backward compatibility: Preserves existing subscription callback Accept headers
• Error handling: Maintains existing error message formats and status codes
• Plugin compatibility: Integrates seamlessly with existing plugin architecture

Review Strategy

Focus on these specific areas not covered by CI:

1. Layer implementation: Review content_negotiation.rs for proper Tower service implementation and error handling patterns

2. HTTP pipeline integration: Verify that the layer integration in HttpClientServiceFactory.create() preserves existing plugin ordering and behavior

3. Accept header behavior: Confirm that Accept headers are properly added to subgraph requests without interfering with existing subscription callback headers

4. Backward compatibility: Check that all existing content type validation behavior and error messages remain identical

5. Test coverage: Review integration tests to ensure they properly validate the Accept header injection and content type processing functionality

---

Checklist

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

• [ ] Changes are compatible[^1]
• [ ] Documentation[^2] completed
• [ ] Performance impact assessed and acceptable
• [ ] Metrics and logs are added[^3] and documented
• Tests added and passing[^4]
  • [ ] Unit Tests
  • [ ] Integration Tests
  • [ ] Manual Tests

Exceptions

Note any exceptions here

Notes

[^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.

[github-actions[bot]]

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

[apollo-librarian[bot]]

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: 54db240af567f6c00c121ddf