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

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

Implements gRFC A106: xDS Unified Matcher and CEL Integration
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

asheshvidyut

Reviewing for learning purposes.

shivaspeaks · 2026-04-20T09:25:46Z

Note on CEL Allowed Functions and Overload IDs
During the implementation of the reference validation in CelCommon.java, I found that the CEL library represents standard operators and some conversion functions in the AST with an empty name in CelReference.name(), relying instead on specific overloadIds (e.g., equals for ==, index_map for map lookup [], and divide_int64 for /).

To enforce the gRFC A106 allowed list while supporting these permitted operations, I updated checkAllowedReferences to also validate overloadIds when the reference name is empty. Consequently, I added the following specific overload IDs to the ALLOWED_FUNCTIONS set to match the gRFC intent:

equals (maps to ==)
index_map (maps to map indexing [])
divide_int64 (maps to /)
int64_to_int64, string_to_int64, etc. (maps to int() conversions)

kannanjgithub · 2026-04-21T08:39:08Z

+   * Set of allowed function names based on gRFC A106.
+   */
+  private static final ImmutableSet<String> ALLOWED_FUNCTIONS = ImmutableSet.of(
+      "size", "matches", "contains", "startsWith", "endsWith", "timestamp", "duration",


The overload ids for standard functions will have suffixes like size_string, size_int64, etc and we should check that the overload id starts with one of these rather than use contains. Applies for timestamp and duration also.
We shouldn't limit overload IDs to specific data type (int64) as divide_int64, and instead should check for starts with divide.
I think we should use regex instead of individually checking each.
We really should have unit tests for each to make sure it is as we expect.
As we are matching by overload id equals for ==, we shouldn't have "equals" in the list.

kannanjgithub · 2026-04-21T08:39:45Z

+          boolean allowed = false;
+          for (String id : ref.overloadIds()) {
+            if (ALLOWED_FUNCTIONS.contains(id)) {
+              allowed = true;


We should check for all overload ids in the list.

kannanjgithub · 2026-04-21T08:41:46Z

+      if (input instanceof CelVariableResolver) {
+        result = program.eval((CelVariableResolver) input);
+      } else {
+        throw new CelEvaluationException(


No need to double catch. Just check for default value here and decide whether to return default or to throw.

But the gRFC explicitly suggests that

If set, and the CEL expression evaluates to an error or a non-string type, this default value will be returned instead.

So the defaultValue check needs to be in catch.

My comment was to avoid the double catch statement. Can we not make it a single one?

kannanjgithub · 2026-04-21T09:21:57Z

Can we move the "CEL foundation" classes to a separate PR so the ext-proc filter that needs Cel string extraction but not the unified matcher functionality can be unblocked sooner?

CelCommon.java
CelStringExtractor.java
CelMatcher.java
GrpcCelEnvironment.java
HeadersWrapper.java
CelStateMatcher.java

kannanjgithub · 2026-04-21T10:01:24Z

Actually, hold off on the above separate PR request. I might have misunderstood about the need to use CEL expression evaluator in the ext-proc filter. The grfc mentions that all CEL request attributes will be supported, not that we must evaluate them using the CEL runtime engine.

kannanjgithub · 2026-04-22T03:52:18Z

I have concluded that ext-proc filter indeed needs to use the CEL evaluation logic to support sending attributes. So do proceed with the suggested refactoring into a separate PR as mentioned above.

kannanjgithub · 2026-04-22T04:29:16Z

+    List<String> components = SPLITTER.splitToList(name);
+    if (components.size() == 2 && components.get(0).equals("request")) {
+      return Optional.ofNullable(getRequestField(components.get(1)));
+    }


The CelVariableResolver is intended to resolve the root of an expression, while the engine itself handles the navigation (dots and brackets) using the objects you provide.
Remove these lines.

By manually splitting request.headers in your find method, you are doing the engine's job for it, which creates several issues:

Redundancy: If you manually split request.headers, but the user writes request["headers"], your SPLITTER (which looks for a dot) might not trigger the same way, leading to inconsistent results.

Shadowing: If you resolve request.headers as a single string name, you might accidentally "shadow" the engine's ability to treat request as a map/object.

Fragility: If the user writes request.headers['x-user-id'], your manual splitter might get confused by the brackets or complex paths.

kannanjgithub · 2026-04-22T06:15:35Z

+  private static final Pattern ALLOWED_OVERLOAD_ID_PATTERN = Pattern.compile(
+      "^(size|matches|contains|startsWith|endsWith|starts_with|ends_with|"
+          + "timestamp|duration|in|index|has|int|uint|double|string|bytes|bool|"
+          + "equals|not_equals|less|less_equals|greater|greater_equals|"


equals, not equals, logical and/or/not never have suffixes. We should therefore do exact matching for these. Have another set

private static final ImmutableSet<String> ALLOWED_EXACT_OVERLOAD_IDS = ImmutableSet.of( "equals", "not_equals", "logical_and", "logical_or", "logical_not");

and do

if (ALLOWED_EXACT_OVERLOAD_IDS.contains(id) || ALLOWED_OVERLOAD_ID_PREFIX_PATTERN.matcher(id).matches()) { allowed = true;

kannanjgithub · 2026-04-22T06:18:02Z

Change the logic to reject any non-empty name when overloadIds is present. Because if a reference has a name, it's not a standard operator or a variable (handled by the first if), so it must be something we don't support, such as custom functions.

Oh, so standard allowed functions never have a name in the AST, so we should remove ALLOWED_FUNCTIONS, which is now an obsolete list here?

kannanjgithub · 2026-04-22T06:41:05Z

+      "^(size|matches|contains|startsWith|endsWith|starts_with|ends_with|"
+          + "timestamp|duration|in|index|has|int|uint|double|string|bytes|bool|"
+          + "equals|not_equals|less|less_equals|greater|greater_equals|"
+          + "add|subtract|multiply|divide|modulo|logical_and|logical_or|logical_not)"


Add negate to this list and unit test for it

@Test public void checkAllowedReferences_negation() throws Exception { assertAllowed("-(1) == -1"); assertAllowed("-(1.0) == -1.0"); }

kannanjgithub · 2026-04-22T06:52:16Z

Can we move the "CEL foundation" classes to a separate PR so the ext-proc filter that needs Cel string extraction but not the unified matcher functionality can be unblocked sooner?

CelCommon.java

CelStringExtractor.java

CelMatcher.java

GrpcCelEnvironment.java

HeadersWrapper.java

CelStateMatcher.java

We can remove CelMatcher and CelStateMatcher from this list (for the separate PR, since ext-proc doesn't need the matching functionality) with the following changes to unit tests:

CelMatcherTestHelper.java: Delete the compile(String expression) method that returns a CelMatcher.
CelEnvironmentTest.java: Delete the test cases that use CelMatcher.

Move these unit tests with the separate PR.

CelCommonTest.java
CelEnvironmentTest.java
CelStringExtractorTest.java

kannanjgithub · 2026-04-22T12:46:09Z

A106 said only request variable will be supported but for use by ext-proc A93, we need response supported as well.

AgraVator · 2026-04-22T13:59:29Z

+  private Object getRequestField(String requestField) {
+    switch (requestField) {
+      case "headers": return new HeadersWrapper(context);
+      case "host": return orEmpty(context.getHost());
+      case "id": return orEmpty(context.getId());
+      case "method": return or(context.getMethod(), "POST");
+      case "path":
+      case "url_path":
+        return orEmpty(context.getPath());
+      case "query": return "";
+      case "scheme": return "";
+      case "protocol": return "";
+      case "time": return null;
+      case "referer": return getHeader("referer");
+      case "useragent": return getHeader("user-agent");
+
+      default:
+        return null; 
+    }
+  }


I noticed that GrpcCelEnvironment.java and MatchContext.java currently only provide support for request variables (headers, method, path, etc.). However, gRFC A103 (Composite Filter) explicitly mentions the need for source and connection variables (e.g., source.address, source.port, connection.tls_version) for server-side matching.

Is there a plan to extend MatchContext and the variable resolver in this PR to include these transport attributes, or should this be tracked as a follow-up task?

I believe these needs to be added as part of Composite filter implementation itself. This gives you the framework for it. It's mentioned in gRFC 103:

In addition to the CEL request attributes described in A106, we will also add support for some additional CEL attributes that we expect to be useful for the composite filter.

AgraVator · 2026-04-22T14:00:43Z

+  public MatchContext(Metadata metadata, @Nullable String path,
+      @Nullable String host, @Nullable String method,
+      @Nullable String id) {
+    this.metadata = Preconditions.checkNotNull(metadata, "metadata");
+    this.path = path;
+    this.host = host;
+    this.method = method;
+    this.id = id;
+  }


To support future attributes beyond just headers (like the aforementioned transport info or cluster metadata), we might want to consider a more pluggable way to populate MatchContext.

Currently, it has a fixed set of fields. A map-based approach or a registry of attribute providers might make it easier to add new attributes without changing the core MatchContext class every time

AgraVator · 2026-04-22T14:02:40Z

-  /** Translates envoy proto HeaderMatcher to internal HeaderMatcher.*/
+  /** Translates envoy proto HeaderMatcher to internal HeaderMatcher. */
  public static Matchers.HeaderMatcher parseHeaderMatcher(
-          io.envoyproxy.envoy.config.route.v3.HeaderMatcher proto) {
+      io.envoyproxy.envoy.config.route.v3.HeaderMatcher proto) {


can we revert the whitespace changes in this file ?

xds: Implementation of Unified Matcher and CEL Integration

f472c63

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

shivaspeaks added 11 commits February 3, 2026 16:01

fix dependency issue

99aeef1

add some unit tests to increase coverage

db4d885

add some more unit tests

33eff21

fix unchecked issue

e28c8f5

add some more unit tests

78895db

fix/add tests

19989eb

remove not required tests

118d7af

add tests

77b01b9

add tests

310677d

add tests

49031b4

add some tests

5a31706

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

shivaspeaks added 2 commits February 12, 2026 23:32

change dependency on dev.cel:cel

c62d193

Subset dev.cel environment in CelCommon and add regression test

0c2d771

ejona86 reviewed Feb 12, 2026

View reviewed changes

l46kok reviewed Feb 13, 2026

View reviewed changes

Address comments

91d6bea

copybara-service Bot pushed a commit to google/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 google/cel-java#954

Merged

copybara-service Bot pushed a commit to google/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 google/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

add dev.cel:common

020f9ff

shivaspeaks mentioned this pull request Feb 25, 2026

xds: Add composite filter #12646

Open

shivaspeaks added 2 commits March 4, 2026 16:15

add unit tests for exactMatchMap case

f20c5f0

add unit tests

0bd57e9

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

asheshvidyut reviewed Mar 25, 2026

View reviewed changes

shivaspeaks added 2 commits March 30, 2026 21:39

Address Ashesh's comments

3b6129f

use switch in PredicateEvaluator

7cad139

ejona86 removed their request for review April 8, 2026 17:30

kannanjgithub reviewed Apr 17, 2026

View reviewed changes

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

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

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

Address comments on CelStringExtractor

7688bd8

shivaspeaks added 2 commits April 20, 2026 15:00

resolve merge conflicts

8c53456

all overloaded methods should be placed together

b379a9e

shivaspeaks requested a review from kannanjgithub April 20, 2026 09:46

kannanjgithub reviewed Apr 21, 2026

View reviewed changes

Use regex for overload ids and add unit tests

60a9356

shivaspeaks requested a review from kannanjgithub April 21, 2026 14:12

kannanjgithub reviewed Apr 22, 2026

View reviewed changes

address comments

8515729

AgraVator reviewed Apr 22, 2026

View reviewed changes

shivaspeaks mentioned this pull request Apr 23, 2026

xds: CEL implementation #12770

Open

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

Conversation

shivaspeaks commented Feb 3, 2026

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!

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!

Uh oh!

Uh oh!

Uh oh!

shivaspeaks commented Apr 20, 2026

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 Apr 21, 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!

Choose a reason for hiding this comment

Uh oh!

kannanjgithub commented Apr 21, 2026

Uh oh!

kannanjgithub commented Apr 21, 2026

Uh oh!

kannanjgithub commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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 Apr 22, 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!

Choose a reason for hiding this comment

Uh oh!

kannanjgithub commented Apr 22, 2026

Uh oh!

kannanjgithub commented Apr 22, 2026

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

shivaspeaks Apr 21, 2026 •

edited

Loading

kannanjgithub commented Apr 22, 2026 •

edited

Loading

shivaspeaks Apr 22, 2026 •

edited

Loading