xds: Add CelStringExtractor and CEL dependencies

Author: kannanjgithub

gradle/libs.versions.toml

@@ -37,6 +37,9 @@ 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.12.0"
+cel-protobuf = "dev.cel:protobuf:0.12.0"
+cel-compiler = "dev.cel:compiler:0.12.0"
 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,9 @@ java_library(
         artifact("com.google.errorprone:error_prone_annotations"),
         artifact("com.google.guava:guava"),
         artifact("com.google.re2j:re2j"),
+        artifact("dev.cel:runtime"),
+        artifact("dev.cel:protobuf"),
+        artifact("dev.cel:common"),
         artifact("io.netty:netty-buffer"),
         artifact("io.netty:netty-codec"),
         artifact("io.netty:netty-common"),
@@ -97,6 +100,8 @@ JAR_JAR_RULES = [
     "rule com.google.api.expr.** io.grpc.xds.shaded.com.google.api.expr.@1",
     "rule com.google.security.** io.grpc.xds.shaded.com.google.security.@1",
     "rule dev.cel.expr.** io.grpc.xds.shaded.dev.cel.expr.@1",
+    "rule dev.cel.** io.grpc.xds.shaded.dev.cel.@1",
+    "rule cel.** io.grpc.xds.shaded.cel.@1",
     "rule envoy.annotations.** io.grpc.xds.shaded.envoy.annotations.@1",
     "rule io.envoyproxy.** io.grpc.xds.shaded.io.envoyproxy.@1",
     "rule udpa.annotations.** io.grpc.xds.shaded.udpa.annotations.@1",

xds/build.gradle

@@ -56,11 +56,18 @@ 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.protobuf) {
+        exclude group: 'com.google.protobuf', module: 'protobuf-java'
+    }
     def nettyDependency = implementation project(':grpc-netty')
 
     testImplementation project(':grpc-api')
     testImplementation project(':grpc-rls')
     testImplementation project(':grpc-inprocess')
+    testImplementation libraries.cel.compiler
     testImplementation testFixtures(project(':grpc-core')),
             testFixtures(project(':grpc-api')),
             testFixtures(project(':grpc-util'))
@@ -175,13 +182,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 +207,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/matcher/CelCommon.java

@@ -0,0 +1,107 @@
+/*
+ * 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.collect.ImmutableSet;
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelOptions;
+import dev.cel.common.ast.CelReference;
+import dev.cel.runtime.CelRuntime;
+import dev.cel.runtime.CelRuntimeFactory;
+import dev.cel.runtime.CelStandardFunctions;
+import dev.cel.runtime.CelStandardFunctions.StandardFunction;
+import dev.cel.runtime.standard.AddOperator.AddOverload;
+import java.util.Map;
+
+/**
+ * Shared utilities for CEL-based matchers and extractors.
+ */
+final class CelCommon {
+  private static final CelOptions CEL_OPTIONS = CelOptions.newBuilder()
+      .enableComprehension(false)
+      .maxRegexProgramSize(100)
+      .build();
+  private static final String REQUEST_VARIABLE = "request";
+  private static final CelStandardFunctions FUNCTIONS = 
+      CelStandardFunctions.newBuilder()
+          .filterFunctions((func, over) -> {
+            if (func == StandardFunction.STRING) {
+              return false;
+            }
+            if (func == StandardFunction.ADD) {
+              return !over.equals(AddOverload.ADD_STRING)
+                  && !over.equals(AddOverload.ADD_LIST);
+            }
+            return true;
+          })
+          .build();
+
+  /**
+   * 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",
+      "int", "uint", "double", "bytes", "bool", "==", "!=", ">", "<", ">=", "<=",
+      "&&", "||", "!", "+", "-", "*", "/", "%", "in", "has", "or", "equals",
+      "index_map", "divide_int64", "int64_to_int64", "uint64_to_int64",
+      "double_to_int64", "string_to_int64", "timestamp_to_int64");
+
+  static final CelRuntime RUNTIME = CelRuntimeFactory.standardCelRuntimeBuilder()
+      .setStandardEnvironmentEnabled(false)
+      .setStandardFunctions(FUNCTIONS)
+      .setOptions(CEL_OPTIONS)
+      .build();
+
+  private CelCommon() {}
+
+  /**
+   * Validates that the AST only references the allowed variable ("request")
+   * and supported functions as defined in gRFC A106.
+   */
+  static void checkAllowedReferences(CelAbstractSyntaxTree ast) {
+    for (Map.Entry<Long, CelReference> entry : ast.getReferenceMap().entrySet()) {
+      CelReference ref = entry.getValue();
+
+      // Check for variables (where overloadIds is empty)
+      if (!ref.value().isPresent() && ref.overloadIds().isEmpty()) {
+        if (!REQUEST_VARIABLE.equals(ref.name())) {
+          throw new IllegalArgumentException(
+              "CEL expression references unknown variable: " + ref.name());
+        }
+      } else if (!ref.overloadIds().isEmpty()) {
+        String name = ref.name();
+        if (name.isEmpty()) {
+          boolean allowed = false;
+          for (String id : ref.overloadIds()) {
+            if (ALLOWED_FUNCTIONS.contains(id)) {
+              allowed = true;
+              break;
+            }
+          }
+          if (!allowed) {
+            throw new IllegalArgumentException(
+                "CEL expression references unknown function with overload IDs: "
+                    + ref.overloadIds());
+          }
+        } else if (!ALLOWED_FUNCTIONS.contains(name)) {
+          throw new IllegalArgumentException(
+              "CEL expression references unknown function: " + name);
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,89 @@
+/*
+ * 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.types.SimpleType;
+import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelRuntime;
+import dev.cel.runtime.CelVariableResolver;
+import javax.annotation.Nullable;
+
+/**
+ * Executes compiled CEL expressions that extract a string.
+ */
+public final class CelStringExtractor {
+  private final CelRuntime.Program program;
+  @Nullable
+  private final String defaultValue;
+
+  private CelStringExtractor(CelRuntime.Program program, @Nullable String defaultValue) {
+    this.program = program;
+    this.defaultValue = defaultValue;
+  }
+
+  /**
+   * Compiles the AST into a CelStringExtractor with an optional default value.
+   * Throws an Exception if evaluation fails during compilation setup.
+   */
+  public static CelStringExtractor compile(CelAbstractSyntaxTree ast, @Nullable String defaultValue)
+      throws CelEvaluationException {
+    if (ast.getResultType() != SimpleType.STRING && ast.getResultType() != SimpleType.DYN) {
+      throw new IllegalArgumentException(
+          "CEL expression must evaluate to string, got: " + ast.getResultType());
+    }
+    CelCommon.checkAllowedReferences(ast);
+    CelRuntime.Program program = CelCommon.RUNTIME.createProgram(ast);
+    return new CelStringExtractor(program, defaultValue);
+  }
+
+  /**
+   * Compiles the AST into a CelStringExtractor with no default value.
+   * Throws an Exception if evaluation fails during compilation setup.
+   */
+  public static CelStringExtractor compile(CelAbstractSyntaxTree ast)
+      throws CelEvaluationException {
+    return compile(ast, null);
+  }
+
+  /**
+   * Evaluates the CEL expression and returns the string result.
+   * Returns the default value if the result is not a string or if evaluation
+   * fails.
+   */
+  public String extract(Object input) throws CelEvaluationException {
+    Object result;
+    try {
+      if (input instanceof CelVariableResolver) {
+        result = program.eval((CelVariableResolver) input);
+      } else {
+        throw new CelEvaluationException(
+            "Unsupported input type for CEL evaluation: " + input.getClass().getName());
+      }
+    } catch (CelEvaluationException e) {
+      if (defaultValue != null) {
+        return defaultValue;
+      }
+      throw e;
+    }
+
+    if (result instanceof String) {
+      return (String) result;
+    }
+    return defaultValue;
+  }
+}