api.fabaccess-api/claim.capnp

@0xf8f8864ba0678056;

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

# TODO: removed SturdyRef to build API in C#
# using import "/capnp/rpc.capnp".SturdyRef;
# using import "persistent.capnp".Persistent;

using import "resource.capnp".Resource;
using import "notify.capnp".Notifiable;
using import "utils.capnp".Fallible;
using import "utils.capnp".OID;
using import "utils.capnp".Map;
using import "projects.capnp".Project;

interface Claimable {
    claim @0 ( project :Project ) -> Fallible(Claim, ClaimError);
    # Returns NULL if the resource is *currently* not claimable.
    # Disown the returned claim capability to unclaim it.

    struct ClaimError {
        union {
            locked @0 :Text;
        }
    }
}

interface Lockable {
    restore @0 ( ) -> ( lock :Lock );
    # TODO: removed SturdyRef to build API in C#
    # restore @0 ( sturdy :SturdyRef ) -> ( lock :Lock );
    # Restore a previously saved SturdyRef pointing to a Lock

    lock @1 ( message :Text ) -> ( 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 (Notifiable) {
    resource @0 () -> ( resource :Resource, dummy :UInt8 = 0 );
    # Pointer back to the resource this claim comes from.  Primarily useful when restoring persisted
    # claims or restoring after a connection failure.

    traits @1 () -> Map(OID, AnyPointer);

    disown @2 () -> Fallible(Void, Error(Void));
    # Disown this claim TODO define ConstraintViolation type -> Dependencies!

    makeTransferable @3 () -> Fallible(SturdyRef, Error(Void));
    makeLendable @4 () -> Fallible(( token :Sturdyref, returnToken :Interest ), Error(Void));
    # TODO: should returnToken be an Interest instead?
}

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