xds: Add header mutations library

[sauravzg]

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.

• [] xds: Add configuration objects for ExtAuthz, GrpcService and Bootstrap changes for GrpcService #12492
• [] xds: Implement channel caching utility for GrpcService channels for ext_authz and ext_proc #12690

[sauravzg]

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

[kannanjgithub]

Sending comments for headermutations.

[kannanjgithub]

Reviewed rest of the PR.

[sauravzg]

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

[sauravzg]

@kannanjgithub Addressed the comments. PTAL.

[sauravzg]

/gemini review

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

[ejona86]

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

[ejona86]

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.

[sauravzg]

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

[sauravzg]

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