Skip to content

xds: Add header mutations library#12494

Open
sauravzg wants to merge 6 commits intogrpc:masterfrom
sauravzg:feat/header-mutations
Open

xds: Add header mutations library#12494
sauravzg wants to merge 6 commits intogrpc:masterfrom
sauravzg:feat/header-mutations

Conversation

@sauravzg
Copy link
Contributor

This PR sits on top of #12493, 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.
@sauravzg sauravzg force-pushed the feat/header-mutations branch from 86d68ac to 759130e Compare March 12, 2026 13:46
@sauravzg
Copy link
Contributor Author

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

@sauravzg sauravzg force-pushed the feat/header-mutations branch from 759130e to 4bfd5e6 Compare March 12, 2026 18:14
@sauravzg sauravzg changed the title feat(xds): Add header mutations library xds: Add header mutations library Mar 12, 2026
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.
@sauravzg sauravzg force-pushed the feat/header-mutations branch from 4bfd5e6 to 6961989 Compare March 12, 2026 19:11
Copy link
Contributor

@kannanjgithub kannanjgithub left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sending comments for headermutations.


/** Represents mutations for response headers. */
@AutoValue
public abstract static class ResponseHeaderMutations {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the need to have disallow header removals for response mutations, as the gRFC doesn't say response headers can't be removed. It looks one class to handle both request and response headers mutations would do.


/**
* Represents a header option to be appended or mutated as part of xDS configuration.
* Avoids direct dependency on Envoy's proto objects.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having essentially mirror protos here and in other places seems unnecessary to me. We have the dependency on envoy protos anyway in GrpcServiceConfigParser that cannot be avoided. What is the problem in directly depending on envoy protos everywhere? If it is helpful to have structurally different protos I can see the need from a utility perspective (we do that for xds resource protos like CdsUpdate) , but not from trying to avoid usage perspective.


default:
// Should be unreachable unless there's a proto schema mismatch.
logger.warning("Unknown HeaderAppendAction: " + action);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As the mutations happen per-rpc we shouldn't be logging these warnings.




public HeaderMutationFilter(Optional<HeaderMutationRulesConfig> mutationRules) { // NOPMD
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove this comment?

if (rules.allowExpression().isPresent()) {
return rules.allowExpression().get().matcher(lowerCaseHeaderName).matches();
}
return !rules.disallowAll();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do this check at the beginning,

if (rules.disallowAll()) {
  return false;
}

Copy link
Contributor

@kannanjgithub kannanjgithub left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed rest of the PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants