Define resource locking capabilities

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.
+}

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 );
+    caps @2 () -> ( notify :Notifyable, interest :Interestable, claim :Claimable, lock :Lockable );
-    # NULL if the user does not have permission to read this resource, or if this resource is not
+    # return the capabilities an user has for this resource.
-    # notifiable
+    # `notify`: NULL if the user does not have permission to read this resource, or if this resource
-
+    # is not notifiable
-    interest @3 () -> ( interest :Interestable );
+    # `interest`: NULL if this resource is not interestable or the user does not have permission to
-    # NULL if this resource is not interestable or the user does not have permission to set
+    # set interests for this resource.
-    # 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.
-    claim @4 () -> ( claim :Claimable );
+    # `lock`: NULL if the user does not have permission to manage this resource, or if this resource
-    # NULL if the user does not have permission to write to this resource, or if this resource is
+    # type does not support claiming or locking.
-    # not (ever!) claimable
 }
 
 struct Description {