A lightweight intermediary for running processes.

Daiyousei is a lightweight program the purpose of which is to act as a different process. Upon starting, it connects to a running, listening program, referred to as server, via a socket. Then daiyousei, in this context the client, transparently sends and receives fundamental runtime execution data. The data include the environment context, arguments, standard input / output streams and the exit code.

Running

When the program starts, the communication channel needs to be already created and the server needs to be listening for connections. The client and server then communicate and after the communication is finished.

If no error is encountered by the client, the exit code from the server is returned. In case of an internal error, the programs attempts to return the value 255, though this may not be guaranteed.

Options

The tool does not use any command-line arguments. All arguments are passed over the communication channel. The tool requires the first argument, i.e. the executable name, also known as argv[0], to be valid.

Environment variables

The tool can be configured using the following environment variables:

Name Description

DAIYOUSEI_UNIX_SOCKET

File path of the Unix socket that will be used for communication

Communication

All communication is encoded in the Bencode encoding. Both parties communicate by sending a single list to each other. The start of the list means initiating communication and the list end means proper termination of communication. The list contains key-value pairs, similar to a dictionary but the keys can be repeated.

Socket path

Currently only Unix domain stream socket communication is supported.

The Unix socket file path used for communication is selected using the following procedure:

  • If the variable DAIYOUSEI_UNIX_SOCKET is defined, it is used.

  • Otherwise if XDG_RUNTIME_DIR is defined, the socket daiyousei.sock inside the directory is used.

  • Otherwise the socket daiyousei.sock inside the /tmp directory is used.

Protocol

The communication protocol used by the communicating parties as follows.

Client to server

When the client starts, it immediately sends its command-line arguments, current working directory and the environment variables over the communication channel. Standard input is sent in chunks as the program receives it. When the standard input is closed on the client side, it sends the closing end of the list and closes the connection.

BNF notation, client-to-server protocol

Request

::=

"l" Argv Cwd Env Stdin "e"

Argv

::=

"4:argv" "l" Args "e"

Args

::=

Ben-string

Args

::=

Args Ben-string

Cwd

::=

"3:cwd" Ben-string

Env

::=

"3:env" "l" Pairs "e"

Pairs

::=

Pairs

::=

Pairs Ben-string Ben-string

Stdin

::=

Stdin

::=

Stdin "5:stdin" Ben-string
Extended BNF notation, client-to-server protocol

request

=

"l", argv, cwd, env, { stdin }, "e";

argv

=

"4:argv", "l", { ben-string }, "e";

cwd

=

"3:cwd", ben-string;

env

=

"3:env", "l", { ben-string, ben-string }, "e";

stdin

=

"5:stdin", ben-string;

Server to client

The server communicates by sending its outputs in chunks and the exit code as the last value. The exit code is returned by the client program unless it encounters a different error.

BNF notation, server-to-client protocol

Response

::=

"l" Chunk Exit "e"

Chunk

::=

"6:stdout" Ben-string

Chunk

::=

"6:stderr" Ben-string

Exit

::=

"8:exitcode" Ben-integer
Extended BNF notation, server-to-client protocol

response

=

"l", { stdout | stderr }, exitcode, "e";

stdout

=

"6:stdout", ben-string;

stderr

=

"6:stderr", ben-string;

exitcode

=

"8:exitcode", ben-integer;

Termination

The client will keep listening until the server sends the end-of-list. After that, the client will attempt to shutdown(2) and close(2) the socket regardless of whether or not the server closes the socket.