Also added the last modification time and proposed a reference implem…

…entation
cs3org · Dec 9, 2021 · b291411 · b291411
1 parent 6d25db1
commit b291411
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 7 deletions.
diff --git a/cs3/storage/provider/v1beta1/resources.proto b/cs3/storage/provider/v1beta1/resources.proto
@@ -122,26 +122,41 @@ enum LockType {
   // 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.
+  // access, but write and unlock 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.
   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.

diff --git a/docs/index.html b/docs/index.html
@@ -16234,7 +16234,7 @@ <h3 id="cs3.storage.provider.v1beta1.Grantee">Grantee</h3>
 
 
         <h3 id="cs3.storage.provider.v1beta1.Lock">Lock</h3>
-        <p>The metadata associated with a lock on a resource.</p>
+        <p>The metadata associated with a lock on a resource.</p><p>Provided that storage drivers are free to implement the storage</p><p>of this metadata according to their constraints, a reference</p><p>implementation is given here. The lock SHOULD be stored</p><p>as an extended attribute on the referenced filesystem entry.</p><p>It MUST NOT be accessible via the Stat/SetArbitraryMetadata APIs,</p><p>and it SHOULD contain a base64-encoded JSON with the following format:</p><p>{</p><p>"type" : "<LOCK_TYPE>",</p><p>"h" : "<holder>",</p><p>"md" : "<metadata>",</p><p>"mtime" : "<Unix timestamp>"</p><p>}</p>
 
 
           <table class="field-table">
@@ -16254,14 +16254,14 @@ <h3 id="cs3.storage.provider.v1beta1.Lock">Lock</h3>
                   <td>user</td>
                   <td><a href="#cs3.identity.user.v1beta1.UserId">cs3.identity.user.v1beta1.UserId</a></td>
                   <td></td>
-                  <td><p>A userid if the lock is held by a user </p></td>
+                  <td><p>A userid if the lock is held by a user. </p></td>
                 </tr>
 
                 <tr>
                   <td>app_name</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p>An application name if the lock is held by an app </p></td>
+                  <td><p>An application name if the lock is held by an app. </p></td>
                 </tr>
 
                 <tr>
@@ -16271,6 +16271,14 @@ <h3 id="cs3.storage.provider.v1beta1.Lock">Lock</h3>
                   <td><p>Some arbitrary metadata associated with the lock. </p></td>
                 </tr>
 
+                <tr>
+                  <td>mtime</td>
+                  <td><a href="#cs3.types.v1beta1.Timestamp">cs3.types.v1beta1.Timestamp</a></td>
+                  <td></td>
+                  <td><p>The last modification time of the lock.
+The value is Unix Epoch timestamp in seconds. </p></td>
+                </tr>
+
             </tbody>
           </table>
 
@@ -16975,7 +16983,7 @@ <h3 id="cs3.storage.provider.v1beta1.LockType">LockType</h3>
                 <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 is restricted to the lock holder.</p></td>
+access, but write and unlock are restricted to the lock holder.</p></td>
               </tr>
 
               <tr>