/*
Proto contract of Files API module.
This is a collection that allows for:
- Managing (image) files

Version     Date            Author      Comment
V0.1.5      27-02-2025      KdJ         Initial Version
V0.1.6      20-06-2025      SGi         Refactor proto files
V0.1.7      07-07-2025      KdJ         Add multipart file upload
V1.3.0      02-10-2025      KdJ         Update all Id's to string values for usage as GUID string
*/

syntax = "proto3";

import "Interfaces/google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/wrappers.proto";
import "Interfaces/PrintManager/Protos/V1/bergstein.digi.printmanager.paging.proto";
import "Interfaces/PrintManager/Protos/V1/bergstein.digi.printmanager.audit.proto";
import "Interfaces/PrintManager/Protos/V1/bergstein.digi.printmanager.proto_options.proto";
import "Interfaces/Application/Protos/V1/bergstein.digi.moduleinfo.proto";

package files;

option csharp_namespace = "Bergstein.Digi.Shared.Interfaces.PrintManager.Files.Protos.V1";

// Service for creating, reading, updating, deleting files.
service FileSourceHandleService {
    
  /*
  Endpoint for creating a filesourcehandle in the system.
  The request contains both file metadata (like filename) and binary data.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filesourcehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filesourcehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc CreateFileSourceHandle (CreateFileSourceHandleRequest) returns (CreateFileSourceHandleReply) {
    option (google.api.http) = {
      post: "/files_module/v1/file_source_handle"
      body: "*"
    };
  }
    
  /*
  Endpoint for creating a filesourcehandle in the system through a stream.
  The request contains both file metadata (like filename) and binary data.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filesourcehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filesourcehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc CreateFileSourceHandleStream (stream CreateFileSourceHandleStreamRequest) returns (CreateFileSourceHandleReply) {
    option (google.api.http) = {
      post: "/files_module/v1/file_source_handle/stream"
      body: "*"
    };
  }

  /*
  Endpoint to intiate partial uploads of files in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filesourcehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filesourcehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc InitiateCreateFileSourceHandlePartial (InitiateCreateFileSourceHandlePartialRequest) returns (InitiateCreateFileSourceHandlePartialReply) {
    option (google.api.http) = {
      post: "/files_module/v1/file_source_handle_partial/initiate"
      body: "*"
    };
  }

  /*
  Endpoint to upload parts of files in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filesourcehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filesourcehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc UploadFileSourceHandlePartial (UploadFileSourceHandlePartialRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/files_module/v1/file_source_handle_partial/{id}/part/{part_number}"
      body: "*"
    };
  }

  /*
  Endpoint to complete partial uploads of files in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filesourcehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filesourcehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc CompleteCreateFileSourceHandlePartial (CompleteCreateFileSourceHandlePartialRequest) returns (CreateFileSourceHandleReply) {
    option (google.api.http) = {
      post: "/files_module/v1/file_source_handle_partial/{id}/complete"
      body: "*"
    };
  }

  /*
  Endpoint for a getting a single filesourcehandle in the system.

  This is only accessible for Administrator accounts or the requesting user.

  Returns on a success:
  - the requested filesourcehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - NOT_FOUND (5) status when the requested filesourcehandle (ID), to fetch, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc GetFileSourceHandle (GetFileSourceHandleRequest) returns (GetFileSourceHandleReply) {
    option (google.api.http) = {
      get: "/files_module/v1/file_source_handle/{id}"
    };
  }

  /*
  Endpoint for getting all the filesourcehandles in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - list of registered filesourcehandles

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc ListFileSourceHandle (ListFileSourceHandleRequest) returns (ListFileSourceHandleReply) {
    option (google.api.http) = {
      get: "/files_module/v1/file_source_handle"
    };
  }

  /*
  Endpoint for updating a registered filesourcehandle in the system.

  This is only accessible for Administrator accounts or the requesting user.

  Returns on a success:
  - the updated filesourcehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filesourcehandle fields no not fall within the set format/limits.
  - NOT_FOUND (5) status when the requested filesourcehandle (ID), to update, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc UpdateFileSourceHandle (UpdateFileSourceHandleRequest) returns (UpdateFileSourceHandleReply) {
    option (google.api.http) = {
      patch: "/files_module/v1/file_source_handle"
      body: "*"
    };
  }

  /*
  Endpoint for deleting a registered filesourcehandle in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - nothing; OK status (0)

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - NOT_FOUND (5) when the requested filesourcehandle (ID), to remove, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc DeleteFileSourceHandle (DeleteFileSourceHandleRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/files_module/v1/file_source_handle/{id}"
    };
  }

    /*
    Endpoint for subscribing on an event when a file source handle is updated.

    Returns on a success:
    - a stream of FileSourceHandle(s); OK status (0)

    Returns on a failure:
    - CANCELLED (1); status when you abort the call. 
    - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
    - UNAUTHENTICATED (16) status when you do not provide a valid access token (when Authentication is enabled)
    */
    rpc OnFileSourceHandleUpdated (SubscribeOnFileSourceHandleUpdated) returns (stream FileSourceHandleUpdated) {

    }    

    /*
    Endpoint for subscribing on an event when a file source handle is created.

    Returns on a success:
    - a stream of FileHandle(s); OK status (0)

    Returns on a failure:
    - CANCELLED (1); status when you abort the call. 
    - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
    - UNAUTHENTICATED (16) status when you do not provide a valid access token (when Authentication is enabled)
    */
    rpc OnFileSourceHandleCreated (SubscribeOnFileSourceHandleCreated) returns (stream FileSourceHandleCreated) {

    }

    /*
    Endpoint for subscribing on an event when a file source handle is deleted.

    Returns on a success:
    - a stream of FileHandle(s); OK status (0)

    Returns on a failure:
    - CANCELLED (1); status when you abort the call. 
    - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
    - UNAUTHENTICATED (16) status when you do not provide a valid access token (when Authentication is enabled)
    */
    rpc OnFileSourceHandleDeleted (SubscribeOnFileSourceHandleDeleted) returns (stream FileSourceHandleDeleted) {

    }
}

// The create filesourcehandle request. 
message CreateFileSourceHandleRequest {
  // The id of the handle.
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
  // The name of the file.
  string file_name = 2;
  // The type of the file (extension).
  FileType file_type = 3;
  // file data as binary data.
  bytes file_data = 4;
}

// The create filesourcehandle stream request. 
message CreateFileSourceHandleStreamRequest {
  // The id of the handle.
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
  // The name of the file.
  string file_name = 2;
  // The type of the file (extension).
  FileType file_type = 3;
  // file data as binary data
  bytes chunk_data = 4;
}

// The initial message to start a multipart file source creation
message InitiateCreateFileSourceHandlePartialRequest
{
  // The name of the file.
  string file_name = 1;
  // The type of the file.
  FileType file_type = 2;
  // The size of the file (in bytes).
  uint64 file_size = 3;
  // The max chunk size of the client (in bytes)
  uint64 max_chunk_size = 4;
  // The hash of the completed file
  // The maximum length is 160 characters (160 bits for sha1).
  string hash = 5;
}

// The reply to start a multipart file source creation
message InitiateCreateFileSourceHandlePartialReply
{
  // The id of the file.
  string creation_id = 1 [(proto_options.field_attributes) = IS_GUID];
  // The size of each chunk
  uint64 chunk_size = 2;
  // A unique key that we use for this file
  string key = 3;
  // A list of uris to upload the file to
  repeated PresignedPartUri uris = 4;
}

// Represents a single part of the file source creation along with its upload URL.
message PresignedPartUri
{
    // The part number of the file
    uint64 part_number = 1;
    // The uri to upload the file part to
    string uri = 2;
}

// The upload part request. 
message UploadFileSourceHandlePartialRequest
{
  // The key to double check
  string key = 1;
  // The hash for this set of data
  string hash = 2;
  // file data as binary data
  bytes chunk_data = 3;
  // Id of the session
  string id = 4 [(proto_options.field_attributes) = IS_GUID];
  // Part number for this part
  uint64 part_number = 5;
}

// Sent by the client to finalize the creation and trigger the server to stitch the parts together.
message CompleteCreateFileSourceHandlePartialRequest
{
    // The id of the file.
    string id = 1 [(proto_options.field_attributes) = IS_GUID];
    // The key for this file
    string key = 2;
    // A list of completed parts
    repeated CompletedPart parts = 3;
}

// Identifies a successfully created part, required to finalize the creation
message CompletedPart
{
    // The part number
    uint64 part_number = 1;
    // Hash/checksum for the part, so we can make sure it was sent correctly
    string hash = 2;
}

// The enum options of the type of upload.
enum UploadType {
  // Unknown.
  UPLOAD_TYPE_UNKNOWN = 0;
  // Normal upload.
  UPLOAD_TYPE_NORMAL = 1;
  // Stream upload.
  UPLOAD_TYPE_STREAM = 2;
  // Multipart upload.
  UPLOAD_TYPE_MULTIPART = 3;
}

enum UploadMode {
  // Unknown.
  UPLOAD_MODE_UNKNOWN = 0;
  // Create
  UPLOAD_MODE_CREATE = 1;
  // Update
  UPLOAD_MODE_UPDATE = 2;
}

// The get filesourcehandle request.
message GetFileSourceHandleRequest {
  // The matching Id of the filesourcehandle to get.
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
}

// A request for listing all filesourcehandles.
message ListFileSourceHandleRequest {
  shared.PagingRequest paging = 1;
  bool descending = 2;
  FileSourceHandle order = 3;
  FileSourceHandle filter = 4;
}

// The update filesourcehandle request.
message UpdateFileSourceHandleRequest {
  // The filesourcehandle entity to update. Matches on the Id field.
  FileSourceHandle file_source_handle = 1;
}

// The delete filesourcehandle request
message DeleteFileSourceHandleRequest {
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
}

// The filesourcehandle Reply.
message GetFileSourceHandleReply {
  // The filesourcehandle entity.
  FileSourceHandle file_source_handle = 1;
}

// The filesourcehandle Reply.
message CreateFileSourceHandleReply {
  // The filesourcehandle entity.
  FileSourceHandle file_source_handle = 1;
}

// The filesourcehandle Reply.
message UpdateFileSourceHandleReply {
  // The filesourcehandle entity.
  FileSourceHandle file_source_handle = 1;
}

// The filesourcehandles Reply.
message ListFileSourceHandleReply {
  // The collection of filesourcehandles.
  repeated FileSourceHandle file_source_handles = 1;
  shared.PagingReply paging = 2;
}

// Status of the file upload for use of streams
message FileUploadStatus {
    uint32 percentage_complete = 1;
    bool is_complete = 2;
}

// The file source handle entity.
message FileSourceHandle {
  // The id of the handle.
  string id = 1 [
      (proto_options.field_attributes) = IS_GUID,
      (proto_options.field_attributes) = IS_PRIMARY_KEY
  ];
  // The name of the file. This is used to visually identify the file. Minimum length is 3 and the maximum is 50 characters.
  string name = 2;
  // The file extension type.
  FileType type = 3;
  // The associated file handles.
  repeated FileHandle file_handles = 4;
  // The audit information about this entity.
  shared.Audit audit = 5;
}

// The subscribe request 
message SubscribeOnFileSourceHandleUpdated {
  repeated string filter_file_source_handle_ids = 1;
}

message FileSourceHandleUpdated {
  FileSourceHandle file_source_handle = 1;
}

// The subscribe request 
message SubscribeOnFileSourceHandleCreated {
  repeated string filter_file_handle_ids = 1;
}

message FileSourceHandleCreated {
  FileSourceHandle file_source_handle = 1;
}

// The subscribe request 
message SubscribeOnFileSourceHandleDeleted {
  repeated string filter_file_handle_ids = 1;
}

message FileSourceHandleDeleted {
  FileSourceHandle file_source_handle = 1;
}

// Service for creating, reading, updating, deleting filehandles.
service FileHandleService {
    
  /*
  Endpoint for creating a filehandle in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc CreateFileHandle (CreateFileHandleRequest) returns (CreateFileHandleReply) {
    option (google.api.http) = {
      post: "/files_module/v1/file_handle"
      body: "*"
    };
  }

  /*
  Endpoint to intiate partial uploads of files in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc InitiateCreateFileHandlePartial (InitiateCreateFileHandlePartialRequest) returns (InitiateCreateFileHandlePartialReply) {
    option (google.api.http) = {
      post: "/files_module/v1/file_handle_partial/initiate"
      body: "*"
    };
  }

  /*
  Endpoint to upload parts of files in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc UploadFileHandlePartial (UploadFileHandlePartialRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/files_module/v1/file_handle_partial/{id}/part/{part_number}"
      body: "*"
    };
  }

  /*
  Endpoint to complete partial uploads of files in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - the created filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filehandle fields no not fall within the set format/limits.
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc CompleteCreateFileHandlePartial (CompleteCreateFileHandlePartialRequest) returns (CreateFileHandleReply) {
    option (google.api.http) = {
      post: "/files_module/v1/file_handle_partial/{id}/complete"
      body: "*"
    };
  }

  /*
  Endpoint for a getting a single filehandle in the system.

  This is only accessible for Administrator accounts or the requesting user.

  Returns on a success:
  - the requested filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - NOT_FOUND (5) status when the requested filehandle (ID), to fetch, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc GetFileHandle (GetFileHandleRequest) returns (GetFileHandleReply) {
    option (google.api.http) = {
      get: "/files_module/v1/file_handle/{id}"
    };
  }

  /*
  Endpoint for getting all the filehandles in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - list of registered filehandles

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc ListFileHandle (ListFileHandleRequest) returns (ListFileHandleReply) {
    option (google.api.http) = {
      get: "/files_module/v1/file_handle"
    };
  }

  /*
  Endpoint for updating a registered filehandle in the system.

  This is only accessible for Administrator accounts or the requesting user.

  Returns on a success:
  - the updated filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INVALID_ARGUMENT status when the one or more filehandle fields no not fall within the set format/limits.
  - NOT_FOUND (5) status when the requested filehandle (ID), to update, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc UpdateFileHandle (UpdateFileHandleRequest) returns (UpdateFileHandleReply) {
    option (google.api.http) = {
      patch: "/files_module/v1/file_handle"
      body: "*"
    };
  }

  /*
  Endpoint for deleting a registered filehandle in the system.

  This is only accessible for Administrator accounts.

  Returns on a success:
  - nothing; OK status (0)

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - NOT_FOUND (5) when the requested filehandle (ID), to remove, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc DeleteFileHandle (DeleteFileHandleRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/files_module/v1/file_handle/{id}"
    };
  }
  
  /*
  Endpoint for a downloading a single filehandle in the system.

  This is only accessible for Administrator accounts or the requesting user.

  Returns on a success:
  - the requested filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - NOT_FOUND (5) status when the requested filehandle (ID), to fetch, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc DownloadFileHandle (DownloadFileHandleRequest) returns (DownloadFileHandleReply) {
    option (google.api.http) = {
      get: "/files_module/v1/file_handle/{id}/download"
    };
  }
  
  /*
  Endpoint for a downloading a single filehandle in the system.

  This is only accessible for Administrator accounts or the requesting user.

  Returns on a success:
  - the requested filehandle

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - NOT_FOUND (5) status when the requested filehandle (ID), to fetch, was not found
  - PERMISSION_DENIED (7) status when you do not have the right role
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  - UNAUTHENTICATED (16) status when you do not provide the required access token
  */
  rpc DownloadFileHandleStream (DownloadFileHandleStreamRequest) returns (stream DownloadFileHandleStreamReply) {
    option (google.api.http) = {
      get: "/files_module/v1/file_handle/{id}/download_stream"
    };
  }

    /*
    Endpoint for subscribing on an event when a file handle is updated.

    Returns on a success:
    - a stream of FileHandle(s); OK status (0)

    Returns on a failure:
    - CANCELLED (1); status when you abort the call. 
    - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
    - UNAUTHENTICATED (16) status when you do not provide a valid access token (when Authentication is enabled)
    */
    rpc OnFileHandleUpdated (SubscribeOnFileHandleUpdated) returns (stream FileHandleUpdated) {

    }

    /*
    Endpoint for subscribing on an event when a file handle is created.

    Returns on a success:
    - a stream of FileHandle(s); OK status (0)

    Returns on a failure:
    - CANCELLED (1); status when you abort the call. 
    - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
    - UNAUTHENTICATED (16) status when you do not provide a valid access token (when Authentication is enabled)
    */
    rpc OnFileHandleCreated (SubscribeOnFileHandleCreated) returns (stream FileHandleCreated) {

    }

    /*
    Endpoint for subscribing on an event when a file handle is deleted.

    Returns on a success:
    - a stream of FileHandle(s); OK status (0)

    Returns on a failure:
    - CANCELLED (1); status when you abort the call. 
    - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
    - UNAUTHENTICATED (16) status when you do not provide a valid access token (when Authentication is enabled)
    */
    rpc OnFileHandleDeleted (SubscribeOnFileHandleDeleted) returns (stream FileHandleDeleted) {

    }
}

// The create filehandle request. The Id field should be left at 0, since this is created by the database.
message CreateFileHandleRequest {
  // The new filehandle
  FileHandle file_handle = 1;
  CreateFileSourceHandleRequest file_source_handle_request = 2;
}

// The initial message to start a multipart file  creation
message InitiateCreateFileHandlePartialRequest
{
  // The name of the file.
  string file_name = 1;
  // The type of the file.
  FileType file_type = 2;
  // The size of the file (in bytes).
  uint64 file_size = 3;
  // The max chunk size of the client (in bytes)
  uint64 max_chunk_size = 4;
  // The hash of the completed file
  // The maximum length is 160 characters (160 bits for sha1).
  string hash = 5;
  // The upload mode (create or update)
  UploadMode upload_mode = 6;
  // Storage Status
  ProcessStatus storage_status = 7;
  // Worker Status
  ProcessStatus worker_status = 8;
  // TopicType
  TopicType topic_type = 9;
  // TopicKey
  google.protobuf.StringValue topic_key = 10;
  // TopicKey checksum
  google.protobuf.StringValue topic_key_checksum = 11;
  // FileSourceHandle id
  google.protobuf.StringValue file_source_handle_id = 12;
  // File ID
  string id = 13;
}

// The reply to start a multipart file  creation
message InitiateCreateFileHandlePartialReply
{
  // The id of the file.
  string creation_id = 1 [(proto_options.field_attributes) = IS_GUID];
  // The size of each chunk
  uint64 chunk_size = 2;
  // A unique key that we use for this file
  string key = 3;
  // A list of uris to upload the file to
  repeated PresignedPartUri uris = 4;
}

// The upload part request. 
message UploadFileHandlePartialRequest
{
  // The key to double check
  string key = 1;
  // The hash for this set of data
  string hash = 2;
  // file data as binary data
  bytes chunk_data = 3;
  // Id of the session
  string id = 4 [(proto_options.field_attributes) = IS_GUID];
  // Part number for this part
  uint64 part_number = 5;
}

// Sent by the client to finalize the creation and trigger the server to stitch the parts together.
message CompleteCreateFileHandlePartialRequest
{
    // The id of the file.
    string id = 1 [(proto_options.field_attributes) = IS_GUID];
    // The key for this file
    string key = 2;
    // A list of completed parts
    repeated CompletedPart parts = 3;
}

// The get filehandle request.
message GetFileHandleRequest {
  // The matching Id of the filehandle to get.
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
}

// A request for listing all filehandles.
message ListFileHandleRequest {
  shared.PagingRequest paging = 1;
  bool descending = 2;
  FileHandle order = 3;
  FileHandle filter = 4;
}

// The update filehandle request.
message UpdateFileHandleRequest {
  // The filehandle entity to update. Matches on the Id field.
  FileHandle file_handle = 1;
  CreateFileSourceHandleRequest file_source_handle_request = 2;
}

// The delete filehandle request
message DeleteFileHandleRequest {
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
}

// A request to download the File. This is the id which is used to store this entity.  
message DownloadFileHandleRequest {
  // The id of the FileHandle.
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
  // The topic type of this file.
  TopicType topic_type = 2;
  // The topic type key is needed to retrieve TopicType, the value is optional.
  google.protobuf.StringValue topic_key = 3;
}

// A request to upload an file to the system.
message DownloadFileHandleStreamRequest {
  // The id of the FileHandle.
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
  // The topic type of this file.
  TopicType topic_type = 2;
  // The topic type key is needed to retrieve TopicType, the value is optional.
  google.protobuf.StringValue topic_key = 3;
  // file data as binary data. Max value is 10.485.760 bytes (10 MB)
  uint32 chunk_size = 4;
}

// The filehandle Reply.
message GetFileHandleReply {
  // The filehandle entity.
  FileHandle file_handle = 1;
}

// The filehandle Reply.
message CreateFileHandleReply {
  // The filehandle entity.
  FileHandle file_handle = 1;
}

// The filehandle Reply.
message UpdateFileHandleReply {
  // The filehandle entity.
  FileHandle file_handle = 1;
}

// The filehandles Reply.
message ListFileHandleReply {
  // The collection of filehandles.
  repeated FileHandle file_handles = 1;
  shared.PagingReply paging = 2;
}

// The download file reply.
message DownloadFileHandleReply {
  // The file data as a byte array.
  bytes file_data = 1;
}

// The download file reply.
message DownloadFileHandleStreamReply {
  // The id of the FileHandle.
  string id = 1 [(proto_options.field_attributes) = IS_GUID];
  // The file data as a byte array.
  bytes chunk_data = 2;
}

// The file handle entity which is a derivative of the file source handle and actually point to the file data. 
message FileHandle {
  // The id of the handle.
  string id = 1 [
      (proto_options.field_attributes) = IS_GUID,
      (proto_options.field_attributes) = IS_PRIMARY_KEY
  ];
  // The id of source file handle.
  google.protobuf.StringValue file_source_handle_id = 2 [(proto_options.field_attributes) = IS_GUID];
  // The source file handle.
  FileSourceHandle file_source_handle = 3;
  // The file extension type.
  FileType file_type = 4;
  // The topic type (subject).
  TopicType topic_type = 5;
  // The optional sub key of the TopicType. When used, this is a key that is auto incremented and managed by the external provider.
  google.protobuf.StringValue topic_key = 6;
  // The optional sub key identifier of the TopicType. When used, this is a unique value for the key that is used to verify external data validity.
  google.protobuf.StringValue topic_key_checksum = 7;
  // The worker process status of this file handle.
  ProcessStatus worker_status = 8;
  // The storage process status of this file handle.
  ProcessStatus storage_status = 9;
  // The audit information about this entity.
  shared.Audit audit = 10;
}

// The subscribe request 
message SubscribeOnFileHandleUpdated {
  repeated string filter_file_handle_ids = 1;
}

message FileHandleUpdated {
  FileHandle file_handle = 1;
}

// The subscribe request 
message SubscribeOnFileHandleCreated {
  repeated string filter_file_handle_ids = 1;
}

message FileHandleCreated {
  FileHandle file_handle = 1;
}

// The subscribe request 
message SubscribeOnFileHandleDeleted {
  repeated string filter_file_handle_ids = 1;
}

message FileHandleDeleted {
  FileHandle file_handle = 1;
}

// The enum options of the type of storage for the associated File.
enum FileType {
  // The file type is unknown and therefore invalid. This can only arise when the file type could not be recognized by the system.
  FILE_TYPE_UNKNOWN = 0;
  // Print document format (upload file type).
  FILE_TYPE_PDF = 1;
  // ISI format (Rasterization result type).
  FILE_TYPE_ISI = 2;
  // DIGI Print format.
  FILE_TYPE_TIFF = 3;
  // Collected DIGI print format.
  FILE_TYPE_DJOB = 4;
  // Bitmap format (for generating preview).
  FILE_TYPE_BMP = 5;
  // Portable Network Graphics (PNG).
  FILE_TYPE_PNG = 6;
  // Archive format.
  FILE_TYPE_ZIP = 7;
}

// The enum options of the Topic Types.
enum TopicType {
  // The Original, unprocessed file.
  TOPIC_TYPE_SOURCE = 0;
  // The thumbnail of the original file in .png format.
  TOPIC_TYPE_THUMBNAIL = 1;
  // The Rasterization result for a specific job template based on the original file in .zip format.
  TOPIC_TYPE_RASTERIZED = 2;
  // The Intermediate result for a rasterized file.
  TOPIC_TYPE_INTERMEDIATE = 3;
}

// The status of the file source handle.
enum ProcessStatus {
    // Status indicating the file hasn't been processed yet. Either it was just initialized or it's awaiting another stage.
    PROCESS_STATUS_UNPROCESSED = 0;
    // Status indicating the file is queued for processing.
    PROCESS_STATUS_QUEUED = 1;
    // Status indicating the file is currently being processed.
    PROCESS_STATUS_IN_PROGRESS = 2;
    // Status indicating the file is queued for processing.
    PROCESS_STATUS_FINISHED = 3;
    // Status indicating the file was rejected. The reason for the rejection can be retrieved from the logs.
    PROCESS_STATUS_REJECTED = 4;
    // Status indicating the file processing encountered an unknown/unhandled internal error. The reason for the error can be retrieved from the logs.
    PROCESS_STATUS_ERROR = 5;
}

// Service for reading info about the module configurations
service FilesModuleInfoService {

  /*
  Endpoint for getting info about the this module.

  Returns on a success:
  - Info about this module

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  */
  rpc GetModuleInfo (google.protobuf.Empty) returns (module_info.ModuleInfoReply) {
    option (google.api.http) = {
      get: "/files_module/v1/module_info"
    };
  }

  /*
  Endpoint for getting the Feature Flag values of this module.

  Returns on a success:
  - list with the Feature Flags and their values.

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  */
  rpc GetFeatureFlags (google.protobuf.Empty) returns (module_info.FeatureFlagsReply) {
    option (google.api.http) = {
      get: "/files_module/v1/feature_flags"
    };
  }

  /*
  Endpoint for getting the Release Notes of this module.

  Returns on a success:
  - the release notes

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  */
  rpc GetReleaseNotes (google.protobuf.Empty) returns (module_info.ReleaseNotesReply) {
    option (google.api.http) = {
      get: "/files_module/v1/release_notes"
    };
  }  

  /*
  Endpoint for getting the Health Checks for this module.

  Returns on a success:
  - a list with healthchecks and their respective status.

  Returns on a failure:
  - CANCELLED (1) status when you abort the call
  - INTERNAL (13) status when something went wrong on the server (please contact your administrator in this case)
  */
  rpc GetHealthChecks (google.protobuf.Empty) returns (module_info.HealthChecksReply) {
    option (google.api.http) = {
      get: "/files_module/v1/health_checks"
    };
  }
}