xds: Add header mutations library by sauravzg · Pull Request #12494 · grpc/grpc-java · GitHub

This commit introduces a library for handling header mutations as specified by the xDS protocol. This library provides the core functionality for modifying request and response headers based on a set of rules.

The main components of this library are:

HeaderMutator: Applies header mutations to Metadata objects.
HeaderMutationFilter: Filters header mutations based on a set of configurable rules, such as disallowing mutations of system headers.
HeaderMutations: A value class that represents the set of mutations to be applied to request and response headers.
HeaderMutationDisallowedException: An exception that is thrown when a disallowed header mutation is attempted.

This commit also includes comprehensive unit tests for the new library.

@kannanjgithub PTAL, if the implementation mutation meets the spec for ext proc. You need to TAL at the last two commits only.
I'll eventually move it down the PR chain later to ensure that the dependencies for ext_proc are merged earlier.

Sending comments for headermutations.

Reviewed rest of the PR.

@kannanjgithub I've resolved or clarified the comments as applicable. PTAL

@kannanjgithub Addressed the comments. PTAL.

/gemini review

Code Review

This pull request introduces a CachedChannelManager to manage gRPC channels based on service configurations, alongside a new framework for processing xDS header mutations. The mutation framework includes components for filtering, applying, and validating header changes. Review feedback highlights the need to align the mutation order with the xDS specification, correct the logic for header allowance expressions, optimize performance by pre-calculating metadata keys, and improve error reporting with more descriptive exception messages.

/gemini review - Please don't repeat previously addressed comments.

Code Review

This pull request introduces a CachedChannelManager for managing gRPC channels and a framework for xDS header mutations, including filtering and application logic. Key feedback includes aligning the order of header operations in HeaderMutator with Envoy by processing removals before additions and caching Metadata.Key objects to optimize performance. Furthermore, the filtering logic in HeaderMutationFilter needs adjustment to ensure disallowed headers properly trigger exceptions when strict validation is active.

This commit introduces a library for handling header mutations as specified by the xDS protocol. This library provides the core functionality for modifying request and response headers based on a set of rules. The main components of this library are: - `HeaderMutator`: Applies header mutations to `Metadata` objects. - `HeaderMutationFilter`: Filters header mutations based on a set of configurable rules, such as disallowing mutations of system headers. - `HeaderMutations`: A value class that represents the set of mutations to be applied to request and response headers. - `HeaderMutationDisallowedException`: An exception that is thrown when a disallowed header mutation is attempted. This commit also includes comprehensive unit tests for the new library.

…spec

… headermutations libraries

https://github.com/grpc/proposal/pull/481/changes#r3022089452

Some unit tests are missing.

Update since it's been 24 hours since comments: I am slightly caught up in other items and gemini is taking more babysitting in generating tests than I expected. So, I'll be able to update this sometime later tonight or early monday.

This commit introduces a library for handling header mutations as specified by the xDS protocol. This library provides the core functionality for modifying request and response headers based on a set of rules. The main components of this library are: - `HeaderMutator`: Applies header mutations to `Metadata` objects. - `HeaderMutationFilter`: Filters header mutations based on a set of configurable rules, such as disallowing mutations of system headers. - `HeaderMutations`: A value class that represents the set of mutations to be applied to request and response headers. - `HeaderMutationDisallowedException`: An exception that is thrown when a disallowed header mutation is attempted. This commit also includes comprehensive unit tests for the new library.

This was referenced Nov 11, 2025

feat(xds): Implement response handling for external authorization #12495

Closed

feat(xds): Add ExtAuthzClientInterceptor and related components #12496

Closed

Feat/server interceptor #12497

Closed

feat(xds): Add ExternalAuthorizationFilter #12498

Closed

sauravzg force-pushed the feat/header-mutations branch 5 times, most recently from 328631a to 86d68ac Compare November 17, 2025 10:36

kannanjgithub reviewed Mar 9, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutator.java Outdated

sauravzg force-pushed the feat/header-mutations branch from 86d68ac to 759130e Compare March 12, 2026 13:46

sauravzg force-pushed the feat/header-mutations branch from 759130e to 4bfd5e6 Compare March 12, 2026 18:14

sauravzg changed the title feat(xds): Add header mutations library xds: Add header mutations library Mar 12, 2026

sauravzg force-pushed the feat/header-mutations branch from 4bfd5e6 to 6961989 Compare March 12, 2026 19:11

kannanjgithub requested changes Mar 13, 2026

View reviewed changes

sauravzg force-pushed the feat/header-mutations branch 2 times, most recently from 90e5491 to efb725f Compare March 15, 2026 21:44

kannanjgithub approved these changes Mar 16, 2026

View reviewed changes

kannanjgithub requested a review from AgraVator March 17, 2026 06:04

sauravzg force-pushed the feat/header-mutations branch 2 times, most recently from 399e233 to 677b251 Compare March 17, 2026 08:40

AgraVator reviewed Mar 23, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/GrpcServiceConfigParser.java Outdated

Comment thread xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationFilter.java Outdated

sauravzg force-pushed the feat/header-mutations branch from 677b251 to 4ca257e Compare March 23, 2026 18:03

kannanjgithub requested a review from Copilot March 24, 2026 17:20

Copilot started reviewing on behalf of kannanjgithub March 24, 2026 17:21 View session

sauravzg added a commit to sauravzg/grpc-java that referenced this pull request Apr 2, 2026

Fixup grpc#12494 : Fix documentation

951b761

sauravzg force-pushed the feat/header-mutations branch from 9ec272a to 951b761 Compare April 2, 2026 11:58

gemini-code-assist Bot reviewed Apr 22, 2026

View reviewed changes

sauravzg force-pushed the feat/header-mutations branch from 8d6cd46 to 312f166 Compare April 22, 2026 13:16

gemini-code-assist Bot reviewed Apr 22, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutator.java

Comment thread xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutator.java

Comment thread xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationFilter.java

sauravzg force-pushed the feat/header-mutations branch from c7777c2 to 46c951d Compare April 22, 2026 14:10

sauravzg added 11 commits April 22, 2026 14:18

Fixup: 12494 address comments and bring back up to updated ext authz …

24b736e

…spec

Fixup 12494: Fixes for logging and additional comment

65eb24f

Fixup 12494: Remove Authz specific abstractions away from the generic…

6653d2e

… headermutations libraries

Fixup 12494: Rename variable

b96db79

Fixup 12494: Address copilot comments

d866186

Fixup 12494: Improve test coverage for headermutations

c17c86a

Fixup grpc#12494 : Fix documentation

e046a49

Make keepEmptyvalue consistent with envoy impl

b9caa47

https://github.com/grpc/proposal/pull/481/changes#r3022089452

Handle gemini review comments.

d2757fb

Change HeaderMutationFilter to match envoy's implementation

9640f87

sauravzg force-pushed the feat/header-mutations branch from 46c951d to 9640f87 Compare April 22, 2026 14:27

kannanjgithub requested changes Apr 23, 2026

View reviewed changes

Fixup 12494: Improve test coverage

985f1c6

sauravzg requested a review from kannanjgithub April 27, 2026 13:55

kannanjgithub approved these changes Apr 27, 2026

View reviewed changes

kannanjgithub merged commit 3e276b0 into grpc:master Apr 28, 2026
15 of 17 checks passed

shivaspeaks mentioned this pull request May 11, 2026

xds: Suppress InlineMeInliner warning in HeaderMutationFilterTest #12804

Merged

sauravzg deleted the feat/header-mutations branch May 14, 2026 14:04

github-actions Bot locked as resolved and limited conversation to collaborators Aug 13, 2026

xds: Add header mutations library by sauravzg · Pull Request #12494 · grpc/grpc-java · GitHub

Uh oh!

xds: Add header mutations library - #12494

xds: Add header mutations library#12494kannanjgithub merged 12 commits intogrpc:mastergrpc/grpc-java:masterfrom sauravzg:feat/header-mutationssauravzg/grpc-java:feat/header-mutationsCopy head branch name to clipboard

Conversation

sauravzg commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

sauravzg commented Mar 12, 2026

Uh oh!

kannanjgithub left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kannanjgithub left a comment

Choose a reason for hiding this comment

Uh oh!

sauravzg commented Mar 15, 2026

Uh oh!

sauravzg commented Mar 16, 2026

Uh oh!

sauravzg commented Mar 16, 2026

Uh oh!

Uh oh!

Uh oh!

sauravzg commented Apr 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sauravzg commented Apr 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kannanjgithub left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sauravzg commented Apr 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

xds: Add header mutations library#12494
kannanjgithub merged 12 commits into
grpc:masterfrom
sauravzg:feat/header-mutations

sauravzg commented Nov 11, 2025 •
edited
Loading