Adding support for a Lock API (#160)

cs3/gateway/v1beta1/gateway_api.proto

@@ -169,6 +169,29 @@ 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.
+  // 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_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_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_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);
   // Creates a storage space.

cs3/storage/provider/v1beta1/provider_api.proto

@@ -148,6 +148,29 @@ 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.
+  // 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_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_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_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);
   // Gets the home path for the user.
@@ -784,6 +807,88 @@ 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.
+  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 RefreshLockRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 1;
+  // REQUIRED.
+  // The reference on which the lock should be refreshed.
+  Reference ref = 2;
+  // REQUIRED.
+  // The lock metadata.
+  Lock lock = 3;
+}
+
+message RefreshLockResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.v1beta1.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 2;
+}
+
+message UnlockRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 1;
+  // REQUIRED.
+  // The reference the lock is associated to.
+  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.

cs3/storage/provider/v1beta1/resources.proto

@@ -115,6 +115,51 @@ message ArbitraryMetadata {
   map<string, string> metadata = 1;
 }
 
+// The available type of locks for a resource.
+enum LockType {
+  LOCK_TYPE_INVALID = 0;
+  // 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, refreshlock and unlock operations
+  // are restricted to the lock holder.
+  LOCK_TYPE_WRITE = 2;
+  // 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.
+    cs3.identity.user.v1beta1.UserId user = 2;
+    // 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.
 enum ResourceType {
   RESOURCE_TYPE_INVALID = 0;