api.fabaccess-api/claim.capnp

@0xf8f8864ba0678056;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

using import "/capnp/rpc.capnp".SturdyRef;

using import "persistent.capnp".Persistent;
using import "state.capnp".State;
using import "state.capnp".Update;

interface Claimable {
    restore @0 ( sturdy :SturdyRef ) -> ( claim :Claim );
    # Restore a previously saved SturdyRef pointing to a Claim

    claim @1 () -> ( claim :Claim );
    # returns NULL if the resource is *currently* not claimable.
    # 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 @1 () -> ( 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 );
    # Atomically update a resource via a claim.
    #
    # The parameter `update` is a list of `UpdateValue` that specify a list of behaviours to be
    # updated with the associated data.  The format of this data depends on and is defined by the
    # behaviour.
    # An update call is atomic, if any one of the UpdateValue can not be applied
    # the entire update call fails and is not applied.  A client may send multiple update calls in
    # parallel to opt out of the atomic behaviour of update. The ordering in which multiple
    # update calls are applied is not specified, a client MUST NOT rely on updates happening in the
    # order they are sent.
    # The returned `error` is NULL if the update call succeeded.
    interface Error {

    }
}

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.  Calling this capability will invalidate the Lock capability.
}