From 72e0437cde34ce2cc7abf06a5b2730fd2eafa3f1 Mon Sep 17 00:00:00 2001
From: Giuseppe Lo Presti
Date: Wed, 29 Mar 2023 17:10:05 +0200
Subject: [PATCH] Added comments to detail the mapping of OCM properties (#206)
---
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 | 24 +++++++++++++++++-------
4 files changed, 33 insertions(+), 10 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 bd7a024..9d1f268 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -8854,7 +8854,9 @@ CreateOCMCoreShareReques
cs3.sharing.ocm.v1beta1.Protocol |
repeated |
REQUIRED.
-The protocols which are used to establish synchronisation. |
+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.
@@ -13417,7 +13419,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 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
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.
Method Name | Request Type | Response Type | Description |
@@ -13703,7 +13705,14 @@ ReceivedShare
protocols |
Protocol |
repeated |
- REQUIRED. |
+ 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. |
@@ -13829,7 +13838,7 @@ Share
cs3.types.v1beta1.Timestamp |
|
OPTIONAL.
-The expiration time for the ocm share. |
+The expiration time for the OCM share.
@@ -13895,7 +13904,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.
@@ -13910,8 +13919,9 @@ ShareId
|
REQUIRED.
The internal id used by service implementor to
-uniquely identity the share in the internal
-implementation of the service. |
+uniquely identify the share in the internal
+implementation of the service.
+In the OCM specifications, this corresponds to the `providerId`.