nitric storage proto proposal

proto/storage/v1/storage.proto

@@ -0,0 +1,124 @@
+syntax = "proto3";
+package nitric.storage.v1;
+
+// protoc plugin options for code generation
+option go_package = "github.com/nitrictech/nitric/core/pkg/api/nitric/v1";
+option java_package = "io.nitric.proto.storage.v1";
+option java_multiple_files = true;
+option java_outer_classname = "Storages";
+option csharp_namespace = "Nitric.Proto.Storage.v1";
+
+// Services for storage and retrieval of files in the form of byte arrays, such as text and binary files.
+service StorageService {
+  // Retrieve an item from a bucket
+  rpc Read (StorageReadRequest) returns (stream StorageReadResponse);
+  // Store an item to a bucket
+  rpc Write (stream StorageWriteRequest) returns (StorageWriteResponse);
+  // Delete an item from a bucket
+  rpc Delete (StorageDeleteRequest) returns (StorageDeleteResponse);
+  // Generate a pre-signed URL for direct operations on an item
+  rpc PreSignUrl (StoragePreSignUrlRequest) returns (StoragePreSignUrlResponse);
+  // List files currently in the bucket
+  rpc ListFiles (StorageListFilesRequest) returns (StorageListFilesResponse);
+  // Determine is an object exists in a bucket
+  rpc Exists (StorageExistsRequest) returns (StorageExistsResponse);
+}
+
+// Request to put (create/update) a storage item
+message StorageWriteRequest {
+  // Nitric name of the bucket to store in
+  //  this will be automatically resolved to the provider specific bucket identifier.
+  string bucket_name = 1;
+
+  // Key to store the item under
+  // Should not be changed once set in a stream
+  string key = 2;
+
+  // The order of the chunk (where in the file it belongs)
+  int32 part = 3;
+
+  // A part of the file the write
+  bytes chunk = 4;
+}
+
+// Result of putting a storage item
+message StorageWriteResponse {}
+
+// Request to retrieve a storage item
+message StorageReadRequest {
+  // Nitric name of the bucket to retrieve from
+  //  this will be automatically resolved to the provider specific bucket identifier.
+  string bucket_name = 1;
+  // Key of item to retrieve
+  string key = 2;
+}
+
+// Returned storage item
+message StorageReadResponse {
+  // The chunk number in order
+  int32 part = 1;
+
+  // The body bytes of the retrieved storage item
+  bytes chunk = 2;
+}
+
+// Request to delete a storage item
+message StorageDeleteRequest {
+  // Name of the bucket to delete from
+  string bucket_name = 1;
+  // Key of item to delete
+  string key = 2;
+}
+
+// Result of deleting a storage item
+message StorageDeleteResponse {}
+
+// Request to generate a pre-signed URL for a file to perform a specific operation, such as read or write.
+message StoragePreSignUrlRequest {
+  // Nitric name of the bucket to retrieve from
+  //  this will be automatically resolved to the provider specific bucket identifier.
+  string bucket_name = 1;
+  // Key of item to generate the signed URL for.
+  // The URL and the token it contains will only be valid for operations on this resource specifically.
+  string key = 2;
+  // Operation
+  enum Operation {
+    READ = 0;
+    WRITE = 1;
+  }
+  Operation operation = 3;
+  // Expiry time in seconds for the token included in the signed URL.
+  //  Time starts from when the access token is generated, not when this request is made.
+  //  e.g. time.Now().Add(expiry * time.Second) on the server
+  uint32 expiry = 4;
+}
+
+message StoragePreSignUrlResponse {
+  // The pre-signed url, restricted to the operation, resource and expiry time specified in the request.
+  string url = 1;
+}
+
+message StorageListFilesRequest {
+  string bucket_name = 1;
+
+  string prefix = 2;
+}
+
+message File {
+  string key = 1;
+}
+
+message StorageListFilesResponse {
+  // keys of the files in the bucket
+  repeated File files = 1;
+}
+
+message StorageExistsRequest {
+  string bucket = 1;
+  // Key of item to retrieve
+  string key = 2 [(validate.rules).string = {min_len: 1}];
+}
+
+message StorageExistsResponse {
+  bool exists = 1;
+}