Server push (IRPCServerDataPush)

View as Markdown

A server-to-client channel: the server pushes requests and notifications to a logged-in client over a long-lived stream.

Overview

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 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. 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, passing its response_id. If preparing the answer takes time (the user is typing), send 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.

Methods