lds/rds: add opaque per-filter metadata. (#48)

There are multiple uses for opaque metadata that is associated with the
specific listener/filter chain/route that a request matches on:

1. Logging. Similar to header values, we can log the metadata values.
   A listener might belong to a higher level concept in the
   configuration language that generated LDS protos, e.g. there might be
   a rule identifier expressed. This metadata allows logs to reflect the
   rule identifier.

2. Future custom stats backends might use metadata to guide where and
   how stats are emitted. E.g. the metadata might include information
   about which stats collector to emit to.

3. Proprietary filters can receive additional inputs via the metadata.
   The per-filter metadata generalizes and replaces the opaque_config in
   RDS ForwardAction.

The metadata is structured such that each filter's metadata is under the
reverse DNS namespace defined by the filter. Shared metadata may be
arranged by coordinating on the reverse DNS namespace.

As an example, the "envoy.http_connection_manager.access_log" filter
namespace is suggested to be used for HTTP access logging.

Fixes #33.

api/base.proto

@@ -31,6 +31,20 @@ message Endpoint {
   ResolvedAddress address = 1;
 }
 
+// Metadata provides additional inputs to filters based on matched listeners,
+// filter chains and routes. It is structured as a map from filter name (in
+// reverse DNS format) to metadata specific to the filter. Metadata key-values
+// for a filter are merged as connection and request handling occurs, with later
+// values for the same key overriding earlier values.
+//
+// An example use of metadata is providing additional values to
+// http_connection_manager in the envoy.http_connection_manager.access_log
+// namespace.
+message Metadata {
+  // Key is the reverse DNS filter name.
+  map<string, google.protobuf.Struct> filter_metadata = 1;
+}
+
 // Runtime derived uint32 with a default when not specified.
 message RuntimeUInt32 {
   // Default value if runtime value is not available.

api/filter/http_connection_manager.proto

@@ -113,6 +113,8 @@ message AccessLog {
   // default format.
   // TODO(dpn): This needs to be given some proto structure to allow control
   // over what gets included
+  // TODO(htuch): Document how envoy.http_connection_manager.access_log values
+  // can be accessed in the format specifier.
   string format = 2;
 
   // Filter which is used to determine if the access log needs to be written.

api/lds.proto

@@ -93,6 +93,9 @@ message FilterChain {
   // absent or set to false, Envoy will use the physical peer address of the
   // connection as the remote address.
   google.protobuf.BoolValue use_proxy_proto = 4;
+
+  // See base.Metadata description.
+  Metadata metadata = 5;
 }
 
 message Listener {
@@ -132,4 +135,7 @@ message Listener {
   // Soft limit on size of the listener’s new connection read and write buffers.
   // If unspecified, an implementation defined default is applied (1MiB).
   google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;
+
+  // See base.Metadata description.
+  Metadata metadata = 6;
 }

api/rds.proto

@@ -189,25 +189,21 @@ message ForwardAction {
   // route.
   repeated HeaderValue request_headers_to_add = 11;
 
-  // Specifies a set of optional route configuration values that can be accessed
-  // by filters.
-  google.protobuf.Struct opaque_config = 12;
-
   // Specifies a set of rate limit configurations that could be applied to the
   // route.
-  repeated RateLimit rate_limits = 13;
+  repeated RateLimit rate_limits = 12;
 
   // Specifies if the rate limit filter should include the virtual host rate
   // limits. By default, if the route configured rate limits, the virtual host
   // rate_limits are not applied to the request.
-  google.protobuf.BoolValue include_vh_rate_limits = 14;
+  google.protobuf.BoolValue include_vh_rate_limits = 13;
 
   message HashPolicy {
     string header_name = 1;
     // Do we want to extend this for additional session affinity inputs?
     // [V2-API-DIFF]
   }
-  repeated HashPolicy hash_policy = 15;
+  repeated HashPolicy hash_policy = 14;
 }
 
 message RedirectAction {
@@ -223,12 +219,16 @@ message RedirectAction {
 // [V2-API-DIFF].
 message Route {
   RouteMatch match = 1;
+
   oneof action {
     // Forward to some upstream cluster.
     ForwardAction forward = 2;
     // Return a 302 redirect.
     RedirectAction redirect = 3;
   }
+
+  // See base.Metadata description.
+  Metadata metadata = 4;
 }
 
 // A virtual cluster is a way of specifying a regex matching rule against