xds: Implementation of Unified Matcher by shivaspeaks · Pull Request #12640 · grpc/grpc-java

shivaspeaks · 2026-02-03T09:46:09Z

Implements gRFC A106: xDS Unified Matcher
grpc/proposal#520

l46kok

Sorry about the drive-by -- I happened to notice this while putting together an unrelated PR in CEL-Java. I'll hold off on submitting it on our end.

ejona86 · 2026-02-12T21:00:22Z

+   * Compiles the CEL expression string into a CelMatcher.
+   */
+  @VisibleForTesting
+  public static CelMatcher compile(String expression)


Move this to the testing code so we don't need a dependency on the Cel compiler. It looks unused for production.

l46kok · 2026-02-13T01:42:11Z

+              String id = over.toString();
+              return !id.equals("ADD_STRING") && !id.equals("ADD_LIST");


You should be able to compare directly against the overload enum instead of the stringified form (ex: over != AddOverload.ADD_STRING).

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

Also removes antlr dependency from `dev.cel:runtime` artifact Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

Also removes antlr dependency from `dev.cel:runtime` artifact Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 872010923

ejona86 · 2026-02-23T18:27:33Z

-              String id = over.toString();
-              return !id.equals("ADD_STRING") && !id.equals("ADD_LIST");
+              return !over.equals(
+                      (Object) dev.cel.runtime.standard.AddOperator.AddOverload.ADD_STRING)


Why are we needing to cast to Object? If you're working around ErrorProne, then something seems broken and casting to Object is just hiding it.

Yes it was an errorProne workaround.
over is statically known as a StandardOverload interface, but ADD_STRING is an AddOverload enum. ErrorProne threw an [EqualsIncompatibleType] build error so we need to cast the ADD_STRING enum specifically to (Object) before passing it into equals.

ADD_STRING is a CelStandardOverload, which isn't a StandardOverload. It seems ErrorProne is correct; these will never be equal.

You should comment cases like this. If this were a bug in ErrorProne we'd probably want to file a bug with ErrorProne, but even if not, the comment helps us know when it is no longer necessary. (We don't have to guess why it was done, so we can confirm if that is no longer the case.)

It looks like that has been adjusted on cel-java master, as the function is now passed CelStandardOverload.

@sergiitk, the interface change looks like a breaking API change. That's surprising since I thought we were using stable APIs. Is this PR using an API that it shouldn't be, was this a known change that just hadn't been released yet, or should we be concerned about the actual stability of the API?

This is a relatively new API that didn't exist when API stabilization doc was made (go/cel-api-stabilization). It's stable now (I'll update the doc when I get a chance). Reason why I suggested this API is that it follows the recommended pattern for how environment subsetting is supposed to be done across all CEL stacks.

As for EP -- I'm surprised it's actually flagging this (internally, it doesn't). AddOperator enum implements CelStandardOverload, so they should equal. My only guess is that CelStandardOverload is a functional interface, so theoretically it's possible to provide a lambda that's not equals comparable. Though we control the standard overload implementations, so in practice this won't happen. Checking for reference identity should likely get around the issue over == AddOverload.ADD_STRING

Oh, I see, this is the new setup flow. I didn't look where this FUNCTIONS constant was used. That's fine; I'm less surprised that changed. (And yes, it's good to add it to the doc.)

I'm surprised it's actually flagging this (internally, it doesn't)

I don't think it'd get flagged on master either. It only looked to be a problem because we're still using 0.11.1; in 0.11.1 I agree with ErrorProne that the equals() will always return false.

ejona86 · 2026-02-25T18:46:35Z

+import javax.annotation.Nullable;
+
+/**
+ * Interface for extracting values from a match context (e.g. HTTP headers).


This says explicitly "from a match context", and the only two implementations use MatchContext, so why is T present? Shouldn't this just have an argument that is MatchContext?

ejona86 · 2026-02-25T18:48:02Z

+    return result.actions;
+  }
+
+  public interface MatchContext {


Nothing implements this. Is this still TODO? There's no mention this is missing in the PR description.

grfc says:

Matcher Context: The input to the Matcher evaluation tree. Provided at runtime by the filter, contains the input data.

MatchContext is the representation of the "Matcher Context" described in gRFC. It is currently an empty shell (no implementations in this PR) because it is designed to be implemented by the specific xDS filters (e.g., RLQS or Composite Filter) that will be the primary consumers of this matching logic, as noted in the gRFC's Implementation section

The implementation section saying "as part of" is saying "it will be part of that effort." We aren't saying CEL will be part of RLQS and the Composite Filter will call the RLQS code if RLQS was implemented first.

I think the filter will construct the Matcher Context and provide its contents, but I don't think each filter will have its own implementation, or at least an implementation from scratch. Headers will be Metadata, Method is always POST, Path will be pulled from MethodDescriptor, etc. I could understand if there was a server-side vs client-side implementation, but even that doesn't seem likely; worst-case looks to be different factory methods as convenience.

ejona86 · 2026-02-25T18:52:45Z

+/**
+ * Represents a compiled xDS Matcher.
+ */
+public abstract class UnifiedMatcher {


How do we have enough information to satisfy:

If set, the return type of the input must match the input type
of the matcher.

I see now. UnifiedMatcher has input+matcher combined together, so there's no need to check types when using it. But I think I got confused because there is not Matcher API. There should be a matcher API; in no way do we want to hard-code each matcher type.

ejona86 · 2026-02-25T19:00:44Z

+final class OnMatch {
+  @Nullable private final UnifiedMatcher nestedMatcher;
+  @Nullable private final TypedExtensionConfig action;
+  final boolean keepMatching;


Overall, it seems like keepMatching is incomplete (beyond this one instance). But that's not mentioned in the PR description. What is the current status of keepMatching?

In MatcherList: keep_matching is used to continue the loop and accumulate actions.

In MatcherTree (Prefix): It is also implemented for traversing the trie/list of prefixes. Check line 133 in MatcherTree (if (!onMatch.keepMatching))

In MatcherTree (Exact): If a key matches, it returns immediately without checking if it should "keep matching" because thats the only logical way it seems. Should it fall back to on_no_match?

keepMatching here is literally not used. Clearly that is wrong. Note that I'm most bothered that there's no TODO or mention in the PR description. There's nothing that calls out "this didn't make sense" or "this was not possible" for us to work through.

It seems you're missing the fact keep_matching means multiple completely different matchers can contribute to the result. You need to accumulate keep_matching results across matchers.

This is probably more clear after reading my comments at https://github.com/grpc/proposal/pull/520/changes#r2683391713 . Basically, the most important thing to understand about keep_matching is that it is a semantically different result. You shouldn't semantically mix the results between a terminal result with those of keep_matching; they aren't interchangeable (if C++ wants to and have an encoding for them to determine which results are what, they are free to, but I don't want the security vulnerability risk). We should either use a callback or a separate list in the result (MatchResult {TypedExecutionConfig action; List<TypedExecutionConfig> keepMatchingActions; }, where action == null means matched == false, or use Optional<TypedExecutionConfig> to track it)

ejona86 · 2026-02-25T19:02:20Z

+          try {
+            com.github.xds.type.matcher.v3.CelMatcher celProto = customConfig.getTypedConfig()
+                .unpack(com.github.xds.type.matcher.v3.CelMatcher.class);
+            if (celProto.hasExprMatch()) {


Invert this condition so that we can more easily see what exception is matched with with if and also can get rid of the else. Ditto elsewhere in this class.

ejona86 · 2026-02-27T19:43:27Z

+   * Returns the type of value extracted by this input.
+   */
+  default Class<?> outputType() {
+    return Object.class;


This disables the check by default and it seems extremely doubtful any implementation would legitimately use Object. Delete the default implementation?

ejona86 · 2026-02-27T19:49:57Z

      }
+
+      if (!input.outputType().isAssignableFrom(matcher.inputType()) 
+          && !matcher.inputType().isAssignableFrom(input.outputType())) {


The only way for the input to be assignable from the output and the output to be assignable from the input is for it to be the same class. This is just a verbose equals() check.

And just using equals() sounds perfect. I don't think we need any complex object hierarchy stuff going on. We just need to make sure they match. Equals() is what I'd hope we use, as it is unlikely to be broken.

ejona86 · 2026-02-27T19:58:30Z

+        this.matcher = new Matcher() {
+          @Override
+          public boolean match(Object value) {
+            if (value instanceof String) {


If the input isn't compatible, this should throw. That is a programmer error, as the class said which type it can handle and that wasn't provided. That lets us find bugs. Note that silently ignoring a failure like that can be a security vulnerability. We need to be just as precise with match and non-match; we can't favor one way or the other, as we have no knowledge of what this matching implies.

ejona86 · 2026-02-27T20:01:01Z

+  }
+
+  @Override
+  public Object apply(MatchContext context) {


You can have this method return String even when the interface returns Object. That would help guarantee we don't accidentally return any other type.

asheshvidyut

Reviewing for learning purposes.

…atcher

AgraVator · 2026-06-15T11:07:13Z


+  /** Translate StringMatcher xDS proto to internal StringMatcher. */
+  public static Matchers.StringMatcher parseStringMatcher(
+            com.github.xds.type.matcher.v3.StringMatcher proto) {


Do we need fully qualified names ?

I kept it intentionally because we have internal form of StringMatcher and this is the proto definition. Having different names didn't made sense, so we need to keep it like that. The other way could be to define a assign a variable with different name during import, but I chose to keep it as is because it's only three usages in the class in function definition and its fairly readable.

AgraVator · 2026-06-15T11:08:32Z

+        return Matchers.StringMatcher.forExact(proto.getExact(), proto.getIgnoreCase());
+      case PREFIX:
+        return Matchers.StringMatcher.forPrefix(
+            checkNonEmpty(proto.getPrefix(), "prefix"), proto.getIgnoreCase());


Is this behaviour same in envoy(as in does it check for emptiness) ??

same as xds*
Yes, check this https://github.com/cncf/xds/blob/main/xds/type/matcher/v3/string.proto

Envoy behavior is right above this function, already existing which has an argument io.envoyproxy.envoy.type.matcher.v3.StringMatcher.

AgraVator · 2026-06-15T11:10:13Z

+    @Override
+    public CelStateMatcher getMatcher(TypedExtensionConfig config) {
+      try {
+        com.github.xds.type.matcher.v3.CelMatcher celProto = config.getTypedConfig()


Do we need fully qualified names here and elsewhere ??

Same reason as above.

AgraVator · 2026-06-15T11:10:45Z

+          sb.append(",");
+        }
+        first = false;
+        sb.append(com.google.common.io.BaseEncoding.base64().encode(value));


Can we cache this ??

AgraVator · 2026-06-15T11:26:20Z

+    }
+    try {
+      if (headerName.endsWith(Metadata.BINARY_HEADER_SUFFIX)) {
+        Metadata.Key.of(headerName, Metadata.BINARY_BYTE_MARSHALLER);


cache Metadata.Key.of(headerName, Metadata.BINARY_BYTE_MARSHALLER) during construction ?

AgraVator · 2026-06-15T11:33:31Z

+    // HeadersWrapper has 3 pseudo headers by default, so size is 3.
+    // We match size to force entrySet check.
+    CelMatcher celMatcher = createCelMatcher(
+        "request.headers == {'a':'1','b':'2','c':'3'}");


We have

@Override public int size() { int count = 0; for (String key : context.getMetadata().keys()) { String lowerKey = key.toLowerCase(java.util.Locale.ROOT); if (!lowerKey.equals("te") && !lowerKey.equals("host") && !PSEUDO_HEADERS.contains(lowerKey) && isMetadataKeyResolvable(lowerKey)) { count++; } } return count + PSEUDO_HEADERS.size() + 1; // +1 for "host" alias }

is 3 correct ??

Should be 4. The test was passing because 4 != 3, CEL instantly evaluates the expression to false and because the expression is false, the matcher fall back to the no-match action.

kannanjgithub

Reviewed source code, yet to review tests.

kannanjgithub · 2026-06-26T06:02:29Z

+            return MatchResult.create(result.action, accumulated);
+          }
+        } else {
+          if (!matcher.onMatch.keepMatching) {


keepMatching is only meant to be used for successful match case, not for failed match case. In matcher list it should just move on to the next matcher in the list.

kannanjgithub · 2026-06-26T06:08:58Z

+  static final int MAX_RECURSION_DEPTH = 16;
+
+  @Nullable
+  public abstract MatchResult match(MatchContext context, int depth);


All concrete subclasses of UnifiedMatcher (MatcherList, MatcherTree, and NoOpMatcher) are package-private, which prevents them from being constructed from outside the package, and checkRecursionDepth check already exists in UnifiedMatcher.fromProto. The depth argument here is redundant and the error condition during match evaluation is unreachable code.

kannanjgithub · 2026-06-26T06:14:22Z

+      this.exactMatchMap = null;
+      this.prefixTrie = null;


Redundant assignments.

kannanjgithub · 2026-06-26T06:20:28Z

+          accumulated.add(result.action);
+        }
+      } else {
+        if (!match.keepMatching) {


As mentioned in MatcherList, keepWatching should not be used for match fail case.
Same for the usage below in matchPrefix also.

kannanjgithub · 2026-06-26T06:47:40Z

+  public final TypedExtensionConfig action;
+  public final List<TypedExtensionConfig> keepMatchingActions;


Maintaining a separate field for action from keepMatchingActions is entirely redundant since when executing the actions it is going to execute them all. In all places we can just keep appending action to the front of the keepMatchingActions returned for the nested matchers in onMatch. We can also rename keepMatchingActions to just actions.

I don't remember exactly but there was a comment/line where it was mentioned that these should be segregated from a normal match with keep_matching=false.

For matches with keep_matching=true the actions are collected, that is done in MatcherList and MatcherTree. Once collected, keep_matching has no relevance anymore. Nor is there any reason to keep the action separate from keepMatchingActions.

This was the reason to keep these segregated: https://github.com/grpc/proposal/pull/520/changes#r2696490278

C core is doing like this as mentioned by Mark: https://github.com/grpc/proposal/pull/520/changes#r2696499658

In the discussion it goes against the segregation idea:

When we get a matching action, we append it to the list of matching actions to return. If the matcher returns true, then we know that the last entry in the list of returned actions is the one we should actually take, and any earlier entries in the list are the ones that matched but had keep_matching set to true. If the match returns false, then all actions in the list are the ones that matched but had keep_matching set to true.

This is the code implementing a single array for all actions in c-core.

Also refer what MatcherRunner.java is doing. It is anyway merging the actions and returning it.

kannanjgithub · 2026-06-26T07:01:08Z

+      case CONTAINS:
+        return Matchers.StringMatcher.forContains(
+            checkNonEmpty(proto.getContains(), "contains"), proto.getIgnoreCase());
+      case SAFE_REGEX:


nit: Maintain same order as in the above method.

kannanjgithub · 2026-06-26T07:01:19Z

+      case SAFE_REGEX:
+        String regex = checkNonEmpty(proto.getSafeRegex().getRegex(), "regex");
+        return Matchers.StringMatcher.forSafeRegEx(Pattern.compile(regex));
+      default:


Add case MATCHPATTERN_NOT_SET:

kannanjgithub · 2026-06-26T07:02:26Z

+      return matcher.match(input.apply(context));
+    }
+
+    private static Matchers.StringMatcher fromStringMatcherProto(


Do we need a separate method for this?

kannanjgithub · 2026-06-26T07:11:26Z

 */

 package io.grpc.xds.internal.matcher;



It looks like this version of the file is from before we made all fields non-nullable.

Yes. Seems like, during merge conflicts it was left behind.

kannanjgithub · 2026-06-26T11:28:47Z

+  public final TypedExtensionConfig action;
+  public final List<TypedExtensionConfig> keepMatchingActions;


For matches with keep_matching=true the actions are collected, that is done in MatcherList and MatcherTree. Once collected, keep_matching has no relevance anymore. Nor is there any reason to keep the action separate from keepMatchingActions.

kannanjgithub · 2026-06-26T11:34:41Z

+    // If we fall through, we only evaluate onNoMatch if there was at least one successful match
+    // with keepMatching=true. If no prefixes matched successfully, we return noMatch.
+    if (anySuccessfulMatch && onNoMatch != null) {


This is the not the correct behavior to implement. For a successful match with keepMatching true only its action is accumulated, but the match should be considered false.

shivaspeaks force-pushed the xds-unified-matcher-and-cel branch from 082243d to f472c63 Compare February 3, 2026 10:11

shivaspeaks marked this pull request as ready for review February 8, 2026 09:01

shivaspeaks requested review from AgraVator, ejona86 and kannanjgithub February 8, 2026 09:02

l46kok reviewed Feb 11, 2026

View reviewed changes

Comment thread gradle/libs.versions.toml Outdated

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/CelCommon.java Outdated

ejona86 reviewed Feb 12, 2026

View reviewed changes

l46kok reviewed Feb 13, 2026

View reviewed changes

copybara-service Bot pushed a commit to cel-expr/cel-java that referenced this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts

1c9d43e

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

copybara-service Bot mentioned this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts cel-expr/cel-java#954

Merged

copybara-service Bot pushed a commit to cel-expr/cel-java that referenced this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts

d960f42

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

copybara-service Bot pushed a commit to cel-expr/cel-java that referenced this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts

6cac827

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

ejona86 requested a review from sergiitk February 23, 2026 18:02

ejona86 reviewed Feb 25, 2026

View reviewed changes

sergiitk requested changes Feb 25, 2026

View reviewed changes

ejona86 reviewed Feb 27, 2026

View reviewed changes

shivaspeaks mentioned this pull request Feb 25, 2026

xds: Add composite filter #12646

Open

shivaspeaks requested review from ejona86 and sergiitk March 4, 2026 10:53

asheshvidyut reviewed Mar 25, 2026

View reviewed changes

shivaspeaks added 18 commits June 8, 2026 13:57

fix/add tests

9267ee4

remove not required tests

5b423ed

add tests

2f53a30

add tests

5c433ce

add tests

568bec1

add some tests

719b90c

Address comments

6da8f60

remove dependency from dev.cel:cel

4d6379d

Refactor StringMatcher parsing logic

a5f70b1

address comments and create registries

91de9cd

address comments

23a00d6

add unit tests for exactMatchMap case

f3042e2

add unit tests

2f68101

Address Ashesh's comments

0518230

use switch in PredicateEvaluator

3f7fc86

Address comments on CelStringExtractor

7a6ca94

all overloaded methods should be placed together

5836446

Restore MatchContext and CelMatcherTestHelper additions for Unified M…

f312c9c

…atcher

shivaspeaks force-pushed the xds-unified-matcher-and-cel branch from 8515729 to f312c9c Compare June 8, 2026 09:35

Remove cel.compiler dependency from interop-testing to fix CI

0af8751

shivaspeaks changed the title ~~xds: Implementation of Unified Matcher and CEL Integration~~ xds: Implementation of Unified Matcher Jun 11, 2026

AgraVator reviewed Jun 15, 2026

View reviewed changes

shivaspeaks added 2 commits June 19, 2026 11:24

Cache Metadata.Key and BaseEncoding in HeaderMatchInput

d86e0aa

review comments

89b2617

shivaspeaks requested review from AgraVator and kannanjgithub June 19, 2026 07:46

kannanjgithub requested changes Jun 26, 2026

View reviewed changes

Address comments

0bbc9e3

shivaspeaks requested a review from kannanjgithub June 26, 2026 11:07

kannanjgithub reviewed Jun 26, 2026

View reviewed changes

		String id = over.toString();
		return !id.equals("ADD_STRING") && !id.equals("ADD_LIST");

		public final TypedExtensionConfig action;
		public final List<TypedExtensionConfig> keepMatchingActions;

Uh oh!

Conversation

shivaspeaks commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

l46kok left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

asheshvidyut left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivaspeaks Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivaspeaks commented Feb 3, 2026 •

edited

Loading

shivaspeaks Jun 19, 2026 •

edited

Loading

AgraVator Jun 15, 2026 •

edited by shivaspeaks

Loading