WIP: file download and upload

proto/caosdb/entity/v1alpha1/main.proto

@@ -344,6 +344,39 @@ message Entity {
   // related to the transaction or the new state of the entity itself or in
   // relation to other entities or the server's state or configuration.
   repeated Message infos = 13;
+
+  // File meta data. The actual binary data has to uploaded or downloaded using the File message.
+  FileDescriptor file_descriptor = 14;
+}
+
+// The file descriptor contains the meta data of the file which describes the
+// file and where the binary data can be retrieved.
+message FileDescriptor {
+  // The corresponding file entity.
+  string entity_id = 1;
+  // The path of this file in the internal file system.
+  string path = 2;
+  // The size of the file
+  int64 size = 3;
+  // Hash sums for consistency checks
+  repeated Hash hashes = 4;
+}
+
+// This represents a hash sum of a file.
+message Hash {
+  // The algorithm of the hash sum, e.g. SHA512
+  string algorithm = 1;
+  // The value of the hash sum
+  string value = 2;
+}
+
+// Wraps an entity a associates it with a file_upload
+message EntityRequest {
+  // The entity.
+  Entity entity = 1;
+  // The transmission id (if any). Note: upload_ids are only meaningful for
+  // File entities.
+  FileTransmissionId upload_id = 2;
 }
 
 // Property of an entity. Don't confuse with an Entity with role="Property"
@@ -457,9 +490,9 @@ message TransactionRequest {
     // Single request for a retrieve transaction.
     QueryOrIdRequest retrieve_request = 1;
     // Single request for an update transaction.
-    Entity update_request = 2;
+    EntityRequest update_request = 2;
     // Single request for an insert transaction.
-    Entity insert_request = 3;
+    EntityRequest insert_request = 3;
     // Single request for a delete transaction.
     QueryOrIdRequest delete_request = 4;
   }
@@ -502,3 +535,191 @@ service EntityTransactionService {
   rpc MultiTransaction(MultiTransactionRequest)
       returns (MultiTransactionResponse);
 }
+
+////////////////////////////////////////////////////////////////////////////
+//////////// FILE UPLOAD/DOWNLOAD
+////////////////////////////////////////////////////////////////////////////
+
+// Indicates whether a registration (for upload or download) has been accepted
+// or rejected.
+enum RegistrationStatus {
+  // The registration status is unspecified.
+  REGISTRATION_STATUS_UNSPECIFIED = 0;
+  // The registration has been accepted and the client may proceed with the
+  // actual transmissions.
+  REGISTRATION_STATUS_ACCEPTED = 1;
+  // The registration has been rejected and the client should not try to
+  // proceed with the transmission.
+  REGISTRATION_STATUS_REJECTED = 2;
+}
+
+// Indicates the state of an upload or a download (a stream of chunks).
+enum TransmissionStatus {
+  // The transmission status is unspecified.
+  TRANSMISSION_STATUS_UNSPECIFIED = 0;
+  // The transmission has been successful.
+  TRANSMISSION_STATUS_SUCCESS = 1;
+  // The transmission terminated with errors.
+  TRANSMISSION_STATUS_ERROR = 2;
+  // The transmission is incomplete and the client may send/request the next chunk.
+  TRANSMISSION_STATUS_GO_ON = 3;
+}
+
+// Register a file upload indicating the total size if possible.
+message RegisterFileUploadRequest {
+  // Estimated total size of the upload.
+  int64 total_size = 1;
+}
+
+// Response of the file server upon an upload registration request.
+message RegisterFileUploadResponse {
+  // Whether the server accepted or rejected the registration.
+  RegistrationStatus status = 1;
+  // The registration id is used to identify chunks and files which belong to the same upload .
+  string registration_id = 2;
+  // The server's maximum number of parallel uploads. Requesting more uploads has undefined behavior.
+  int32 max_parallel_transmissions = 3;
+  // The server's maximum chunk size. Submitting bigger chunks has undefined behavior.
+  int64 max_chunk_size = 4;
+  // The server's maximum file size. Submitting bigger files has undefined behavior.
+  int64 max_file_size = 5;
+}
+
+// Represents a download request.
+message RegisterFileDownloadRequest {
+  // The files requested for download.
+  repeated FileIdentifier files = 1;
+  // The server's maximum chunk size. Submitting bigger chunks has undefined
+  // behavior.
+  int64 max_chunk_size = 4;
+  // The server's maximum file size. Submitting bigger files has undefined
+  // behavior.
+  int64 max_file_size = 5;
+}
+
+// Identifies a file which is to be downloaded.
+message FileIdentifier {
+  // Wraps several identifiers in order to have them as a repeatable field in other messages.
+  oneof wrapped_identifier {
+    // An entity id.
+    string entity_id = 1;
+    // A path in the internal file system
+    string path = 2;
+  }
+}
+
+// Metadata and status information of a file which is about to be downloaded.
+message FileDownloadHeader {
+  // The file identifier exactly as it has been requested during a
+  // RegisterFileDownloadRequest.
+  FileIdentifier id = 1;
+  // The file descriptor of the file.
+  FileDescriptor file_descriptor = 2;
+  // Errors for this file (e.g. MESSAGE_CODE_ENTITY_DOES_NOT_EXIST, or
+  // MESSAGE_CODE_FILE_NOT_FOUND).
+  repeated Message errors = 3;
+  // Warnings for this file.
+  repeated Message warnings = 4;
+  // Info messages for this file.
+  repeated Message infos = 5;
+}
+
+
+// Response to a download registration request.
+message RegisterFileDownloadResponse {
+  // Whether the server accepted or rejected the registration.
+  RegistrationStatus status = 1;
+  // The registration id is used to identify chunks and files which belong to
+  // the same upload .
+  string registration_id = 2;
+  // The server's maximum number of parallel downloads. Starting more parallel
+  // uploads has undefined behavior.
+  int32 max_parallel_transmissions = 3;
+  // The estimated total size of the downloaded files.
+  int64 total_size = 4;
+}
+
+// Stores a single chunk of a file
+message FileChunk {
+  // Chunk metadata.
+  FileChunkMetadata metadata = 1;
+  // Chunk id.
+  FileChunkId id = 2;
+  // Binary data of a chunk.
+  bytes data = 5;
+}
+
+// Identifies a chunk in a file transmission.
+message FileChunkId {
+  // Temporary identifier containing the file and registration_id.
+  FileTransmissionId file_transmission_id = 1;
+  // The number of this chunk. Chunks do not have to be uploaded in the correct
+  // sequence. This chunk number is used to define the order of the chunks.
+  int32 chunk_no = 3;
+}
+
+// Temporary identifier of a single file during a transmission.
+message FileTransmissionId {
+  // The registration id which has been issued by the target of the trans
+  string registration_id = 1;
+  // A temporary identifier which identifies the file of this chunk. The
+  // file_id is also used by transaction to associate entities (which are to be
+  // inserted or updated) with a binary blob.
+  string file_id = 2;
+}
+
+// Chunk metadata.
+message FileChunkMetadata {
+  // The size of this chunk
+  int64 chunk_size = 4;
+}
+
+// Request for a file upload which has been registered previously. Chunks may be send in any order.
+message FileUploadRequest {
+  // A single file chunk
+  FileChunk chunk = 1;
+}
+
+// Response of the server upon a finished FileUpload.
+message FileUploadResponse {
+  // Status of the upload.
+  TransmissionStatus status = 1;
+}
+
+// Request for a file download which has been registered previously.
+message FileDownloadRequest {
+  // Download a chunk by identifying the chunk explicitely or by letting the
+  // server decide which chunk is to be send.
+  oneof request {
+    // The registration id which has previously been issued by the server. This
+    // request means: Send any chunk
+    string registration_id = 1;
+    // An id of a chunk. The client can guess a chunk id or use one from a
+    // previous download request's next field.
+    FileChunkId chunk_id = 2;
+  }
+}
+
+// Response containing a chunk of a file.
+message FileDownloadResponse {
+  // Status of the download
+  TransmissionStatus status = 1;
+  // A single file chunk
+  FileChunk chunk = 2;
+  // The next chunk (if any)
+  FileChunkId next = 3;
+}
+
+// File Transaction Service
+service FileTransmissionService {
+  // Register a file upload. This needs to be done prior to the actual upload
+  // and prior to the transaction request which uses the uploaded files.
+  rpc RegisterFileUpload(RegisterFileUploadRequest) returns (RegisterFileUploadResponse);
+  // The actual file upload. The upload has to be registered prior to this rpc.
+  rpc FileUpload(FileUploadRequest) returns (FileUploadResponse);
+  // Register a file download. This needs to be done prior to the actual download.
+  rpc RegisterFileDownload(RegisterFileDownloadRequest) returns (RegisterFileDownloadResponse);
+  // The actual download. The download has to be registered prior this rpc.
+  rpc FileDownload(FileDownloadRequest) returns (FileDownloadResponse);
+}
+