Joscha Schmiedt
--- a/proto/caosdb/file_transmission/v1alpha1/file_transmission.proto 0 → 100644

+ 201

− 0
+++ b/proto/caosdb/file_transmission/v1alpha1/file_transmission.proto 0 → 100644

+ 201

− 0
+//
+// This file is a part of the LinkAhead Project.
+//
+// Copyright (C) 2021-2022 Timm Fitschen <t.fitschen@indiscale.com>
+// Copyright (C) 2025 Joscha Schmiedt <joscha@schmiedt.dev>
+// Copyright (C) 2021-2025 IndiScale GmbH <info@indiscale.com>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+//
+
+// This is the main file of the caosdb.entity.v1 package.
+syntax = "proto3";
+package caosdb.file_transmission.v1alpha1;
+
+option cc_enable_arenas = true;
+option java_multiple_files = true;
+option java_package = "org.caosdb.api.file_transmission.v1";
+
+///////////////////////////////////////////////////////////////////////////
+// File transmission
+///////////////////////////////////////////////////////////////////////////
+
+// Stores a single chunk of a file
+message FileChunk {
+  // Temporary identifier containing the file and registration_id.
+  FileTransmissionId file_transmission_id = 1;
+  // Binary data of a chunk.
+  bytes data = 2;
+}
+
+// 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;
+}
+
+// Settings for the the file transmission.
+message FileTransmissionSettings {
+  // The maximum chunk size.
+  int64 max_chunk_size = 1;
+  // The maximum file size.
+  int64 max_file_size = 2;
+}
+
+// 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;
+}
+
+// TODO: This is very similar to the Hash message in the entity API. We should discuss
+//       if and how they can be merged.
+enum ChecksumAlgorithm {
+  // The checksum algorithm is unspecified.
+  CHECKSUM_ALGORITHM_UNSPECIFIED = 0;
+  // The MD5 checksum algorithm.
+  CHECKSUM_ALGORITHM_MD5 = 1;
+  // The SHA-1 checksum algorithm.
+  CHECKSUM_ALGORITHM_SHA1 = 2;
+  // The SHA-256 checksum algorithm.
+  CHECKSUM_ALGORITHM_SHA256 = 3;
+  // The SHA-512 checksum algorithm.
+  CHECKSUM_ALGORITHM_SHA512 = 4;
+}
+
+// Checksum contains the checksum value and the algorithm used to compute it.
+message Checksum {
+  // The checksum value.
+  string checksum = 1;
+  // The algorithm used to compute the checksum.
+  ChecksumAlgorithm checksum_algorithm = 2;
+}
+
+// Information about a file which is to be uploaded.
+// TODO: This is very similar to the FileDescriptor message in the entity API with the
+//       difference that it has no relation to an entity and is purely filesystem-oriented.
+//       Maybe we should re-use FileInformation s part of the entity API?
+message FileInformation {
+  // The local filename is the filename, which is used on the client.
+  string local_filename = 1;
+  // The target filename is the filename which will be used on the server.
+  string target_filename = 2;
+  // Size of the file in bytes.
+  int64 size_bytes = 3;
+  // Checksum of the file according to the checksum algorithm.
+  Checksum checksum = 4;
+}
+
+// Register a file upload for a list of files. The server will respond with a
+// registration id and URLs to which the files can be uploaded.
+message RegisterFileUploadRequest {
+  // Information about the files to be uploaded.
+  repeated FileInformation file_information = 1;
+}
+
+// The URL to which a file should be uploaded using the given LinkAhead
+// UploadProtocolVersion.
+message UploadLocation {
+  // The URL to which the file should be uploaded.
+  string url = 1;
+}
+
+// The version of the LinkAhead upload protocol. This is currently identical to
+// the TUS protocol version.
+message UploadProtocolVersion {
+  // The major version number of the upload protocol.
+  int32 major = 1;
+  // The minor version number of the upload protocol.
+  int32 minor = 2;
+  // The patch version number of the upload protocol.
+  int32 patch = 3;
+}
+
+// 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 transmission settings for the upload.
+  FileTransmissionSettings upload_settings = 4;
+  // The version of the LinkAhead upload protocol.
+  UploadProtocolVersion version = 5;
+  // The locations where the files should be uploaded.
+  repeated UploadLocation locations = 6;
+}
+
+// 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 {
+  // Request the next chunk for this file.
+  FileTransmissionId file_transmission_id = 1;
+}
+
+// Response containing a chunk of a file.
+message FileDownloadResponse {
+  // Status of the download
+  TransmissionStatus status = 1;
+  // A single file chunk
+  FileChunk chunk = 2;
+}
+
+// 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(stream FileUploadRequest) returns (FileUploadResponse);
+  // A file download. The download has to be registered prior this rpc in the
+  // RetrieveRequest.
+  rpc FileDownload(FileDownloadRequest) returns (stream FileDownloadResponse);
+}