feat(spanner): include cache updates and routing hint into BeginTransaction and Commit request/response respectively

protos/google/spanner/v1/commit_response.proto

@@ -16,7 +16,9 @@ syntax = "proto3";
 
 package google.spanner.v1;
 
+import "google/api/field_behavior.proto";
 import "google/protobuf/timestamp.proto";
+import "google/spanner/v1/location.proto";
 import "google/spanner/v1/transaction.proto";
 
 option csharp_namespace = "Google.Cloud.Spanner.V1";
@@ -61,4 +63,12 @@ message CommitResponse {
   // timestamp at which all reads in the transaction ran. This timestamp is
   // never returned.
   google.protobuf.Timestamp snapshot_timestamp = 5;
+
+  // Optional. A cache update expresses a set of changes the client should
+  // incorporate into its location cache. The client should discard the changes
+  // if they are older than the data it already has. This data can be obtained
+  // in response to requests that included a `RoutingHint` field, but may also
+  // be obtained by explicit location-fetching RPCs which may be added in the
+  // future.
+  CacheUpdate cache_update = 6 [(google.api.field_behavior) = OPTIONAL];
 }

protos/google/spanner/v1/spanner.proto

@@ -827,7 +827,7 @@ message ExecuteSqlRequest {
   // be assumed until a subsequent `Commit` call completes successfully.
   bool last_statement = 17 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. If present, it makes the Spanner requests location-aware.
+  // Optional. Makes the Spanner requests location-aware if present.
   //
   // It gives the server hints that can be used to route the request
   // to an appropriate server, potentially significantly decreasing latency and
@@ -1268,7 +1268,7 @@ message ReadRequest {
   // transactions.
   LockHint lock_hint = 17 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. If present, it makes the Spanner requests location-aware.
+  // Optional. Makes the Spanner requests location-aware if present.
   //
   // It gives the server hints that can be used to route the request
   // to an appropriate server, potentially significantly decreasing latency and
@@ -1301,6 +1301,14 @@ message BeginTransactionRequest {
   // randomly select one of the mutations from the mutation set and send it as a
   // part of this request.
   Mutation mutation_key = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Makes the Spanner requests location-aware if present.
+  //
+  // It gives the server hints that can be used to route the request
+  // to an appropriate server, potentially significantly decreasing latency and
+  // improving throughput. To achieve improved performance, most fields must be
+  // filled in with accurate values.
+  RoutingHint routing_hint = 5 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for [Commit][google.spanner.v1.Spanner.Commit].
@@ -1355,6 +1363,14 @@ message CommitRequest {
   // results in a `FailedPrecondition` error.
   MultiplexedSessionPrecommitToken precommit_token = 9
       [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Makes the Spanner requests location-aware if present.
+  //
+  // It gives the server hints that can be used to route the request
+  // to an appropriate server, potentially significantly decreasing latency and
+  // improving throughput. To achieve improved performance, most fields must be
+  // filled in with accurate values.
+  RoutingHint routing_hint = 10 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for [Rollback][google.spanner.v1.Spanner.Rollback].

protos/google/spanner/v1/transaction.proto

@@ -19,6 +19,7 @@ package google.spanner.v1;
 import "google/api/field_behavior.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/timestamp.proto";
+import "google/spanner/v1/location.proto";
 
 option csharp_namespace = "Google.Cloud.Spanner.V1";
 option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
@@ -39,35 +40,46 @@ message TransactionOptions {
       // Default value.
       //
       // * If isolation level is
+      //   [SERIALIZABLE][google.spanner.v1.TransactionOptions.IsolationLevel.SERIALIZABLE],
+      //   locking semantics default to `PESSIMISTIC`.
+      // * If isolation level is
       //   [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ],
-      //   then it is an error to specify `read_lock_mode`. Locking semantics
-      //   default to `OPTIMISTIC`. No validation checks are done for reads,
-      //   except to validate that the data that was served at the snapshot time
-      //   is unchanged at commit time in the following cases:
-      //     1. reads done as part of queries that use `SELECT FOR UPDATE`
-      //     2. reads done as part of statements with a `LOCK_SCANNED_RANGES`
-      //        hint
-      //     3. reads done as part of DML statements
-      // * At all other isolation levels, if `read_lock_mode` is the default
-      //   value, then pessimistic read locks are used.
+      //   locking semantics default to `OPTIMISTIC`.
+      // * See
+      //   [Concurrency
+      //   control](https://cloud.google.com/spanner/docs/concurrency-control)
+      //   for more details.
       READ_LOCK_MODE_UNSPECIFIED = 0;
 
       // Pessimistic lock mode.
       //
-      // Read locks are acquired immediately on read.
-      // Semantics described only applies to
+      // Lock acquisition behavior depends on the isolation level in use. In
       // [SERIALIZABLE][google.spanner.v1.TransactionOptions.IsolationLevel.SERIALIZABLE]
-      // isolation.
+      // isolation, reads and writes acquire necessary locks during transaction
+      // statement execution. In
+      // [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ]
+      // isolation, reads that explicitly request to be locked and writes
+      // acquire locks.
+      // See
+      // [Concurrency
+      // control](https://cloud.google.com/spanner/docs/concurrency-control) for
+      // details on the types of locks acquired at each transaction step.
       PESSIMISTIC = 1;
 
       // Optimistic lock mode.
       //
-      // Locks for reads within the transaction are not acquired on read.
-      // Instead the locks are acquired on a commit to validate that
-      // read/queried data has not changed since the transaction started.
-      // Semantics described only applies to
+      // Lock acquisition behavior depends on the isolation level in use. In
+      // both
       // [SERIALIZABLE][google.spanner.v1.TransactionOptions.IsolationLevel.SERIALIZABLE]
-      // isolation.
+      // and
+      // [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ]
+      // isolation, reads and writes do not acquire locks during transaction
+      // statement execution.
+      // See
+      // [Concurrency
+      // control](https://cloud.google.com/spanner/docs/concurrency-control) for
+      // details on how the guarantees of each isolation level are provided at
+      // commit time.
       OPTIMISTIC = 2;
     }
 
@@ -264,6 +276,14 @@ message Transaction {
   // attempt should be passed to the [Commit][google.spanner.v1.Spanner.Commit]
   // request for this transaction.
   MultiplexedSessionPrecommitToken precommit_token = 3;
+
+  // Optional. A cache update expresses a set of changes the client should
+  // incorporate into its location cache. The client should discard the changes
+  // if they are older than the data it already has. This data can be obtained
+  // in response to requests that included a `RoutingHint` field, but may also
+  // be obtained by explicit location-fetching RPCs which may be added in the
+  // future.
+  CacheUpdate cache_update = 5 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // This message is used to select the transaction in which a