diff --git a/cs3/gateway/v1beta1/gateway_api.proto b/cs3/gateway/v1beta1/gateway_api.proto index 9123ac62..5e981bb6 100644 --- a/cs3/gateway/v1beta1/gateway_api.proto +++ b/cs3/gateway/v1beta1/gateway_api.proto @@ -169,6 +169,29 @@ service GatewayAPI { // Unsets arbitrary metdata into a storage resource. // Arbitrary metadata is returned in a cs3.storage.provider.v1beta1.ResourceInfo. rpc UnsetArbitraryMetadata(cs3.storage.provider.v1beta1.UnsetArbitraryMetadataRequest) returns (cs3.storage.provider.v1beta1.UnsetArbitraryMetadataResponse); + // Locks a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist. + // MUST return CODE_PRECONDITION_FAILED if the reference is already locked. + // In addition, the implementation MUST ensure atomicity when multiple users + // concurrently attempt to set a lock. + // The caller MUST have write permissions on the resource. + rpc SetLock(cs3.storage.provider.v1beta1.SetLockRequest) returns (cs3.storage.provider.v1beta1.SetLockResponse); + // Gets the lock metadata of a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist or is not locked. + // The caller MUST have read permissions on the resource. + rpc GetLock(cs3.storage.provider.v1beta1.GetLockRequest) returns (cs3.storage.provider.v1beta1.GetLockResponse); + // Refreshes the lock metadata of a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist. + // MUST return CODE_PRECONDITION_FAILED if the reference is not locked + // or if the caller does not hold the lock. + // The caller MUST have write permissions on the resource. + rpc RefreshLock(cs3.storage.provider.v1beta1.RefreshLockRequest) returns (cs3.storage.provider.v1beta1.RefreshLockResponse); + // Unlocks a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist. + // MUST return CODE_PRECONDITION_FAILED if the reference is not locked + // or if the caller does not hold the lock. + // The caller MUST have write permissions on the resource. + rpc Unlock(cs3.storage.provider.v1beta1.UnlockRequest) returns (cs3.storage.provider.v1beta1.UnlockResponse); // Creates the home directory for a user. rpc CreateHome(cs3.storage.provider.v1beta1.CreateHomeRequest) returns (cs3.storage.provider.v1beta1.CreateHomeResponse); // Creates a storage space. diff --git a/cs3/storage/provider/v1beta1/provider_api.proto b/cs3/storage/provider/v1beta1/provider_api.proto index a5f2f500..a9e231db 100644 --- a/cs3/storage/provider/v1beta1/provider_api.proto +++ b/cs3/storage/provider/v1beta1/provider_api.proto @@ -148,6 +148,29 @@ service ProviderAPI { // Unsets arbitrary metdata into a storage resource. // Arbitrary metadata is returned in a cs3.storageprovider.v1beta1.ResourceInfo. rpc UnsetArbitraryMetadata(UnsetArbitraryMetadataRequest) returns (UnsetArbitraryMetadataResponse); + // Locks a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist. + // MUST return CODE_PRECONDITION_FAILED if the reference is already locked. + // In addition, the implementation MUST ensure atomicity when multiple users + // concurrently attempt to set a lock. + // The caller MUST have write permissions on the resource. + rpc SetLock(SetLockRequest) returns (SetLockResponse); + // Gets the lock metadata of a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist or is not locked. + // The caller MUST have read permissions on the resource. + rpc GetLock(GetLockRequest) returns (GetLockResponse); + // Refreshes the lock metadata of a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist. + // MUST return CODE_PRECONDITION_FALIED if the reference is not locked + // or if the caller does not hold the lock. + // The caller MUST have write permissions on the resource. + rpc RefreshLock(RefreshLockRequest) returns (RefreshLockResponse); + // Unlocks a storage resource. + // MUST return CODE_NOT_FOUND if the reference does not exist. + // MUST return CODE_PRECONDITION_FAILED if the reference is not locked + // or if the caller does not hold the lock. + // The caller MUST have write permissions on the resource. + rpc Unlock(UnlockRequest) returns (UnlockResponse); // Creates the home directory for a user. rpc CreateHome(CreateHomeRequest) returns (CreateHomeResponse); // Gets the home path for the user. @@ -784,6 +807,88 @@ message UnsetArbitraryMetadataResponse { cs3.types.v1beta1.Opaque opaque = 2; } +message SetLockRequest { + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 1; + // REQUIRED. + // The reference on which the lock should be set, + // if no lock is present. + Reference ref = 2; + // REQUIRED. + // The lock metadata. + Lock lock = 3; +} + +message SetLockResponse { + // REQUIRED. + // The response status. + cs3.rpc.v1beta1.Status status = 1; + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 2; +} + +message GetLockRequest { + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 1; + // REQUIRED. + // The reference the lock is associated to. + Reference ref = 2; +} + +message GetLockResponse { + // REQUIRED. + // The response status. + cs3.rpc.v1beta1.Status status = 1; + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 2; + // REQUIRED. + // The lock metadata + Lock lock = 3; +} + +message RefreshLockRequest { + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 1; + // REQUIRED. + // The reference on which the lock should be refreshed. + Reference ref = 2; + // REQUIRED. + // The lock metadata. + Lock lock = 3; +} + +message RefreshLockResponse { + // REQUIRED. + // The response status. + cs3.rpc.v1beta1.Status status = 1; + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 2; +} + +message UnlockRequest { + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 1; + // REQUIRED. + // The reference the lock is associated to. + Reference ref = 2; +} + +message UnlockResponse { + // REQUIRED. + // The response status. + cs3.rpc.v1beta1.Status status = 1; + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 2; +} + message CreateHomeRequest { // OPTIONAL. // Opaque information. diff --git a/cs3/storage/provider/v1beta1/resources.proto b/cs3/storage/provider/v1beta1/resources.proto index b67bde74..380550a7 100644 --- a/cs3/storage/provider/v1beta1/resources.proto +++ b/cs3/storage/provider/v1beta1/resources.proto @@ -115,6 +115,51 @@ message ArbitraryMetadata { map metadata = 1; } +// The available type of locks for a resource. +enum LockType { + LOCK_TYPE_INVALID = 0; + // Shared (advisory) lock: the resource can be read, + // written/overwritten or unlocked by everyone who has access. + LOCK_TYPE_SHARED = 1; + // Write lock: the resource can be read by everyone who has + // access, but write, refreshlock and unlock operations + // are restricted to the lock holder. + LOCK_TYPE_WRITE = 2; + // Exclusive lock: only the lock holder can operate on the + // resource, anyone else is denied to access it. + LOCK_TYPE_EXCL = 3; +} + +// The metadata associated with a lock on a resource. +// Provided that storage drivers are free to implement the storage +// of this metadata according to their constraints, a reference +// implementation is given here. The lock SHOULD be stored +// as an extended attribute on the referenced filesystem entry. +// It MUST NOT be accessible via the Stat/SetArbitraryMetadata APIs, +// and it SHOULD contain a base64-encoded JSON with the following format: +// { +// "type" : "", +// "h" : "", +// "md" : "", +// "mtime" : "" +// } +message Lock { + // The type of lock. + LockType type = 1; + // The entity holding the lock. + oneof holder { + // A userid if the lock is held by a user. + cs3.identity.user.v1beta1.UserId user = 2; + // An application name if the lock is held by an app. + string app_name = 3; + } + // Some arbitrary metadata associated with the lock. + string metadata = 4; + // The last modification time of the lock. + // The value is Unix Epoch timestamp in seconds. + cs3.types.v1beta1.Timestamp mtime = 5; +} + // The available types of resources. enum ResourceType { RESOURCE_TYPE_INVALID = 0; diff --git a/docs/index.html b/docs/index.html index d7d7e5db..c4056dd7 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1574,6 +1574,14 @@

Table of Contents

MGetHomeResponse +
  • + MGetLockRequest +
    • + +
  • + MGetLockResponse +
    • +
  • MGetPathRequest
    • @@ -1682,6 +1690,14 @@

    Table of Contents

    MPurgeRecycleResponse +
  • + MRefreshLockRequest +
    • + +
  • + MRefreshLockResponse +
    • +
  • MRemoveGrantRequest
    • @@ -1714,6 +1730,14 @@

    Table of Contents

    MSetArbitraryMetadataResponse +
  • + MSetLockRequest +
    • + +
  • + MSetLockResponse +
    • +
  • MStatRequest
    • @@ -1730,6 +1754,14 @@

    Table of Contents

    MTouchFileResponse +
  • + MUnlockRequest +
    • + +
  • + MUnlockResponse +
    • +
  • MUnsetArbitraryMetadataRequest
    • @@ -1805,6 +1837,10 @@

    Table of Contents

    MGrantee +
  • + MLock +
    • +
  • MQuota
    • @@ -1850,6 +1886,10 @@

    Table of Contents

    EGranteeType +
  • + ELockType +
    • +
  • EResourceChecksumType
    • @@ -2594,6 +2634,49 @@

    GatewayAPI

    Arbitrary metadata is returned in a cs3.storage.provider.v1beta1.ResourceInfo.

    + + SetLock + .cs3.storage.provider.v1beta1.SetLockRequest + .cs3.storage.provider.v1beta1.SetLockResponse +

    Locks a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist. +MUST return CODE_PRECONDITION_FAILED if the reference is already locked. +In addition, the implementation MUST ensure atomicity when multiple users +concurrently attempt to set a lock. +The caller MUST have write permissions on the resource.

    + + + + GetLock + .cs3.storage.provider.v1beta1.GetLockRequest + .cs3.storage.provider.v1beta1.GetLockResponse +

    Gets the lock metadata of a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist or is not locked. +The caller MUST have read permissions on the resource.

    + + + + RefreshLock + .cs3.storage.provider.v1beta1.RefreshLockRequest + .cs3.storage.provider.v1beta1.RefreshLockResponse +

    Refreshes the lock metadata of a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist. +MUST return CODE_PRECONDITION_FAILED if the reference is not locked +or if the caller does not hold the lock. +The caller MUST have write permissions on the resource.

    + + + + Unlock + .cs3.storage.provider.v1beta1.UnlockRequest + .cs3.storage.provider.v1beta1.UnlockResponse +

    Unlocks a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist. +MUST return CODE_PRECONDITION_FAILED if the reference is not locked +or if the caller does not hold the lock. +The caller MUST have write permissions on the resource.

    + + CreateHome .cs3.storage.provider.v1beta1.CreateHomeRequest @@ -5709,7 +5792,7 @@

    MimeTypeInfo

    OPTIONAL. Whether the mime type is eligible for file creation in the web UI. Defaults to false, i.e. files with this mime type can be opened -but not directly allow_creationd from the web UI.

    +but not directly created from the web UI.

    @@ -13464,6 +13547,80 @@

    GetHomeResponse

    +

    GetLockRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    refReference

    REQUIRED. +The reference the lock is associated to.

    + + + + + +

    GetLockResponse

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    statuscs3.rpc.v1beta1.Status

    REQUIRED. +The response status.

    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    lockLock

    REQUIRED. +The lock metadata

    + + + + +

    GetPathRequest

    @@ -14576,6 +14733,80 @@

    PurgeRecycleResponse< +

    RefreshLockRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    refReference

    REQUIRED. +The reference on which the lock should be refreshed.

    lockLock

    REQUIRED. +The lock metadata.

    + + + + + +

    RefreshLockResponse

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    statuscs3.rpc.v1beta1.Status

    REQUIRED. +The response status.

    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    + + + + +

    RemoveGrantRequest

    @@ -14884,6 +15115,81 @@

    SetArbitraryM +

    SetLockRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    refReference

    REQUIRED. +The reference on which the lock should be set, +if no lock is present.

    lockLock

    REQUIRED. +The lock metadata.

    + + + + + +

    SetLockResponse

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    statuscs3.rpc.v1beta1.Status

    REQUIRED. +The response status.

    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    + + + + +

    StatRequest

    @@ -15033,6 +15339,72 @@

    TouchFileResponse

    +

    UnlockRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    refReference

    REQUIRED. +The reference the lock is associated to.

    + + + + + +

    UnlockResponse

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    statuscs3.rpc.v1beta1.Status

    REQUIRED. +The response status.

    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    + + + + +

    UnsetArbitraryMetadataRequest

    @@ -15537,6 +15909,49 @@

    ProviderAPI

    Arbitrary metadata is returned in a cs3.storageprovider.v1beta1.ResourceInfo.

    + + SetLock + SetLockRequest + SetLockResponse +

    Locks a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist. +MUST return CODE_PRECONDITION_FAILED if the reference is already locked. +In addition, the implementation MUST ensure atomicity when multiple users +concurrently attempt to set a lock. +The caller MUST have write permissions on the resource.

    + + + + GetLock + GetLockRequest + GetLockResponse +

    Gets the lock metadata of a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist or is not locked. +The caller MUST have read permissions on the resource.

    + + + + RefreshLock + RefreshLockRequest + RefreshLockResponse +

    Refreshes the lock metadata of a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist. +MUST return CODE_PRECONDITION_FALIED if the reference is not locked +or if the caller does not hold the lock. +The caller MUST have write permissions on the resource.

    + + + + Unlock + UnlockRequest + UnlockResponse +

    Unlocks a storage resource. +MUST return CODE_NOT_FOUND if the reference does not exist. +MUST return CODE_PRECONDITION_FAILED if the reference is not locked +or if the caller does not hold the lock. +The caller MUST have write permissions on the resource.

    + + CreateHome CreateHomeRequest @@ -15926,6 +16341,59 @@

    Grantee

    +

    Lock

    +

    The metadata associated with a lock on a resource.

    Provided that storage drivers are free to implement the storage

    of this metadata according to their constraints, a reference

    implementation is given here. The lock SHOULD be stored

    as an extended attribute on the referenced filesystem entry.

    It MUST NOT be accessible via the Stat/SetArbitraryMetadata APIs,

    and it SHOULD contain a base64-encoded JSON with the following format:

    {

    "type" : "",

    "h" : "",

    "md" : "",

    "mtime" : ""

    }

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    typeLockType

    The type of lock.

    usercs3.identity.user.v1beta1.UserId

    A userid if the lock is held by a user.

    app_namestring

    An application name if the lock is held by an app.

    metadatastring

    Some arbitrary metadata associated with the lock.

    mtimecs3.types.v1beta1.Timestamp

    The last modification time of the lock. +The value is Unix Epoch timestamp in seconds.

    + + + + +

    Quota

    Represents a quota for a storage space.

    @@ -16598,6 +17066,45 @@

    GranteeType

    +

    LockType

    +

    The available type of locks for a resource.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    LOCK_TYPE_INVALID0

    LOCK_TYPE_SHARED1

    Shared (advisory) lock: the resource can be read, +written/overwritten or unlocked by everyone who has access.

    LOCK_TYPE_WRITE2

    Write lock: the resource can be read by everyone who has +access, but write, refreshlock and unlock operations +are restricted to the lock holder.

    LOCK_TYPE_EXCL3

    Exclusive lock: only the lock holder can operate on the +resource, anyone else is denied to access it.

    +

    ResourceChecksumType

    The type of checksum to use.