From ee499bbc1bee5cdd4fe6bdeebec6fb8eeebcc143 Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Tue, 21 Mar 2023 17:46:06 +0100 Subject: [PATCH] Added comments to detail the mapping of OCM properties --- cs3/ocm/core/v1beta1/ocm_core_api.proto | 2 + cs3/sharing/ocm/v1beta1/ocm_api.proto | 3 ++ cs3/sharing/ocm/v1beta1/resources.proto | 14 +++++-- docs/index.html | 54 +++++++++++++------------ 4 files changed, 45 insertions(+), 28 deletions(-) diff --git a/cs3/ocm/core/v1beta1/ocm_core_api.proto b/cs3/ocm/core/v1beta1/ocm_core_api.proto index 2f04a40..258fbfd 100644 --- 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 index 04c82d7..0132740 100644 --- 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 index 4a77650..780bc04 100644 --- 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 index d2976f3..fee15b3 100644 --- a/docs/index.html +++ b/docs/index.html @@ -12900,11 +12900,10 @@

ListOCMSharesRequest

int32

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

+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

@@ -13006,8 +13005,8 @@

ListOCMSharesResponse

string

OPTIONAL. -This field represents the pagination token to retrieve the next page of -results. If the value is "", 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 "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

@@ -13041,11 +13040,10 @@

ListReceivedOCMSha int32

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

+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

@@ -13102,8 +13100,8 @@

ListReceivedOCMSh string

OPTIONAL. -This field represents the pagination token to retrieve the next page of -results. If the value is "", 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 "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

@@ -13316,8 +13314,7 @@

UpdateReceivedOCM google.protobuf.FieldMask

The update mask applies to the resource. For the `FieldMask` definition, -see -https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

+see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

@@ -13420,7 +13417,7 @@

ListOCMSharesR

OcmAPI

-

OCM Share Provider API

The OCM Share Provider API is meant to manipulate share

resources from the perspective of the creator or the share and

from the perspective of the receiver of the share.

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

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

+

OCM Share Provider API

The OCM Share Provider API is meant to manipulate share

resources from the perspective of the creator or the share and

from the perspective of the receiver of the share.

The following APIs implement OCM v2.0, including the invitation

workflow and multi-protocol shares, and assume OCM v2.0 compliant

remote endpoints.

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

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

@@ -13433,9 +13430,9 @@

OcmAPI

+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.

@@ -13706,7 +13703,13 @@

ReceivedShare

- + @@ -13832,7 +13835,7 @@

Share

+The expiration time for the OCM share.

@@ -13898,7 +13901,7 @@

ShareGrant

ShareId

-

A share id identifies uniquely a // share in the share provider namespace.

A ShareId MUST be unique inside the share provider.

+

A share id identifies uniquely a share in the share provider namespace.

A ShareId MUST be unique inside the share provider.

Method NameRequest TypeResponse TypeDescription
CreateOCMShareResponse

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.
protocols Protocol repeated

REQUIRED.

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.

cs3.types.v1beta1.Timestamp

OPTIONAL. -The expiration time for the ocm share.

@@ -13913,8 +13916,9 @@

ShareId

+uniquely identify the share in the internal +implementation of the service. +In the OCM specifications, this corresponds to the `providerId`.

REQUIRED. The internal id used by service implementor to -uniquely identity the share in the internal -implementation of the service.