http2: allow configuring upstream headers as HPACK never indexed
- Dominant language
- C++
- Stars
- 28.9k
- Forks
- 5.6k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 437
Description
*Title*: http2: allow configuring upstream headers as HPACK never indexed
*Description*:
Envoy should allow operators to configure HTTP/2 request headers to use
HPACK's "Literal Header Field Never Indexed" representation when forwarding
requests to an upstream.
This is useful for high-cardinality values such as request IDs, trace IDs, or
per-request tokens. These values are unlikely to be reused, so adding them to
the dynamic HPACK table provides little compression benefit while causing
unnecessary insertions, lookups, and evictions. Marking them as never indexed
avoids this table churn and can reduce CPU usage in Envoy and the upstream
HTTP/2 decoder.
Envoy terminates the downstream HTTP/2 connection and creates a separate
upstream HTTP/2 connection. Therefore, the client's HPACK indexing decision
cannot be preserved automatically. Envoy must apply the configured policy
when it re-encodes the headers for the upstream connection.
Example configuration:
```yaml
static_resources:
clusters:
- name: upstream
connect_timeout: 2s
type: STRICT_DNS
load_assignment:
cluster_name: upstream
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: upstream.example.com
port_value: 8080
typed_extension_protocol_options:
envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
"@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
explicit_http_config:
http2_protocol_options:
headers_to_never_index:
- x-request-id
- x-trace-id
- x-high-cardinality-token
```
Configured headers are forwarded unchanged, but their upstream HTTP/2 header
fields are encoded using the never-indexed representation. Headers not listed
in the configuration retain their existing HPACK indexing behavior.
*Relevant Links*:
- [POC Implementation branch](https://github.com/petedmarsh/envoy/tree/http2-never-index-headers)
- [RFC 7541 section 6.2.3: Literal Header Field Never Indexed](https://www.rfc-editor.org/rfc/rfc7541#section-6.2.3)
The POC implementation branch was generated by OpenAI Codex using GPT-5. It works and improves both cpu and bytes transferred in my benchmarks, but I am not a C++ programmer so I cannot vouch for the code. It is a POC/example only.
Contributor guide
Research direction
Start by reviewing the linked POC implementation branch and RFC 7541 section 6.2.3, then trace how the HttpProtocolOptions http2_protocol_options configuration reaches upstream header encoding. Done means configured headers use HPACK's never-indexed representation while remaining unchanged, unconfigured headers retain current behavior, and the relevant behavior is covered by validation or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- networking
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100