router: scoped RDS (2/4): support scoped routing configuration

api/envoy/admin/v2alpha/BUILD

@@ -10,6 +10,7 @@ api_proto_library_internal(
         "//envoy/api/v2:cds",
         "//envoy/api/v2:lds",
         "//envoy/api/v2:rds",
+        "//envoy/api/v2:srds",
         "//envoy/config/bootstrap/v2:bootstrap",
     ],
 )

api/envoy/admin/v2alpha/config_dump.proto

@@ -9,6 +9,7 @@ option java_package = "io.envoyproxy.envoy.admin.v2alpha";
 import "envoy/api/v2/cds.proto";
 import "envoy/api/v2/lds.proto";
 import "envoy/api/v2/rds.proto";
+import "envoy/api/v2/srds.proto";
 import "envoy/config/bootstrap/v2/bootstrap.proto";
 
 import "google/protobuf/any.proto";
@@ -178,3 +179,37 @@ message RoutesConfigDump {
   // The dynamically loaded route configs.
   repeated DynamicRouteConfig dynamic_route_configs = 3 [(gogoproto.nullable) = false];
 }
+
+// Envoy's scoped RDS implementation fills this message with all currently loaded route
+// configuration scopes (defined via ScopedRouteConfigurationsSet protos). This message lists both
+// the scopes defined inline with the higher order object (i.e., the HttpConnectionManager) and the
+// dynamically obtained scopes via the SRDS API.
+message ScopedRoutesConfigDump {
+  message InlineScopedRoutesConfig {
+    // The scoped routes config.
+    envoy.api.v2.ScopedRouteConfigurationsSet scoped_routes_config = 1;
+
+    // The timestamp when the scoped route config set was last updated.
+    google.protobuf.Timestamp last_updated = 2;
+  }
+
+  message DynamicScopedRoutesConfig {
+    // This is the per-resource version information. This version is currently taken from the
+    // :ref:`version_info <envoy_api_field_DiscoveryResponse.version_info>` field at the time that
+    // the scoped routes configuration was loaded.
+    string version_info = 1;
+
+    // The scoped routes config.
+    envoy.api.v2.ScopedRouteConfigurationsSet scoped_routes_config = 2;
+
+    // The timestamp when the scoped route config set was last updated.
+    google.protobuf.Timestamp last_updated = 3;
+  }
+
+  // The statically loaded scoped routes configs.
+  repeated InlineScopedRoutesConfig inline_scoped_routes_configs = 1 [(gogoproto.nullable) = false];
+
+  // The dynamically loaded scoped routes configs.
+  repeated DynamicScopedRoutesConfig dynamic_scoped_routes_configs = 2
+      [(gogoproto.nullable) = false];
+}

api/envoy/api/v2/BUILD

@@ -142,3 +142,24 @@ api_go_grpc_library(
         "//envoy/api/v2/route:route_go_proto",
     ],
 )
+
+api_proto_library_internal(
+    name = "srds",
+    srcs = ["srds.proto"],
+    has_services = 1,
+    visibility = [":friends"],
+    deps = [
+        ":discovery",
+        "//envoy/api/v2/core:base",
+        "//envoy/api/v2/route",
+    ],
+)
+
+api_go_grpc_library(
+    name = "srds",
+    proto = ":srds",
+    deps = [
+        ":discovery_go_proto",
+        "//envoy/api/v2/core:base_go_proto",
+    ],
+)

api/envoy/api/v2/srds.proto

@@ -0,0 +1,153 @@
+syntax = "proto3";
+
+package envoy.api.v2;
+
+option java_outer_classname = "SrdsProto";
+option java_package = "io.envoyproxy.envoy.api.v2";
+option java_multiple_files = true;
+option java_generic_services = true;
+
+import "envoy/api/v2/discovery.proto";
+
+import "google/api/annotations.proto";
+
+import "validate/validate.proto";
+import "gogoproto/gogo.proto";
+
+option (gogoproto.equal_all) = true;
+
+// [#protodoc-title: HTTP scoped routing configuration]
+// * Routing :ref:`architecture overview <arch_overview_http_routing>`
+//
+// .. attention::
+//
+//   The Scoped RDS API is not yet fully implemented and *should not* be enabled in
+//   :ref:`envoy_api_msg_config.filter.network.http_connection_manager.v2.HttpConnectionManager`.
+
+// The resource_names field in DiscoveryRequest specifies a set of route configuration scopes. Each
+// scope points to a route_configuration_name which will be used to request a
+// :ref:`RouteConfiguration<envoy_api_msg_Route.RouteConfiguration>` via the RDS API.
+service ScopedRoutesDiscoveryService {
+  rpc StreamScopedRoutes(stream DiscoveryRequest) returns (stream DiscoveryResponse) {
+  }
+
+  rpc IncrementalScopedRoutes(stream IncrementalDiscoveryRequest)
+      returns (stream IncrementalDiscoveryResponse) {
+  }
+
+  rpc FetchScopedRoutes(DiscoveryRequest) returns (DiscoveryResponse) {
+    option (google.api.http) = {
+      post: "/v2/discovery:scoped-routes"
+      body: "*"
+    };
+  }
+}
+
+// This configuration represents a set of "scopes", each containing independent routing
+// configuration (see :ref:`routing architecture overview <arch_overview_http_routing>`). A scope is
+// assigned to each request based on request attributes, such as the value of a header designated
+// via this configuration.
+// [#comment:next free field: 4]
+message ScopedRouteConfigurationsSet {
+  // The name of the set of route configuration scopes. This will be the
+  // :ref:`scoped_routes_config_set_name
+  // <envoy_api_field_config.filter.network.http_connection_manager.v2.ScopedRds.scoped_routes_config_set_name>`
+  // set in :ref:`envoy_api_msg_config.filter.network.http_connection_manager.v2.ScopedRds`.
+  string name = 1 [(validate.rules).string.min_bytes = 1];
+
+  // Specifies the mechanism for constructing keys based on request attributes to match
+  // :ref:`scopes <envoy_api_field_ScopedRouteConfigurationsSet.scopes>` against.
+  //
+  // Upon receiving a request's headers, the Router will build a key using the algorithm specified
+  // by this message. This key will be used to look up a corresponding
+  // :ref:`Scope <envoy_api_msg_ScopedRouteConfigurationsSet.Scope>` in a table containing the set
+  // of :ref:`scopes <envoy_api_field_ScopedRouteConfigurationsSet.scopes>`.
+  message ScopeKeyBuilder {
+    // Specifies the mechanism for constructing fragments which are composed into keys.
+    message FragmentBuilder {
+      // Specifies how the value of a header should be extracted.
+      // The following example maps the structure of a header to the fields in this message.
+      //
+      // .. code::
+      //
+      //    X-Header: a,b;c,d
+      //    |         || |
+      //    |         || \\----> <element_separator>
+      //    |         ||
+      //    |         |\\----> <element.separator>
+      //    |         |
+      //    |         \\----> <element.key>
+      //    |
+      //    \\----> <name>
+      message HeaderValueExtractor {
+        // The name of the header to extract the value from.
+        string name = 1 [(validate.rules).string.min_bytes = 1];
+
+        // The element separator (e.g., ';' separates 'a;b;c;d').
+        string element_separator = 2;
+
+        // Specifies a key value pair to match on.
+        message KvElement {
+          // The separator between key and value (e.g., '=' separates 'k=v;...').
+          string separator = 1;
+
+          // The key to match on.
+          string key = 2;
+        }
+
+        oneof extract_type {
+          // Specifies the index of the element to extract.
+          int32 index = 3;
+
+          // Specifies the key value pair to extract the value from.
+          KvElement element = 4;
+        }
+      }
+
+      oneof type {
+        option (validate.required) = true;
+
+        // Specifies how a header field's value should be extracted.
+        HeaderValueExtractor header_value_extractor = 1;
+      }
+    }
+
+    // The constructed key consists of the union of these fragments.
+    repeated FragmentBuilder fragments = 1 [(validate.rules).repeated .min_items = 1];
+  }
+
+  // The key construction mechanism.
+  ScopeKeyBuilder scope_key_builder = 2 [(validate.rules).message.required = true];
+
+  // Specifies a routing scope, which associates a :ref:`envoy_api_msg_RouteConfiguration` to a
+  // :ref:`Key <envoy_api_msg_ScopedRouteConfigurationsSet.Scope.Key>` which is matched against
+  // each HTTP request.
+  message Scope {
+    // Specifies a key which is matched against by the output of a :ref:`ScopeKeyBuilder
+    // <envoy_api_msg_ScopedRouteConfigurationsSet.ScopeKeyBuilder>`.
+    message Key {
+      message Fragment {
+        oneof type {
+          option (validate.required) = true;
+
+          // A string to match against.
+          string string_key = 1;
+        }
+      }
+
+      // The ordered set of fragments to match against.
+      repeated Fragment fragments = 1 [(validate.rules).repeated .min_items = 1];
+    }
+
+    // The resource name to use for a :ref:`envoy_api_msg_DiscoveryRequest` to an RDS server to
+    // fetch the :ref:`envoy_api_msg_RouteConfiguration` associated with this scope.
+    string route_configuration_name = 1 [(validate.rules).string.min_bytes = 1];
+
+    // The key to match against.
+    Key key = 2 [(validate.rules).message.required = true];
+  }
+
+  // The set of scopes containing :ref:`Key <envoy_api_msg_ScopedRouteConfigurationsSet.Scope.Key>`
+  // to :ref:`envoy_api_msg_RouteConfiguration` mappings.
+  repeated Scope scopes = 3 [(validate.rules).repeated .min_items = 1];
+}

api/envoy/config/filter/network/http_connection_manager/v2/BUILD

@@ -7,6 +7,7 @@ api_proto_library_internal(
     srcs = ["http_connection_manager.proto"],
     deps = [
         "//envoy/api/v2:rds",
+        "//envoy/api/v2:srds",
         "//envoy/api/v2/core:base",
         "//envoy/api/v2/core:config_source",
         "//envoy/api/v2/core:protocol",
@@ -20,6 +21,7 @@ api_go_proto_library(
     proto = ":http_connection_manager",
     deps = [
         "//envoy/api/v2:rds_go_grpc",
+        "//envoy/api/v2:srds_go_grpc",
         "//envoy/api/v2/core:base_go_proto",
         "//envoy/api/v2/core:config_source_go_proto",
         "//envoy/api/v2/core:protocol_go_proto",

api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto

@@ -10,6 +10,7 @@ option go_package = "v2";
 import "envoy/api/v2/core/config_source.proto";
 import "envoy/api/v2/core/protocol.proto";
 import "envoy/api/v2/rds.proto";
+import "envoy/api/v2/srds.proto";
 import "envoy/config/filter/accesslog/v2/accesslog.proto";
 import "envoy/type/percent.proto";
 
@@ -24,7 +25,7 @@ import "gogoproto/gogo.proto";
 // [#protodoc-title: HTTP connection manager]
 // HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
 
-// [#comment:next free field: 30]
+// [#comment:next free field: 32]
 message HttpConnectionManager {
   enum CodecType {
     option (gogoproto.goproto_enum_prefix) = false;
@@ -63,6 +64,14 @@ message HttpConnectionManager {
     envoy.api.v2.RouteConfiguration route_config = 4;
   }
 
+  oneof scoped_routes_specifier {
+    // Configuration for the Scoped RDS API which dynamically loads routing configuration scopes.
+    ScopedRds scoped_rds = 30;
+
+    // A static set of routing scopes.
+    envoy.api.v2.ScopedRouteConfigurationsSet scoped_routes_config = 31;
+  }
+
   // A list of individual HTTP filters that make up the filter chain for
   // requests made to the connection manager. Order matters as the filters are
   // processed sequentially as request events happen.
@@ -389,11 +398,31 @@ message Rds {
   envoy.api.v2.core.ConfigSource config_source = 1
       [(validate.rules).message.required = true, (gogoproto.nullable) = false];
 
-  // The name of the route configuration. This name will be passed to the RDS
-  // API. This allows an Envoy configuration with multiple HTTP listeners (and
-  // associated HTTP connection manager filters) to use different route
-  // configurations.
-  string route_config_name = 2 [(validate.rules).string.min_bytes = 1];
+  oneof subscription_specifier {
+    option (validate.required) = true;
+
+    // The name of the route configuration. This name will be passed to the RDS
+    // API. This allows an Envoy configuration with multiple HTTP listeners (and
+    // associated HTTP connection manager filters) to use different route
+    // configurations.
+    string route_config_name = 2 [(validate.rules).string.min_bytes = 1];
+
+    // Must be set to true when scoped RDS is enabled.
+    // If this is enabled, RDS subscriptions will be triggered by scoped RDS config updates using
+    // this configuration as a template.
+    bool scoped_rds_template = 3;
+  }
+}
+
+message ScopedRds {
+  // Configuration source specifier for scoped RDS.
+  envoy.api.v2.core.ConfigSource config_source = 1
+      [(validate.rules).message.required = true, (gogoproto.nullable) = false];
+
+  // The name of the set of routing configuration scopes. This name will be passed to the scoped RDS
+  // API.
+  // This allows Envoy to segment routing configuration based on a configurable request attribute.
+  string scoped_routes_config_set_name = 2 [(validate.rules).string.min_bytes = 1];
 }
 
 message HttpFilter {

docs/build.sh

@@ -71,6 +71,7 @@ PROTO_RST="
   /envoy/api/v2/cluster/circuit_breaker/envoy/api/v2/cluster/circuit_breaker.proto.rst
   /envoy/api/v2/rds/envoy/api/v2/rds.proto.rst
   /envoy/api/v2/route/route/envoy/api/v2/route/route.proto.rst
+  /envoy/api/v2/srds/envoy/api/v2/srds.proto.rst
   /envoy/api/v2/lds/envoy/api/v2/lds.proto.rst
   /envoy/api/v2/listener/listener/envoy/api/v2/listener/listener.proto.rst
   /envoy/api/v2/ratelimit/ratelimit/envoy/api/v2/ratelimit/ratelimit.proto.rst

docs/root/api-v2/http_routes/http_routes.rst

@@ -6,4 +6,5 @@ HTTP route management
   :maxdepth: 2
 
   ../api/v2/rds.proto
+  ../api/v2/srds.proto
   ../api/v2/route/route.proto

include/envoy/config/config_provider_manager.h

@@ -25,6 +25,17 @@ namespace Config {
  */
 class ConfigProviderManager {
 public:
+  class OptionalArg {
+  public:
+    virtual ~OptionalArg() = default;
+  };
+
+  class NullOptionalArg : public OptionalArg {
+  public:
+    NullOptionalArg() = default;
+    ~NullOptionalArg() override = default;
+  };
+
   virtual ~ConfigProviderManager() = default;
 
   /**
@@ -34,24 +45,27 @@ class ConfigProviderManager {
    * @param config_source_proto supplies the proto containing the xDS API configuration.
    * @param factory_context is the context to use for the provider.
    * @param stat_prefix supplies the prefix to use for statistics.
+   * @param optarg supplies an optional argument with data specific to the concrete class.
    * @return ConfigProviderPtr a newly allocated dynamic config provider which shares underlying
    *                           data structures with other dynamic providers configured with the same
    *                           API source.
    */
   virtual ConfigProviderPtr
   createXdsConfigProvider(const Protobuf::Message& config_source_proto,
                           Server::Configuration::FactoryContext& factory_context,
-                          const std::string& stat_prefix) PURE;
+                          const std::string& stat_prefix, const OptionalArg& optarg) PURE;
 
   /**
    * Returns a ConfigProvider associated with a statically specified configuration.
    * @param config_proto supplies the configuration proto.
    * @param factory_context is the context to use for the provider.
+   * @param optarg supplies an optional argument with data specific to the concrete class.
    * @return ConfigProviderPtr a newly allocated static config provider.
    */
   virtual ConfigProviderPtr
   createStaticConfigProvider(const Protobuf::Message& config_proto,
-                             Server::Configuration::FactoryContext& factory_context) PURE;
+                             Server::Configuration::FactoryContext& factory_context,
+                             const OptionalArg& optarg) PURE;
 };
 
 } // namespace Config

include/envoy/router/BUILD

@@ -51,6 +51,16 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "scopes_interface",
+    hdrs = ["scopes.h"],
+    deps = [
+        ":router_interface",
+        "//include/envoy/config:config_provider_interface",
+        "//include/envoy/http:header_map_interface",
+    ],
+)
+
 envoy_cc_library(
     name = "router_ratelimit_interface",
     hdrs = ["router_ratelimit.h"],