metadata: Add ValueFromOutgoingContext

[yuyangguo42]

Partially Fixes: #8860

Why

There are use cases where only a single value needs to be read from outgoing gRPC metadata. Today the only way to do that is metadata.FromOutgoingContext, which merges and copies every header already staged into a brand-new map, even though the caller only wants one of them. The cost of that copy grows with however many headers have already accumulated in outgoing context — exactly the complaint raised in #8860.

What

This PR adds metadata.ValueFromOutgoingContext(ctx, key) []string, symmetric to the existing ValueFromIncomingContext, for reading a single header from outgoing gRPC metadata without merging and copying every other header already staged via AppendToOutgoingContext.

This is the API @easwars suggested in #8860 (comment):

Would adding a ValueFromOutgoingContext that is similar to ValueFromIncomingContext work for you? Please note that ValueFromOutgoingContext will not be as fast as ValueFromIncomingContext as the implementation would have check entries from the map and the added entries.

per #8860 (comment).

That tradeoff is exactly what this implementation does: it checks rawMD.md (case-insensitively, matching ValueFromIncomingContext's semantics) and then walks rawMD.added, accumulating matches in the same order FromOutgoingContext would, without allocating a new map or copying unrelated keys/values.

Matching rawMD.added entries case-insensitively via strings.EqualFold, rather than assuming they're already lowercased by AppendToOutgoingContext, makes no assumption about how rawMD.added was populated — the same guarantee FromOutgoingContext already makes for both rawMD.md and rawMD.added.

The allocation of vals is deferred until a match is actually found in rawMD.added (per gemini-code-assist's review suggestion), rather than always calling copyOf as soon as rawMD.md matches. When the key is found in both rawMD.md and rawMD.added, this avoids paying for a copyOf allocation that would otherwise immediately be discarded by the first append's growth — roughly halving allocations for that case (see key-found-in-md-and-added in the benchmark below).

The rawMD.added loop also tries a direct == before falling back to strings.EqualFold (a second gemini-code-assist suggestion), since AppendToOutgoingContext already lowercases keys in practice. Benchmarked with realistic-length keys (e.g. "grpc-timeout", not "k1"), this is a modest win when the key is found (~2-7% faster) at the cost of a small regression when it isn't (~6% slower — one extra comparison with no payoff) — a reasonable trade since looking up a header you expect to be present is the common case.

Benchmark

n is the number of unrelated headers already staged (one NewOutgoingContext call plus one AppendToOutgoingContext call) before reading the target key:

goos: darwin
goarch: arm64
pkg: google.golang.org/grpc/metadata
cpu: Apple M4 Pro
FromOutgoingContext/n=1         141.7 ns/op    432 B/op    4 allocs/op
ValueFromOutgoingContext/n=1     56.0 ns/op     16 B/op    1 allocs/op
FromOutgoingContext/n=10        404.9 ns/op    968 B/op   15 allocs/op
ValueFromOutgoingContext/n=10   107.2 ns/op     16 B/op    1 allocs/op
FromOutgoingContext/n=50       1596.0 ns/op   3592 B/op   55 allocs/op
ValueFromOutgoingContext/n=50   314.7 ns/op     16 B/op    1 allocs/op

(measured with b.Loop, per review feedback, which also removes the need for the manual anti-optimization b.Fatal checks the previous numbers were measured with)

At n=50, roughly 5x faster with 55x fewer allocations. This is still O(n) in the number of already-staged headers in the worst case, since rawMD.added isn't indexed by key, but it avoids the wasted work of copying and lowercasing every header the caller doesn't want.

Separately, BenchmarkValueFromOutgoingContext (now using realistic-length keys like "grpc-timeout"/"content-type" instead of "k1"/"k3", which understated strings.EqualFold's cost) shows both rawMD.added optimizations above:

key-found                    59.6 ns/op    16 B/op   1 allocs/op
key-not-found                50.7 ns/op     0 B/op   0 allocs/op
key-found-in-md-and-added    38.7 ns/op    32 B/op   1 allocs/op

Testing

• TestValueFromOutgoingContext covers exact match, case-insensitive match, a value present in rawMD.md accumulated with two later AppendToOutgoingContext calls (must match FromOutgoingContext's order, per TestAppendToOutgoingContext), values split solely across multiple AppendToOutgoingContext calls, not-found, and no-outgoing-metadata-at-all.
• TestValueFromOutgoingContext_AddedCaseInsensitive constructs rawMD.added directly with a mixed-case key (bypassing AppendToOutgoingContext's lowercasing) to verify the match is still found.
• TestValueFromOutgoingContext_PanicsOnOddPairs covers the defensive panic on a malformed rawMD.added entry, mirroring the identical guard already present in FromOutgoingContext.
• BenchmarkValueFromOutgoingContext mirrors the existing BenchmarkValueFromIncomingContext shape (key-found / key-not-found), plus a key-found-in-md-and-added case covering the deferred-allocation path above.
• BenchmarkValueFromOutgoingContextVsFromOutgoingContext produced the comparison table above.
• ValueFromOutgoingContext itself is at 100% statement coverage (go test -cover).
• go test ./metadata/..., go vet ./metadata/..., and gofmt are all clean. This branch is rebased on current master.

This is additive only — no existing exported behavior changes.

RELEASE NOTES:

• metadata: Add ValueFromOutgoingContext, which reads a single metadata value from outgoing context without copying the entire outgoing metadata into a new map.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: yuyangguo42 / name: Yuyang Guo (b2caded)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.21%. Comparing base (6f508fa) to head (4581f1b).
⚠️ Report is 24 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #9282      +/-   ##
==========================================
+ Coverage   83.05%   83.21%   +0.16%     
==========================================
  Files         422      423       +1     
  Lines       35040    35348     +308     
==========================================
+ Hits        29101    29415     +314     
+ Misses       4427     4425       -2     
+ Partials     1512     1508       -4     

Files with missing lines	Coverage Δ
metadata/metadata.go	94.73% <100.00%> (+1.08%)	⬆️

... and 53 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[yuyangguo42]

/easycla

[yuyangguo42]

PR Validation CI -- Don't have permission to apply a type label and will need help from owners.

[yuyangguo42]

@mbissa gentle ping for a review! ty!

[yuyangguo42]

@mbissa sry gentle ping again! Or @easwars is there anyone who might have a bit more bandwidth to help take a look? tyty!!

[easwars]

/gemini review

[easwars]

Moving to @mbissa for second set of eyes

[gemini-code-assist]

Code Review

This pull request introduces the 'ValueFromOutgoingContext' function to retrieve a specific metadata value from the outgoing context without copying the entire metadata map, accompanied by comprehensive unit tests and benchmarks. The feedback suggests an optimization to avoid double slice allocation and redundant copying when matches are found in both 'raw.md' and 'raw.added' by deferring the slice allocation until an append is actually needed.

[yuyangguo42]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the ValueFromOutgoingContext function to retrieve metadata values from the outgoing context case-insensitively without copying the entire metadata structure, along with comprehensive unit tests and benchmarks. The feedback suggests a performance optimization in the hot path of ValueFromOutgoingContext by performing a direct string comparison before falling back to strings.EqualFold, as keys are typically already lowercased.

[yuyangguo42]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the ValueFromOutgoingContext function to retrieve specific metadata values from the outgoing context in a case-insensitive manner without copying the entire metadata map, along with corresponding tests and benchmarks. The review feedback highlights a compatibility issue where the new benchmarks use b.Loop() (introduced in Go 1.24), which will break compilation on older supported Go versions. It is recommended to revert to the traditional for i := 0; i < b.N; i++ loop structure to maintain backward compatibility.

[yuyangguo42]

@easwars sry I updated some code according to the gemini review, left the comments unresolved, in case you'd like to take another look 🙏 ty!

[yuyangguo42]

@mbissa any chance you are around for review? thank you!!!

[yuyangguo42]

@easwars @mbissa gentle nudge! ty!