envoyproxy / envoyproxy/envoy

http2: allow configuring upstream headers as HPACK never indexed

Open
#46,584 4 comments 0 reactions 0 assignees View on GitHub
area/http enhancement stale
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.