Added/updated methods to manipulate OCM shares and invitees (#211)

Author: glpatcern

cs3/gateway/v1beta1/gateway_api.proto

@@ -384,6 +384,8 @@ service GatewayAPI {
   rpc GetAcceptedUser(cs3.ocm.invite.v1beta1.GetAcceptedUserRequest) returns (cs3.ocm.invite.v1beta1.GetAcceptedUserResponse);
   // Finds users who accepted invite tokens by their attributes.
   rpc FindAcceptedUsers(cs3.ocm.invite.v1beta1.FindAcceptedUsersRequest) returns (cs3.ocm.invite.v1beta1.FindAcceptedUsersResponse);
+  // Delete a previously accepted remote user, that is unfriend that user.
+  rpc DeleteAcceptedUser(cs3.ocm.invite.v1beta1.DeleteAcceptedUserRequest) returns (cs3.ocm.invite.v1beta1.DeleteAcceptedUserResponse);
   // *****************************************************************/
   // ******************** OCM PROVIDER AUTHORIZER ********************/
   // *****************************************************************/
@@ -400,8 +402,12 @@ service GatewayAPI {
   // **************************** OCM CORE ***************************/
   // *****************************************************************/
 
-  // Creates a new ocm share.
+  // Creates a new OCM share.
   rpc CreateOCMCoreShare(cs3.ocm.core.v1beta1.CreateOCMCoreShareRequest) returns (cs3.ocm.core.v1beta1.CreateOCMCoreShareResponse);
+  // Updates an OCM share.
+  rpc UpdateOCMCoreShare(cs3.ocm.core.v1beta1.UpdateOCMCoreShareRequest) returns (cs3.ocm.core.v1beta1.UpdateOCMCoreShareResponse);
+  // Deletes an OCM share.
+  rpc DeleteOCMCoreShare(cs3.ocm.core.v1beta1.DeleteOCMCoreShareRequest) returns (cs3.ocm.core.v1beta1.DeleteOCMCoreShareResponse);
   // *****************************************************************/
   // ************************** FILE TRANSFER ************************/
   // *****************************************************************/

cs3/ocm/core/v1beta1/ocm_core_api.proto

@@ -36,7 +36,10 @@ import "cs3/types/v1beta1/types.proto";
 
 // OCM Core API
 //
-// The OCM Core API is the mapping in GRPC of the OCM core protocol.
+// the OCM Core API is the mapping for the local system of the OCM protocol,
+// including multi-protocol shares. Implementations are expected to expose
+// the `/ocm` endpoints according to the OCM API, and in response to those
+// endpoints implement the following API.
 //
 // The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
 // NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
@@ -50,11 +53,17 @@ import "cs3/types/v1beta1/types.proto";
 // Any method MAY return UNKNOWN.
 // Any method MAY return UNAUTHENTICATED.
 service OcmCoreAPI {
-  // Creates a new ocm share.
+  // Creates a new OCM share, in response to a call from remote to:
+  // https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1shares/post
   rpc CreateOCMCoreShare(CreateOCMCoreShareRequest) returns (CreateOCMCoreShareResponse);
+  // Updates an OCM share, in response to a notification from the remote system to:
+  // https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
+  rpc UpdateOCMCoreShare(UpdateOCMCoreShareRequest) returns (UpdateOCMCoreShareResponse);
+  // Deletes an OCM share, in response to a notification from the remote system to:
+  // https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
+  rpc DeleteOCMCoreShare(DeleteOCMCoreShareRequest) returns (DeleteOCMCoreShareResponse);
 }
 
-// https://rawgit.com/GEANT/OCM-API/v1/docs.html#null%2Fpaths%2F~1shares%2Fpost
 message CreateOCMCoreShareRequest {
   // OPTIONAL.
   // Opaque information.
@@ -87,10 +96,11 @@ message CreateOCMCoreShareRequest {
   // Recipient share type.
   cs3.sharing.ocm.v1beta1.ShareType share_type = 9;
   // OPTIONAL.
-  // The expiration time for the ocm share.
+  // The expiration time for the OCM share.
   cs3.types.v1beta1.Timestamp expiration = 10;
   // REQUIRED.
-  // The protocols which are used to establish synchronisation.
+  // The protocols which are used to establish synchronisation,
+  // with their access rights.
   // 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;
@@ -109,3 +119,52 @@ message CreateOCMCoreShareResponse {
   // REQUIRED.
   cs3.types.v1beta1.Timestamp created = 4;
 }
+
+message UpdateOCMCoreShareRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 1;
+  // REQUIRED.
+  // Unique ID to identify the share at the consumer side.
+  string ocm_share_id = 2;
+  // OPTIONAL.
+  // Description for the share.
+  string description = 3;
+  // OPTIONAL.
+  // Recipient share type.
+  cs3.sharing.ocm.v1beta1.ShareType share_type = 5;
+  // OPTIONAL.
+  // The expiration time for the OCM share.
+  cs3.types.v1beta1.Timestamp expiration = 6;
+  // OPTIONAL.
+  // The protocols which are used to establish synchronisation,
+  // with their access rights.
+  repeated cs3.sharing.ocm.v1beta1.Protocol protocols = 7;
+}
+
+message UpdateOCMCoreShareResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.v1beta1.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 2;
+}
+
+message DeleteOCMCoreShareRequest {
+  // REQUIRED.
+  // Unique ID to identify the share at the consumer side.
+  string id = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 2;
+}
+
+message DeleteOCMCoreShareResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.v1beta1.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 2;
+}

cs3/ocm/invite/v1beta1/invite_api.proto

@@ -39,6 +39,8 @@ import "cs3/types/v1beta1/types.proto";
 // The Invite API is meant to invite users and groups belonging to other
 // sync'n'share systems, so that collaboration of resources can be enabled.
 //
+// The following APIs match the OCM v1.1 spec for the /invite-accepted endpoint.
+//
 // 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
@@ -55,7 +57,9 @@ service InviteAPI {
   rpc GenerateInviteToken(GenerateInviteTokenRequest) returns (GenerateInviteTokenResponse);
   // Lists the valid tokens generated by the user.
   rpc ListInviteTokens(ListInviteTokensRequest) returns (ListInviteTokensResponse);
-  // Forwards a received invite to the sync'n'share system provider.
+  // Forwards a received invite to the remote sync'n'share system provider. The remote
+  // system SHALL get an `invite-accepted` call as follows:
+  // https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1invite-accepted/post
   // MUST return CODE_NOT_FOUND if the token does not exist.
   // MUST return CODE_INVALID_ARGUMENT if the token expired.
   // MUST return CODE_ALREADY_EXISTS if the user already accepted an invite.
@@ -71,6 +75,9 @@ service InviteAPI {
   rpc GetAcceptedUser(GetAcceptedUserRequest) returns (GetAcceptedUserResponse);
   // Finds users who accepted invite tokens by their attributes.
   rpc FindAcceptedUsers(FindAcceptedUsersRequest) returns (FindAcceptedUsersResponse);
+  // Delete a previously accepted remote user, that is unfriend that user.
+  // MUST return CODE_NOT_FOUND if the user does not exist.
+  rpc DeleteAcceptedUser(DeleteAcceptedUserRequest) returns (DeleteAcceptedUserResponse);
 }
 
 message GenerateInviteTokenRequest {
@@ -206,3 +213,21 @@ message FindAcceptedUsersResponse {
   // The accepted users matching the specified filter.
   repeated cs3.identity.user.v1beta1.User accepted_users = 3;
 }
+
+message DeleteAcceptedUserRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 1;
+  // REQUIRED.
+  // The id of the user.
+  cs3.identity.user.v1beta1.UserId remote_user_id = 2;
+}
+
+message DeleteAcceptedUserResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.v1beta1.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.v1beta1.Opaque opaque = 2;
+}

cs3/sharing/ocm/v1beta1/ocm_api.proto

@@ -42,8 +42,7 @@ 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 following APIs match the OCM v1.1 spec including multi-protocol shares.
 //
 // The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
 // NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
@@ -61,10 +60,15 @@ service OcmAPI {
   // 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.
+  // New shares MUST be created in the state SHARE_STATE_PENDING, and MUST be sent
+  // to the remote system using the OCM API at:
+  // https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1shares/post
   rpc CreateOCMShare(CreateOCMShareRequest) returns (CreateOCMShareResponse);
   // Removes a share.
   // MUST return CODE_NOT_FOUND if the share reference does not exist.
+  // This action SHALL be notified to the remote system
+  // using the OCM API at:
+  // https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
   rpc RemoveOCMShare(RemoveOCMShareRequest) returns (RemoveOCMShareResponse);
   // Gets share information for a single share.
   // MUST return CODE_NOT_FOUND if the share reference does not exist.
@@ -78,6 +82,9 @@ service OcmAPI {
   rpc ListOCMShares(ListOCMSharesRequest) returns (ListOCMSharesResponse);
   // Updates a share.
   // MUST return CODE_NOT_FOUND if the share reference does not exist.
+  // This action SHALL be notified to the remote system
+  // using the OCM API at:
+  // https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
   rpc UpdateOCMShare(UpdateOCMShareRequest) returns (UpdateOCMShareResponse);
   // List all shares the authenticated principal has received.
   rpc ListReceivedOCMShares(ListReceivedOCMSharesRequest) returns (ListReceivedOCMSharesResponse);
@@ -128,21 +135,19 @@ message UpdateOCMShareRequest {
   // OPTIONAL.
   // Opaque information.
   cs3.types.v1beta1.Opaque opaque = 1;
-  // REQUIRED.
-
   // REQUIRED.
   ShareReference ref = 2;
   // REQUIRED.
   message UpdateField {
     // One of the update fields MUST be specified.
     oneof field {
-      // Update the permissions.
-      SharePermissions permissions = 2;
-      // Update the display name.
-      string display_name = 3;
+      // Update the expiration.
+      cs3.types.v1beta1.Timestamp expiration = 1;
+      // Update access methods.
+      AccessMethod access_methods = 2;
     }
   }
-  UpdateField field = 3;
+  repeated UpdateField field = 3;
 }
 
 message UpdateOCMShareResponse {

cs3/sharing/ocm/v1beta1/resources.proto

@@ -224,7 +224,7 @@ message ShareGrant {
   SharePermissions permissions = 2;
 }
 
-// The protocol which is used to establish synchronisation.
+// The protocol which is used to give access to a remote OCM user.
 message Protocol {
   // REQUIRED.
   // One of the protocols MUST be specified.
@@ -287,7 +287,7 @@ enum ShareType {
   SHARE_TYPE_GROUP = 2;
 }
 
-// Defines how the recipient accesses the share.
+// Defines how the recipient accesses an incoming remote OCM share.
 message AccessMethod {
   // REQUIRED.
   // One of the access method MUST be specified.
@@ -308,15 +308,19 @@ message AccessMethod {
 message WebDAVAccessMethod {
   // REQUIRED.
   // The permissions for the share.
-  storage.provider.v1beta1.ResourcePermissions permissions = 2;
+  storage.provider.v1beta1.ResourcePermissions permissions = 1;
 }
 
 // Defines the options for the Webapp access method.
 message WebappAccessMethod {
   // REQUIRED.
   // The view mode for the share.
-  cs3.app.provider.v1beta1.ViewMode view_mode = 2;
+  cs3.app.provider.v1beta1.ViewMode view_mode = 1;
 }
 
 // Defines the options for the Transfer access method.
-message TransferAccessMethod {}
+message TransferAccessMethod {
+  // REQUIRED.
+  // The destination path of the data transfer.
+  storage.provider.v1beta1.Reference destination = 1;
+}