HTTP/1.1 Header Casing

When handling HTTP/1.1, Envoy will normalize the header keys to be all lowercase. While this is compliant with the HTTP/1.1 spec, in practice this can result in issues when migrating existing systems that might rely on specific header casing.

To support these use cases, Envoy allows configuring a formatting scheme for the headers, which will have Envoy transform the header keys during serialization.

To configure this formatting on response headers, specify the format in the http_protocol_options. To configure this for upstream request headers, specify the formatting in http_protocol_options in the cluster’s extension_protocol_options.

Currently Envoy supports two mutually exclusive types of header key formatters:

Stateless formatters

Stateless formatters are run on encoding and do not depend on any previous knowledge of the headers. An example of this type of formatter is the proper case words formatter. These formatters are useful when converting from non-HTTP/1 to HTTP/1 (within a single proxy or across multiple hops) or when stateful formatting is not desired due to increased memory requirements.

Stateful formatters

Stateful formatters are instantiated on decoding, called for every decoded header, attached to the header map, and are then available during encoding to format the headers prior to writing. Thus, they traverse the entire proxy stack. An example of this type of formatter is the preserve case formatter configured via the stateful_formatter field. The following is an example configuration which will preserve HTTP/1 header case across the proxy.

Note

When Stateful formatters are used, headers added internally by Envoy or by filters (e.g. the Lua filter) will still be lowercased.

static_resources:
  listeners:
  - address:
      socket_address:
        address: 0.0.0.0
        port_value: 443
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          http_protocol_options:
            header_key_format:
              stateful_formatter:
                name: preserve_case
                typed_config:
                  "@type": type.googleapis.com/envoy.extensions.http.header_formatters.preserve_case.v3.PreserveCaseFormatterConfig
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
          route_config:
            virtual_hosts:
            - name: default
              domains: ["*"]
              routes:
              - match: {prefix: "/"}
                route:
                  cluster: service_foo
  clusters:
  - name: service_foo
    typed_extension_protocol_options:
      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
        explicit_http_config:
          http_protocol_options:
            header_key_format:
              stateful_formatter:
                name: preserve_case
                typed_config:
                  "@type": type.googleapis.com/envoy.extensions.http.header_formatters.preserve_case.v3.PreserveCaseFormatterConfig
    load_assignment:
      cluster_name: some_service
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 8080