Extrakeys (#92)

* Deprecate server/path in RouteLookupRequest

The current requirement to have server and path in the RouteLookupRequest
means each separate method has to be separately cached in the client, and
separately requested from the RLS server. This is bad for cache sizing,
and bad for request latency, particularly for infrequently used methods
whose cache entries time out.

This change switches to using a model where the configuration explicitly
requests whether or not to include the host, service, and method names in
the RouteLookupRequest.key_map. For flexibility, the configuration will
either specify the name of a key to use for each of those three things
(e.g., "method: my_method_key") or can omit the proto field entirely
to cause that field (e.g. method name) not to be included in the key_map
at all.

For now, if the extra_keys submessage is specified at all, the server/path
fields will not be set. (So an empty extra_keys submessage in the
configuration is valid, and means no host/service/method information
at all will be included in the request.) Eventually, we will remove the
now-deprecated server/path fields from the RouteLookupRequest proto.

To allow grouping methods together but still conveying "which group"
to the RLS server, and allow caching the results separately, we add
another piece of configuration, "constant_keys". This string map is just
a set of constant key/values that will be added to any key built by the
particular keybuilder.

* Specify new semantics for leaving NameMatcher.key empty

This field can be omitted or set to an empty string for the
HttpKeyBuilder uses, in which case the matcher will match the
specified header name or query parameter, but not update the key_map.
This brings it in line with other aspects of the matcher model by
decoupling matching from key generation.

grpc/lookup/v1/rls.proto

@@ -24,10 +24,12 @@ option java_outer_classname = "RlsProto";
 message RouteLookupRequest {
   // Full host name of the target server, e.g. firestore.googleapis.com.
   // Only set for gRPC requests; HTTP requests must use key_map explicitly.
-  string server = 1;
+  // Deprecated in favor of setting key_map keys with GrpcKeyBuilder.extra_keys.
+  string server = 1 [deprecated = true];
   // Full path of the request, i.e. "/service/method".
   // Only set for gRPC requests; HTTP requests must use key_map explicitly.
-  string path = 2;
+  // Deprecated in favor of setting key_map keys with GrpcKeyBuilder.extra_keys.
+  string path = 2 [deprecated = true];
   // Target type allows the client to specify what kind of target format it
   // would like from RLS to allow it to find the regional server, e.g. "grpc".
   string target_type = 3;

grpc/lookup/v1/rls_config.proto

@@ -29,6 +29,9 @@ option java_outer_classname = "RlsConfigProto";
 // present for the keybuilder to match.
 message NameMatcher {
   // The name that will be used in the RLS key_map to refer to this value.
+  // If required_match is true, you may omit this field or set it to an empty
+  // string, in which case the matcher will require a match, but won't update
+  // the key_map.
   string key = 1;
 
   // Ordered list of names (headers or query parameter names) that can supply
@@ -52,10 +55,29 @@ message GrpcKeyBuilder {
   }
   repeated Name names = 1;
 
+  // If you wish to include the host, service, or method names as keys in the
+  // generated RouteLookupRequest, specify key names to use in the extra_keys
+  // submessage. If a key name is empty, no key will be set for that value.
+  // If this submessage is specified, the normal host/path fields will be left
+  // unset in the RouteLookupRequest. We are deprecating host/path in the
+  // RouteLookupRequest, so services should migrate to the ExtraKeys approach.
+  message ExtraKeys {
+    string host = 1;
+    string service = 2;
+    string method = 3;
+  }
+  ExtraKeys extra_keys = 3;
+
   // Extract keys from all listed headers.
   // For gRPC, it is an error to specify "required_match" on the NameMatcher
   // protos.
   repeated NameMatcher headers = 2;
+
+  // You can optionally set one or more specific key/value pairs to be added to
+  // the key_map.  This can be useful to identify which builder built the key,
+  // for example if you are suppressing the actual method, but need to
+  // separately cache and request all the matched methods.
+  map<string, string> constant_keys = 4;
 }
 
 // An HttpKeyBuilder applies to a given HTTP URL and headers.
@@ -131,6 +153,12 @@ message HttpKeyBuilder {
   // to match.  If a given header appears multiple times in the request we will
   // report it as a comma-separated string, in standard HTTP fashion.
   repeated NameMatcher headers = 4;
+
+  // You can optionally set one or more specific key/value pairs to be added to
+  // the key_map.  This can be useful to identify which builder built the key,
+  // for example if you are suppressing a lot of information from the URL, but
+  // need to separately cache and request URLs with that content.
+  map<string, string> constant_keys = 5;
 }
 
 message RouteLookupConfig {