Documentation - Controller - Specification - Packet
Author: Kevin Day
Description: Controller program packet specification.
Keywords: Kevin Day, Kevux, FLL, Featureless, Linux, Library, Controller, Open-Source, Specification

# Controller Packet Specifications

The version date of this specification is `2024/07/02`.

The controller program communicates use the `FSS-000F (Packet)`.

This specification declares how the Payload Block, which is in `FSS-000E (Payload)` format, is required to be used.

Only a single `header` is allowed.

Only a single `payload` is allowed.

Packet Structure:

- Packet is grouped into the following blocks:

  - `control`: A single 1-byte block representing control codes.
  - `size`: A single 4-byte block representing the size of the entire packet, including the control block.

The `header` Object contains the following `FSS-0001 (Extended Object)` (depending on `type`):

- `action`: A valid action type: `freeze`, `kexec`, `kill`, `pause`, `reboot`, `reload`, `rerun`, `restart`, `resume`, `shutdown`, `start`, `stop`, or `thaw`.
- `length`: A positive whole number inclusively between 0 and 4294965248 representing the length of the `payload` (may be in binary, octal, decimal, duodecimal, or hexidecimal).
- `status`: The status code name or number representing an FSS status code, such as `F_none`, `F_failure`, or `200` (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal).
- `type`: The packet type that is one of `controller`, `error`, or `init`.

When there are multiple Objects of the same name inside the `header`:

- `action`: The order represents the order in which the actions are performed..
- `length`: There may only be one length Object, all others after the first are ignored (may be in binary, octal, decimal, duodecimal, or hexidecimal).
- `status`: A status for each action, in the same order as the order of the action, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal).
- `type`: The first represent the type and all others represents a sub-type.

There are different headers and payload properties based on the `type`.

The `controller` type:

- Supports the following headers: `action`, `length`, `status`, and `type`.
- Only a single `action` may be provided and must exist for request and response packets.
- Only a single `status` may be provided and must exist for response packets.
- The `payload` is dependent on the `action`.

The `error` type:

- Supports the following headers: `length`, `status`, and `type`.
- Only a single `status` may be provided and must exist for request and response packets.
- The `payload` is a NULL terminated string whose length is defined by the `length` `header` Content.

There are different headers and payload properties based on the `type`.

The `init` type:

- Supports the following headers: `action`, `length`, `status`, and `type`.
- Only a single `action` may be provided and must exist for request and response packets.
- Only a single `status` may be provided and must exist for response packets.
- The `payload` is dependent on the `action`.

## Packet Documentation

Describes how a packet is designed and intended to be used.

The `packet` is the general category in which multiple types of packets belong. This describes the different packets based on their `type`.

Each packet begins with a control block and a size block followed by a payload block.

The `control` block:

- The leading bit (starting from the left) designates the the format of the payload, which is 0 for string and 1 for binary.
- The second bit (starting from the left) designates the the byte order for the rest of the packet, which 0 is for little endian and 1 is for big endian.
- The remaining 6-bits are reserved for future use.

- The size block:

  - The size block represents the size of the entire packet (the control block, the size blocks, and the payload block).
  - This number is a single 32-bit unsigned integer.

- Example packet structure:

      [ Control Block ] [ Size Block                                  ] [ Payload Block         ]
      [ 0b10000000    ] [ 0b00000000 0b00000000 0b00000100 0b11010010 ] [ size: 1229 (1234 - 5) ]

- The payload block:

  This block is represented by the `FSS-000E` payload specification and its structure ad use is described in the next sections.

  The following types of payload are received or sent:

  1. controller payload.
  2. error payload.
  3. init payload.

The controller payload:

- Commands being sent to the controller and their respective responses utilize a controller payload.
- These are pre-defined commands to rules or the controller program itself.
- Commands such as starting or stopping some rule, for example.
- A controller payload is also sent in response to a controller payload request to represent a success.
  - The `now` condition designates that the kexec, reboot, or shutdown is to begin immediately.
  - The `at` condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock.
  - The `in` condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started.

For these `time` conditions, different units of time should be supported, such as `seconds`, `days`, `years` as standard time, Time, or UNIX Time (Epoch Time).

The normal `controller` payload commands are any valid Rule Action that performs some action. This does not include Actions that provide some setting or configuration (such as `with_pid`). Some of the supported commands are: `freeze`, `kill`, `pause`, `reload`, `rerun`, `restart`, `resume`, `start`, `stop`, or `thaw`. Multiple commands may be sent multiple `action` headers. The `action` headers are order sensitive, executing from top to bottom, and one does not start until the previous successfully completes.

Multiple `status` headers may exist in the response so long as they each match an `action` in the request.

The `payload` is expected to be empty and have a length of 0 for a request. The `payload` may have an `FSS-0000 (Basic)` format containing a single Object `message` to represent a message associated with an action. Multiple `message` may exist in the response so long as they each match an `action` in the request.

The error payload:

- The error payload is intended to communicate some sort of failure.
- The error payload is only sent in response to some request (and not in response to another response).
- The control (the client) is not expected to send error payloads and the controller (the service) should send an error in response to an error payload or ignore it entirely.
- The `status` from the `header` designates the status code as either a status code name string or a status code number (where a number may have error and warning bits).
- The `payload` will contain a NULL terminated string representing the message used to describe the error.

The init payload:

- The init payload is intended exclusively for the `init` operation mode and is expected to only be available when running as `init`.
- This is used to provide special actions, namely `kexec`, `reboot`, and `shutdown`.
- The `kexec` is for booting into another kernel, which may effectively be the same as a `reboot` (`kexec` is currently neither supported nor implemented).
- The `reboot` is for rebooting the machine (currently not implemented).
- The `shutdown` is for shutting down the machine (currently not implemented).
- These three commands are configurable to fire off based on conditions.