ProcessWrapperMessageProtocol

• Overview
• Type/Word Bytes
  • List of Valid Word Bytes
• Message Structures
  • INIT
  • ACK
  • KEEP_ALIVE
  • STILL_ALIVE
  • LINE
  • ERROR
  • STOP
  • KILL
  • EXIT
• Message Exchanges
  • INIT Handshake
  • INIT Reconnect
  • START Pprocess
  • STOP Process
  • LINE From Wrapper
  • LINE From Daemon

Overview

This article outlines the protocol for messages exchanged between the daemon and process wrapper.

Type/Word Bytes

Each message contains a message type or "word" byte. This byte defines what type of message follows, and can be used to determine how to handle or respond to a message.

List of Valid Word Bytes

Enum Name	Byte Value	Meaning
INIT	0x00	Used to initialize the connection between daemon and wrapper
ACK	0x01	Standard acknowledgement of message receipt/execution
KEEP_ALIVE	0x02	Standard keep alive message
STILL_ALIVE	0x03	Keep alive acknowledgement
LINE	0x10	A line of output from the wrapper, or a line of input from the daemon
ERROR	0xA0	Reports an error
START	0xE0	Instructs wrapper to start process
STOP	0xE1	Instructs wrapper to stop process
KILL	0xE2	Instructs wrapper to kill process
EXIT	0xFF	Instructs wrapper to exit

Message Structures

INIT

Initializes the connection between the daemon and wrapper.

Key	Value
txId	Transaction ID for this request
protoVer	The protocol version being used
clientId	The PID of the wrapper process

ACK

Acknowledges successful receipt/execution of a message. Ack messages have varying properties depending on the type of message that is being acknowledged.

Key	Value
txId	ID of the transaction this message is acknowledging

KEEP_ALIVE

Keep alive messages have no K/V pairs.

STILL_ALIVE

Still alive messages have no K/V pairs.

LINE

Line messages contain a single K/V pair containing the line of output being delivered from the process to the daemon, or the line of input to be sent to the process from the daemon

Key	Value
l	The line of input/output
txId	The transaction ID for this request (Daemon to Wrapper only)

ERROR

Reports an error

Key	Value
txId	The ID of the request that resulted in an error (absent if error was not the result of an action requested by a message)
code	The error code
exitCode	(optional) The Process' exit code, if there was

STOP

Key	Value
txId	Transaction ID for this request

KILL

Key	Value
txId	Transaction ID for this request

EXIT

Key	Value
txId	Transaction ID for this request

Message Exchanges

D>W and D<W represent the direction of the message (daemon to wrapper, or wrapper to daemon).

INIT Handshake

Sent as first exchange between daemon and wrapper

Sequence	Direction	Message/Key	Description/Value
1	D<-W	INIT	Start handshake
2a	D->W	ACK	Handshake successful
2b	D->W	EXIT	Sent as response if error such as protocol mismatch is encountered

INIT Reconnect

Sent if daemon restarts to re-establish connection with wrapper

Sequence	Direction	Message/Key	Description/Value
1	D->W	INIT
2	D<-W	ACK

START Pprocess

Instructs wrapper to start the designated process, and establish a connection to the process' IO channels.

Sequence	Direction	Message/Key	Description/Value
1	D->W	START
2	D<-W	ACK	Acknowledge message received
3a	D<-W	ACK	Acknowledge process started successfully
3b	D<-W	ERROR	If process did not start successfully

STOP Process

Instructs wrapper to send SIGTERM the running process

Sequence	Direction	Message/Key	Description/Value
1	D->W	STOP
2a	D<-W	ACK	Acknowledge message received
2b	D<-W	ERROR	Sent if process is not running
3a	D<-W	ACK	Acknowledge process stopped successfully
		exitCode	The process' exit code
3c	D<-W	ERROR	Sent if process did not respond to stop message

LINE From Wrapper

This will be the most common transaction type. We do not need guaranteed delivery for these messages, so the daemon does not sent an ACK response

Sequence	Direction	Message/Key	Description/Value
1	D<-W	LINE

LINE From Daemon

We need to ensure that commands we are trying to send to the process are getting executed, so an ACK is required

Sequence	Direction	Message/Key	Description/Value
1	D->W	LINE
2	D<-W	ACK

Work in progress...