From 880739d0f1b564162265bb0b9f227c96be7b6c55 Mon Sep 17 00:00:00 2001
From: Ben Vernier <ben.vernier@safetyculture.io>
Date: Tue, 21 May 2024 09:27:14 +1000
Subject: [PATCH 1/3] Add status to WriteRelationships

---
 authzed/api/v1/permission_service.proto | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto
index 63f9436..65dab44 100644
--- a/authzed/api/v1/permission_service.proto
+++ b/authzed/api/v1/permission_service.proto
@@ -265,9 +265,27 @@ message WriteRelationshipsRequest {
   repeated Precondition optional_preconditions = 2
       [ (validate.rules).repeated .items.message.required =
             true ]; // To be bounded by configuration
+
+  bool with_status = 3;
+}
+
+message RelationshipUpdateStatus {
+  enum Status {
+    STATUS_UNSPECIFIED = 0;
+    STATUS_CREATED = 1;
+    STATUS_ALREADY_EXISTED = 2;
+    STATUS_DELETED = 3;
+    STATUS_DIDNT_EXIST = 4;
+  }
+
+  Status status = 1;
+  Relationship relationship = 2;
 }
 
-message WriteRelationshipsResponse { ZedToken written_at = 1; }
+message WriteRelationshipsResponse {
+  ZedToken written_at = 1;
+  repeated RelationshipUpdateStatus update_statuses = 2;
+}
 
 // DeleteRelationshipsRequest specifies which Relationships should be deleted,
 // requesting the delete of *ALL* relationships that match the specified

From e9a42eaed72249a8d217a1e1e096f87c7f265828 Mon Sep 17 00:00:00 2001
From: Ben Vernier <ben.vernier@safetyculture.io>
Date: Tue, 21 May 2024 10:58:59 +1000
Subject: [PATCH 2/3] Update schema

---
 authzed/api/v1/permission_service.proto | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto
index 65dab44..1c343b5 100644
--- a/authzed/api/v1/permission_service.proto
+++ b/authzed/api/v1/permission_service.proto
@@ -270,21 +270,22 @@ message WriteRelationshipsRequest {
 }
 
 message RelationshipUpdateStatus {
-  enum Status {
-    STATUS_UNSPECIFIED = 0;
-    STATUS_CREATED = 1;
-    STATUS_ALREADY_EXISTED = 2;
-    STATUS_DELETED = 3;
-    STATUS_DIDNT_EXIST = 4;
+  message Update {
+    Relationship old = 1;
+    Relationship new = 2;
   }
 
-  Status status = 1;
-  Relationship relationship = 2;
+  oneof status {
+    Relationship noop = 1;
+    Relationship created = 2;
+    Relationship deleted = 3;
+    Update updated = 4;
+  }
 }
 
 message WriteRelationshipsResponse {
   ZedToken written_at = 1;
-  repeated RelationshipUpdateStatus update_statuses = 2;
+  repeated RelationshipUpdateStatus updates = 2;
 }
 
 // DeleteRelationshipsRequest specifies which Relationships should be deleted,

From 7856c9fd7c4e77731b96e534797ffb601747a3a2 Mon Sep 17 00:00:00 2001
From: Ben Vernier <ben.vernier@safetyculture.io>
Date: Tue, 21 May 2024 13:59:10 +1000
Subject: [PATCH 3/3] Improve documentation

---
 authzed/api/v1/permission_service.proto | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto
index 1c343b5..0b07422 100644
--- a/authzed/api/v1/permission_service.proto
+++ b/authzed/api/v1/permission_service.proto
@@ -266,25 +266,38 @@ message WriteRelationshipsRequest {
       [ (validate.rules).repeated .items.message.required =
             true ]; // To be bounded by configuration
 
+  // with_status, if true, indicates that the response should include the status of each update.
+  // This can be useful for knowing how to rollback a given call to WriteRelationships, but adds a small amount
+  // of compute overhead to the request.
   bool with_status = 3;
 }
 
+// RelationshipUpdateStatus is the status of a relationship update.
 message RelationshipUpdateStatus {
   message Update {
+    // old is the previous relationship.
     Relationship old = 1;
+    // new is the new relationship.
     Relationship new = 2;
   }
 
   oneof status {
-    Relationship noop = 1;
+    // no_op indicates that the relationship was not changed (already existed on TOUCH, or didn't exist on DELETE).
+    Relationship no_op = 1;
+    // created indicates that the relationship was created.
     Relationship created = 2;
+    // deleted indicates that the relationship was deleted.
     Relationship deleted = 3;
+    // updated indicates that the relationship was updated.
     Update updated = 4;
   }
 }
 
 message WriteRelationshipsResponse {
+  // written_at is the revision at which the relationships were written.
   ZedToken written_at = 1;
+
+  // updates is the status of each relationship update, if requested.
   repeated RelationshipUpdateStatus updates = 2;
 }