// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";
import "mfiles/structs.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// File transfer methods that stream the file data.
//
// These methods can't be defined in the IDL, as the IDL based services support only unary methods.
//
// The two methods that stream file data to the server. They belong to the `file_ref` uploads of
// [IRPCFileTransfer](mfiles:MFiles.IRPCFileTransfer); read its overview first. Like that service,
// they work only when [ServerVaultCapabilities](mfiles:MFiles.ServerVaultCapabilities)
// `file_upload_stateless_supported` is true; otherwise the call fails with "Not implemented.".
// Stateless uploads are switched off by default in M-Files Server 26.11; upload with
// [UploadTempFile](mfiles:MFiles.IRPCObjectOperations.UploadTempFile) and
// [UploadTempFileCommit](mfiles:MFiles.IRPCObjectOperations.UploadTempFileCommit) there.
//
// Both methods take a stream of request messages: one `header`, then the data as any number of
// `file_data` chunks of a few megabytes at most, then one `end`. The server sends one response when
// the stream is complete.
service IRPCFileTransferStreaming {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Streaming file upload" };

	// Uploads a whole file by streaming its content.
	//
	// The content is sent as a stream of chunks, so neither the client nor the server needs to have the
	// whole content in one message.
	//
	// The client sends the messages in the following order:
	// 1. One header message.
	// 2. Any number of file_data messages containing the file content in order.
	// 3. One end message.
	// The upload is complete only when the end message has been received. If the request stream ends
	// without the end message, the upload is discarded.
	//
	// The server streams the content forward with a single request while it is received, so the
	// size of the file is limited by the maximum size of content Master Storage accepts in a single request
	// (the MaxSingleOperationBlobSize setting, 25 MiB by default). The call fails with ERROR_FILE_TOO_LARGE
	// before any content is stored if the declared size exceeds the limit. Larger files must be uploaded in
	// blocks with FileUploadBegin, FileUploadBlock and FileUploadEnd.
	//
	// The content should be sent in chunks of a few megabytes at most. Each file_data message is limited by
	// the maximum gRPC message size of the server.
	//
	// Without `obj_id` and `file` in the header, the result is an ended upload that you use by its
	// `file_ref`, for example in
	// [AddObjectWithFiles](mfiles:MFiles.IRPCObjectOperations.AddObjectWithFiles) or
	// [FileUploadAttach](mfiles:MFiles.IRPCFileTransfer.FileUploadAttach). With both, the content is
	// attached to that file right away, as with `FileUploadAttach`, so the object must be checked out to
	// the caller.
	rpc FileUploadWhole( stream FileUploadWholeRequest ) returns ( FileUploadWholeResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION };
	}

	// Uploads one block of a stateless file upload by streaming its data.
	//
	// The file is started with FileUploadBegin, its blocks are uploaded with this method and the file is
	// completed with FileUploadEnd (IRPCFileTransfer). The block data is sent as a stream of chunks, so
	// neither the client nor the server needs to have the whole block in one message.
	//
	// The client sends the messages in the following order:
	// 1. One header message.
	// 2. Any number of file_data messages containing the block data in order.
	// 3. One end message.
	// The block is stored only when the end message has been received. If the request stream ends without
	// the end message, the call fails and the block must be uploaded again.
	//
	// The server streams the data forward with a single request while it is received. The block
	// size is limited by the maxBlockSize returned by FileUploadBegin. Blocks may be uploaded in any order and
	// concurrently, also to different server instances. Uploading a block again replaces it.
	//
	// The data should be sent in chunks of a few megabytes at most. Each file_data message is limited by the
	// maximum gRPC message size of the server.
	//
	// Begin the upload with [FileUploadBegin](mfiles:MFiles.IRPCFileTransfer.FileUploadBegin) and
	// follow its `max_block_size` and `require_sequential_blocks`. A block index must be less than
	// 50,000 and a block must not be empty.
	rpc FileUploadBlock( stream FileUploadBlockRequest ) returns ( FileUploadBlockResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION_OR_ASSERTION };
	}
}

// A message of the FileUploadWhole request stream.
message FileUploadWholeRequest {

	oneof item {

		// The first message of the stream. Describes the upload.
		FileUploadWholeHeader header = 1;

		// A chunk of the file content.
		bytes file_data = 2;

		// The last message of the stream. Marks the upload as complete.
		FileUploadWholeEnd end = 3;
	}
}

// The first message of the FileUploadWhole request stream.
message FileUploadWholeHeader {

	// The id of the object to which the file is bound, if attaching immediately.
	//
	// If set, together with file, attach the content to this object's file immediately. If not set,
	// the content is only stored as a stateless temp file, retrievable later via the returned
	// file_ref, using a separate FileUploadAttach call. obj_id and file must either both be set or
	// both be omitted.
	ObjID obj_id = 1;

	// Information about the uploaded file, if attaching immediately.
	File file = 2;

	// The size of the whole file content in bytes. Required.
	//
	// The content must be exactly this size. Zero means an empty file. The server uses the size to reject a
	// file that exceeds the maximum upload size before any content is sent, and to stream the content
	// forward as it is received.
	uint64 file_size = 3;
}

// The last message of the FileUploadWhole request stream.
message FileUploadWholeEnd {
}

// The response of the FileUploadWhole streaming method.
message FileUploadWholeResponse {

	// The file_ref identifier of the now-ended content.
	//
	// If obj_id and file were not supplied, the content can be attached later with FileUploadAttach. If they were
	// supplied, the content has already been attached and the file_ref can't be attached to another file.
	string file_ref = 1;

	// True if information about the object after the attach was provided.
	//
	// Always false if obj_id and file were not supplied, or if the user can't see the object after the attach.
	bool is_object_info_available = 2;

	// If is_object_info_available is true, information about the object after the attach.
	ObjectVersionEx after_upload = 3;

	// Information about objects that were also updated during the operation.
	repeated ObjectVersionEx updated_objects = 4;
}

// A message of the FileUploadBlock request stream.
message FileUploadBlockRequest {

	oneof item {

		// The first message of the stream. Describes the block.
		FileUploadBlockHeader header = 1;

		// A chunk of the block data.
		bytes file_data = 2;

		// The last message of the stream. Marks the block as complete.
		FileUploadBlockEnd end = 3;
	}
}

// The first message of the FileUploadBlock request stream.
message FileUploadBlockHeader {

	// The file_ref received from FileUploadBegin.
	string file_ref = 1;

	// The zero-based index of the block within the file, in content order. Must be less than 50 000.
	int64 block_index = 2;

	// The size of the block data in bytes. Required.
	//
	// The data must be exactly this size and must not exceed the maxBlockSize returned by FileUploadBegin.
	uint64 block_size = 3;
}

// The last message of the FileUploadBlock request stream.
message FileUploadBlockEnd {
}

// The response of the FileUploadBlock streaming method.
message FileUploadBlockResponse {
}