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

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

// The M-Files Ground Link channel: a long-lived two-way stream between a Ground Link proxy and the
// M-Files Server that hosts the vault, typically in M-Files Cloud.
//
// **For M-Files components only.** M-Files Ground Link connects a vault, typically in M-Files Cloud,
// to external repositories (connectors) that run on premises. The on-premises side, a Ground Link
// proxy on an M-Files Server, opens the channel to the server that hosts the vault. Applications
// should not call this service.
//
// - **Who opens it and in which direction:** the Ground Link proxy calls
//   [OpenGroundLinkChannel](mfiles:MFiles.IRPCGroundLink.OpenGroundLinkChannel), a connection
//   from the premises to the vault's server. Over the open stream each side can send calls and
//   returns; typically the vault side calls the connector services on the premises.
// - **What flows over it:** [GroundLinkMessage](mfiles:MFiles.GroundLinkMessage)s that wrap .NET
//   remoting calls and their returns of the M-Files external connector framework. A response
//   carries the `id` of its request. The server does not interpret the messages; it hands them to
//   the vault's Ground Link application.
// - **Authentication:** no M-Files session. The call metadata names the target vault and carries a
//   secret that the vault's Ground Link application checks.
// - **Lifetime:** the channel stays open until either side closes it. The server closes all channels
//   of a vault when the vault stops accepting Ground Link connections, for example when it goes
//   offline.
service IRPCGroundLink {
	option (mfiles.api.service) = { book: "integration" level: LEVEL_SPECIALIZED title: "Ground Link channel" };

	// Opens a bi-directional Ground Link channel between the client and server.
	//
	// **For M-Files components only.** The Ground Link proxy of M-Files Ground Link opens it.
	// Applications should not call it.
	// - Bidirectional streaming call without a session; see the service overview for the required
	//   metadata. Missing vault or service metadata fails with "Vault and/or service headers are
	//   missing."; a vault that does not accept Ground Link connections (its Ground Link application
	//   is not running) fails with "Vault does not exist or is not accepting Ground Link connections.";
	//   another service name fails with "Unknown Ground Link service."; an offline vault fails with a
	//   vault-offline error.
	// - The server's initial response metadata carries `mfiles-max-message-size` (the largest message
	//   the server accepts; a larger message makes gRPC close the stream) and
	//   `mfiles-groundlink-split-message-support` = `1` (the vault side accepts a large message split
	//   into parts), plus headers from the vault's Ground Link application.
	rpc OpenGroundLinkChannel( stream GroundLinkMessage ) returns ( stream GroundLinkMessage ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE internal: true };
	}
}

// Wrapper for passing .NET remoting messages over gRPC.
message GroundLinkMessage {

	// Whether the message is a call (`REQUEST`) or the return of a call (`RESPONSE`).
	GroundLinkMessageType type = 1;

	// The ID of the call. A response carries the ID of its request.
	string id = 2;

	// The URI of the call, if any. Can be empty.
	string uri = 3;

	// The serialized .NET remoting message headers.
	bytes headers = 4;

	// The serialized .NET remoting message.
	bytes data = 5;
}

// Types of .NET remoting messages.
enum GroundLinkMessageType {

	// For method calls.
	REQUEST = 0;

	// For method returns.
	RESPONSE = 1;
}