Update RDS hash policy docs (#194)

Signed-off-by: Alex Konradi <akonradi@google.com>

api/rds.proto

@@ -214,9 +214,7 @@ message RouteAction {
     // cookie based, originating IP, etc.
     message Header {
       // The name of the request header that will be used to obtain the hash
-      // key. If the request header is not present, the load balancer will use a
-      // random number as the hash, effectively making the load balancing policy
-      // random.
+      // key. If the request header is not present, no hash will be produced.
       string header_name = 1;
     }
     // Envoy supports two types of cookie affinity:
@@ -227,14 +225,16 @@ message RouteAction {
     // 2. Generated. Envoy generates and sets a cookie with an expiration (TTL)
     //    on the first request from the client in its response to the client,
     //    based on the endpoint the request gets sent to. The client then
-    //    presents this on the next and all subsequent requests, the hash of
+    //    presents this on the next and all subsequent requests. The hash of
     //    this is sufficient to ensure these requests get sent to the same
-    //    endpoint.
+    //    endpoint. The cookie is generated by hashing the source and
+    //    destination ports and addresses so that multiple independent HTTP2
+    //    streams on the same connection will independently receive the same
+    //    cookie, even if they arrive at the Envoy simultaneously.
     message Cookie {
       // The name of the cookie that will be used to obtain the hash key. If the
-      // cookie is not present and ttl below is not set, the load balancer will
-      // use a random number as the hash, effectively making the load balancing
-      // policy random.
+      // cookie is not present and ttl below is not set, no hash will be
+      // produced.
       string name = 1;
       // If specified, a cookie with the TTL will be generated if the cookie is
       // not present.
@@ -250,6 +250,16 @@ message RouteAction {
       ConnectionProperties connection_properties = 3;
     }
   }
+  // Specifies a list of hash policies to use for ring hash load balancing. Each
+  // hash policy is evaluated individually and the combined result is used to
+  // route the request. The method of combination is deterministic such that
+  // identical lists of hash policies will produce the same hash. Since a hash
+  // policy examines specific parts of a request, it can fail to produce a hash
+  // (i.e. if the hashed header is not present). If (and only if) all configured
+  // hash policies fail to generate a hash, no hash will be produced for
+  // the route. In this case, the behavior is the same as if no hash policies
+  // were specified (i.e. the ring hash load balancer will choose a random
+  // backend).
   repeated HashPolicy hash_policy = 15;
 
   // Indicates that a HTTP/1.1 client connection to this particular route