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

// An interface for testing connection between a client and the server.
//
// This interface offers simple methods to test if a connection is valid,
// either to the server (without a need to login) or to a specific vault
// (requires login).
//
// Connectivity, throughput and health checks. Each method checks one thing and returns; none of them
// reads or changes objects or metadata, and several need no session at all.
//
// | Job | Methods | Session |
// |---|---|---|
// | Round-trip time to the server | `TestConnectionToServer` | None |
// | Is the vault session still valid? | `TestConnectionToVault` | Vault |
// | Download and upload throughput | `DownloadTestFile_Begin`, `UploadTestFile_Begin` | Vault |
// | Is a vault ready? (load balancers) | `CheckVaultHealthAnonymous`, `TestVaultAvailability` | None |
// | Is the server ready? | `CheckServerHealthAnonymous` | None |
// | Which server check fails? | `GetServerHealth` | Any |
// | Connection from this server to another | `TestConnectionToRemoteServer` | None |
//
// Where another service is the better choice:
//
// - To find out whether the server answers and which version it runs, call
//   [QueryVersion](mfiles:MFiles.IRPCQueryVersion.QueryVersion). It needs no session either and is
//   the usual first call of a client. Use `TestConnectionToServer` when you want to time repeated
//   round trips with an empty request and response.
// - To keep a session from expiring, call [KeepAlive](mfiles:MFiles.IRPCLogin.KeepAlive).
//   `TestConnectionToVault` checks the session but does not extend its lifetime.
//
// Errors follow the usual pattern: a missing, invalid or logged-out session is reported as gRPC
// status `UNAUTHENTICATED` without error trailers, and every other failure as `UNKNOWN` with the
// M-Files error stack in the `mfiles-error-serialized-bin` trailer. See
// [Errors](https://developer.m-files.com/APIs/gRPC-API/runtime/errors/) and
// [Connecting to the server](https://developer.m-files.com/APIs/gRPC-API/runtime/connecting/).
service IRPCTest {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Connection and health checks" };

	// Does nothing and returns at once. Use it to check that calls reach the server and to measure the
	// round-trip time.
	//
	// Needs no session; an `mfiles-session-id-bin` header, if sent, is ignored. The request and the
	// response are empty, so the time a call takes is the network round trip plus the server's minimal
	// call overhead.
	//
	// The first call on a new channel also includes setting up the connection (on a local server, about
	// 18 ms against about 1 ms for the calls after it), so leave it out of round-trip measurements.
	rpc TestConnectionToServer( TestConnectionToServerRequest ) returns ( TestConnectionToServerResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE highlighted: true };
	}

	// Checks that the session is a valid vault session, and does nothing else.
	//
	// Send the session in `mfiles-session-id-bin`. The call succeeds with an empty response while the
	// session is valid. A missing, unknown or logged-out session fails with `UNAUTHENTICATED`.
	// A server-level session (opened with the all-zero vault GUID) fails with `E_MFILES_LOGIN_REQUIRED`
	// ("Login required.").
	//
	// This is the cheapest way to find out whether a session is still usable before a batch of work, and
	// to measure the round-trip time of authenticated vault calls. It does not reset the session's idle
	// timer: keep the session open with [KeepAlive](mfiles:MFiles.IRPCLogin.KeepAlive).
	rpc TestConnectionToVault( TestConnectionToVaultRequest ) returns ( TestConnectionToVaultResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION highlighted: true };
	}

	// Asks this server to connect to another M-Files Server and call `TestConnectionToServer` there.
	// Normally disabled.
	//
	// Needs no session. Unless the server enables cached replica connections, which is normally
	// disabled, the call fails with `E_MFILES_CONFIGURING_REPLICA_VAULTS_NOT_ALLOWED` ("M-Files no
	// longer supports the creation of replica vaults."). That check comes first, so the server makes no
	// connection in that case. Applications have no use for this method; to test your own connection to
	// a server, call [TestConnectionToServer](mfiles:MFiles.IRPCTest.TestConnectionToServer) on that
	// server.
	rpc TestConnectionToRemoteServer( TestConnectionToRemoteServerRequest ) returns ( TestConnectionToRemoteServerResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Checks that a vault on this server is online and that its database and file data storage can be
	// accessed. No session needed.
	//
	// Needs no session; an `mfiles-session-id-bin` header, if sent, is ignored. The call succeeds with an
	// empty response when the vault passes the checks.
	//
	// When the vault is fully online, the server checks that the vault database and the vault's file
	// data storage can be accessed. A failed check returns the error code of the failure, with any
	// details replaced by `********`.
	//
	// When the vault is not fully online, or the server is shutting down, the result depends on
	// `check_online_status`:
	//
	// - `false`: the call succeeds without checking anything. Use this when an offline vault is not an
	//   error for you.
	// - `true`: the call fails with `E_MFILES_SHUTDOWN_IN_PROGRESS`, `E_MFILES_VAULT_OFFLINE`,
	//   `E_MFILES_VAULT_GOING_OFFLINE` or `E_MFILES_VAULT_NOT_READY` (the vault is still starting).
	//   The exception is a vault taken offline by its scheduled optimization job: the call succeeds.
	//
	// An unknown vault GUID fails with `E_MFILES_UNKNOWN_VAULT` ("The specified document vault does not
	// exist.", with the detail `Vault ID: <guid>`) whatever `check_online_status` is. An empty string
	// counts as the all-zero GUID and fails the same way; a malformed GUID fails with `E_INVALIDARG`
	// ("The parameter is incorrect.").
	//
	// For a load balancer probe, prefer
	// [CheckVaultHealthAnonymous](mfiles:MFiles.IRPCTest.CheckVaultHealthAnonymous), which is made for
	// that purpose.
	rpc TestVaultAvailability( TestVaultAvailabilityRequest ) returns ( TestVaultAvailabilityResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Creates a file of random bytes on the server and opens a download session for it, for measuring
	// download throughput.
	//
	// Needs a vault session. Without a session the call fails with `UNAUTHENTICATED`; a server-level
	// session fails with `E_MFILES_LOGIN_REQUIRED`. `file_size` must be from 0 to 52428800 (50 MiB);
	// other values fail with `E_INVALIDARG` ("The parameter is incorrect.").
	//
	// The server writes `file_size` random bytes to a temporary file of the vault; the content differs
	// on every call and does not compress. Read it like any other download:
	//
	// 1. Call this method and keep `download_id`.
	// 2. Read the blocks with
	//    [DownloadFile_ReadBlock](mfiles:MFiles.IRPCObjectOperations.DownloadFile_ReadBlock), at most
	//    4 MiB per call, and time those calls. Creating the file is part of this method, not of the
	//    reads (on a local server, `DownloadTestFile_Begin` for 50 MiB took about 200 ms).
	// 3. Close the session with
	//    [DownloadFile_Stop](mfiles:MFiles.IRPCObjectOperations.DownloadFile_Stop). When the file was read
	//    in order and the last read returned fewer bytes than requested, the server has already closed
	//    the session; `DownloadFile_Stop` still succeeds.
	//
	// The response carries only `download_id`.
	rpc DownloadTestFile_Begin( DownloadTestFile_BeginRequest ) returns ( DownloadTestFile_BeginResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true highlighted: true };
	}

	// Starts an upload whose bytes the server discards, for measuring upload throughput.
	//
	// Needs a vault session. Without a session the call fails with `UNAUTHENTICATED`; a server-level
	// session fails with `E_MFILES_LOGIN_REQUIRED`.
	//
	// The response's `upload_id` is always -1, which tells the upload methods to accept the bytes and
	// store nothing. Nothing is created, so there is nothing to clean up:
	//
	// 1. Call this method; it returns `upload_id` -1.
	// 2. Send the blocks with
	//    [UploadTempFile](mfiles:MFiles.IRPCObjectOperations.UploadTempFile), each with `upload_id` -1,
	//    `total_size_in_bytes` and the `offset` of the block, and time those calls. Each call succeeds
	//    and returns `upload_id` 0; keep using -1.
	// 3. Optionally finish with
	//    [UploadTempFileCommit](mfiles:MFiles.IRPCObjectOperations.UploadTempFileCommit) with
	//    `upload_id` -1, as a real upload would.
	//
	// Use the block size your application uses for real uploads, so that the measurement matches.
	rpc UploadTestFile_Begin( UploadTestFile_BeginRequest ) returns ( UploadTestFile_BeginResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Succeeds when the server and all its vaults have finished starting; fails otherwise. No session
	// needed.
	//
	// Needs no session. The call succeeds with an empty response when all of these hold:
	//
	// - Every vault has finished going online.
	// - Every vault that is set to be online is online.
	// - On servers that load their vaults from One DB, the latest refresh from One DB succeeded.
	//
	// Otherwise it fails with `E_FAIL` and no details. Use it as a readiness probe for the whole server,
	// for example after a restart. To see which check fails, call
	// [GetServerHealth](mfiles:MFiles.IRPCTest.GetServerHealth) with a session; to probe one vault, use
	// [CheckVaultHealthAnonymous](mfiles:MFiles.IRPCTest.CheckVaultHealthAnonymous).
	rpc CheckServerHealthAnonymous( CheckServerHealthAnonymousRequest ) returns ( CheckServerHealthAnonymousResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Runs the server health checks you select and returns the result of each.
	//
	// Needs a session. Without a session the call fails with `UNAUTHENTICATED`.
	//
	// These are the checks of
	// [CheckServerHealthAnonymous](mfiles:MFiles.IRPCTest.CheckServerHealthAnonymous), selected one by one
	// in `data_request`:
	//
	// - `vault_refresh_from_one_db`: the latest refresh of the vault list from One DB succeeded.
	// - `online_state_transition_finished_for_all_vaults`: every vault has finished going online.
	// - `all_vaults_in_correct_end_state`: every vault that is set to be online is online.
	//
	// Each of them is a `ServerHealthItem`:
	//
	// - `SERVER_HEALTH_ITEM_IGNORE` (the default): the check is not run and its result field stays
	//   `TRI_STATE_BOOLEAN_UNDEFINED`. An empty request therefore returns an empty result.
	// - `SERVER_HEALTH_ITEM_CHECK`: the check is run and its result field is `TRI_STATE_BOOLEAN_TRUE` or
	//   `TRI_STATE_BOOLEAN_FALSE`.
	// - `SERVER_HEALTH_ITEM_FAIL_IF_UNHEALTHY`: the check is run, and the call fails instead of
	//   returning `TRI_STATE_BOOLEAN_FALSE`.
	//
	// A vault that has not finished going online counts as unhealthy for both vault checks.
	rpc GetServerHealth( GetServerHealthRequest ) returns ( GetServerHealthResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Succeeds when a vault on this server is ready for use; fails otherwise. No session needed. Made for
	// load balancer health probes.
	//
	// Needs no session. The call succeeds with an empty response when the vault is fully online, its
	// database can be read and its file data storage can be accessed. A load balancer in front of
	// several servers that host the same vault can call it on each server and route traffic only to the
	// servers that answer successfully.
	//
	// Any failed check, including a vault that is offline or still starting, fails with
	// `E_MFILES_VAULT_CANT_BE_USED_RIGHT_NOW` ("The vault can't be used right now.") without further
	// details. An unknown vault GUID, an empty string and the all-zero GUID fail with
	// `E_MFILES_UNKNOWN_VAULT` ("The specified document vault does not exist."); a malformed GUID fails
	// with `E_INVALIDARG` ("The parameter is incorrect.").
	//
	// Compared with [TestVaultAvailability](mfiles:MFiles.IRPCTest.TestVaultAvailability), this method
	// always treats a vault that is not ready as a failure and never reveals why it failed.
	rpc CheckVaultHealthAnonymous( CheckVaultHealthAnonymousRequest ) returns ( CheckVaultHealthAnonymousResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE highlighted: true };
	}
}

// The request of TestConnectionToServer.
message TestConnectionToServerRequest {
}

// The response of TestConnectionToServer.
message TestConnectionToServerResponse {
}

// The request of TestConnectionToVault.
message TestConnectionToVaultRequest {
}

// The response of TestConnectionToVault.
message TestConnectionToVaultResponse {
}

// The request of TestConnectionToRemoteServer.
message TestConnectionToRemoteServerRequest {

	// The MS-RPC address of the other server. Used only where the feature is enabled.
	ServerAddress remote = 1;
}

// The response of TestConnectionToRemoteServer.
message TestConnectionToRemoteServerResponse {
}

// The request of TestVaultAvailability.
message TestVaultAvailabilityRequest {

	// The vault GUID, with or without braces, in any case.
	string vault = 1;

	// `true` to fail when the vault is not fully online; `false` to succeed without checks in that case.
	bool check_online_status = 2;
}

// The response of TestVaultAvailability.
message TestVaultAvailabilityResponse {
}

// The request of DownloadTestFile_Begin.
message DownloadTestFile_BeginRequest {

	// The size of the test file in bytes, 0 to 52428800 (50 MiB).
	int64 file_size = 1;
}

// The response of DownloadTestFile_Begin.
message DownloadTestFile_BeginResponse {

	// The download session for `DownloadFile_ReadBlock` and `DownloadFile_Stop`. Valid only with the session that started it.
	int32 download_id = 1;
}

// The request of UploadTestFile_Begin.
message UploadTestFile_BeginRequest {

	// The planned size of the test upload.
	int64 file_size = 1;
}

// The response of UploadTestFile_Begin.
message UploadTestFile_BeginResponse {

	// Always -1. Pass it to `UploadTempFile` and `UploadTempFileCommit`.
	int32 upload_id = 1;
}

// The request of CheckServerHealthAnonymous.
message CheckServerHealthAnonymousRequest {
}

// The response of CheckServerHealthAnonymous.
message CheckServerHealthAnonymousResponse {
}

// The request of GetServerHealth.
message GetServerHealthRequest {

	// Which checks to run, and whether a failed check fails the call; see Remarks.
	ServerHealthRequest data_request = 1;
}

// The response of GetServerHealth.
message GetServerHealthResponse {

	// One result per check. A check that was not requested is `TRI_STATE_BOOLEAN_UNDEFINED`. `vault_refresh_from_one_db_succeeded` is also `TRI_STATE_BOOLEAN_UNDEFINED` on servers that do not use One DB, which is the normal case on premises.
	ServerHealthResult data_result = 1;
}

// The request of CheckVaultHealthAnonymous.
message CheckVaultHealthAnonymousRequest {

	// The vault GUID, with or without braces, in any case.
	string guid = 1;
}

// The response of CheckVaultHealthAnonymous.
message CheckVaultHealthAnonymousResponse {
}