Add option to resize HPACK dynamic table

[petedmarsh]

Add disableHpackDynamicTable() to the Netty client and server builders.

When enabled, Netty uses a zero-sized HPACK dynamic table and advertises SETTINGS_HEADER_TABLE_SIZE = 0 to its peer. The default remains unchanged.

Also fix grpc-okhttp to apply a peer's header-table setting to its outbound encoder instead of its inbound decoder.

Compliant peers require no configuration changes. Older grpc-okhttp releases must be upgraded before enabling this option on their Netty peer.

OpenAI Codex (GPT-5) was used to implement all changes in this PR.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: petedmarsh / name: Peter Marsh (9f17470, eec3174)

[ejona86]

Can you describe what your goal is? It seems like it is to reduce idle memory usage?

The okhttp bug has been on our radar, but needed some further investigation (#12819 . #12818 is similar but I saw it didn't remove hpackReader.headerTableSizeSetting(), so it was highly suspect; it was also AI-generated, and we really want a human to look at it). We will definitely want to keep any changes there as a separate commit.

[petedmarsh]

Where I work we send a lot of high cardinality metadata/header values on our internal request paths and we have seen via profiling that the dynamic HPACK table just burns CPU and doesn't save network bytes. I'm perfectly happy if this PR is not merged BUT I would really like the ability to turn off the dynamic HPACK table one way or another.

…

On Thu, 6 Aug 2026, 19:57 Eric Anderson, ***@***.***> wrote: *ejona86* left a comment (grpc/grpc-java#12973) <#12973 (comment)> Can you describe what your goal is? It seems like it is to reduce idle memory usage? The okhttp bug has been on our radar, but needed some further investigation (#12819 <#12819> . #12818 <#12818> is similar but I saw it didn't remove hpackReader.headerTableSizeSetting(), so it was highly suspect; it was also AI-generated, and we really want a human to look at it). We will definitely want to keep any changes there as a separate commit. — Reply to this email directly, view it on GitHub <#12973?email_source=notifications&email_token=AAJDC6UHQTM3WGO2JIQ3OVT5ITBI7A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMRQHAYDAOJVGEY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5208009511>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJDC6XX6ZA72ZA3U5WQT5L5ITBI7AVCNFSNUABEKJSXA33TNF2G64TZHMZDONZSHE4TENR3JFZXG5LFHM2TAOBSGYYDEMZRGSQXMAQ> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AAJDC6XA2JZI6COD62Q7WOL5ITBI7A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMRQHAYDAOJVGEY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/AAJDC6T2T545PBQNIAGMKHD5ITBI7A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMRQHAYDAOJVGEY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

[ejona86]

Can you share what function(s) is hot? Is it the key/value hashing?

Receiving indexed values in HPACK seems reasonably cheap. I expect it is just the encoder costing you.

One thing for us to consider is this approach looks to be incompatible with Http2FrameCodecBuilder. We really need to migrate off the old Netty API that we are using, at which point we'll be limited to what Http2FrameCodecBuilder offers. (So then we have to either drop this feature or upstream it to Netty.)

[petedmarsh]

We have quite a significant amount of headers (a lot of individual headers, some with high cardinality, and some with high cardinality and size of value), we've observed via production profiling that this is actually casuing signficiant CPU usage.

Here's a benchmark:

https://github.com/petedmarsh/grpc-java/tree/disable-dynamic-hpack-benchmark

## Direct change when disabling the table

Positive throughput is better; negative bytes and CPU are better.

| Value profile | Throughput | Modeled bytes | Process CPU |
| --- | ---: | ---: | ---: |
| Low length | +98.275% | +102.576% | -49.069% |
| High length | +18.114% | +19.040% | -15.381% |

The direct encoder results show statistically resolved CPU and throughput improvements, accompanied
by statistically resolved increases in encoded bytes.

## End-to-end unary gRPC

| Value profile | Dynamic table | Throughput (RPC/s) | Client bytes/RPC | Process CPU (us/RPC) |
| --- | --- | ---: | ---: | ---: |
| Low length | 4 KiB | 24,807.936 +/- 4,357.322 | 350.793 +/- 0.004 | 36.032 +/- 7.189 |
| Low length | Disabled | 25,666.263 +/- 983.054 | 717.585 +/- 0.002 | 34.700 +/- 1.669 |
| High length | 4 KiB | 24,187.775 +/- 1,832.197 | 1,524.586 +/- 0.004 | 36.926 +/- 2.476 |
| High length | Disabled | 25,873.456 +/- 3,399.571 | 1,803.585 +/- 0.002 | 34.459 +/- 4.809 |

### End-to-end change when disabling the table

| Value profile | Throughput | Client bytes | Process CPU |
| --- | ---: | ---: | ---: |
| Low length | +3.460% | +104.561% | -3.697% |
| High length | +6.969% | +18.300% | -6.681% |

The end-to-end CPU and throughput confidence intervals overlap, so those observed changes are not
statistically resolved by this run. The client-byte increases are resolved.

(Benchmark also generated with Open AI / Codex / Sol 5)

[petedmarsh]

I'm also happy to change this to make the HPACK dynamic table size configurable, rather than just disable-able, in some cases bigger tables might be better.

I also know that AI generated contributions are slightly suspect, but I am confident in the analysis from our production profiling and that the benchmark is at least somewhat representative. This PR itself I am not too concernred about but I would like this functionality in grpc-java (as well as the never index changes in my other pr #12976) if someone has to re-do by hand.

If AI generated code is not an issue then I am happy to adjut - cheers!

[teorosu]

( for context: i work with @petedmarsh )

hey @ejona86. i tried to correlate our findings with the encoder/decoder code flow.

Can you share what function(s) is hot?

the hot logic is in HpackEncoder.encodeHeader but also some in HpackDecoder (less though on decoder side)

Is it the key/value hashing?

the hashing is a meaningful chunk, but not the majority

• 2 x AsciiString.hashCode(name/value) per header ( in encodeHeader )
• ( i think there's more hashing later e.g. on eviction, but i assume you were referring to hashCode above )

the rest is always a miss walk:

• getEntryInsensitive ( + equalsVariableTime under it) - lookup misses
• ensureCapacity() -> remove() - > removeNameEntryMatchingCounter + removeNameValueEntry
• encodeAndAddEntries() -> getEntry + addNameEntry / addNameValueEntry - the insert half

Is it just the encoder?

mostly. the decoder side is smaller, but it's not free:

• caller sends literal-with-incremental-index => the receiver pays HpackDecoder.insertHeader ( + HpackDynamicTable.add inside )
• eviction happens on decoder side as well

let me/us know if anything is missing. thank you!

[petedmarsh]

I have updated this to make it possible to change the size of the table, not just disable it, for two reasons:

1. This is more generally flexible
2. Once we take into account bytes transferred and networking fees even with thrashing it might be cheaper to have a bigger table

[ejona86]

Looking at the benchmark, I feel like it is making a case that this approach is not appropriate. It shows 100% increase with maybe 2 µs saved, but it is too noisy to really say. "A benchmark got 7%±14% faster". And it is using direct executor and pre-serializing headers, so that this is the best case you'll see and seems pretty far from reality. Also, it shows that HPACK is working, as the number of bytes sent doubles when disabling it (which is surprising to me, because the benchmark looks really pathological yet HPACK was still helping).

#12976 seems like it'd get you all you need and is easier to accept. If that's not sufficient it seems you really need changes to Netty.

... This had me look into other things (like other approaches, optimizations) and took me pretty far afield. Sending what I've written just so I won't lose it over the weekend.

[petedmarsh]

Thanks for looking into it!

We also did some more benchmarking and came to similar conclusions (never indexing is better than disabling).

Increasing the size of the dynamic table also helped drive down the number of bytes sent for headers. I've changed this PR to allow for the table size to be set rather than just disabled.

[petedmarsh]

Hi @ejona86!

After more examination, I am still interesting in having this option but to increase HPACK table size rather than set it to 0 (disable).

On that basis would this be more acceptable?

[ejona86]

We could increase the receive header table size, but since netty/netty@7e8b325 Netty is limited to 8 KiB for sending, and 4 KiB by default. So this code right now will max out at 4 KiB for sending.

[petedmarsh]

In that case would something like this:

https://github.com/grpc/grpc-java/compare/master...petedmarsh:grpc-java:hpack-8k-default-master?expand=1

where advertised/accepted table sizes default to 8 kIb be possible to merge?

[ejona86]

where advertised/accepted table sizes default to 8 kIb be possible to merge?

Is your system mixed between languages? Because that would have no behavior changes when grpc-java clients and servers are communicating.

[petedmarsh]

For us it's largely grpc-java servers/clients - perhaps I am mistaken but I thought the changes in https://github.com/grpc/grpc-java/compare/master...petedmarsh:grpc-java:hpack-8k-default-master?expand=1 would:

1. make grpc servers advertise 8kib hpack tables by default
2. let grpc clients accept and use 8kib hpack tables by default

(I could well be wrong, sorry if so)

Maybe that is a simpler change than allowing this to be configurable, but perhaps it's too drastic of a change to put out by default too

[ejona86]

(I could well be wrong, sorry if so)

Both sides would advertise 8 KiB. But both encoders would limit themselves to 4 KiB because of the maxHeaderTableSize = Math.min(maxHeaderTableSize, nameEntries.length * 64); in netty/netty@7e8b325 and the default nameEntries.length is 64.

... Which I see now is inaccurate, because gRPC actually uses a hash table size of 16 (on both client and server), so is now recently limited to 1 KiB. 16 used to be the old default, but was changed in netty/netty@0df408e .

[petedmarsh]

Ah! That is probably quite bad for us if it's 1 KiB tables - I will raise a PR against netty (unless its easier/faster for you to do so).

[ejona86]

What would be in the Netty PR? I would have expected a gRPC PR to change the hard-coded 16