xds: Implementation of Unified Matcher

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

@@ -90,14 +90,47 @@ 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(
                 "Unknown StringMatcher match pattern: " + proto.getMatchPatternCase());
     }
   }
 
+  /** Translate StringMatcher xDS proto to internal StringMatcher. */
+  public static Matchers.StringMatcher parseStringMatcher(
+            com.github.xds.type.matcher.v3.StringMatcher proto) {
+    switch (proto.getMatchPatternCase()) {
+      case EXACT:
+        return Matchers.StringMatcher.forExact(proto.getExact(), proto.getIgnoreCase());
+      case PREFIX:
+        return Matchers.StringMatcher.forPrefix(
+            checkNonEmpty(proto.getPrefix(), "prefix"), proto.getIgnoreCase());
+      case SUFFIX:
+        return Matchers.StringMatcher.forSuffix(
+            checkNonEmpty(proto.getSuffix(), "suffix"), proto.getIgnoreCase());
+      case SAFE_REGEX:
+        String regex = checkNonEmpty(proto.getSafeRegex().getRegex(), "regex");
+        return Matchers.StringMatcher.forSafeRegEx(Pattern.compile(regex));
+      case CONTAINS:
+        return Matchers.StringMatcher.forContains(
+            checkNonEmpty(proto.getContains(), "contains"), proto.getIgnoreCase());
+      case MATCHPATTERN_NOT_SET:
+      default:
+        throw new IllegalArgumentException(
+            "Unknown StringMatcher match pattern: " + proto.getMatchPatternCase());
+    }
+  }
+
+  private static String checkNonEmpty(String value, String name) {
+    if (value.isEmpty()) {
+      throw new IllegalArgumentException("StringMatcher " + name 
+          + " (match_pattern) must be non-empty");
+    }
+    return value;
+  }
+
   /** Translates envoy proto FractionalPercent to internal FractionMatcher. */
   public static Matchers.FractionMatcher parseFractionMatcher(
       io.envoyproxy.envoy.type.v3.FractionalPercent proto) {

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/CelMatcher.java

@@ -0,0 +1,71 @@
+/*
+ * 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;
+
+/**
+ * Executes compiled CEL expressions.
+ */
+final class CelMatcher {
+  private final CelRuntime.Program program;
+
+  private CelMatcher(CelRuntime.Program program) {
+    this.program = program;
+  }
+
+  /**
+   * Compiles the AST into a CelMatcher.
+   * Throws an Exception if evaluation fails during compilation setup.
+   */
+  static CelMatcher compile(CelAbstractSyntaxTree ast)
+      throws CelEvaluationException {
+    // CelEvaluationException -> inside cel-runtime -> Allowed in production signatures
+    // CelValidationException -> inside cel-compiler -> Forbidden in production signatures
+    if (ast.getResultType() != SimpleType.BOOL) {
+      throw new IllegalArgumentException(
+          "CEL expression must evaluate to boolean, got: " + ast.getResultType());
+    }
+    CelCommon.checkAllowedReferences(ast);
+    CelRuntime.Program program = CelCommon.RUNTIME.createProgram(ast);
+    return new CelMatcher(program);
+  }
+
+  /**
+   * Evaluates the CEL expression against the input activation.
+   */
+  boolean match(Object input) throws CelEvaluationException {
+    Object result;
+    if (input instanceof CelVariableResolver) {
+      result = program.eval((CelVariableResolver) input);
+    } else {
+      throw new CelEvaluationException(
+          "Unsupported input type for CEL evaluation: "
+               + (input == null ? "null" : input.getClass().getName()));
+    }
+
+    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/CelStateMatcher.java

@@ -0,0 +1,79 @@
+/*
+ * 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.github.xds.core.v3.TypedExtensionConfig;
+import com.github.xds.type.v3.CelExpression;
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelProtoAbstractSyntaxTree;
+import dev.cel.runtime.CelEvaluationException;
+
+/**
+ * Matcher for CEL expressions handling xDS CEL Matcher extension.
+ */
+final class CelStateMatcher implements Matcher {
+  private final CelMatcher compiledEndpoint;
+  static final String TYPE_URL = "type.googleapis.com/xds.type.matcher.v3.CelMatcher";
+
+  CelStateMatcher(CelMatcher compiledEndpoint) {
+    this.compiledEndpoint = compiledEndpoint;
+  }
+
+  @Override
+  public boolean match(Object value) {
+    try {
+      return compiledEndpoint.match(value);
+    } catch (CelEvaluationException e) {
+      return false;
+    }
+  }
+
+  @Override
+  public Class<?> inputType() {
+    return GrpcCelEnvironment.class;
+  }
+
+  static final class Provider implements MatcherProvider {
+    @Override
+    public CelStateMatcher getMatcher(TypedExtensionConfig config) {
+      try {
+        com.github.xds.type.matcher.v3.CelMatcher celProto = config.getTypedConfig()
+            .unpack(com.github.xds.type.matcher.v3.CelMatcher.class);
+        if (!celProto.hasExprMatch()) {
+          throw new IllegalArgumentException("CelMatcher must have expr_match");
+        }
+        CelExpression expr = celProto.getExprMatch();
+        if (!expr.hasCelExprChecked()) {
+          throw new IllegalArgumentException("CelMatcher must have cel_expr_checked");
+        }
+        CelAbstractSyntaxTree ast = 
+            CelProtoAbstractSyntaxTree.fromCheckedExpr(
+                expr.getCelExprChecked()).getAst();
+        CelMatcher compiled = CelMatcher.compile(ast);
+
+        return new CelStateMatcher(compiled);
+      } catch (Exception e) {
+        throw new IllegalArgumentException("Invalid CelMatcher config", e);
+      }
+    }
+
+    @Override
+    public String typeUrl() {
+      return TYPE_URL;
+    }
+  }
+}

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

@@ -26,7 +26,7 @@
 /**
  * Executes compiled CEL expressions that extract a string.
  */
-public final class CelStringExtractor {
+final class CelStringExtractor {
   private final CelRuntime.Program program;
   @Nullable
   private final String defaultValue;
@@ -40,7 +40,7 @@ private CelStringExtractor(CelRuntime.Program program, @Nullable String defaultV
    * 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)
+  static CelStringExtractor compile(CelAbstractSyntaxTree ast, @Nullable String defaultValue)
       throws CelEvaluationException {
     if (ast.getResultType() != SimpleType.STRING && ast.getResultType() != SimpleType.DYN) {
       throw new IllegalArgumentException(
@@ -55,7 +55,7 @@ public static CelStringExtractor compile(CelAbstractSyntaxTree ast, @Nullable St
    * 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)
+  static CelStringExtractor compile(CelAbstractSyntaxTree ast)
       throws CelEvaluationException {
     return compile(ast, null);
   }
@@ -65,7 +65,7 @@ public static CelStringExtractor compile(CelAbstractSyntaxTree ast)
    * Returns the default value if the result is not a string or if evaluation
    * fails.
    */
-  public String extract(Object input) throws CelEvaluationException {
+  String extract(Object input) throws CelEvaluationException {
     if (input instanceof CelVariableResolver) {
       try {
         Object result = program.eval((CelVariableResolver) input);

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

@@ -0,0 +1,114 @@
+/*
+ * 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 static com.google.common.base.Preconditions.checkNotNull;
+
+import com.github.xds.core.v3.TypedExtensionConfig;
+import com.google.common.io.BaseEncoding;
+import com.google.protobuf.InvalidProtocolBufferException;
+import io.envoyproxy.envoy.type.matcher.v3.HttpRequestHeaderMatchInput;
+import io.grpc.Metadata;
+import java.util.Locale;
+
+/**
+ * MatchInput for extracting HTTP headers.
+ */
+final class HeaderMatchInput implements MatchInput {
+  private static final BaseEncoding BASE64 = BaseEncoding.base64();
+  private final String headerName;
+  private final Metadata.Key<byte[]> binaryKey;
+  private final Metadata.Key<String> stringKey;
+
+  static final String TYPE_URL =
+      "type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput";
+
+  HeaderMatchInput(String headerName) {
+    this.headerName = checkNotNull(headerName, "headerName");
+    if (headerName.isEmpty() || headerName.length() >= 16384) {
+      throw new IllegalArgumentException(
+          "Header name length must be in range [1, 16384): " + headerName.length());
+    }
+    if (!headerName.equals(headerName.toLowerCase(Locale.ROOT))) {
+      throw new IllegalArgumentException("Header name must be lowercase: " + headerName);
+    }
+    try {
+      if (headerName.endsWith(Metadata.BINARY_HEADER_SUFFIX)) {
+        this.binaryKey = Metadata.Key.of(headerName, Metadata.BINARY_BYTE_MARSHALLER);
+        this.stringKey = null;
+      } else {
+        this.binaryKey = null;
+        this.stringKey = Metadata.Key.of(headerName, Metadata.ASCII_STRING_MARSHALLER);
+      }
+    } catch (IllegalArgumentException e) {
+      throw new IllegalArgumentException("Invalid header name: " + headerName, e);
+    }
+  }
+
+  @Override
+  public String apply(MatchContext context) {
+    if ("te".equals(headerName)) {
+      return null;
+    }
+    if (binaryKey != null) {
+      Iterable<byte[]> values = context.getMetadata().getAll(binaryKey);
+      if (values == null) {
+        return null;
+      }
+      StringBuilder sb = new StringBuilder();
+      boolean first = true;
+      for (byte[] value : values) {
+        if (!first) {
+          sb.append(",");
+        }
+        first = false;
+        sb.append(BASE64.encode(value));
+      }
+      return sb.toString();
+    }
+    Metadata metadata = context.getMetadata();
+    Iterable<String> values = metadata.getAll(stringKey);
+    if (values == null) {
+      return null;
+    }
+    return String.join(",", values);
+  }
+
+  @Override
+  public Class<?> outputType() {
+    return String.class;
+  }
+
+  static final class Provider implements MatchInputProvider {
+    @Override
+    public HeaderMatchInput getInput(TypedExtensionConfig config) {
+      try {
+        HttpRequestHeaderMatchInput proto = config.getTypedConfig()
+            .unpack(HttpRequestHeaderMatchInput.class);
+        return new HeaderMatchInput(proto.getHeaderName());
+      } catch (InvalidProtocolBufferException e) {
+        throw new IllegalArgumentException(
+            "Invalid input config: " + config.getTypedConfig().getTypeUrl(), e);
+      }
+    }
+
+    @Override
+    public String typeUrl() {
+      return TYPE_URL;
+    }
+  }
+}