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.

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
                route_config:
                  virtual_hosts:
                    - name: default
                      domains: ["*"]
                      routes:
                        - match: { prefix: "/" }
                          route:
                            cluster: service_foo
  clusters:
    - name: service_foo
      connect_timeout: 15s
      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