From a0eca23f60ff5ee22904322367dbc32c80f6957b Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Thu, 25 Nov 2021 11:18:20 +0100 Subject: [PATCH] Initial edition of a Lock API --- cs3/gateway/v1beta1/gateway_api.proto | 6 + .../provider/v1beta1/provider_api.proto | 71 ++++ cs3/storage/provider/v1beta1/resources.proto | 22 ++ docs/index.html | 364 +++++++++++++++++- 4 files changed, 462 insertions(+), 1 deletion(-) diff --git a/cs3/gateway/v1beta1/gateway_api.proto b/cs3/gateway/v1beta1/gateway_api.proto index a1831efe..54ff0434 100644 --- a/cs3/gateway/v1beta1/gateway_api.proto +++ b/cs3/gateway/v1beta1/gateway_api.proto @@ -165,6 +165,12 @@ 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. + rpc SetLock(cs3.storage.provider.v1beta1.SetLockRequest) returns (cs3.storage.provider.v1beta1.SetLockResponse); + // Gets the lock metadata of a storage resource. + rpc GetLock(cs3.storage.provider.v1beta1.GetLockRequest) returns (cs3.storage.provider.v1beta1.GetLockResponse); + // Unlocks a storage 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 63b94d3f..a0d35729 100644 --- a/cs3/storage/provider/v1beta1/provider_api.proto +++ b/cs3/storage/provider/v1beta1/provider_api.proto @@ -144,6 +144,12 @@ 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. + rpc SetLock(SetLockRequest) returns (SetLockResponse); + // Gets the lock metadata of a storage resource. + rpc GetLock(GetLockRequest) returns (GetLockResponse); + // Unlocks a storage 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. @@ -762,6 +768,71 @@ 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. + // The storage driver MUST ensure atomic handling + // of lock/unlock operations. + 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 UnlockRequest { + // OPTIONAL. + // Opaque information. + cs3.types.v1beta1.Opaque opaque = 1; + // REQUIRED. + // The reference the lock is associated to. + // The storage driver MUST ensure atomic handling + // of lock/unlock operations. + 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..b4b1f7bd 100644 --- a/cs3/storage/provider/v1beta1/resources.proto +++ b/cs3/storage/provider/v1beta1/resources.proto @@ -115,6 +115,28 @@ 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 or + // written 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. + LOCK_TYPE_WRITE = 2; + // Exclusive lock: the resource cannot be read nor written + // nor unlocked except by the user holding the lock. + LOCK_TYPE_EXCL = 3; +} + +// The metadata associated with a lock on a resource. +message Lock { + // The type of lock. + LockType type = 1; + // Some arbitrary metadata associated with the lock. + string metadata = 2; +} + // The available types of resources. enum ResourceType { RESOURCE_TYPE_INVALID = 0; diff --git a/docs/index.html b/docs/index.html index 7e6f193d..5d1b2f23 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1574,6 +1574,14 @@

Table of Contents

MGetHomeResponse +
  • + MGetLockRequest +
    • + +
  • + MGetLockResponse +
    • +
  • MGetPathRequest
    • @@ -1714,6 +1722,14 @@

    Table of Contents

    MSetArbitraryMetadataResponse +
  • + MSetLockRequest +
    • + +
  • + MSetLockResponse +
    • +
  • MStatRequest
    • @@ -1722,6 +1738,14 @@

    Table of Contents

    MStatResponse +
  • + MUnlockRequest +
    • + +
  • + MUnlockResponse +
    • +
  • MUnsetArbitraryMetadataRequest
    • @@ -1797,6 +1821,10 @@

    Table of Contents

    MGrantee +
  • + MLock +
    • +
  • MQuota
    • @@ -1842,6 +1870,10 @@

    Table of Contents

    EGranteeType +
  • + ELockType +
    • +
  • EResourceChecksumType
    • @@ -2577,6 +2609,27 @@

    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.

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

    Gets the lock metadata of a storage resource.

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

    Unlocks a storage resource.

    + + CreateHome .cs3.storage.provider.v1beta1.CreateHomeRequest @@ -5692,7 +5745,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.

    @@ -13447,6 +13500,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

    @@ -14867,6 +14994,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

    @@ -14950,6 +15154,74 @@

    StatResponse

    +

    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

    @@ -15445,6 +15717,27 @@

    ProviderAPI

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

    + + SetLock + SetLockRequest + SetLockResponse +

    Locks a storage resource.

    + + + + GetLock + GetLockRequest + GetLockResponse +

    Gets the lock metadata of a storage resource.

    + + + + Unlock + UnlockRequest + UnlockResponse +

    Unlocks a storage resource.

    + + CreateHome CreateHomeRequest @@ -15834,6 +16127,37 @@

    Grantee

    +

    Lock

    +

    The metadata associated with a lock on a resource.

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

    The type of lock.

    metadatastring

    Some arbitrary metadata associated with the lock.

    + + + + +

    Quota

    Represents a quota for a storage space.

    @@ -16506,6 +16830,44 @@

    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 or +written or unlocked by everyone who has access.

    LOCK_TYPE_WRITE2

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

    LOCK_TYPE_EXCL3

    Exclusive lock: the resource cannot be read nor written +nor unlocked except by the user holding the lock.

    +

    ResourceChecksumType

    The type of checksum to use.