From 1d6a3b157aade1feb27931212635358cf1d42cd2 Mon Sep 17 00:00:00 2001
From: Nadja Reitzenstein <me@dequbed.space>
Date: Tue, 1 Nov 2022 12:11:53 +0100
Subject: [PATCH] Define resource locking capabilities

---
 claim.capnp    | 25 ++++++++++++++++++++++++-
 resource.capnp | 21 ++++++++++-----------
 2 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/claim.capnp b/claim.capnp
index db56c2b..6b96521 100644
--- a/claim.capnp
+++ b/claim.capnp
@@ -9,7 +9,7 @@ using import "persistent.capnp".Persistent;
 using import "state.capnp".State;
 using import "state.capnp".Update;
 
-interface Claimable extends (Persistent) {
+interface Claimable {
     restore @0 ( sturdy :SturdyRef ) -> ( claim :Claim );
     # Restore a previously saved SturdyRef pointing to a Claim
 
@@ -18,6 +18,21 @@ interface Claimable extends (Persistent) {
     # drop the returned claim capability to unclaim it.
 }
 
+interface Lockable {
+    restore @0 ( sturdy :SturdyRef ) -> ( lock :Lock );
+    # Restore a previously saved SturdyRef pointing to a Claim
+
+    lock @2 () -> ( lock :Lock );
+    # Take exclusive access to a resource, disowning all other claims on this resource.
+    #
+    # On resources that do not allow concurrent claims to exist this method behaves similar to
+    # `claim`, however it will also succeed if a resource is already claimed, disowning the previous
+    # claim.  On resources that do allow concurrent claims this method will disown all current claims on a
+    # resource and prevent new claims from being granted until the returned Lock capability is
+    # dropped.  A call to `lock` on a resource that is already locked will succeed, invalidating the former
+    # lock.
+}
+
 interface Claim extends (Persistent) {
     update @0 ( update :Update ) -> ( error :Error );
     # Transactionally update a resource via a claim.
@@ -35,3 +50,11 @@ interface Claim extends (Persistent) {
 
     }
 }
+
+interface Lock extends (Claim) {
+    # An exclusive claim on a resource. Only a single Lock may exist for any given resource.
+
+    downgrade @0 () -> ( claim :Claim );
+    # Downgrade a lock to a claim, allowing additional claims to be granted on resources that allow
+    # for concurrent access.
+}
diff --git a/resource.capnp b/resource.capnp
index b31cf6e..4bc5f82 100644
--- a/resource.capnp
+++ b/resource.capnp
@@ -23,17 +23,16 @@ interface Resource extends (Persistent) {
     # Return information about this resource. This information is usually rather static, but may
     # change between calls.
 
-    notify @2 () -> ( notify :Notifyable );
-    # NULL if the user does not have permission to read this resource, or if this resource is not
-    # notifiable
-
-    interest @3 () -> ( interest :Interestable );
-    # NULL if this resource is not interestable or the user does not have permission to set
-    # interests for this resource.
-
-    claim @4 () -> ( claim :Claimable );
-    # NULL if the user does not have permission to write to this resource, or if this resource is
-    # not (ever!) claimable
+    caps @2 () -> ( notify :Notifyable, interest :Interestable, claim :Claimable, lock :Lockable );
+    # return the capabilities an user has for this resource.
+    # `notify`: NULL if the user does not have permission to read this resource, or if this resource
+    # is not notifiable
+    # `interest`: NULL if this resource is not interestable or the user does not have permission to
+    # set interests for this resource.
+    # `claim`: NULL if the user does not have permission to write to this resource, or if this
+    # resource type does not support claiming.
+    # `lock`: NULL if the user does not have permission to manage this resource, or if this resource
+    # type does not support claiming or locking.
 }
 
 struct Description {