Skip to content

Commit 4d576d6

Browse files
glpatcernglpatcern
authored
Introduced the Incoming OCM API (#253)
* Introduced the Incoming OCM API. Fixes #150. This is a one-on-one replacement of the so-called "Core OCM" API, which is now deprecated and will be removed in a later change. * Added corresponding gateway APIs
1 parent 53793f4 commit 4d576d6

File tree

5 files changed

+219
-36
lines changed

5 files changed

+219
-36
lines changed

‎cs3/gateway/v1beta1/gateway_api.proto‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import "cs3/identity/group/v1beta1/group_api.proto";
2929
import "cs3/identity/user/v1beta1/resources.proto";
3030
import "cs3/identity/user/v1beta1/user_api.proto";
3131
import "cs3/ocm/core/v1beta1/ocm_core_api.proto";
32+
import "cs3/ocm/incoming/v1beta1/ocm_incoming_api.proto";
3233
import "cs3/ocm/invite/v1beta1/invite_api.proto";
3334
import "cs3/ocm/provider/v1beta1/provider_api.proto";
3435
import "cs3/permissions/v1beta1/permissions_api.proto";
@@ -416,14 +417,21 @@ service GatewayAPI {
416417
// Get the information of all the providers registered in the mesh.
417418
rpc ListAllProviders(cs3.ocm.provider.v1beta1.ListAllProvidersRequest) returns (cs3.ocm.provider.v1beta1.ListAllProvidersResponse);
418419
// *****************************************************************/
419-
// **************************** OCM CORE ***************************/
420+
// **************************** OCM INCOMING ***********************/
420421
// *****************************************************************/
421422

422-
// Creates a new OCM share.
423+
// Creates a new incoming OCM share.
424+
rpc CreateOCMIncomingShare(cs3.ocm.incoming.v1beta1.CreateOCMIncomingShareRequest) returns (cs3.ocm.incoming.v1beta1.CreateOCMIncomingShareResponse);
425+
// Updates an incoming OCM share.
426+
rpc UpdateOCMIncomingShare(cs3.ocm.incoming.v1beta1.UpdateOCMIncomingShareRequest) returns (cs3.ocm.incoming.v1beta1.UpdateOCMIncomingShareResponse);
427+
// Deletes an incoming OCM share.
428+
rpc DeleteOCMIncomingShare(cs3.ocm.incoming.v1beta1.DeleteOCMIncomingShareRequest) returns (cs3.ocm.incoming.v1beta1.DeleteOCMIncomingShareResponse);
429+
430+
// Deprecated. Creates a new OCM share.
423431
rpc CreateOCMCoreShare(cs3.ocm.core.v1beta1.CreateOCMCoreShareRequest) returns (cs3.ocm.core.v1beta1.CreateOCMCoreShareResponse);
424-
// Updates an OCM share.
432+
// Deprecated. Updates an OCM share.
425433
rpc UpdateOCMCoreShare(cs3.ocm.core.v1beta1.UpdateOCMCoreShareRequest) returns (cs3.ocm.core.v1beta1.UpdateOCMCoreShareResponse);
426-
// Deletes an OCM share.
434+
// Deprecated. Deletes an OCM share.
427435
rpc DeleteOCMCoreShare(cs3.ocm.core.v1beta1.DeleteOCMCoreShareRequest) returns (cs3.ocm.core.v1beta1.DeleteOCMCoreShareResponse);
428436
// *****************************************************************/
429437
// ************************** FILE TRANSFER ************************/

‎cs3/ocm/core/v1beta1/ocm_core_api.proto‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,13 @@ option java_package = "com.cs3.ocm.core.v1beta1";
3434
option objc_class_prefix = "COC";
3535
option php_namespace = "Cs3\\Ocm\\Core\\V1Beta1";
3636

37-
// OCM Core API
37+
// OCM Core API (deprecated and to be removed, use cs3/ocm/incoming/v1beta1/incoming_api.proto instead)
3838
//
39-
// the OCM Core API is the mapping for the local system of the OCM protocol,
40-
// including multi-protocol shares. Implementations are expected to expose
41-
// the `/ocm` endpoints according to the OCM API, and in response to those
42-
// endpoints implement the following API.
39+
// This API is the mapping for the local system of the Open Cloud Mesh
40+
// (OCM) sharing protocol. Implementations are expected to expose the `/ocm`
41+
// endpoints according to the OCM API, and in response to those endpoints call the
42+
// following API. Support for multi-protocol shares is included, if the remote
43+
// sender supplies a multi-protocol share.
4344
//
4445
// The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
4546
// NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
@@ -53,17 +54,15 @@ option php_namespace = "Cs3\\Ocm\\Core\\V1Beta1";
5354
// Any method MAY return UNKNOWN.
5455
// Any method MAY return UNAUTHENTICATED.
5556
service OcmCoreAPI {
56-
// Creates a new OCM share, in response to a call from remote to:
57-
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1shares/post
57+
// Deprecated. Creates a new OCM share, in response to a call from the remote system
5858
rpc CreateOCMCoreShare(CreateOCMCoreShareRequest) returns (CreateOCMCoreShareResponse);
59-
// Updates an OCM share, in response to a notification from the remote system to:
60-
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
59+
// Deprecated. Updates an OCM share, in response to a notification from the remote system
6160
rpc UpdateOCMCoreShare(UpdateOCMCoreShareRequest) returns (UpdateOCMCoreShareResponse);
62-
// Deletes an OCM share, in response to a notification from the remote system to:
63-
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
61+
// Deprecated. Deletes an OCM share, in response to a notification from the remote system
6462
rpc DeleteOCMCoreShare(DeleteOCMCoreShareRequest) returns (DeleteOCMCoreShareResponse);
6563
}
6664

65+
6766
message CreateOCMCoreShareRequest {
6867
// OPTIONAL.
6968
// Opaque information.

‎cs3/ocm/incoming/v1beta1/ocm_incoming_api.proto‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
// Copyright 2018-2025 CERN
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
//
15+
// In applying this license, CERN does not waive the privileges and immunities
16+
// granted to it by virtue of its status as an Intergovernmental Organization
17+
// or submit itself to any jurisdiction.
18+
19+
syntax = "proto3";
20+
21+
package cs3.ocm.incoming.v1beta1;
22+
23+
import "cs3/identity/user/v1beta1/resources.proto";
24+
import "cs3/rpc/v1beta1/status.proto";
25+
import "cs3/sharing/ocm/v1beta1/resources.proto";
26+
import "cs3/storage/provider/v1beta1/resources.proto";
27+
import "cs3/types/v1beta1/types.proto";
28+
29+
option csharp_namespace = "Cs3.Ocm.Incoming.V1Beta1";
30+
option go_package = "incomingv1beta1";
31+
option java_multiple_files = true;
32+
option java_outer_classname = "OcmIncomingApiProto";
33+
option java_package = "com.cs3.ocm.incoming.v1beta1";
34+
option objc_class_prefix = "COI";
35+
option php_namespace = "Cs3\\Ocm\\Incoming\\V1Beta1";
36+
37+
// OCM Incoming API
38+
//
39+
// The OCM Incoming API is used to persist in the local system the incoming remote
40+
// shares that are sent via the Open Cloud Mesh (OCM) sharing protocol.
41+
// Implementations are expected to expose the `/ocm` endpoints according to the
42+
// OCM API, and in response to those endpoints call the following API.
43+
// Support for multi-protocol shares is included, if the remote sender supplies
44+
// a multi-protocol share.
45+
//
46+
// The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
47+
// NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
48+
// "OPTIONAL" in this document are to be interpreted as described in
49+
// RFC 2119.
50+
//
51+
// The following are global requirements that apply to all methods:
52+
// Any method MUST return CODE_OK on a succesful operation.
53+
// Any method MAY return NOT_IMPLEMENTED.
54+
// Any method MAY return INTERNAL.
55+
// Any method MAY return UNKNOWN.
56+
// Any method MAY return UNAUTHENTICATED.
57+
service OcmIncomingAPI {
58+
// Creates a new OCM share in response to a call from remote to `/ocm/shares`. See:
59+
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1shares/post
60+
rpc CreateOCMIncomingShare(CreateOCMIncomingShareRequest) returns (CreateOCMIncomingShareResponse);
61+
// Updates an OCM share in response to a notification from remote to `/ocm/notifications`. See:
62+
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
63+
rpc UpdateOCMIncomingShare(UpdateOCMIncomingShareRequest) returns (UpdateOCMIncomingShareResponse);
64+
// Deletes an OCM share in response to a notification from remote to `/ocm/notifications`. See:
65+
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
66+
rpc DeleteOCMIncomingShare(DeleteOCMIncomingShareRequest) returns (DeleteOCMIncomingShareResponse);
67+
}
68+
69+
message CreateOCMIncomingShareRequest {
70+
// OPTIONAL.
71+
// Opaque information.
72+
cs3.types.v1beta1.Opaque opaque = 1;
73+
// OPTIONAL.
74+
// Description for the share.
75+
string description = 2;
76+
// REQUIRED.
77+
// Name of the resource (file or folder).
78+
string name = 3;
79+
// REQUIRED.
80+
// Identifier to identify the resource at the provider side. This is unique per provider.
81+
string resource_id = 4;
82+
// REQUIRED.
83+
// Provider specific identifier of the owner of the resource.
84+
cs3.identity.user.v1beta1.UserId owner = 5;
85+
// REQUIRED.
86+
// Provider specific identifier of the user that wants to share the resource.
87+
cs3.identity.user.v1beta1.UserId sender = 6;
88+
// REQUIRED.
89+
// Consumer specific identifier of the user or group the provider wants to share the resource with.
90+
// This is known in advance, for example using the OCM invitation flow.
91+
// Please note that the consumer service endpoint is known in advance as well, so this is no part of the request body.
92+
// TODO: this field needs to represent either a user or group in the future, not only a user.
93+
cs3.identity.user.v1beta1.UserId share_with = 7;
94+
// REQUIRED.
95+
// Resource type.
96+
cs3.storage.provider.v1beta1.ResourceType resource_type = 8;
97+
// REQUIRED.
98+
// Recipient share type.
99+
cs3.sharing.ocm.v1beta1.ShareType share_type = 9;
100+
// OPTIONAL.
101+
// The expiration time for the OCM share.
102+
cs3.types.v1beta1.Timestamp expiration = 10;
103+
// REQUIRED.
104+
// The protocols which are used to establish synchronisation,
105+
// with their access rights.
106+
// See also cs3/sharing/ocm/v1beta1/resources.proto for how to map
107+
// this to the OCM share payload.
108+
repeated cs3.sharing.ocm.v1beta1.Protocol protocols = 11;
109+
// OPTIONAL.
110+
// A nonce to be exchanged for a (potentially short-lived) bearer token.
111+
string code = 12;
112+
}
113+
114+
message CreateOCMIncomingShareResponse {
115+
// REQUIRED.
116+
// The response status.
117+
cs3.rpc.v1beta1.Status status = 1;
118+
// OPTIONAL.
119+
// Opaque information.
120+
cs3.types.v1beta1.Opaque opaque = 2;
121+
// REQUIRED.
122+
// Unique ID to identify the share at the consumer side.
123+
string id = 3;
124+
// REQUIRED.
125+
cs3.types.v1beta1.Timestamp created = 4;
126+
}
127+
128+
message UpdateOCMIncomingShareRequest {
129+
// OPTIONAL.
130+
// Opaque information.
131+
cs3.types.v1beta1.Opaque opaque = 1;
132+
// REQUIRED.
133+
// Unique ID to identify the share at the consumer side.
134+
string ocm_share_id = 2;
135+
// OPTIONAL.
136+
// Description for the share.
137+
string description = 3;
138+
// OPTIONAL.
139+
// Recipient share type.
140+
cs3.sharing.ocm.v1beta1.ShareType share_type = 5;
141+
// OPTIONAL.
142+
// The expiration time for the OCM share.
143+
cs3.types.v1beta1.Timestamp expiration = 6;
144+
// OPTIONAL.
145+
// The protocols which are used to establish synchronisation,
146+
// with their access rights.
147+
repeated cs3.sharing.ocm.v1beta1.Protocol protocols = 7;
148+
}
149+
150+
message UpdateOCMIncomingShareResponse {
151+
// REQUIRED.
152+
// The response status.
153+
cs3.rpc.v1beta1.Status status = 1;
154+
// OPTIONAL.
155+
// Opaque information.
156+
cs3.types.v1beta1.Opaque opaque = 2;
157+
}
158+
159+
message DeleteOCMIncomingShareRequest {
160+
// REQUIRED.
161+
// Unique ID to identify the share at the consumer side.
162+
string id = 1;
163+
// OPTIONAL.
164+
// Opaque information.
165+
cs3.types.v1beta1.Opaque opaque = 2;
166+
}
167+
168+
message DeleteOCMIncomingShareResponse {
169+
// REQUIRED.
170+
// The response status.
171+
cs3.rpc.v1beta1.Status status = 1;
172+
// OPTIONAL.
173+
// Opaque information.
174+
cs3.types.v1beta1.Opaque opaque = 2;
175+
}

‎cs3/sharing/collaboration/v1beta1/collaboration_api.proto‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,10 @@ option php_namespace = "Cs3\\Sharing\\Collaboration\\V1Beta1";
3737
// User Share Provider API
3838
//
3939
// The User Share Provider API is meant to manipulate share
40-
// resources for a specific share type (user, group, ocm, ...)
41-
// from the perspective of the creator or the share and
42-
// from the perspective of the receiver of the share.
40+
// resources for a specific share type (user or group)
41+
// from the perspective of the creator of the share and
42+
// from the perspective of the recipient, both known to
43+
// the local system. See OCM for remote shares.
4344
//
4445
// The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
4546
// NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

‎cs3/sharing/ocm/v1beta1/ocm_api.proto‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,15 @@ option java_package = "com.cs3.sharing.ocm.v1beta1";
3636
option objc_class_prefix = "CSO";
3737
option php_namespace = "Cs3\\Sharing\\Ocm\\V1Beta1";
3838

39-
// OCM Share Provider API
39+
// OCM API
4040
//
41-
// The OCM Share Provider API is meant to manipulate share
42-
// resources from the perspective of the creator or the share and
43-
// from the perspective of the receiver of the share.
41+
// The OCM API is a share API meant for local users to offer local
42+
// resources to remote recipients via the Open Cloud Mesh (OCM) protocol,
43+
// and to manipulate shares received from remote users.
44+
// Implementations are expected to call remote `/ocm` endpoints
45+
// in response to the payloads received via this API.
4446
//
45-
// The following APIs match the OCM v1.1 spec including multi-protocol shares.
47+
// The APIs match the OCM v1.2 spec including multi-protocol shares.
4648
//
4749
// The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
4850
// NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
@@ -56,37 +58,35 @@ option php_namespace = "Cs3\\Sharing\\Ocm\\V1Beta1";
5658
// Any method MAY return UNKNOWN.
5759
// Any method MAY return UNAUTHENTICATED.
5860
service OcmAPI {
59-
// Creates a new ocm share.
61+
// Creates a new OCM share.
6062
// MUST return CODE_NOT_FOUND if the resource reference does not exist.
61-
// MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of
63+
// MUST return CODE_ALREADY_EXISTS if the share already exists for the 3-tuple consisting of
6264
// (owner, shared_resource, grantee).
6365
// New shares MUST be created in the state SHARE_STATE_PENDING, and MUST be sent
64-
// to the remote system using the OCM API at:
65-
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1shares/post
66+
// to the remote system using the `/ocm/shares` OCM API, see:
67+
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1shares/post
6668
rpc CreateOCMShare(CreateOCMShareRequest) returns (CreateOCMShareResponse);
67-
// Removes a share.
69+
// Removes an OCM share.
6870
// MUST return CODE_NOT_FOUND if the share reference does not exist.
69-
// This action SHALL be notified to the remote system
70-
// using the OCM API at:
71-
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
71+
// This action MUST be notified to the remote system using the `/ocm/notifications` OCM API at:
72+
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
7273
rpc RemoveOCMShare(RemoveOCMShareRequest) returns (RemoveOCMShareResponse);
7374
// Gets share information for a single share.
7475
// MUST return CODE_NOT_FOUND if the share reference does not exist.
7576
rpc GetOCMShare(GetOCMShareRequest) returns (GetOCMShareResponse);
7677
// Gets share information for a single share by its unlisted token.
7778
// MUST return CODE_NOT_FOUND if the share does not exist.
7879
rpc GetOCMShareByToken(GetOCMShareByTokenRequest) returns (GetOCMShareByTokenResponse);
79-
// List the shares the authenticated principal has created,
80+
// List the shares the currently authenticated user has created,
8081
// both as owner and creator. If a filter is specified, only
8182
// shares satisfying the filter MUST be returned.
8283
rpc ListOCMShares(ListOCMSharesRequest) returns (ListOCMSharesResponse);
8384
// Updates a share.
8485
// MUST return CODE_NOT_FOUND if the share reference does not exist.
85-
// This action SHALL be notified to the remote system
86-
// using the OCM API at:
87-
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
86+
// This action MUST be notified to the remote system using the `/ocm/notifications` OCM API at:
87+
// https://cs3org.github.io/OCM-API/docs.html?branch=v1.2.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post
8888
rpc UpdateOCMShare(UpdateOCMShareRequest) returns (UpdateOCMShareResponse);
89-
// List all shares the authenticated principal has received.
89+
// List all shares the currently authenticated user has received.
9090
rpc ListReceivedOCMShares(ListReceivedOCMSharesRequest) returns (ListReceivedOCMSharesResponse);
9191
// Update the received share to change the share state or the display name.
9292
// MUST return CODE_NOT_FOUND if the share reference does not exist.

0 commit comments

Comments
 (0)