OCM share provider (cs3org#18)

cs3/ocmshareprovider/v0alpha/ocmshareprovider.proto

@@ -0,0 +1,254 @@
+// Copyright 2018-2019 CERN
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// In applying this license, CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+syntax = "proto3";
+
+package cs3.ocmshareproviderv0alpha;
+
+option csharp_namespace = "CS3.OCMShareProviderV0Alpha";
+option go_package = "ocmshareproviderv0alphapb";
+option java_multiple_files = true;
+option java_outer_classname = "OcmshareproviderProto";
+option java_package = "com.cs3.ocmshareproviderv0alpha";
+option objc_class_prefix = "CBOXOCMSHAREPROVIDER";
+option php_namespace = "CS3\\OCMShareProviderV0Alpha";
+
+import "cs3/ocmshareprovider/v0alpha/resources.proto";
+import "cs3/rpc/status.proto";
+import "cs3/storageprovider/v0alpha/resources.proto";
+import "cs3/types/types.proto";
+
+// 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.
+service OCMShareProviderService {
+  // Creates a new 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.
+  rpc CreateShare(CreateShareRequest) returns (CreateShareResponse);
+  // Removes a share.
+  // MUST return CODE_NOT_FOUND if the share reference does not exist.
+  rpc RemoveShare(RemoveShareRequest) returns (RemoveShareResponse);
+  // Gets share information for a single share.
+  // MUST return CODE_NOT_FOUND if the share reference does not exist.
+  rpc GetShare(GetShareRequest) returns (GetShareResponse);
+  // List the shares the authenticated principal has created,
+  // both as owner and creator. If a filter is specified, only
+  // shares satisfying the filter MUST be returned.
+  rpc ListShares(ListSharesRequest) returns (ListSharesResponse);
+  // Updates a share.
+  // MUST return CODE_NOT_FOUND if the share reference does not exist.
+  rpc UpdateShare(UpdateShareRequest) returns (UpdateShareResponse);
+  // List all shares the authenticated principal has received.
+  rpc ListReceivedShares(ListReceivedSharesRequest) returns (ListReceivedSharesResponse);
+  // Update the received share to change the share state or the display name.
+  // MUST return CODE_NOT_FOUND if the share reference does not exist.
+  rpc UpdateReceivedShare(UpdateReceivedShareRequest) returns (UpdateReceivedShareResponse);
+}
+
+message CreateShareRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 1;
+  // REQUIRED.
+  // The unique identifier for the shared storage resource.
+  cs3.storageproviderv0alpha.ResourceId resource_id = 2;
+  // REQUIRED.
+  // The share grant for the share.
+  ShareGrant grant = 3;
+}
+
+message CreateShareResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 2;
+  // REQUIRED.
+  // The created share.
+  Share share = 3;
+}
+
+message UpdateShareRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 1;
+  // REQUIRED.
+
+  ShareReference ref = 2;
+  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;
+    }
+  }
+  UpdateField field = 3;
+}
+
+message UpdateShareResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 2;
+}
+
+message ListSharesRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 1;
+  // represents a filter to apply to the request.
+  message Filter {
+    enum Type {
+      LIST_SHARES_REQUEST_FILTER_TYPE_INVALID = 0;
+      LIST_SHARES_REQUEST_FILTER_TYPE_NO_FILTER = 1;
+      LIST_SHARES_REQUEST_FILTER_TYPE_RESOURCE_ID = 2;
+      LIST_SHARES_REQUEST_FILTER_TYPE_OWNER = 3;
+      LIST_SHARES_REQUEST_FILTER_TYPE_CREATOR = 4;
+      LIST_SHARES_REQUEST_FILTER_TYPE_OWNER_PROVIDER = 5;
+      LIST_SHARES_REQUEST_FILTER_TYPE_CREATOR_PROVIDER = 6;
+    }
+    Type type = 2;
+    oneof term {
+      cs3.storageproviderv0alpha.ResourceId resource_id = 3;
+      cs3.types.UserId owner = 4;
+      cs3.types.UserId creator = 5;
+    }
+  }
+  // OPTIONAL.
+  // The list of filters to apply if any.
+  repeated Filter filters = 2;
+}
+
+message ListSharesResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 2;
+  // REQUIRED.
+  // The list of shares.
+  repeated Share shares = 3;
+}
+
+message RemoveShareRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 1;
+  // REQUIRED.
+  // The reference to which the action should be performed.
+  ShareReference ref = 2;
+}
+
+message RemoveShareResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 2;
+}
+
+message GetShareRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 1;
+  // REQUIRED.
+  // The reference to which the action should be performed.
+  ShareReference ref = 2;
+}
+
+message GetShareResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 2;
+  // REQUIRED.
+  // The share.
+  Share share = 3;
+}
+
+message ListReceivedSharesRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 1;
+}
+
+message ListReceivedSharesResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 2;
+  // REQUIRED.
+  // The list of received shares.
+  repeated ReceivedShare shares = 3;
+}
+
+// TODO(labkode): clean up display_name ? we'll use storage links for that.
+message UpdateReceivedShareRequest {
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 1;
+  // REQUIRED.
+  ShareReference ref = 2;
+  message UpdateField {
+    // One of the update fields MUST be specified.
+    oneof field {
+      // Update the display name.
+      string display_name = 1;
+      // Update the share state
+      ShareState state = 2;
+    }
+  }
+  UpdateField field = 3;
+}
+
+message UpdateReceivedShareResponse {
+  // REQUIRED.
+  // The response status.
+  cs3.rpc.Status status = 1;
+  // OPTIONAL.
+  // Opaque information.
+  cs3.types.Opaque opaque = 2;
+}