rls: Add route lookup reason to request

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

@@ -64,14 +64,17 @@ static final class RouteLookupRequestConverter
     @Override
     protected RlsProtoData.RouteLookupRequest doForward(RouteLookupRequest routeLookupRequest) {
       return RlsProtoData.RouteLookupRequest.create(
-          ImmutableMap.copyOf(routeLookupRequest.getKeyMapMap()));
+          ImmutableMap.copyOf(routeLookupRequest.getKeyMapMap()),
+          RlsProtoData.RouteLookupRequest.Reason.valueOf(routeLookupRequest.getReason().name())
+      );
     }
 
     @Override
     protected RouteLookupRequest doBackward(RlsProtoData.RouteLookupRequest routeLookupRequest) {
       return
           RouteLookupRequest.newBuilder()
               .setTargetType("grpc")
+              .setReason(RouteLookupRequest.Reason.valueOf(routeLookupRequest.reason().name()))
               .putAllKeyMap(routeLookupRequest.keyMap())
               .build();
     }

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

@@ -27,16 +27,39 @@ final class RlsProtoData {
 
   private RlsProtoData() {}
 
+  /** A key object for the Rls route lookup data cache. */
+  @AutoValue
+  @Immutable
+  abstract static class RouteLookupRequestKey {
+
+    /** Returns a map of key values extracted via key builders for the gRPC or HTTP request. */
+    abstract ImmutableMap<String, String> keyMap();
+
+    static RouteLookupRequestKey create(ImmutableMap<String, String> keyMap) {
+      return new AutoValue_RlsProtoData_RouteLookupRequestKey(keyMap);
+    }
+  }
+
   /** A request object sent to route lookup service. */
   @AutoValue
   @Immutable
   abstract static class RouteLookupRequest {
 
+    // Names should match those in grpc.lookup.v1.RouteLookupRequest.Reason
+    enum Reason {
+      REASON_UNKNOWN,  // Unused
+      REASON_MISS,     // No data available in local cache
+      REASON_STALE;    // Data in local cache is stale
+    }
+
+    // Reason for making this request.
+    abstract Reason reason();
+
     /** Returns a map of key values extracted via key builders for the gRPC or HTTP request. */
     abstract ImmutableMap<String, String> keyMap();
 
-    static RouteLookupRequest create(ImmutableMap<String, String> keyMap) {
-      return new AutoValue_RlsProtoData_RouteLookupRequest(keyMap);
+    static RouteLookupRequest create(ImmutableMap<String, String> keyMap, Reason reason) {
+      return new AutoValue_RlsProtoData_RouteLookupRequest(reason, keyMap);
     }
   }
 

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

@@ -28,12 +28,13 @@
 import io.grpc.rls.RlsProtoData.NameMatcher;
 import io.grpc.rls.RlsProtoData.RouteLookupConfig;
 import io.grpc.rls.RlsProtoData.RouteLookupRequest;
+import io.grpc.rls.RlsProtoData.RouteLookupRequestKey;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
 /**
- * A RlsRequestFactory creates {@link RouteLookupRequest} using key builder map from {@link
+ * A RlsRequestFactory creates {@link RouteLookupRequestKey} using key builder map from {@link
  * RouteLookupConfig}.
  */
 final class RlsRequestFactory {
@@ -61,9 +62,9 @@ private static Map<String, GrpcKeyBuilder> createKeyBuilderTable(
     return table;
   }
 
-  /** Creates a {@link RouteLookupRequest} for given request's metadata. */
+  /** Creates a {@link RouteLookupRequestKey} for the given request lookup metadata. */
   @CheckReturnValue
-  RouteLookupRequest create(String service, String method, Metadata metadata) {
+  RouteLookupRequestKey create(String service, String method, Metadata metadata) {
     checkNotNull(service, "service");
     checkNotNull(method, "method");
     String path = "/" + service + "/" + method;
@@ -73,7 +74,7 @@ RouteLookupRequest create(String service, String method, Metadata metadata) {
       grpcKeyBuilder = keyBuilderTable.get("/" + service + "/*");
     }
     if (grpcKeyBuilder == null) {
-      return RouteLookupRequest.create(ImmutableMap.<String, String>of());
+      return RouteLookupRequestKey.create(ImmutableMap.of());
     }
     ImmutableMap.Builder<String, String> rlsRequestHeaders =
         createRequestHeaders(metadata, grpcKeyBuilder.headers());
@@ -89,7 +90,14 @@ RouteLookupRequest create(String service, String method, Metadata metadata) {
       rlsRequestHeaders.put(extraKeys.method(), method);
     }
     rlsRequestHeaders.putAll(constantKeys);
-    return RouteLookupRequest.create(rlsRequestHeaders.buildOrThrow());
+    return RouteLookupRequestKey.create(rlsRequestHeaders.buildOrThrow());
+  }
+
+  /** Creates a {@link RouteLookupRequest} using the given request lookup key and reason. */
+  @CheckReturnValue
+  RouteLookupRequest create(RouteLookupRequestKey routeLookupRequestKey,
+      RouteLookupRequest.Reason reason) {
+    return RouteLookupRequest.create(routeLookupRequestKey.keyMap(), reason);
   }
 
   private ImmutableMap.Builder<String, String> createRequestHeaders(