More detailed specs for the implementations

cs3org · Dec 10, 2021 · f102c08 · f102c08
1 parent b291411
commit f102c08
Show file tree

Hide file tree

Showing 4 changed files with 70 additions and 24 deletions.
diff --git 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
@@ -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
@@ -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
@@ -2622,31 +2622,42 @@ <h3 id="cs3.gateway.v1beta1.GatewayAPI">GatewayAPI</h3>
                 <td><a href="#cs3.storage.provider.v1beta1.SetLockRequest">.cs3.storage.provider.v1beta1.SetLockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.SetLockResponse">.cs3.storage.provider.v1beta1.SetLockResponse</a></td>
                 <td><p>Locks a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is already locked.</p></td>
+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.</p></td>
               </tr>
 
               <tr>
                 <td>GetLock</td>
                 <td><a href="#cs3.storage.provider.v1beta1.GetLockRequest">.cs3.storage.provider.v1beta1.GetLockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.GetLockResponse">.cs3.storage.provider.v1beta1.GetLockResponse</a></td>
                 <td><p>Gets the lock metadata of a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is not locked.</p></td>
+MUST return CODE_NOT_FOUND if the reference does not exist or is not locked.
+The caller MUST have read permissions on the resource.</p></td>
               </tr>
 
               <tr>
                 <td>RefreshLock</td>
                 <td><a href="#cs3.storage.provider.v1beta1.RefreshLockRequest">.cs3.storage.provider.v1beta1.RefreshLockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.RefreshLockResponse">.cs3.storage.provider.v1beta1.RefreshLockResponse</a></td>
                 <td><p>Refreshes the lock metadata of a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is not locked.</p></td>
+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.</p></td>
               </tr>
 
               <tr>
                 <td>Unlock</td>
                 <td><a href="#cs3.storage.provider.v1beta1.UnlockRequest">.cs3.storage.provider.v1beta1.UnlockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.UnlockResponse">.cs3.storage.provider.v1beta1.UnlockResponse</a></td>
                 <td><p>Unlocks a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is not locked.</p></td>
+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.</p></td>
               </tr>
 
               <tr>
@@ -15817,31 +15828,42 @@ <h3 id="cs3.storage.provider.v1beta1.ProviderAPI">ProviderAPI</h3>
                 <td><a href="#cs3.storage.provider.v1beta1.SetLockRequest">SetLockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.SetLockResponse">SetLockResponse</a></td>
                 <td><p>Locks a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is already locked.</p></td>
+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.</p></td>
               </tr>
 
               <tr>
                 <td>GetLock</td>
                 <td><a href="#cs3.storage.provider.v1beta1.GetLockRequest">GetLockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.GetLockResponse">GetLockResponse</a></td>
                 <td><p>Gets the lock metadata of a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is not locked.</p></td>
+MUST return CODE_NOT_FOUND if the reference does not exist or is not locked.
+The caller MUST have read permissions on the resource.</p></td>
               </tr>
 
               <tr>
                 <td>RefreshLock</td>
                 <td><a href="#cs3.storage.provider.v1beta1.RefreshLockRequest">RefreshLockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.RefreshLockResponse">RefreshLockResponse</a></td>
                 <td><p>Refreshes the lock metadata of a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is not locked.</p></td>
+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.</p></td>
               </tr>
 
               <tr>
                 <td>Unlock</td>
                 <td><a href="#cs3.storage.provider.v1beta1.UnlockRequest">UnlockRequest</a></td>
                 <td><a href="#cs3.storage.provider.v1beta1.UnlockResponse">UnlockResponse</a></td>
                 <td><p>Unlocks a storage resource.
-MUST return CODE_PRECONDITION_FAILED if the reference is not locked.</p></td>
+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.</p></td>
               </tr>
 
               <tr>
@@ -16975,22 +16997,23 @@ <h3 id="cs3.storage.provider.v1beta1.LockType">LockType</h3>
               <tr>
                 <td>LOCK_TYPE_SHARED</td>
                 <td>1</td>
-                <td><p>Shared (advisory) lock: the resource can be read or
-written or unlocked by everyone who has access.</p></td>
+                <td><p>Shared (advisory) lock: the resource can be read,
+written/overwritten or unlocked by everyone who has access.</p></td>
               </tr>
 
               <tr>
                 <td>LOCK_TYPE_WRITE</td>
                 <td>2</td>
                 <td><p>Write lock: the resource can be read by everyone who has
-access, but write and unlock are restricted to the lock holder.</p></td>
+access, but write, refreshlock and unlock operations
+are restricted to the lock holder.</p></td>
               </tr>
 
               <tr>
                 <td>LOCK_TYPE_EXCL</td>
                 <td>3</td>
-                <td><p>Exclusive lock: the resource cannot be read nor written
-nor unlocked except by the user holding the lock.</p></td>
+                <td><p>Exclusive lock: only the lock holder can operate on the
+resource, anyone else is denied to access it.</p></td>
               </tr>
 
           </tbody>