xds: Implementation of Unified Matcher and CEL Integration

Author: shivaspeaks

gradle/libs.versions.toml

@@ -34,6 +34,8 @@ checkstyle = "com.puppycrawl.tools:checkstyle:10.26.1"
 # checkstyle 10.0+ requires Java 11+
 # See https://checkstyle.sourceforge.io/releasenotes_old_8-35_10-26.html#Release_10.0
 # checkForUpdates: checkstylejava8:9.+
+cel-runtime = "dev.cel:runtime:0.11.1"
+cel-compiler = "dev.cel:compiler:0.11.1"
 checkstylejava8 = "com.puppycrawl.tools:checkstyle:9.3"
 commons-math3 = "org.apache.commons:commons-math3:3.6.1"
 conscrypt = "org.conscrypt:conscrypt-openjdk-uber:2.5.2"

xds/BUILD.bazel

@@ -41,6 +41,7 @@ java_library(
         artifact("com.google.errorprone:error_prone_annotations"),
         artifact("com.google.guava:guava"),
         artifact("com.google.re2j:re2j"),
+        artifact("dev.cel:cel-bundle"),
         artifact("io.netty:netty-buffer"),
         artifact("io.netty:netty-codec"),
         artifact("io.netty:netty-common"),

xds/build.gradle

@@ -56,6 +56,12 @@ dependencies {
             libraries.re2j,
             libraries.auto.value.annotations,
             libraries.protobuf.java.util
+    implementation(libraries.cel.runtime) {
+        exclude group: 'com.google.protobuf', module: 'protobuf-java'
+    }
+    implementation(libraries.cel.compiler) {
+        exclude group: 'com.google.protobuf', module: 'protobuf-java'
+    }
     def nettyDependency = implementation project(':grpc-netty')
 
     testImplementation project(':grpc-api')
@@ -175,13 +181,15 @@ tasks.named("javadoc").configure {
     exclude 'io/grpc/xds/XdsNameResolverProvider.java'
     exclude 'io/grpc/xds/internal/**'
     exclude 'io/grpc/xds/Internal*'
+    exclude 'dev/cel/**'
 }
 
 def prefixName = 'io.grpc.xds'
 tasks.named("shadowJar").configure {
     archiveClassifier = null
     dependencies {
         include(project(':grpc-xds'))
+        include(dependency('dev.cel:.*'))
     }
     // Relocated packages commonly need exclusions in jacocoTestReport and javadoc
     // Keep in sync with BUILD.bazel's JAR_JAR_RULES
@@ -198,6 +206,8 @@ tasks.named("shadowJar").configure {
     // TODO: missing java_package option in .proto
     relocate 'udpa.annotations', "${prefixName}.shaded.udpa.annotations"
     relocate 'xds.annotations', "${prefixName}.shaded.xds.annotations"
+    relocate 'dev.cel', "${prefixName}.shaded.dev.cel"
+    relocate 'cel', "${prefixName}.shaded.cel"
     exclude "**/*.proto"
 }
 

xds/src/main/java/io/grpc/xds/internal/MatcherParser.java

@@ -90,7 +90,7 @@ public static Matchers.StringMatcher parseStringMatcher(
         return Matchers.StringMatcher.forSafeRegEx(
                 Pattern.compile(proto.getSafeRegex().getRegex()));
       case CONTAINS:
-        return Matchers.StringMatcher.forContains(proto.getContains());
+        return Matchers.StringMatcher.forContains(proto.getContains(), proto.getIgnoreCase());
       case MATCHPATTERN_NOT_SET:
       default:
         throw new IllegalArgumentException(

xds/src/main/java/io/grpc/xds/internal/Matchers.java

@@ -257,10 +257,15 @@ public static StringMatcher forSafeRegEx(Pattern regEx) {
     }
 
     /** The input string should contain this substring. */
-    public static StringMatcher forContains(String contains) {
+    public static StringMatcher forContains(String contains, boolean ignoreCase) {
       checkNotNull(contains, "contains");
       return StringMatcher.create(null, null, null, null, contains,
-          false/* doesn't matter */);
+          ignoreCase);
+    }
+
+    /** The input string should contain this substring. */
+    public static StringMatcher forContains(String contains) {
+      return forContains(contains, false);
     }
 
     /** Returns the matching result for this string. */
@@ -281,7 +286,9 @@ public boolean matches(String args) {
             ? args.toLowerCase(Locale.ROOT).endsWith(suffix().toLowerCase(Locale.ROOT))
             : args.endsWith(suffix());
       } else if (contains() != null) {
-        return args.contains(contains());
+        return ignoreCase()
+            ? args.toLowerCase(Locale.ROOT).contains(contains().toLowerCase(Locale.ROOT))
+            : args.contains(contains());
       }
       return regEx().matches(args);
     }

xds/src/main/java/io/grpc/xds/internal/matcher/CelCommon.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2026 The gRPC Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.grpc.xds.internal.matcher;
+
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelOptions;
+import dev.cel.common.types.SimpleType;
+import dev.cel.compiler.CelCompiler;
+import dev.cel.compiler.CelCompilerFactory;
+import dev.cel.runtime.CelRuntime;
+import dev.cel.runtime.CelRuntimeFactory;
+
+/**
+ * Shared utilities for CEL-based matchers and extractors.
+ */
+final class CelCommon {
+  private static final CelOptions CEL_OPTIONS = CelOptions.newBuilder()
+      .enableComprehension(false)
+      .enableStringConversion(false)
+      .enableStringConcatenation(false)
+      .enableListConcatenation(false)
+      .maxRegexProgramSize(100)
+      .build();
+
+  static final CelCompiler COMPILER = CelCompilerFactory.standardCelCompilerBuilder()
+      .addVar("request", SimpleType.DYN)
+      .setOptions(CEL_OPTIONS)
+      .build();
+
+  static final CelRuntime RUNTIME = CelRuntimeFactory.standardCelRuntimeBuilder()
+      .setOptions(CEL_OPTIONS)
+      .build();
+
+  private CelCommon() {}
+
+  static void checkAllowedVariables(CelAbstractSyntaxTree ast) {
+    // Basic validation to ensure only supported variables (request) are used.
+    // This iterates over the reference map generated by the type checker.
+    for (java.util.Map.Entry<Long, dev.cel.common.ast.CelReference> entry : 
+        ast.getReferenceMap().entrySet()) {
+      dev.cel.common.ast.CelReference ref = entry.getValue();
+      // If overload_id is empty, it's a variable reference or type name.
+      // We only support "request".
+      if (ref.value() == null && ref.overloadIds().isEmpty()) {
+        if (!"request".equals(ref.name())) {
+          throw new IllegalArgumentException(
+              "CEL expression references unknown variable: " + ref.name());
+        }
+      }
+    }
+  }
+}

xds/src/main/java/io/grpc/xds/internal/matcher/CelMatcher.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2026 The gRPC Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.grpc.xds.internal.matcher;
+
+import com.google.common.annotations.VisibleForTesting;
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelValidationException;
+import dev.cel.common.types.SimpleType;
+import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelRuntime;
+
+
+
+/**
+ * Executes compiled CEL expressions.
+ */
+public final class CelMatcher {
+
+
+  private final CelRuntime.Program program;
+
+  private CelMatcher(CelRuntime.Program program) {
+    this.program = program;
+  }
+
+  /**
+   * Compiles the AST into a CelMatcher.
+   */
+  public static CelMatcher compile(CelAbstractSyntaxTree ast)
+      throws CelValidationException, CelEvaluationException {
+    if (ast.getResultType() != SimpleType.BOOL) {
+      throw new IllegalArgumentException(
+          "CEL expression must evaluate to boolean, got: " + ast.getResultType());
+    }
+    CelCommon.checkAllowedVariables(ast);
+    CelRuntime.Program program = CelCommon.RUNTIME.createProgram(ast);
+    return new CelMatcher(program);
+  }
+
+  /**
+   * Compiles the CEL expression string into a CelMatcher.
+   */
+  @VisibleForTesting
+  public static CelMatcher compile(String expression)
+      throws CelValidationException, CelEvaluationException {
+    CelAbstractSyntaxTree ast = CelCommon.COMPILER.compile(expression).getAst();
+    return compile(ast);
+  }
+
+  /**
+   * Evaluates the CEL expression against the input activation.
+   */
+  public boolean match(Object input) throws CelEvaluationException {
+    Object result;
+    if (input instanceof dev.cel.runtime.CelVariableResolver) {
+      result = program.eval((dev.cel.runtime.CelVariableResolver) input);
+    } else if (input instanceof java.util.Map) {
+      @SuppressWarnings("unchecked")
+      java.util.Map<String, ?> mapInput = (java.util.Map<String, ?>) input;
+      result = program.eval(mapInput);
+    } else {
+      throw new CelEvaluationException(
+          "Unsupported input type for CEL evaluation: " + input.getClass().getName());
+    }
+    // Validated to be boolean during compile check ideally, or we cast safely
+    if (result instanceof Boolean) {
+      return (Boolean) result;
+    }
+    throw new CelEvaluationException(
+        "CEL expression must evaluate to boolean, got: " + result.getClass().getName());
+  }
+}

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

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2026 The gRPC Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.grpc.xds.internal.matcher;
+
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelValidationException;
+import dev.cel.common.types.SimpleType;
+import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelRuntime;
+
+
+/**
+ * Executes compiled CEL expressions that extract a string.
+ */
+public final class CelStringExtractor {
+
+
+  private final CelRuntime.Program program;
+
+  private CelStringExtractor(CelRuntime.Program program) {
+    this.program = program;
+  }
+
+  /**
+   * Compiles the AST into a CelStringExtractor.
+   */
+  public static CelStringExtractor compile(CelAbstractSyntaxTree ast) 
+      throws CelValidationException, CelEvaluationException {
+    if (ast.getResultType() != SimpleType.STRING && ast.getResultType() != SimpleType.DYN) {
+      throw new IllegalArgumentException(
+          "CEL expression must evaluate to string, got: " + ast.getResultType());
+    }
+    CelCommon.checkAllowedVariables(ast);
+    CelRuntime.Program program = CelCommon.RUNTIME.createProgram(ast);
+    return new CelStringExtractor(program);
+  }
+
+  /**
+   * Compiles the CEL expression string into a CelStringExtractor.
+   */
+  public static CelStringExtractor compile(String expression)
+      throws CelValidationException, CelEvaluationException {
+    CelAbstractSyntaxTree ast = CelCommon.COMPILER.compile(expression).getAst();
+    return compile(ast);
+  }
+
+  /**
+   * Evaluates the CEL expression against the input activation and returns the string result.
+   * Returns null if the result is not a string.
+   */
+  public String extract(Object input) throws CelEvaluationException {
+    Object result;
+    if (input instanceof dev.cel.runtime.CelVariableResolver) {
+      result = program.eval((dev.cel.runtime.CelVariableResolver) input);
+    } else if (input instanceof java.util.Map) {
+      @SuppressWarnings("unchecked")
+      java.util.Map<String, ?> mapInput = (java.util.Map<String, ?>) input;
+      result = program.eval(mapInput);
+    } else {
+      throw new CelEvaluationException(
+          "Unsupported input type for CEL evaluation: " + input.getClass().getName());
+    }
+    
+    if (result instanceof String) {
+      return (String) result;
+    }
+    // Return null key for non-string results (which will likely match nothing or be handled)
+    return null; 
+  }
+}