Communication protocol

The communication protocol relies on the following things:

  • the worker shell writes input parameters of the task into files (before starting the task process)
  • the task process reads the input parameters from the files
  • the task process prints to its standard output to send messages or logs to the worker shell
  • the task process reads its standard input to receive messages from the worker shell
  • the task process writes the output parameters into files
  • the worker shell reads output parameters of the task from files (after the end of the task process)

Environment variables

The worker shell may set the following environment variables:

  • DBOS_INPUTS_DIR the path to the directory where to find input parameter files
  • DBOS_OUTPUTS_DIR the path to the directory where to place output parameter files

Inputs and outputs directories

If DBOS_INPUTS_DIR is set, then look for input parameter files into this folder. Otherwise, look into the inputs folder in the working directory of the task process.

If DBOS_OUTPUTS_DIR is set, then look for output parameter files into this folder. Otherwise, look into the outputs folder in the working directory of the task process.

The name of the files in these directories are the parameter names.

Messages syntax

Outgoing or incoming messages have all the following form:

DBOS_<type>:<payload>\n

All messages fit on one line of text, ended by new line (\n) character.

The <type> part defines the type of message.

The :<payload> might be absent, the <payload> part contains the message data and is a json string that must not contains \n characters, the protocol requires that a message fit in one line. Thank to the json format, multiline text can be transmitted because \n can be escaped in json text values.

Outgoing messages

The task process can print messages or logs, it is interpreted as a log only if what is printed doesn’t match the message syntax or is not a known message type.

The task process can send the following types of message:

  • INSTANCE: instance metrics
  • PROGRESS: progression metrics of the task
  • SOLUTION: solution metrics of the task

The payload of these messages have the following form (prettified json below):

{
    <optional field>
    "values": [
        {"name": "<name>", "value": <value>, "coefficient": <coefficient>},
        {"name": "<name>", "value": <value>, "coefficient": <coefficient>}
    ]
}

<name> is the name of a metric, <value> its value (might be string or numeric) and <coefficient> the optional numeric value for the coefficient. The <optional field> is not required and depends on the type of message:

  • a string field named instanceId for INSTANCE messages
  • a string field named message for PROGRESS messages
  • a numeric field named elapsedTime for SOLUTION messages

So for instance, a complete SOLUTION message would look like:

DBOS_SOLUTION:{"elapsedTime":123456789,"values":[{"name":"The answer","value":42}]}\n

Incoming message

For now, task processes can only receive the following message:

DBOS_STOP\n

When the task process receive this message, it must send its solution and exit.

Bridge

In case a bridge is available in your task’s target language, we strongly recommend using it. If not available, it is recommended to use existing json library to serialize you data properly.