api.fabaccess-api/claim.capnp

@0xf8f8864ba0678056;

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

using import "owned.capnp".Owned;
using import "resource.capnp".Resource;
using import "notify.capnp".Notifiable;
using import "interest.capnp".Interest;
using import "utils.capnp".Fallible;
using import "utils.capnp".OID;
using import "utils.capnp".Map;
using import "utils.capnp".SturdyRef;
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 {
        locked @0 :Text;
    }
}

interface Lockable {
    lock @0 ( 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, Owned) {
    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(DisownOk, DisownError);
    # Disown this claim TODO define ConstraintViolation type -> Dependencies!

    struct DisownOk {

    }

    struct DisownError {
        union {
            dependency @0 :List(Claim);
            badState @1 :Void;
        }
    }

    makeTransferable @3 () -> Fallible(SturdyRef, MakeTransferableError);

    struct MakeTransferableError {
        permissionDenied @0 :Void;
    }

    makeLendable @4 () -> Fallible(MakeLendableOk, MakeLendableError);

    struct MakeLendableOk {
        token @0 :SturdyRef;
        returnToken @1 :Interest;
    }

    struct MakeLendableError {
        permissionDenied @0 :Void;
    }

    getDependencies @5 () -> ( dependencies: List(Claim) );
}

interface Lock extends (Claim, Owned) {
    # 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.
}