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

@@ -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);

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);

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" : "<LOCK_TYPE>",
+//   "h" : "<holder>",
+//   "md" : "<metadata>",
+//   "mtime" : "<Unix timestamp>"
+// }
 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.