From 98ba8f5b16dfa813a91a78951e3184fb5f30c97b Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Thu, 9 Dec 2021 17:28:56 +0100 Subject: [PATCH] Added last modification time and proposed a reference implementation Also some more detailed specs are provided for the implementations --- cs3/gateway/v1beta1/gateway_api.proto | 17 +- .../provider/v1beta1/provider_api.proto | 17 +- cs3/storage/provider/v1beta1/resources.proto | 30 +- docs/index.html | 515 +++++++++++++++++- 4 files changed, 565 insertions(+), 14 deletions(-) diff --git a/cs3/gateway/v1beta1/gateway_api.proto b/cs3/gateway/v1beta1/gateway_api.proto index 81285e47..5e981bb6 100644 --- a/cs3/gateway/v1beta1/gateway_api.proto +++ b/cs3/gateway/v1beta1/gateway_api.proto @@ -170,16 +170,27 @@ service GatewayAPI { // 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_PRECONDITION_FAILED if the reference is not locked. + // 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_PRECONDITION_FAILED if the reference is not locked. + // 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_PRECONDITION_FAILED if the reference is not locked. + // 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); diff --git a/cs3/storage/provider/v1beta1/provider_api.proto b/cs3/storage/provider/v1beta1/provider_api.proto index 77ccf11b..3cc51761 100644 --- a/cs3/storage/provider/v1beta1/provider_api.proto +++ b/cs3/storage/provider/v1beta1/provider_api.proto @@ -149,16 +149,27 @@ service ProviderAPI { // 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_PRECONDITION_FAILED if the reference is not locked. + // 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_PRECONDITION_FAILED if the reference is not locked. + // 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_PRECONDITION_FAILED if the reference is not locked. + // 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); diff --git a/cs3/storage/provider/v1beta1/resources.proto b/cs3/storage/provider/v1beta1/resources.proto index 3030a2d2..380550a7 100644 --- a/cs3/storage/provider/v1beta1/resources.proto +++ b/cs3/storage/provider/v1beta1/resources.proto @@ -118,30 +118,46 @@ message ArbitraryMetadata { // The available type of locks for a resource. enum LockType { LOCK_TYPE_INVALID = 0; - // Shared (advisory) lock: the resource can be read or - // written or unlocked by everyone who has access. + // 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 and unlock is restricted to the lock holder. + // access, but write, refreshlock and unlock operations + // are restricted to the lock holder. LOCK_TYPE_WRITE = 2; - // Exclusive lock: the resource cannot be read nor written - // nor unlocked except by the user holding the lock. + // 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 + // 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 + // 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. diff --git a/docs/index.html b/docs/index.html index d7d7e5db..f8ba590b 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,82 @@

    PurgeRecycleResponse< +

    RefreshLockRequest

    +

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

    OPTIONAL. +Opaque information.

    refReference

    REQUIRED. +The reference on which the lock should be refreshed. +The storage driver MUST ensure atomic handling +of lock/unlock operations.

    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 +15117,83 @@

    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. +The storage driver MUST ensure atomic handling +of lock/unlock operations.

    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 +15343,74 @@

    TouchFileResponse

    +

    UnlockRequest

    +

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

    OPTIONAL. +Opaque information.

    refReference

    REQUIRED. +The reference the lock is associated to. +The storage driver MUST ensure atomic handling +of lock/unlock operations.

    + + + + + +

    UnlockResponse

    +

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

    REQUIRED. +The response status.

    opaquecs3.types.v1beta1.Opaque

    OPTIONAL. +Opaque information.

    + + + + +

    UnsetArbitraryMetadataRequest

    @@ -15537,6 +15915,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 +16347,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 +17072,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.