Added comments to detail the mapping of OCM properties

cs3org · Mar 29, 2023 · ee499bb · ee499bb
1 parent 1dbd0fa
commit ee499bb
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 28 deletions.
diff --git a/cs3/ocm/core/v1beta1/ocm_core_api.proto b/cs3/ocm/core/v1beta1/ocm_core_api.proto
@@ -91,6 +91,8 @@ message CreateOCMCoreShareRequest {
   cs3.types.v1beta1.Timestamp expiration = 10;
   // REQUIRED.
   // The protocols which are used to establish synchronisation.
+  // See also cs3/sharing/ocm/v1beta1/resources.proto for how to map
+  // this to the OCM share payload.
   repeated cs3.sharing.ocm.v1beta1.Protocol protocols = 11;
 }
 

diff --git a/cs3/sharing/ocm/v1beta1/ocm_api.proto b/cs3/sharing/ocm/v1beta1/ocm_api.proto
@@ -42,6 +42,9 @@ import "google/protobuf/field_mask.proto";
 // resources from the perspective of the creator or the share and
 // from the perspective of the receiver of the share.
 //
+// The following APIs match the OCM v1.1 spec, including the invitation
+// workflow and multi-protocol shares.
+//
 // The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
 // NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
 // "OPTIONAL" in this document are to be interpreted as described in

diff --git a/cs3/sharing/ocm/v1beta1/resources.proto b/cs3/sharing/ocm/v1beta1/resources.proto
@@ -72,7 +72,7 @@ message Share {
   // Last modification time of the share.
   cs3.types.v1beta1.Timestamp mtime = 9;
   // OPTIONAL.
-  // The expiration time for the ocm share.
+  // The expiration time for the OCM share.
   cs3.types.v1beta1.Timestamp expiration = 10;
   // REQUIRED.
   // Recipient share type.
@@ -127,6 +127,13 @@ message ReceivedShare {
   // Recipient share type.
   cs3.sharing.ocm.v1beta1.ShareType share_type = 10;
   // REQUIRED.
+  // List of protocols offered for this share.
+  // In the OCM specifications, this corresponds to the `protocol`
+  // property, to maintain backwards compatibility with OCM v1 where
+  // only a single protocol was implemented. Furthermore,
+  // `protocol.name` MAY be set to `multi` and `protocol.options`
+  // MAY be left empty in the OCM share payload, in order to use
+  // the `protocol.webdav` and similar properties.
   repeated Protocol protocols = 11;
   // REQUIRED.
   // The state of the share.
@@ -176,13 +183,14 @@ message ShareKey {
   storage.provider.v1beta1.Grantee grantee = 3;
 }
 
-// A share id identifies uniquely a // share in the share provider namespace.
+// A share id identifies uniquely a share in the share provider namespace.
 // A ShareId MUST be unique inside the share provider.
 message ShareId {
   // REQUIRED.
   // The internal id used by service implementor to
-  // uniquely identity the share in the internal
+  // uniquely identify the share in the internal
   // implementation of the service.
+  // In the OCM specifications, this corresponds to the `providerId`.
   string opaque_id = 1;
 }
 

diff --git a/docs/index.html b/docs/index.html
@@ -12900,11 +12900,10 @@ <h3 id="cs3.sharing.ocm.v1beta1.ListOCMSharesRequest">ListOCMSharesRequest</h3>
                   <td><a href="#int32">int32</a></td>
                   <td></td>
                   <td><p>OPTIONAL.
-Clients use this field to specify the maximum number of results to be
-returned by the server. The server may further constrain the maximum number
-of results returned in a single page. If the page_size is 0, the server
-will decide the number of results to be returned. see
-https://cloud.google.com/apis/design/design_patterns#list_pagination </p></td>
+Clients use this field to specify the maximum number of results to be returned by the server.
+The server may further constrain the maximum number of results returned in a single page.
+If the page_size is 0, the server will decide the number of results to be returned.
+see https://cloud.google.com/apis/design/design_patterns#list_pagination </p></td>
                 </tr>
 
                 <tr>
@@ -13006,8 +13005,8 @@ <h3 id="cs3.sharing.ocm.v1beta1.ListOCMSharesResponse">ListOCMSharesResponse</h3
                   <td><a href="#string">string</a></td>
                   <td></td>
                   <td><p>OPTIONAL.
-This field represents the pagination token to retrieve the next page of
-results. If the value is &#34;&#34;, it means no further results for the request.
+This field represents the pagination token to retrieve the next page of results.
+If the value is &#34;&#34;, it means no further results for the request.
 see https://cloud.google.com/apis/design/design_patterns#list_pagination </p></td>
                 </tr>
 
@@ -13041,11 +13040,10 @@ <h3 id="cs3.sharing.ocm.v1beta1.ListReceivedOCMSharesRequest">ListReceivedOCMSha
                   <td><a href="#int32">int32</a></td>
                   <td></td>
                   <td><p>OPTIONAL.
-Clients use this field to specify the maximum number of results to be
-returned by the server. The server may further constrain the maximum number
-of results returned in a single page. If the page_size is 0, the server
-will decide the number of results to be returned. see
-https://cloud.google.com/apis/design/design_patterns#list_pagination </p></td>
+Clients use this field to specify the maximum number of results to be returned by the server.
+The server may further constrain the maximum number of results returned in a single page.
+If the page_size is 0, the server will decide the number of results to be returned.
+see https://cloud.google.com/apis/design/design_patterns#list_pagination </p></td>
                 </tr>
 
                 <tr>
@@ -13102,8 +13100,8 @@ <h3 id="cs3.sharing.ocm.v1beta1.ListReceivedOCMSharesResponse">ListReceivedOCMSh
                   <td><a href="#string">string</a></td>
                   <td></td>
                   <td><p>OPTIONAL.
-This field represents the pagination token to retrieve the next page of
-results. If the value is &#34;&#34;, it means no further results for the request.
+This field represents the pagination token to retrieve the next page of results.
+If the value is &#34;&#34;, it means no further results for the request.
 see https://cloud.google.com/apis/design/design_patterns#list_pagination </p></td>
                 </tr>
 
@@ -13316,8 +13314,7 @@ <h3 id="cs3.sharing.ocm.v1beta1.UpdateReceivedOCMShareRequest">UpdateReceivedOCM
                   <td><a href="#google.protobuf.FieldMask">google.protobuf.FieldMask</a></td>
                   <td></td>
                   <td><p>The update mask applies to the resource. For the `FieldMask` definition,
-see
-https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask </p></td>
+see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask </p></td>
                 </tr>
 
             </tbody>
@@ -13420,7 +13417,7 @@ <h3 id="cs3.sharing.ocm.v1beta1.ListOCMSharesRequest.Filter.Type">ListOCMSharesR
 
 
         <h3 id="cs3.sharing.ocm.v1beta1.OcmAPI">OcmAPI</h3>
-        <p>OCM Share Provider API</p><p>The OCM Share Provider API is meant to manipulate share</p><p>resources from the perspective of the creator or the share and</p><p>from the perspective of the receiver of the share.</p><p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL</p><p>NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and</p><p>"OPTIONAL" in this document are to be interpreted as described in</p><p>RFC 2119.</p><p>The following are global requirements that apply to all methods:</p><p>Any method MUST return CODE_OK on a succesful operation.</p><p>Any method MAY return NOT_IMPLEMENTED.</p><p>Any method MAY return INTERNAL.</p><p>Any method MAY return UNKNOWN.</p><p>Any method MAY return UNAUTHENTICATED.</p>
+        <p>OCM Share Provider API</p><p>The OCM Share Provider API is meant to manipulate share</p><p>resources from the perspective of the creator or the share and</p><p>from the perspective of the receiver of the share.</p><p>The following APIs implement OCM v2.0, including the invitation</p><p>workflow and multi-protocol shares, and assume OCM v2.0 compliant</p><p>remote endpoints.</p><p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL</p><p>NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and</p><p>"OPTIONAL" in this document are to be interpreted as described in</p><p>RFC 2119.</p><p>The following are global requirements that apply to all methods:</p><p>Any method MUST return CODE_OK on a succesful operation.</p><p>Any method MAY return NOT_IMPLEMENTED.</p><p>Any method MAY return INTERNAL.</p><p>Any method MAY return UNKNOWN.</p><p>Any method MAY return UNAUTHENTICATED.</p>
         <table class="enum-table">
           <thead>
             <tr><td>Method Name</td><td>Request Type</td><td>Response Type</td><td>Description</td></tr>
@@ -13433,9 +13430,9 @@ <h3 id="cs3.sharing.ocm.v1beta1.OcmAPI">OcmAPI</h3>
                 <td><a href="#cs3.sharing.ocm.v1beta1.CreateOCMShareResponse">CreateOCMShareResponse</a></td>
                 <td><p>Creates a new ocm share.
 MUST return CODE_NOT_FOUND if the resource reference does not exist.
-MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple
-consisting of (owner, shared_resource, grantee). New shares MUST be created
-in the state SHARE_STATE_PENDING.</p></td>
+MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of
+(owner, shared_resource, grantee).
+New shares MUST be created in the state SHARE_STATE_PENDING.</p></td>
               </tr>
 
               <tr>
@@ -13706,7 +13703,13 @@ <h3 id="cs3.sharing.ocm.v1beta1.ReceivedShare">ReceivedShare</h3>
                   <td>protocols</td>
                   <td><a href="#cs3.sharing.ocm.v1beta1.Protocol">Protocol</a></td>
                   <td>repeated</td>
-                  <td><p>REQUIRED. </p></td>
+                  <td><p>REQUIRED.
+List of protocols offered for this share.
+In the OCM specifications, this corresponds to the `protocol`,
+to maintain backwards compatibility with OCM v1 where
+only a single `protocol` was implemented. Furthermore,
+`protocol.name` shall be set to `multi` and `protocol.options`
+shall be left empty in the OCM share payload. </p></td>
                 </tr>
 
                 <tr>
@@ -13832,7 +13835,7 @@ <h3 id="cs3.sharing.ocm.v1beta1.Share">Share</h3>
                   <td><a href="#cs3.types.v1beta1.Timestamp">cs3.types.v1beta1.Timestamp</a></td>
                   <td></td>
                   <td><p>OPTIONAL.
-The expiration time for the ocm share. </p></td>
+The expiration time for the OCM share. </p></td>
                 </tr>
 
                 <tr>
@@ -13898,7 +13901,7 @@ <h3 id="cs3.sharing.ocm.v1beta1.ShareGrant">ShareGrant</h3>
 
 
         <h3 id="cs3.sharing.ocm.v1beta1.ShareId">ShareId</h3>
-        <p>A share id identifies uniquely a // share in the share provider namespace.</p><p>A ShareId MUST be unique inside the share provider.</p>
+        <p>A share id identifies uniquely a share in the share provider namespace.</p><p>A ShareId MUST be unique inside the share provider.</p>
 
 
           <table class="field-table">
@@ -13913,8 +13916,9 @@ <h3 id="cs3.sharing.ocm.v1beta1.ShareId">ShareId</h3>
                   <td></td>
                   <td><p>REQUIRED.
 The internal id used by service implementor to
-uniquely identity the share in the internal
-implementation of the service. </p></td>
+uniquely identify the share in the internal
+implementation of the service.
+In the OCM specifications, this corresponds to the `providerId`. </p></td>
                 </tr>
 
             </tbody>