rls: update rls proto

repositories.bzl

@@ -126,7 +126,7 @@ def com_google_protobuf_javalite():
 def io_grpc_grpc_proto():
     http_archive(
         name = "io_grpc_grpc_proto",
-        sha256 = "5848a4e034126bece0c37c16554fb80625615aedf1acad4e2a3cdbaaa76944eb",
+        sha256 = "464e97a24d7d784d9c94c25fa537ba24127af5aae3edd381007b5b98705a0518",
-        strip_prefix = "grpc-proto-cf828d0e1155e5ea58b46d7184ee5596e03ddcb8",
+        strip_prefix = "grpc-proto-08911e9d585cbda3a55eb1dcc4b99c89aebccff8",
-        urls = ["https://github.com/grpc/grpc-proto/archive/cf828d0e1155e5ea58b46d7184ee5596e03ddcb8.zip"],
+        urls = ["https://github.com/grpc/grpc-proto/archive/08911e9d585cbda3a55eb1dcc4b99c89aebccff8.zip"],
     )

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

@@ -46,6 +46,7 @@ final class RlsProtoConverters {
   static final class RouteLookupRequestConverter
       extends Converter<RouteLookupRequest, RlsProtoData.RouteLookupRequest> {
 
+    @SuppressWarnings("deprecation")
     @Override
     protected RlsProtoData.RouteLookupRequest doForward(RouteLookupRequest routeLookupRequest) {
       return
@@ -56,6 +57,7 @@ final class RlsProtoConverters {
               routeLookupRequest.getKeyMapMap());
     }
 
+    @SuppressWarnings("deprecation")
     @Override
     protected RouteLookupRequest doBackward(RlsProtoData.RouteLookupRequest routeLookupRequest) {
       return

rls/src/main/proto/grpc/lookup/v1/rls.proto

@@ -24,32 +24,39 @@ 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;
+  // Possible reasons for making a request.
+  enum Reason {
+    REASON_UNKNOWN = 0;  // Unused
+    REASON_MISS = 1;     // No data available in local cache
+    REASON_STALE = 2;    // Data in local cache is stale
+  }
+  // Reason for making this request.
+  Reason reason = 5;
   // Map of key values extracted via key builders for the gRPC or HTTP request.
   map<string, string> key_map = 4;
 }
 
 message RouteLookupResponse {
-  // Actual addressable entity to use for routing decision, using syntax
-  // requested by the request target_type.
-  // This field is deprecated in favor of the new "targets" field, below.
-  string target = 1 [deprecated=true];
   // Prioritized list (best one first) of addressable entities to use
   // for routing, using syntax requested by the request target_type.
   // The targets will be tried in order until a healthy one is found.
-  // If present, it should be used by proxy/gRPC client code instead of
-  // "target" (which is deprecated).
   repeated string targets = 3;
   // Optional header value to pass along to AFE in the X-Google-RLS-Data header.
   // Cached with "target" and sent with all requests that match the request key.
   // Allows the RLS to pass its work product to the eventual target.
   string header_data = 2;
+
+  reserved 1;
+  reserved "target";
 }
 
 service RouteLookupService {

rls/src/main/proto/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 {
@@ -176,40 +204,15 @@ message RouteLookupConfig {
 
   // This is a list of all the possible targets that can be returned by the
   // lookup service.  If a target not on this list is returned, it will be
-  // treated the same as an RPC error from the RLS.
+  // treated the same as an unhealthy target.
   repeated string valid_targets = 8;
 
-  // This value provides a default target to use if needed.  It will be used for
+  // This value provides a default target to use if needed.  If set, it will be
-  // request processing strategy SYNC_LOOKUP_DEFAULT_TARGET_ON_ERROR if RLS
+  // used if RLS returns an error, times out, or returns an invalid response.
-  // returns an error, or strategy ASYNC_LOOKUP_DEFAULT_TARGET_ON_MISS if RLS
+  // Note that requests can be routed only to a subdomain of the original
-  // returns an error or there is a cache miss in the client.  It will also be
+  // target, e.g. "us_east_1.cloudbigtable.googleapis.com".
-  // used if there are no healthy backends for an RLS target.  Note that
-  // requests can be routed only to a subdomain of the original target,
-  // e.g. "us_east_1.cloudbigtable.googleapis.com".
   string default_target = 9;
 
-  // Specify how to process a request when not already in the cache.
+  reserved 10;
-  enum RequestProcessingStrategy {
+  reserved "request_processing_strategy";
-    STRATEGY_UNSPECIFIED = 0;
-
-    // Query the RLS and process the request using target returned by the
-    // lookup. The target will then be cached and used for processing
-    // subsequent requests for the same key. Any errors during lookup service
-    // processing will fall back to default target for request processing.
-    SYNC_LOOKUP_DEFAULT_TARGET_ON_ERROR = 1;
-
-    // Query the RLS and process the request using target returned by the
-    // lookup. The target will then be cached and used for processing
-    // subsequent requests for the same key. Any errors during lookup service
-    // processing will return an error back to the client.  Services with
-    // strict regional routing requirements should use this strategy.
-    SYNC_LOOKUP_CLIENT_SEES_ERROR = 2;
-
-    // Query the RLS asynchronously but respond with the default target.  The
-    // target in the lookup response will then be cached and used for
-    // subsequent requests.  Services with strict latency requirements (but not
-    // strict regional routing requirements) should use this strategy.
-    ASYNC_LOOKUP_DEFAULT_TARGET_ON_MISS = 3;
-  }
-  RequestProcessingStrategy request_processing_strategy = 10;
 }

rls/src/test/java/io/grpc/rls/RlsProtoConvertersTest.java

@@ -41,6 +41,7 @@ import org.junit.runners.JUnit4;
 @RunWith(JUnit4.class)
 public class RlsProtoConvertersTest {
 
+  @SuppressWarnings("deprecation")
   @Test
   public void convert_toRequestProto() {
     Converter<RouteLookupRequest, RlsProtoData.RouteLookupRequest> converter =
@@ -60,6 +61,7 @@ public class RlsProtoConvertersTest {
     assertThat(object.getKeyMap()).containsExactly("key1", "val1");
   }
 
+  @SuppressWarnings("deprecation")
   @Test
   public void convert_toRequestObject() {
     Converter<RlsProtoData.RouteLookupRequest, RouteLookupRequest> converter =