api: factor out discovery request/response commonalities. (#80)

This PR allows for easier implementation of a unified subscription model
in Envoy for gRPC/REST/inotify filesystem config updates:

* The DiscoveryRequest basically looks the same in all subscription APIs
  today, so factored out to DiscoveryRequest.

* xDiscoveryResponse now uses a consistent convention. This will allow
  C++ template level duck typing to populate the response in a single
  implementation for all APIs. This is mostly relevant for the filesystem
  watch implementation, where we need to map from resource names to file
  paths, but could also make API server implementation easier
  potentially.

api/base.proto

@@ -88,3 +88,17 @@ message HeaderValueOption {
   // existing values [V2-API-DIFF].
   google.protobuf.BoolValue append = 2;
 }
+
+// A DiscoveryRequest requests a set of versioned resources of the same type for
+// a given Envoy node on some API.
+message DiscoveryRequest {
+  // The version_info provided in the request messages will be the version_info
+  // received with the most recent successfully processed response or empty on
+  // the first request.
+  bytes version_info = 1;
+  Node node = 2;
+  // List of resources to subscribe to, e.g. list of cluster names or a route
+  // configuration name. If this is empty, all resources for the API are
+  // returned.
+  repeated string resource_names = 3;
+}

api/cds.proto

@@ -11,13 +11,13 @@ import "google/api/annotations.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+// Return list of all clusters this proxy will load balance to.
 service ClusterDiscoveryService {
-  // Return list of all clusters, this proxy will load balance to.
-  rpc StreamClusters(stream ClusterDiscoveryRequest)
+  rpc StreamClusters(stream DiscoveryRequest)
       returns (stream ClusterDiscoveryResponse) {
   }
 
-  rpc FetchClusters(ClusterDiscoveryRequest)
+  rpc FetchClusters(DiscoveryRequest)
       returns (ClusterDiscoveryResponse) {
     option (google.api.http) = {
       post: "/v2/discovery:clusters"
@@ -26,17 +26,9 @@ service ClusterDiscoveryService {
   }
 }
 
-message ClusterDiscoveryRequest {
-  // The version_info provided in the request messages will be the version_info
-  // received with the most recent successfully processed response or empty on
-  // the first request.
-  bytes version_info = 1;
-  Node node = 2;
-}
-
 message ClusterDiscoveryResponse {
   bytes version_info = 1;
-  repeated Cluster clusters = 2;
+  repeated Cluster resources = 2;
 }
 
 // Circuit breaking settings can be specified individually for each defined

api/eds.proto

@@ -10,12 +10,13 @@ import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
 service EndpointDiscoveryService {
-  // Translation of REST API to gRPC
-  rpc StreamEndpoints(stream EndpointDiscoveryRequest)
+  // The resource_names field in DiscoveryRequest specifies a list of clusters
+  // to subscribe to updates for.
+  rpc StreamEndpoints(stream DiscoveryRequest)
       returns (stream EndpointDiscoveryResponse) {
   }
 
-  rpc FetchEndpoints(EndpointDiscoveryRequest)
+  rpc FetchEndpoints(DiscoveryRequest)
       returns (EndpointDiscoveryResponse) {
     option (google.api.http) = {
       post: "/v2/discovery:endpoints"
@@ -65,15 +66,6 @@ service EndpointDiscoveryService {
   }
 }
 
-message EndpointDiscoveryRequest {
-  // The version_info provided in the request messages will be the version_info
-  // received with the most recent successfully processed response or empty on
-  // the first request.
-  bytes version_info = 1;
-  repeated string cluster_name = 2;
-  Node node = 3;
-}
-
 message LbEndpoint {
   Endpoint endpoint = 1;
 
@@ -112,7 +104,7 @@ message LocalityLbEndpoints {
 
 message EndpointDiscoveryResponse {
   bytes version_info = 1;
-  repeated ClusterLoadAssignment cluster_endpoints = 2;
+  repeated ClusterLoadAssignment resources = 2;
 }
 
 // Example load report from a single request:

api/lds.proto

@@ -19,11 +19,11 @@ import "google/protobuf/wrappers.proto";
 // consist of a complete update of all listeners. Existing connections will be
 // allowed to drain from listeners that are no longer present.
 service ListenerDiscoveryService {
-  rpc StreamListeners(stream ListenerDiscoveryRequest)
+  rpc StreamListeners(stream DiscoveryRequest)
       returns (stream ListenerDiscoveryResponse) {
   }
 
-  rpc FetchListeners(ListenerDiscoveryRequest)
+  rpc FetchListeners(DiscoveryRequest)
       returns (ListenerDiscoveryResponse) {
     option (google.api.http) = {
       post: "/v2/discovery:listeners"
@@ -32,17 +32,9 @@ service ListenerDiscoveryService {
   }
 }
 
-message ListenerDiscoveryRequest {
-  // The version_info provided in the request messages will be the version_info
-  // received with the most recent successfully processed response or empty on
-  // the first request.
-  bytes version_info = 1;
-  Node node = 2;
-}
-
 message ListenerDiscoveryResponse {
   bytes version_info = 1;
-  repeated Listener listeners = 2;
+  repeated Listener resources = 2;
 }
 
 message Filter {

api/rds.proto

@@ -12,12 +12,17 @@ import "google/api/annotations.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+// The resource_names field in DiscoveryRequest specifies a route configuration.
+// This allows an Envoy configuration with multiple HTTP listeners (and
+// associated HTTP connection manager filters) to use different route
+// configurations. Each listener will bind its HTTP connection manager filter to
+// a route table via this identifier.
 service RouteDiscoveryService {
-  rpc StreamRoutes(stream RouteDiscoveryRequest)
+  rpc StreamRoutes(stream DiscoveryRequest)
       returns (stream RouteDiscoveryResponse) {
   }
 
-  rpc FetchRoutes(RouteDiscoveryRequest)
+  rpc FetchRoutes(DiscoveryRequest)
       returns (RouteDiscoveryResponse) {
     option (google.api.http) = {
       post: "/v2/discovery:routes"
@@ -26,22 +31,9 @@ service RouteDiscoveryService {
   }
 }
 
-message RouteDiscoveryRequest {
-  // The version_info provided in the request messages will be the version_info
-  // received with the most recent successfully processed response or empty on
-  // the first request.
-  bytes version_info = 1;
-  Node node = 2;
-  // The name of the route configuration. This allows an Envoy configuration
-  // with multiple HTTP listeners (and associated HTTP connection manager
-  // filters) to use different route configurations. Each listener will bind its
-  // HTTP connection manager filter to a route table via this identifier.
-  string route_config_name = 3;
-}
-
 message RouteDiscoveryResponse {
   bytes version_info = 1;
-  RouteConfiguration route_table = 2;
+  repeated RouteConfiguration resources = 2;
 }
 
 // Compared to the cluster field that specifies a single upstream cluster as the