Add middleware for header count and header list item limits in limits plugin

[Copilot]

Overview

Expands the middleware functionality in the limits plugin to include two new header-based request limits, building on the foundation established in PR #8269.

New Features

1. Request Header Count Limit

Adds http_max_request_headers configuration to limit the total number of headers in an HTTP request:

limits:
  http_max_request_headers: 100  # Reject requests with >100 headers

2. Header List Items Limit

Adds http_max_header_list_items configuration to limit the number of values within individual header fields:

limits:
  http_max_header_list_items: 5  # Reject headers with >5 comma-separated values

Both limits are opt-in (when not specified, no limit is enforced) and respond with 431 Request Header Fields Too Large when exceeded.

Implementation Details

Middleware Architecture

• RequestHeaderCountLimitLayer: Enforced at the middleware level, counts total headers per request
• RequestHeaderListItemsLimitLayer: Counts individual values within each header field (e.g., Accept: json, xml, html = 3 items)
• Integrated into existing limits plugin service stack using tower service patterns
• Consistent error handling with existing body limit middleware

Error Response Format

When limits are exceeded, returns standard GraphQL error format:

{
  "errors": [
    {
      "message": "Request header fields too many",
      "extensions": {
        "details": "Request header fields too many",
        "code": "INVALID_GRAPHQL_REQUEST"
      }
    }
  ]
}

Distinction from Server-Level Limits

These middleware-level limits complement existing server-level configuration (server.http.max_headers):

• Server-level: Enforced by HTTP implementation, protocol-specific, maximum performance
• Middleware-level: Enforced by Apollo Router, consistent across HTTP versions, configurable routing logic

Testing

• Unit tests: Verify middleware behavior with various header configurations
• Integration tests: End-to-end validation through router request pipeline
• Fixtures: Test configuration files for different limit scenarios

Documentation

Updated docs/source/routing/security/request-limits.mdx with:

• Configuration examples for both new limits
• Explanation of middleware vs server-level limit differences
• JSON response format examples
• Usage recommendations

Backward Compatibility

• All changes are additive and opt-in
• Existing functionality unchanged
• No breaking changes to configuration or API

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• esm.ubuntu.com
  • Triggering command: /usr/lib/apt/methods/https (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

This pull request was created as a result of the following prompt from Copilot chat.

Expand the middleware functionality added in PR #8269 to address additional linked issues. Specifically:

1. Add middleware to limit the number of headers in a request.
2. Add middleware to limit the number of items in a header list.

Ensure that the new middleware integrates seamlessly with the existing implementation of the max header size middleware. Provide appropriate configuration options for each new middleware feature, such as default values and overrides. Update documentation and unit tests to cover the new functionalities.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[apollo-cla]

@Copilot: Thank you for submitting a pull request! Before we can merge it, you'll need to sign the Apollo Contributor License Agreement here: https://contribute.apollographql.com/

[apollo-librarian]

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 0 removed

* graphos/routing/(latest)/security/request-limits.mdx

Build ID: e3b3077edcf1cd2a71f32d95
Build Logs: View logs

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