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

sauravzg · 2025-11-11T08:51:30Z

This PR sits on top of #12690, so only the last commit + any fixups need to be reviewed.

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 commit introduces configuration objects for the external authorization (ExtAuthz) filter and the gRPC service it uses. These classes provide a structured, immutable representation of the configuration defined in the xDS protobuf messages. The main new classes are: - `ExtAuthzConfig`: Represents the configuration for the `ExtAuthz` filter, including settings for the gRPC service, header mutation rules, and other filter behaviors. - `GrpcServiceConfig`: Represents the configuration for a gRPC service, including the target URI, credentials, and other settings. - `HeaderMutationRulesConfig`: Represents the configuration for header mutation rules. This commit also includes parsers to create these configuration objects from the corresponding protobuf messages, as well as unit tests for the new classes.

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

sauravzg · 2026-03-12T13:49:24Z

@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.

… the updated requirements

kannanjgithub

Sending comments for headermutations.

xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutations.java

xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderValueOption.java

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

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

kannanjgithub

Reviewed rest of the PR.

sauravzg · 2026-03-15T21:00:41Z

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

… address nits.

sauravzg · 2026-03-16T11:08:50Z

@kannanjgithub Addressed the comments. PTAL.

sauravzg · 2026-03-16T11:43:02Z

/gemini review

… and add test coverage

xds/src/main/java/io/grpc/xds/internal/grpcservice/GrpcServiceConfigParser.java

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

… bug Makes `allowedGrpcServices` to be a non-optional struct instead of an `Optional<Map<str,AllowedService>>` since it's essentially an immuatable hash map, making it preferable to use an empty instance instead of null. Change a small bug where we continued instead of return when parsing bootstrap credentials.

Copilot

Pull request overview

This PR introduces an internal library to apply and constrain xDS-defined header mutations, and extends the xDS gRPC-service/bootstrap parsing utilities to support related configuration (including allowed_grpc_services) plus a small channel-caching helper.

Changes:

Add core header-mutation types (HeaderValue, HeaderValueOption, HeaderMutations) and logic to filter/apply mutations (HeaderMutationFilter, HeaderMutator).
Add parsing/value objects for header mutation rules and gRPC service config parsing/context (HeaderMutationRules*, GrpcService*), and extend bootstrap parsing for allowed_grpc_services.
Add CachedChannelManager utility and comprehensive unit tests for the new components.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderValueOption.java	New value type for header + append action + keep-empty behavior
xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutator.java	Applies header add/append/overwrite/remove mutations to `Metadata`
xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutations.java	Container for headers-to-add/update and headers-to-remove
xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationRulesParser.java	Parses Envoy `HeaderMutationRules` proto into internal config
xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationRulesConfig.java	Internal config for allow/disallow regex + disallow flags
xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationFilter.java	Filters/blocks mutations using validation + mutation rules
xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationDisallowedException.java	StatusException used when disallowed mutations should error
xds/src/main/java/io/grpc/xds/internal/grpcservice/HeaderValueValidationUtils.java	Shared header-key/value validation rules for filtering/parsing
xds/src/main/java/io/grpc/xds/internal/grpcservice/HeaderValue.java	Internal immutable representation of header key + (string/bytes) value
xds/src/main/java/io/grpc/xds/internal/grpcservice/GrpcServiceXdsContextProvider.java	Context-provider interface for parsing gRPC service config
xds/src/main/java/io/grpc/xds/internal/grpcservice/GrpcServiceXdsContext.java	Context object (trusted/untrusted, overrides, scheme support)
xds/src/main/java/io/grpc/xds/internal/grpcservice/GrpcServiceParseException.java	Parse exception for GrpcService parsing
xds/src/main/java/io/grpc/xds/internal/grpcservice/GrpcServiceConfigParser.java	Parses `GrpcService` protos into internal `GrpcServiceConfig`
xds/src/main/java/io/grpc/xds/internal/grpcservice/GrpcServiceConfig.java	Internal immutable gRPC service config model
xds/src/main/java/io/grpc/xds/internal/grpcservice/ConfiguredChannelCredentials.java	Pairs `ChannelCredentials` with its config for comparison/caching
xds/src/main/java/io/grpc/xds/internal/grpcservice/ChannelCredsConfig.java	Interface for comparable channel-creds config
xds/src/main/java/io/grpc/xds/internal/grpcservice/CachedChannelManager.java	Single-channel cache keyed by (target, creds config)
xds/src/main/java/io/grpc/xds/internal/grpcservice/AllowedGrpcServices.java	Model for bootstrap `allowed_grpc_services` map
xds/src/main/java/io/grpc/xds/internal/grpcservice/AllowedGrpcService.java	Model for one allowed target’s channel/call credentials
xds/src/main/java/io/grpc/xds/internal/extauthz/ExtAuthzParseException.java	Parse exception for ext_authz parsing
xds/src/main/java/io/grpc/xds/internal/extauthz/ExtAuthzConfigParser.java	Parses ext_authz proto and wires header mutation rules parsing
xds/src/main/java/io/grpc/xds/internal/extauthz/ExtAuthzConfig.java	Internal immutable ext_authz config model
xds/src/main/java/io/grpc/xds/internal/MatcherParser.java	Adds FractionalPercent parsing to internal matcher type
xds/src/main/java/io/grpc/xds/client/BootstrapperImpl.java	Hooks parsing of `allowed_grpc_services` into bootstrap builder
xds/src/main/java/io/grpc/xds/client/Bootstrapper.java	Adds `allowedGrpcServices()` to bootstrap info with default
xds/src/main/java/io/grpc/xds/GrpcBootstrapperImpl.java	Implements `allowed_grpc_services` parsing and wraps channel creds/config
xds/src/test/java/io/grpc/xds/internal/headermutations/HeaderValueOptionTest.java	Unit tests for HeaderValueOption creation
xds/src/test/java/io/grpc/xds/internal/headermutations/HeaderMutatorTest.java	Unit tests for mutation application across actions/types
xds/src/test/java/io/grpc/xds/internal/headermutations/HeaderMutationsTest.java	Unit tests for HeaderMutations container
xds/src/test/java/io/grpc/xds/internal/headermutations/HeaderMutationRulesParserTest.java	Unit tests for rules parser and invalid regex handling
xds/src/test/java/io/grpc/xds/internal/headermutations/HeaderMutationRulesConfigTest.java	Unit tests for rules config builder/defaults
xds/src/test/java/io/grpc/xds/internal/headermutations/HeaderMutationFilterTest.java	Unit tests for filtering behavior + system header behavior
xds/src/test/java/io/grpc/xds/internal/grpcservice/HeaderValueValidationUtilsTest.java	Unit tests for key/value ignore rules (length/case/system/grpc)
xds/src/test/java/io/grpc/xds/internal/grpcservice/HeaderValueTest.java	Unit tests for HeaderValue construction variants
xds/src/test/java/io/grpc/xds/internal/grpcservice/GrpcServiceXdsContextTestUtil.java	Test helper for dummy parsing context provider
xds/src/test/java/io/grpc/xds/internal/grpcservice/GrpcServiceConfigParserTest.java	Unit tests for grpc_service parsing, creds, timeout, trust behavior
xds/src/test/java/io/grpc/xds/internal/grpcservice/CachedChannelManagerTest.java	Unit tests for channel cache keying, replacement, shutdown
xds/src/test/java/io/grpc/xds/internal/extauthz/ExtAuthzConfigParserTest.java	Unit tests for ext_authz parsing with mutation rules
xds/src/test/java/io/grpc/xds/internal/MatcherParserTest.java	Unit tests for StringMatcher + new FractionMatcher parsing
xds/src/test/java/io/grpc/xds/GrpcBootstrapperImplTest.java	Unit tests for bootstrap parsing of `allowed_grpc_services`

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

xds/src/test/java/io/grpc/xds/internal/headermutations/HeaderMutationFilterTest.java

xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationRulesParser.java

xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationRulesConfig.java

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

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

xds/src/main/java/io/grpc/xds/internal/grpcservice/CachedChannelManager.java

xds/src/main/java/io/grpc/xds/GrpcBootstrapperImpl.java

ejona86

Drive-by comment. Started looking, but then got pulled into other things.

xds/src/main/java/io/grpc/xds/client/Bootstrapper.java

ejona86 · 2026-03-24T16:06:14Z

xds/src/main/java/io/grpc/xds/client/Bootstrapper.java

+     * Parsed allowed_grpc_services configuration.
+     * Returns an opaque object containing the parsed configuration.
+     */
+    public abstract Object allowedGrpcServices();


Let's not have this have any semantics in the BootstrapInfo. Instead, we'll use this single object to hold any number of things we need associated with the bootstrap.

Can you elaborate? allowedGrpcServices is a top level field, do we want to get rid of this and create an arbitrary getImplSpecificConfig ?

sauravzg · 2026-03-25T11:41:45Z

@kannanjgithub All copilot comments have been addressed in the PR chain.

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

This was referenced Nov 11, 2025

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

Open

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

Open

Feat/server interceptor #12497

Open

feat(xds): Add ExternalAuthorizationFilter #12498

Open

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

xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutator.java Outdated Show resolved Hide resolved

Fixup: Address comments from grpc#12492

5654c64

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

Fixup: 12492 Split HeaderValueValidationUtils to GrpcService to match…

5ed6993

… the updated requirements

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 from 555eebe to 90e5491 Compare March 15, 2026 21:33

Fixup: 12492 Remove artifact from old channelcreds implementation and…

35f3956

… address nits.

sauravzg force-pushed the feat/header-mutations branch 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

Fixup 12492: Use builder instead of newBuilder

1d4e48b

sauravzg force-pushed the feat/header-mutations branch from 461b942 to 399e233 Compare March 17, 2026 07:02

Fixup: 12492 Fix callcredentials to not apply instead of erroring out…

c1b95f1

… and add test coverage

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

AgraVator reviewed Mar 23, 2026

View reviewed changes

xds/src/main/java/io/grpc/xds/internal/grpcservice/GrpcServiceConfigParser.java Show resolved Hide resolved

xds/src/main/java/io/grpc/xds/internal/headermutations/HeaderMutationFilter.java Outdated Show resolved Hide resolved

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

Copilot AI reviewed Mar 24, 2026

View reviewed changes

ejona86 reviewed Mar 25, 2026

View reviewed changes

Fixup 12492: Address copilot comments

779b8ed

sauravzg force-pushed the feat/header-mutations branch from 4ca257e to e866d93 Compare March 25, 2026 11:32

sauravzg force-pushed the feat/header-mutations branch from e866d93 to c059382 Compare March 25, 2026 13:05

sauravzg added 11 commits March 25, 2026 14:14

Fixup 12492: Eliminate bootstrap dependency on grpc

804cb09

feat(xds): Add CachedChannelManager for caching channel instances

91a482a

Fixup: grpc#12690: Add VisibleForTesting

8e8da61

Fixup: 12690 Use builder in unit tests

7f1907d

Fixup 12690: Addres copilot comments

b47fa3f

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

17c6c0b

…spec

Fixup 12494: Fixes for logging and additional comment

1a7a005

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

a560271

… headermutations libraries

Fixup 12494: Rename variable

26a52b6

Fixup 12494: Address copilot comments

d70afc7

sauravzg force-pushed the feat/header-mutations branch from c059382 to d70afc7 Compare March 25, 2026 14:28

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ejona86 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ejona86 Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

sauravzg Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

sauravzg commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

sauravzg commented Nov 11, 2025 •

edited

Loading