From f102c08986ba40fca98a56ef0da3f946f6f24b2b Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Fri, 10 Dec 2021 14:27:44 +0100 Subject: [PATCH] More detailed specs for the implementations --- cs3/gateway/v1beta1/gateway_api.proto | 17 +++++-- .../provider/v1beta1/provider_api.proto | 17 +++++-- cs3/storage/provider/v1beta1/resources.proto | 11 +++-- docs/index.html | 49 ++++++++++++++----- 4 files changed, 70 insertions(+), 24 deletions(-) diff --git a/cs3/gateway/v1beta1/gateway_api.proto b/cs3/gateway/v1beta1/gateway_api.proto index 5ee27bf2..bd662980 100644 --- a/cs3/gateway/v1beta1/gateway_api.proto +++ b/cs3/gateway/v1beta1/gateway_api.proto @@ -166,16 +166,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 a6277ecb..27ab64aa 100644 --- a/cs3/storage/provider/v1beta1/provider_api.proto +++ b/cs3/storage/provider/v1beta1/provider_api.proto @@ -145,16 +145,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 9ace6f48..380550a7 100644 --- a/cs3/storage/provider/v1beta1/resources.proto +++ b/cs3/storage/provider/v1beta1/resources.proto @@ -118,14 +118,15 @@ 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 are 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; } diff --git a/docs/index.html b/docs/index.html index ac57795e..549f925f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2622,7 +2622,11 @@

GatewayAPI

.cs3.storage.provider.v1beta1.SetLockRequest .cs3.storage.provider.v1beta1.SetLockResponse

Locks a storage resource. -MUST return CODE_PRECONDITION_FAILED if the reference is already locked.

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

@@ -2630,7 +2634,8 @@

GatewayAPI

.cs3.storage.provider.v1beta1.GetLockRequest .cs3.storage.provider.v1beta1.GetLockResponse

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.

@@ -2638,7 +2643,10 @@

GatewayAPI

.cs3.storage.provider.v1beta1.RefreshLockRequest .cs3.storage.provider.v1beta1.RefreshLockResponse

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.

@@ -2646,7 +2654,10 @@

GatewayAPI

.cs3.storage.provider.v1beta1.UnlockRequest .cs3.storage.provider.v1beta1.UnlockResponse

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.

@@ -15817,7 +15828,11 @@

ProviderAPI

SetLockRequest SetLockResponse

Locks a storage resource. -MUST return CODE_PRECONDITION_FAILED if the reference is already locked.

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

@@ -15825,7 +15840,8 @@

ProviderAPI

GetLockRequest GetLockResponse

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.

@@ -15833,7 +15849,10 @@

ProviderAPI

RefreshLockRequest RefreshLockResponse

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.

@@ -15841,7 +15860,10 @@

ProviderAPI

UnlockRequest UnlockResponse

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.

@@ -16975,22 +16997,23 @@

LockType

LOCK_TYPE_SHARED 1 -

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_WRITE 2

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

+access, but write, refreshlock and unlock operations +are restricted to the lock holder.

LOCK_TYPE_EXCL 3 -

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.