-
Notifications
You must be signed in to change notification settings - Fork 1
Communication
Communication between C-Troll and the Tray applications happens through the passing of JSON messages. The fundamental structure for each of these messages is that they need to have a type key that specifies what type of message is contained in this package and a version number so that we can ensure that the protocol has not changed if either one of the two applications is updated. Each message type has a fixed sender and a recipient. What follows is a list of all message types that are used for communication between C-Troll and the Tray applications.
Sender: Tray
Receiver: C-Troll
This message is sent whenever the Tray detects a change about a process that is running on the local machine. These changes most commonly are whether a process was started, when it started running, whether it closed successfully, or if it was terminated. This message type informs C-Troll about this local change.
processId [ int ]
This is the process id that was used to originally start the process (see CommandMessage). This number was given to the Tray by the C-Troll application.
status [ "Starting", "Running", "NormalExit", "CrashExit", "FailedToStart", "TimedOut", "WriteError", "ReadError", or "UnknownError" ]
This field contains the new status that this process entered. It is this transition that triggered the sending on this message type in the first place. The "Starting" status is sent when the process has been started but is not yet running. The "Running" status is sent when the application properly starts executing. "FailedToStart" is sent if the application could not be started correctly for whatever reason; common reasons might be that a resources needed at load time was not present, the executable's file was not found, or the Tray application has insufficient privileges to start the program. The "NormalExit" status is sent if the application closed gracefully. The "CrashExit" status is used if the process was terminated for whatever reason. "TimedOut", "WriteError", "ReadError", and "UnknownError" should at the moment never be sent as a status message and are reserved for future functionalities.
Sender: C-Troll
Receiver: Tray
This message is sent from C-Troll to the Tray applications as a command to start a new process.
executable [ string ]
This is the name of the executable that is to be started with this process id.
forwardOutErr [ boolean ]
This value specifies whether the child process should forward its StdOut and StdErr messages to the C-Troll application
id [ integer ]
This is the ID that the Tray application has to use whenever it is communicating information about this process. This ID is also used by C-Troll when signalling to Exit or Kill this process.
secret [ string ]
If the receiving Tray application requires a secret to authenticate a valid message, this string has to be the same as the string defined in the
config-tray.jsonconfiguration file for the Tray, if it is not, an InvalidAuthMessage is returned to the C-Troll. If the Tray was configured without a secret message, the value for this key must be empty.
commandlineArguments [ string ]
These are all of the commandline arguments that should be passed to the executable when starting the process.
workingDirectory [ string ]
This is the working directory from which the application should be started
Sender: C-Troll
Receiver: Tray
This message is sent from C-Troll to the Tray applications as a command to stop a running process.
id [ integer ]
The id of the process that is to be terminated.
secret [ string ]
If the receiving Tray application requires a secret to authenticate a valid message, this string has to be the same as the string defined in the
config-tray.jsonconfiguration file for the Tray, if it is not, an InvalidAuthMessage is returned to the C-Troll. If the Tray was configured without a secret message, the value for this key must be empty.
Sender: Tray
Receiver: C-Troll
This message is sent when the Tray received a CommandMessage that did not have the correct secret, this message is sent back to the C-Troll application.
Sender: C-Troll Receiver: Tray
This message is sent by C-Troll to the Tray to command the Tray to kill all processes that are currently running. This message can be used if bugs have arisen that caused the C-Troll's and the Tray's state to diverge. For example if C-Troll thinks a process is no longer running and thus has no UI option to stop a process.
secret [ string ]
If the receiving Tray application requires a secret to authenticate a valid message, this string has to be the same as the string defined in the
config-tray.jsonconfiguration file for the Tray, if it is not, an InvalidAuthMessage is returned to the C-Troll. If the Tray was configured without a secret message, the value for this key must be empty.
Sender: Tray
Receiver: C-Troll
This message is sent by the Tray when it encounters a near-fatal error. This means that some error has occurred that would have otherwise crashed the program. The message contains the last messages that have been received by the Tray as well as a textual description what has gone wrong. When the C-Troll application receives this message, it is displayed as a modal dialog on top of everything else. If this happens, contacts one of the maintainers and report this as a bug.
error [ string ]
The error message that the Tray application raised
lastMessages [ array ]
A list of the last messages that were received by the Tray application. Each message is a string that contains the timestamp when the message was received, who the sender was, and the contents of the message
Sender: Tray
Receiver: C-Troll
This message is sent whenever there is a new initial C-Troll connection to the Tray. This message will inform the C-Troll about the current state of the Tray. Currently, only the list of process id's that are running on the Tray are sent back to C-Troll.
runningProcesses [ list of integers ]
A list of all process id's that are currently running on this Tray.
In the Tray application's configuration file, the secret key can be used to enable encrypted traffic for that particular Tray. If a Tray specifies a secret, then the C-Troll's Node configuration for that particular Tray must contain a secret configuration as well. If either the Tray or the C-Troll's Node has a secret key specified, the application encrypts and decrypts all incoming traffic using the secret as a password. The details of the encryption algorithm exists here, but the short version is that it is by no means to be considered a cryptographically safe encryption.
The secret between each Tray and C-Troll can be different (or some of the _Tray_s might not use a secret at all).
config-tray.json for Tray #1
{
"port": 5000,
"secret": "super-secret-password"
}config-tray.json for Tray #2
{
"port": 5001,
"secret": ""
}Node configuration node1.json for _C-Troll:
{
"name": "Home",
"ip": "localhost",
"port": 5000,
"secret": "super-secret-password"
}Node configuration node2.json for _C-Troll:
{
"name": "Home",
"ip": "localhost",
"port": 5001
}In this example, all traffic going both ways between C-Troll and Tray #1 is encrypted using the super-secret-password, whereas the traffic between C-Troll and Tray #2 is not encrypted.