xds: add RlsClusterSpecifierPlugin for RLS-in-xDS

rls/src/main/java/io/grpc/rls/RlsProtoData.java

@@ -25,6 +25,7 @@
 import com.google.common.base.Objects;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
+import io.grpc.Internal;
 import io.grpc.rls.RlsProtoData.GrpcKeyBuilder.Name;
 import java.util.HashSet;
 import java.util.List;
@@ -35,7 +36,10 @@
 import javax.annotation.concurrent.Immutable;
 
 /** RlsProtoData is a collection of internal representation of RouteLookupService proto messages. */
-final class RlsProtoData {
+@Internal
+public final class RlsProtoData {
+
+  private RlsProtoData() {}
 
   /** A request object sent to route lookup service. */
   @Immutable
@@ -138,7 +142,7 @@ public String toString() {
 
   /** A config object for gRPC RouteLookupService. */
   @Immutable
-  static final class RouteLookupConfig {
+  public static final class RouteLookupConfig {
 
     private static final long MAX_AGE_MILLIS = TimeUnit.MINUTES.toMillis(5);
     private static final long MAX_CACHE_SIZE = 5 * 1024 * 1024;
@@ -160,7 +164,8 @@ static final class RouteLookupConfig {
     @Nullable
     private final String defaultTarget;
 
-    RouteLookupConfig(
+    /** Constructor. */
+    public RouteLookupConfig(
         List<GrpcKeyBuilder> grpcKeyBuilders,
         String lookupService,
         long lookupServiceTimeoutInMillis,
@@ -197,6 +202,9 @@ static final class RouteLookupConfig {
       checkArgument(cacheSizeBytes > 0, "cacheSize must be positive");
       this.cacheSizeBytes = Math.min(cacheSizeBytes, MAX_CACHE_SIZE);
       this.validTargets = ImmutableList.copyOf(checkNotNull(validTargets, "validTargets"));
+      if (defaultTarget != null && defaultTarget.isEmpty()) {
+        defaultTarget = null;
+      }
       this.defaultTarget = defaultTarget;
     }
 
@@ -328,15 +336,16 @@ private static void checkUniqueName(List<GrpcKeyBuilder> grpcKeyBuilders) {
    * is true, one of the specified names must be present for the keybuilder to match.
    */
   @Immutable
-  static final class NameMatcher {
+  public static final class NameMatcher {
 
     private final String key;
 
     private final ImmutableList<String> names;
 
     private final boolean optional;
 
-    NameMatcher(String key, List<String> names, @Nullable Boolean optional) {
+    /** Constructor. */
+    public NameMatcher(String key, List<String> names, @Nullable Boolean optional) {
       this.key = checkNotNull(key, "key");
       this.names = ImmutableList.copyOf(checkNotNull(names, "names"));
       this.optional = optional != null ? optional : true;
@@ -389,14 +398,15 @@ public String toString() {
   }
 
   /** GrpcKeyBuilder is a configuration to construct headers consumed by route lookup service. */
-  static final class GrpcKeyBuilder {
+  public static final class GrpcKeyBuilder {
 
     private final ImmutableList<Name> names;
 
     private final ImmutableList<NameMatcher> headers;
     private final ExtraKeys extraKeys;
     private final ImmutableMap<String, String> constantKeys;
 
+    /** Constructor. All args should be nonnull. Headers should head unique keys. */
     public GrpcKeyBuilder(
         List<Name> names, List<NameMatcher> headers, ExtraKeys extraKeys,
         Map<String, String> constantKeys) {
@@ -476,17 +486,18 @@ public String toString() {
      * required and includes the proto package name. The method name may be omitted, in which case
      * any method on the given service is matched.
      */
-    static final class Name {
+    public static final class Name {
 
       private final String service;
 
       private final String method;
 
-      Name(String service) {
+      public Name(String service) {
         this(service, "*");
       }
 
-      Name(String service, String method) {
+      /** The primary constructor. */
+      public Name(String service, String method) {
         checkState(
             !checkNotNull(service, "service").isEmpty(),
             "service must not be empty or null");
@@ -531,7 +542,7 @@ public String toString() {
   }
 
   @AutoValue
-  abstract static class ExtraKeys {
+  public abstract static class ExtraKeys {
     static final ExtraKeys DEFAULT = create(null, null, null);
 
     @Nullable abstract String host();
@@ -540,7 +551,7 @@ abstract static class ExtraKeys {
 
     @Nullable abstract String method();
 
-    static ExtraKeys create(
+    public static ExtraKeys create(
         @Nullable String host, @Nullable String service, @Nullable String method) {
       return new AutoValue_RlsProtoData_ExtraKeys(host, service, method);
     }

xds/build.gradle

@@ -39,6 +39,7 @@ dependencies {
             libraries.autovalue_annotation,
             libraries.opencensus_proto,
             libraries.protobuf_util
+    implementation project(path: ':grpc-rls')
     def nettyDependency = implementation project(':grpc-netty')
 
     testImplementation project(':grpc-core').sourceSets.test.output

xds/src/main/java/io/grpc/xds/ClientXdsClient.java

@@ -73,7 +73,6 @@
 import io.grpc.xds.EnvoyServerProtoData.FilterChainMatch;
 import io.grpc.xds.EnvoyServerProtoData.UpstreamTlsContext;
 import io.grpc.xds.Filter.ClientInterceptorBuilder;
-import io.grpc.xds.Filter.ConfigOrError;
 import io.grpc.xds.Filter.FilterConfig;
 import io.grpc.xds.Filter.NamedFilterConfig;
 import io.grpc.xds.Filter.ServerInterceptorBuilder;

xds/src/main/java/io/grpc/xds/ClusterSpecifierPlugin.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2021 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;
+
+import com.google.protobuf.Message;
+
+/**
+ * Defines the parsing functionality of a ClusterSpecifierPlugin as defined in the Enovy proto
+ * api/envoy/config/route/v3/route.proto.
+ */
+interface ClusterSpecifierPlugin {
+  /**
+   * The proto message types supported by this plugin. A plugin will be registered by each of its
+   * supported message types.
+   */
+  String[] typeUrls();
+
+  ConfigOrError<? extends PluginConfig> parsePlugin(Message rawProtoMessage);
+
+  /** Represents an opaque data structure holding configuration for a ClusterSpecifierPlugin. */
+  interface PluginConfig {
+    String typeUrl();
+  }
+}

xds/src/main/java/io/grpc/xds/ClusterSpecifierPluginRegistry.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2021 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;
+
+import java.util.HashMap;
+import java.util.Map;
+import javax.annotation.Nullable;
+
+final class ClusterSpecifierPluginRegistry {
+  private static ClusterSpecifierPluginRegistry instance;
+
+  private final Map<String, ClusterSpecifierPlugin> supportedPlugins = new HashMap<>();
+
+  private ClusterSpecifierPluginRegistry() {}
+
+  static synchronized ClusterSpecifierPluginRegistry getDefaultRegistry() {
+    if (instance == null) {
+      instance = newRegistry().register(RouteLookupServiceClusterSpecifierPlugin.INSTANCE);
+    }
+    return instance;
+  }
+
+  private static ClusterSpecifierPluginRegistry newRegistry() {
+    return new ClusterSpecifierPluginRegistry();
+  }
+
+  private ClusterSpecifierPluginRegistry register(ClusterSpecifierPlugin... plugins) {
+    for (ClusterSpecifierPlugin plugin : plugins) {
+      for (String typeUrl : plugin.typeUrls()) {
+        supportedPlugins.put(typeUrl, plugin);
+      }
+    }
+    return this;
+  }
+
+  @Nullable
+  ClusterSpecifierPlugin get(String typeUrl) {
+    return supportedPlugins.get(typeUrl);
+  }
+}

xds/src/main/java/io/grpc/xds/ConfigOrError.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2021 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;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+// TODO(zdapeng): Unify with ClientXdsClient.StructOrError, or just have parseFilterConfig() throw
+//     certain types of Exception.
+final class ConfigOrError<T> {
+
+  /**
+   * Returns a {@link ConfigOrError} for the successfully converted data object.
+   */
+  static <T> ConfigOrError<T> fromConfig(T config) {
+    return new ConfigOrError<>(config);
+  }
+
+  /**
+   * Returns a {@link ConfigOrError} for the failure to convert the data object.
+   */
+  static <T> ConfigOrError<T> fromError(String errorDetail) {
+    return new ConfigOrError<>(errorDetail);
+  }
+
+  final String errorDetail;
+  final T config;
+
+  private ConfigOrError(T config) {
+    this.config = checkNotNull(config, "config");
+    this.errorDetail = null;
+  }
+
+  private ConfigOrError(String errorDetail) {
+    this.config = null;
+    this.errorDetail = checkNotNull(errorDetail, "errorDetail");
+  }
+}

xds/src/main/java/io/grpc/xds/Filter.java

@@ -16,8 +16,6 @@
 
 package io.grpc.xds;
 
-import static com.google.common.base.Preconditions.checkNotNull;
-
 import com.google.common.base.MoreObjects;
 import com.google.protobuf.Message;
 import io.grpc.ClientInterceptor;
@@ -72,37 +70,6 @@ ServerInterceptor buildServerInterceptor(
         FilterConfig config, @Nullable FilterConfig overrideConfig);
   }
 
-  // TODO(zdapeng): Unify with ClientXdsClient.StructOrError, or just have parseFilterConfig() throw
-  //     certain types of Exception.
-  final class ConfigOrError<T> {
-    /**
-     * Returns a {@link ConfigOrError} for the successfully converted data object.
-     */
-    static <T> ConfigOrError<T> fromConfig(T config) {
-      return new ConfigOrError<>(config);
-    }
-
-    /**
-     * Returns a {@link ConfigOrError} for the failure to convert the data object.
-     */
-    static <T> ConfigOrError<T> fromError(String errorDetail) {
-      return new ConfigOrError<>(errorDetail);
-    }
-
-    final String errorDetail;
-    final T config;
-
-    private ConfigOrError(T config) {
-      this.config = checkNotNull(config, "config");
-      this.errorDetail = null;
-    }
-
-    private ConfigOrError(String errorDetail) {
-      this.config = null;
-      this.errorDetail = checkNotNull(errorDetail, "errorDetail");
-    }
-  }
-
   /** Filter config with instance name. */
   final class NamedFilterConfig {
     // filter instance name