// 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_";

// A server-to-client channel: the server pushes requests and notifications to a logged-in client
// over a long-lived stream.
//
// Some operations need something from the user while the server is processing a call, for
// example an electronic signature for a workflow state transition, or credentials for a vault
// application or external repository. The server asks for it over the push channel of the
// session, and the client answers with a separate call. M-Files clients use this service;
// applications that perform such operations interactively need it too.
//
// **Lifecycle**
//
// 1. Log in, then call [OpenServerDataPush](mfiles:MFiles.IRPCServerDataPush.OpenServerDataPush)
//    with the session's `mfiles-session-id-bin` metadata. It is a server-streaming call that stays
//    open, without messages, until the server has something to push. Do not set a short deadline
//    on it. Session assertions are not accepted.
// 2. Each session has at most one channel. Opening a new one ends the previous stream with status
//    `OK`. Logging out also ends the stream with `OK`. If the stream ends while the session is
//    still valid, open it again.
// 3. Each message is a [ServerDataPushItem](mfiles:MFiles.ServerDataPushItem). Its
//    `request_data.type` tells what it is:
//    - `SERVER_DATA_PUSH_REQUEST_TYPE_ELECTRONIC_SIGNATURE_REQUEST`: sign an operation. Needs a
//      response.
//    - `SERVER_DATA_PUSH_REQUEST_TYPE_EXTENSION_AUTHENTICATION_REQUEST`: authenticate the user to a
//      vault application or external repository. Needs a response.
//    - `SERVER_DATA_PUSH_REQUEST_TYPE_OBJECTS_CHANGED_NOTIFICATION`: object versions that the
//      server changed on behalf of this session; refresh any cached copies. No response.
// 4. Answer a request with
//    [SendDataPushResponse](mfiles:MFiles.IRPCServerDataPush.SendDataPushResponse), passing its
//    `response_id`. If preparing the answer takes time (the user is typing), send
//    [SendPushDataPendingHeartbeat](mfiles:MFiles.IRPCVault.SendPushDataPendingHeartbeat) with the
//    same ID every few seconds.
//
// **Timing.** While the original call waits for the answer, the server gives up, and fails the
// original call, if the request is not delivered to an open channel within about 10 seconds, or
// if neither an answer nor a heartbeat arrives within about 35 seconds. In the latter case the
// server also closes the push channel; open it again. When the waiting call holds a database
// transaction, the server waits at most about 20 seconds and then fails the call with an error
// that asks the client to retry it. These are server defaults that administrators can change.
//
// **Open the channel early.** Operations that need a response from the client fail if the session
// has never opened a push channel. Requests that arrive while no stream is open are queued and
// delivered when the next stream opens.
service IRPCServerDataPush {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Server push" };

	// Opens the session's push channel: a stream of requests and notifications from the server.
	//
	// - Requires a vault session in `mfiles-session-id-bin`; without one the call fails with
	//   `UNAUTHENTICATED`. No special vault rights are needed.
	// - The stream has no deadline on the server side and sends nothing while there is nothing to
	//   push. It ends with status `OK` when another stream is opened for the same session or when
	//   the session logs out.
	// - Requests queued while no stream was open are sent first. A queued request whose waiting call
	//   has already given up arrives with `response_id` 0.
	// - See the service overview for the message types and the timing rules.
	rpc OpenServerDataPush( OpenServerDataPushRequest ) returns ( stream ServerDataPushItem ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Sends the client's answer to a push request received from
	// [OpenServerDataPush](mfiles:MFiles.IRPCServerDataPush.OpenServerDataPush).
	//
	// - Requires the same vault session that received the request.
	// - `id` must be the `response_id` of a request that the server is still waiting for. Any other
	//   ID, including 0, an ID of a notification, or an ID whose wait has timed out, fails with "The
	//   parameter is incorrect. (<id>)".
	// - Has the same effect as [SendPushDataResponse](mfiles:MFiles.IRPCVault.SendPushDataResponse).
	rpc SendDataPushResponse( SendDataPushResponseRequest ) returns ( SendDataPushResponseResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// Request to open the server data push channel.
message OpenServerDataPushRequest {
}

// One push message from the server: a request or a notification for the client.
message ServerDataPushItem {

	// The activity ID of the client call that caused the request, as a GUID string in braces. Use it to tie the request to the call that is waiting for it. A GUID of zeros for notifications that no call is waiting for.
	string activity_id = 1;

	// The ID to send back in [SendDataPushResponse](mfiles:MFiles.IRPCServerDataPush.SendDataPushResponse). Respond only to request types that need a response, and never when the ID is 0.
	int32 response_id = 2;

	// What the server asks for or tells. See [ServerDataPushRequest](mfiles:MFiles.ServerDataPushRequest).
	ServerDataPushRequest request_data = 3;
}

// The request of SendDataPushResponse: the client's answer to a push request.
message SendDataPushResponseRequest {

	// The `response_id` of the [ServerDataPushItem](mfiles:MFiles.ServerDataPushItem) being answered.
	int32 id = 1;

	// The answer: set `type` to the type of the request and fill the matching member of `data`, or report a failure in `error`. See [ServerDataPushResponse](mfiles:MFiles.ServerDataPushResponse).
	ServerDataPushResponse response_data = 2;
}

// Response for the SendDataPushResponse call.
message SendDataPushResponseResponse {
}