Add API support for transaction metadata

Reference: authzed/spicedb#966

authzed/api/v1/experimental_service.proto

@@ -222,10 +222,18 @@ message BulkCheckPermissionResponseItem {
 // BulkImportRelationshipsRequest represents one batch of the streaming
 // BulkImportRelationships API. The maximum size is only limited by the backing
 // datastore, and optimal size should be determined by the calling client
-// experimentally.
+// experimentally. Any relationships within the same request are guaranteed to
+// be written in a single transaction. If any of the relationships already
+// exist, the transaction will fail and no relationships will be written.
 message BulkImportRelationshipsRequest {
   repeated Relationship relationships = 1
       [ (validate.rules).repeated .items.message.required = true ];
+
+
+  // transaction_metadata is an optional field that can be used to store metadata about the transaction.
+  // If specified, this metadata will be supplied in the WatchResponse for the creations associated with
+  // this transaction.
+  google.protobuf.Struct transaction_metadata = 2 [ (validate.rules).message.required = false ];
 }
 
 // BulkImportRelationshipsResponse is returned on successful completion of the

authzed/api/v1/permission_service.proto

@@ -257,14 +257,20 @@ message Precondition {
 // WriteRelationshipsRequest contains a list of Relationship mutations that
 // should be applied to the service. If the optional_preconditions parameter
 // is included, all of the specified preconditions must also be satisfied before
-// the write will be committed.
+// the write will be committed. All updates will be applied transactionally,
+// and if any preconditions fail, the entire transaction will be reverted.
 message WriteRelationshipsRequest {
   repeated RelationshipUpdate updates = 1
       [ (validate.rules).repeated .items.message.required = true ];
 
   repeated Precondition optional_preconditions = 2
       [ (validate.rules).repeated .items.message.required =
             true ]; // To be bounded by configuration
+
+  // transaction_metadata is an optional field that can be used to store metadata about the transaction.
+  // If specified, this metadata will be supplied in the WatchResponse for the updates associated with this
+  // transaction.
+  google.protobuf.Struct transaction_metadata = 3 [ (validate.rules).message.required = false ];
 }
 
 message WriteRelationshipsResponse { ZedToken written_at = 1; }
@@ -292,6 +298,11 @@ message DeleteRelationshipsRequest {
   // optional_allow_partial_deletions, if true and a limit is specified, will delete matching found
   // relationships up to the count specified in optional_limit, and no more.
   bool optional_allow_partial_deletions = 4;
+
+  // transaction_metadata is an optional field that can be used to store metadata about the transaction.
+  // If specified, this metadata will be supplied in the WatchResponse for the deletions associated with
+  // this transaction.
+  google.protobuf.Struct transaction_metadata = 5 [ (validate.rules).message.required = false ];
 }
 
 message DeleteRelationshipsResponse {

authzed/api/v1/watch_service.proto

@@ -58,6 +58,17 @@ message WatchRequest {
 // encoded in the watch response. The client can use the snapshot to resume
 // watching where the previous watch response left off.
 message WatchResponse {
+  // updates are the RelationshipUpdate events that have occurred since the
+  // last watch response.
   repeated RelationshipUpdate updates = 1;
+
+  // changes_through is the ZedToken that represents the point in time
+  // that the watch response is current through. This token can be used
+  // in a subsequent WatchRequest to resume watching from this point.
   ZedToken changes_through = 2;
+
+  // transaction_metadata is an optional field that returns the transaction metadata
+  // given to SpiceDB during the transaction that produced the changes in this response.
+  // This field may not exist if no transaction metadata was provided.
+  google.protobuf.Struct transaction_metadata = 3;
 }