// 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 "google/protobuf/timestamp.proto";
import "mfiles/api/annotations.proto";
import "mfiles/enums.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_";

// Persistent task queues and broadcast messages that vault applications use to share background
// work between the server instances of a vault.
//
// This interface provides access to vault specific task queue for adding and managing the tasks.
//
// This is the server side of the task queue API that vault applications use through the M-Files
// API (`Vault.ApplicationTaskOperations`). A vault application opens named queues, adds tasks
// with an opaque payload, and its instances on every server of the vault reserve, process and
// update them. Queues also carry broadcast messages that every consumer reads.
//
// **Who should call it.** Vault applications, through the M-Files API. An external application
// normally should not: the queues belong to the vault applications that open them, and reserving
// or updating their tasks takes work away from those applications. Use it only for queues that
// your own code owns, or read-only for diagnostics
// ([GetTaskQueues](mfiles:MFiles.IRPCApplicationTaskQueue.GetTaskQueues),
// [GetTaskIdentifiersFromQueue](mfiles:MFiles.IRPCApplicationTaskQueue.GetTaskIdentifiersFromQueue),
// [GetApplicationTasks](mfiles:MFiles.IRPCApplicationTaskQueue.GetApplicationTasks)).
//
// **Rights.** Every method needs a vault session of a user with an account in the vault and the
// vault right `change_full_control_role`, which only users with full control of the vault have; a
// normal user gets "Access denied.". The vault's internal queues, such as
// `m-files.server.core.broadcast`, are refused with "Access denied." by the methods that open,
// add to, reserve from, broadcast to or destroy a queue, but they are listed by
// [GetTaskQueues](mfiles:MFiles.IRPCApplicationTaskQueue.GetTaskQueues).
//
// **Task life cycle** ([ApplicationTaskState](mfiles:MFiles.ApplicationTaskState)):
//
// 1. [OpenTaskQueue](mfiles:MFiles.IRPCApplicationTaskQueue.OpenTaskQueue) creates the queue if
//    it does not exist. Call it before adding or reserving.
// 2. [AddTask](mfiles:MFiles.IRPCApplicationTaskQueue.AddTask) or
//    [AddScheduledTask](mfiles:MFiles.IRPCApplicationTaskQueue.AddScheduledTask) adds a task in
//    state `APPLICATION_TASK_STATE_WAITING`.
// 3. [ReserveTasksForProcessing](mfiles:MFiles.IRPCApplicationTaskQueue.ReserveTasksForProcessing)
//    moves a waiting task to `APPLICATION_TASK_STATE_IN_PROGRESS` and returns it to one caller.
// 4. [UpdateTask](mfiles:MFiles.IRPCApplicationTaskQueue.UpdateTask) reports progress and finally
//    sets `COMPLETED`, `FAILED` or `CANCELED`. An in-progress task that is not updated within its
//    restore timeout goes back to waiting and can be reserved again.
//
// The server cleans up by itself: completed tasks are deleted; failed and cancelled tasks and
// broadcast messages after a day; and queues that have not been used for seven days, together with
// their tasks.
service IRPCApplicationTaskQueue {
	option (mfiles.api.service) = { book: "integration" level: LEVEL_SPECIALIZED title: "Application task queue" };

	// Creates a task queue if it does not exist, or confirms an existing one.
	//
	// - Safe to call repeatedly; there is no close call. Opening a queue that exists with a
	//   different `queue_behavior` fails with "The parameter is incorrect.".
	// - Requires a vault session and the vault right `change_full_control_role`. Internal queue IDs
	//   are refused with "Access denied.".
	rpc OpenTaskQueue( OpenTaskQueueRequest ) returns ( OpenTaskQueueResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a task to a task queue, ready to be reserved at once.
	//
	// - The queue must have been opened with
	//   [OpenTaskQueue](mfiles:MFiles.IRPCApplicationTaskQueue.OpenTaskQueue); otherwise the call fails
	//   with "The task queue is not open.".
	// - Requires a vault session and the vault right `change_full_control_role`.
	rpc AddTask( AddTaskRequest ) returns ( AddTaskResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Reserves the next waiting task from each of the given queues for the caller to process.
	//
	// - Returns at most one task per queue, already in state `APPLICATION_TASK_STATE_IN_PROGRESS`;
	//   queues with nothing to do contribute nothing. Call it again to get more tasks.
	// - From a sequential queue, no task is returned while another task of that queue is in progress.
	// - Tasks added with [AddScheduledTask](mfiles:MFiles.IRPCApplicationTaskQueue.AddScheduledTask)
	//   are not returned before their activation time.
	// - Every queue must be open ("The task queue is not open." otherwise), and the same queue ID must
	//   not appear twice. Requires a vault session and the vault right `change_full_control_role`.
	rpc ReserveTasksForProcessing( ReserveTasksForProcessingRequest ) returns ( ReserveTasksForProcessingResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Reports the progress or the final state of a task.
	//
	// - Allowed changes: an in-progress task can stay in progress (progress update) or become
	//   `COMPLETED`, `FAILED` or `CANCELED`; a waiting task can only be cancelled. A task in a final
	//   state cannot change, and no call can set `WAITING` or `IN_PROGRESS`. Other changes fail with
	//   "Invalid transition of application task ...".
	// - Update an in-progress task at least once within its restore timeout to keep it reserved.
	// - An unknown task ID fails with "Not found.". Requires a vault session and the vault right
	//   `change_full_control_role`.
	rpc UpdateTask( UpdateTaskRequest ) returns ( UpdateTaskResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the IDs of all task queues of the vault.
	//
	// - For diagnostics. Includes the vault's internal queues.
	// - Requires a vault session and the vault right `change_full_control_role`.
	rpc GetTaskQueues( GetTaskQueuesRequest ) returns ( GetTaskQueuesResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the IDs of the tasks of a queue that are in the given states.
	//
	// - For diagnostics; reserves nothing. An unknown queue returns an empty list.
	// - Requires a vault session and the vault right `change_full_control_role`.
	rpc GetTaskIdentifiersFromQueue( GetTaskIdentifiersFromQueueRequest ) returns ( GetTaskIdentifiersFromQueueResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets tasks by ID without reserving them.
	//
	// - For diagnostics: the returned states can change at any time. Tasks that no longer exist are
	//   left out, so the response can be shorter than the request.
	// - Requires a vault session and the vault right `change_full_control_role`.
	rpc GetApplicationTasks( GetApplicationTasksRequest ) returns ( GetApplicationTasksResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Sends a broadcast message through a task queue to every consumer of that queue.
	//
	// - Consumers read new messages with
	//   [GetNewBroadcastMessages](mfiles:MFiles.IRPCApplicationTaskQueue.GetNewBroadcastMessages).
	//   Messages are removed by the server after a day.
	// - Requires a vault session and the vault right `change_full_control_role`. Internal queue IDs
	//   are refused with "Access denied.".
	rpc SendBroadcastMessage( SendBroadcastMessageRequest ) returns ( SendBroadcastMessageResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the ID of the newest broadcast message of each given queue.
	//
	// - A consumer that starts calls this once and then passes the IDs to
	//   [GetNewBroadcastMessages](mfiles:MFiles.IRPCApplicationTaskQueue.GetNewBroadcastMessages) to
	//   receive only messages sent after that point.
	// - Requires a vault session and the vault right `change_full_control_role`.
	rpc GetLatestBroadcastMessageIdentifiers( GetLatestBroadcastMessageIdentifiersRequest ) returns ( GetLatestBroadcastMessageIdentifiersResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the broadcast messages of a queue that are newer than the given message ID.
	//
	// - Pass the ID of the last message you processed; use `0` to get all messages that still exist.
	//   An unknown queue returns an empty list.
	// - Requires a vault session and the vault right `change_full_control_role`.
	rpc GetNewBroadcastMessages( GetNewBroadcastMessagesRequest ) returns ( GetNewBroadcastMessagesResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes a task queue and all of its tasks.
	//
	// - **Destructive.** Deletes the queue and its tasks, whatever their state; meant for development
	//   and testing. Vault applications that still use the queue lose their work.
	// - Requires a vault session and the vault right `change_full_control_role`. Internal queue IDs
	//   are refused with "Access denied.".
	rpc ClearAndDestroyTaskQueue( ClearAndDestroyTaskQueueRequest ) returns ( ClearAndDestroyTaskQueueResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a task to a task queue that becomes available for processing at a given time.
	//
	// - Same as [AddTask](mfiles:MFiles.IRPCApplicationTaskQueue.AddTask), except that
	//   [ReserveTasksForProcessing](mfiles:MFiles.IRPCApplicationTaskQueue.ReserveTasksForProcessing)
	//   does not return the task before `activation_timestamp`.
	// - Requires a vault session and the vault right `change_full_control_role`.
	rpc AddScheduledTask( AddScheduledTaskRequest ) returns ( AddScheduledTaskResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of OpenTaskQueue.
message OpenTaskQueueRequest {

	// The ID of the queue, chosen by the application; make it unique, for example prefixed with the application's name. Leading and trailing spaces are removed.
	string queue_id = 1;

	// `APPLICATION_TASK_QUEUE_PROCESSING_BEHAVIOR_SEQUENTIAL` to process the tasks one at a time in the order they were added, or `..._CONCURRENT` to process them in parallel.
	ApplicationTaskQueueProcessingBehavior queue_behavior = 2;
}

// The response of OpenTaskQueue.
message OpenTaskQueueResponse {
}

// The request of AddTask.
message AddTaskRequest {

	// The ID of the queue.
	string queue_id = 1;

	// How long the task may stay in progress without an [UpdateTask](mfiles:MFiles.IRPCApplicationTaskQueue.UpdateTask) call before it goes back to waiting. 0 or less means 5 minutes.
	int32 restore_to_waiting_timeout_in_minutes = 2;

	// A free-form type name that tells the processor how to read `task_data`.
	string task_type = 3;

	// The payload of the task.
	bytes task_data = 4;
}

// The response of AddTask.
message AddTaskResponse {

	// The ID of the new task, a decimal number as a string.
	string task_id = 1;
}

// The request of ReserveTasksForProcessing.
message ReserveTasksForProcessingRequest {

	// The IDs of the queues to take tasks from.
	repeated string queue_id_collection = 1;
}

// The response of ReserveTasksForProcessing.
message ReserveTasksForProcessingResponse {

	// The reserved tasks, at most one per queue.
	repeated ApplicationTaskInfo task_info_collection = 1;
}

// The request of UpdateTask.
message UpdateTaskRequest {

	// The ID of the task.
	string task_id = 1;

	// The new state of the task.
	ApplicationTaskState state = 2;

	// Free-form progress information, at most 1,048,575 characters.
	string progress = 3;
}

// The response of UpdateTask.
message UpdateTaskResponse {
}

// The request of GetTaskQueues.
message GetTaskQueuesRequest {
}

// The response of GetTaskQueues.
message GetTaskQueuesResponse {

	// The queue IDs.
	repeated string queue_id_collection = 1;
}

// The request of GetTaskIdentifiersFromQueue.
message GetTaskIdentifiersFromQueueRequest {

	// The ID of the queue.
	string queue_id = 1;

	// The states to include, as a comma-separated list of [ApplicationTaskState](mfiles:MFiles.ApplicationTaskState) numbers, for example `0,1` for waiting and in progress. Must not be empty and must not repeat a state; otherwise the call fails with "The parameter is incorrect.".
	string included_states = 2;
}

// The response of GetTaskIdentifiersFromQueue.
message GetTaskIdentifiersFromQueueResponse {

	// The IDs of the matching tasks.
	repeated string task_id_collection = 1;
}

// The request of GetApplicationTasks.
message GetApplicationTasksRequest {

	// The IDs of the tasks.
	repeated string task_id_collection = 1;
}

// The response of GetApplicationTasks.
message GetApplicationTasksResponse {

	// The tasks that still exist.
	repeated ApplicationTaskInfo task_info_collection = 1;
}

// The request of SendBroadcastMessage.
message SendBroadcastMessageRequest {

	// The ID of the queue.
	string queue_id = 1;

	// A free-form type name that tells consumers how to read `broadcast_data`.
	string broadcast_type = 2;

	// The payload of the message.
	bytes broadcast_data = 3;
}

// The response of SendBroadcastMessage.
message SendBroadcastMessageResponse {
}

// The request of GetLatestBroadcastMessageIdentifiers.
message GetLatestBroadcastMessageIdentifiersRequest {

	// The IDs of the queues.
	repeated string queue_id_collection = 1;
}

// The response of GetLatestBroadcastMessageIdentifiers.
message GetLatestBroadcastMessageIdentifiersResponse {

	// The IDs of the newest broadcast messages.
	repeated string task_id_collection = 1;
}

// The request of GetNewBroadcastMessages.
message GetNewBroadcastMessagesRequest {

	// The ID of the queue.
	string queue_id = 1;

	// The ID of the newest message already processed, as a decimal string.
	string latest_broadcast_id = 2;
}

// The response of GetNewBroadcastMessages.
message GetNewBroadcastMessagesResponse {

	// The newer messages.
	repeated ApplicationBroadcastMessage broadcast_messages = 1;
}

// The request of ClearAndDestroyTaskQueue.
message ClearAndDestroyTaskQueueRequest {

	// The ID of the queue to delete.
	string queue_id = 1;
}

// The response of ClearAndDestroyTaskQueue.
message ClearAndDestroyTaskQueueResponse {
}

// The request of AddScheduledTask.
message AddScheduledTaskRequest {

	// The ID of the queue.
	string queue_id = 1;

	// As in [AddTask](mfiles:MFiles.IRPCApplicationTaskQueue.AddTask); 0 or less means 5 minutes.
	int32 restore_to_waiting_timeout_in_minutes = 2;

	// A free-form type name that tells the processor how to read `task_data`.
	string task_type = 3;

	// The payload of the task.
	bytes task_data = 4;

	// The earliest time (UTC) at which the task can be reserved.
	google.protobuf.Timestamp activation_timestamp = 5;
}

// The response of AddScheduledTask.
message AddScheduledTaskResponse {

	// The ID of the new task, a decimal number as a string.
	string task_id = 1;
}