NAME

yaqd - Daemon infrastructure for the yaq system

COMMUNICATION PROTOCOL

Version 0.2.0

yaq daemons MUST communicate over tcp(7) ports. By convention, daemons SHOULD serve on ports in the range 36000-39999. This range avoids most collisions with common TCP port usage in other applications. Users MAY use ports outside of this range, however tools like yaqd scan will not check ports other than this range by default.

TCP was chosen to maximize cross system and cross language compatibility. Future versions of this specification may allow for other socket(7) implementations as alternatives to tcp(7) at the users option.

REQUEST CONTENT

The request takes the form of a JSON-RPC v2.0 (https://www.jsonrpc.org/specification) request object. All standard JSON data types (Number, String, Boolean, Array, Object, null) are supported. In addition, the non-standard values "Infinity" "-Infinity" and "NaN" are allowed. These are considered floating point numbers. Many JSON encoders/decoders support these values by default or with a simple flag. Strings are utf-8(7) encoded.

Future versions of this standard may specify additional data types not in the JSON standard.

RESPONSE CONTENT

The daemon's response MUST use the same JSON serialization as the request. The response object is complient with JSON-RPC v2.0

ENTRY POINT

The standard entry point to initiate a daemon SHALL be yaqd- <kind> where <kind> is a lowercase name for the daemon with words separated by hyphens.

Examples of valid entry points include yaqd-base, yaqd-micro-hr , and yaqd-zaber-binary .

The entry point SHALL accept the option --config <filepath> and the short form -c of this option.

The entry point SHALL accept the option --version <filepath> which prints version information and exits without starting daemons.

CONFIGURATION

The default configuration file location SHALL be:

macOS "~/Library/Application Support/yaqd/<kind>/config.toml"

XDG Spec (e.g. Linux) "~/.config/yaqd/<kind>/config.toml"

Windows "C:\Users\<User>\AppData\Local\yaq\yaqd\<kind>\config.toml"

Where <kind> is the same as in the ENTRY POINT section.

Configuration is in TOML (https://github.com/toml-lang/toml). Any valid TOML types MAY be used.

Top level keys are used for

enable optional boolean

If given and set to false, the daemon MUST exit immediately without opening TCP ports. If not given, true is assumed.

shared-settings optional table

If present, provides defaults that apply to all other tables. These defaults MAY be overridden by the other tables for the individual port.

Every other top-level key MUST be a table, for which the name indicates the name of the daemon which MUST be exposed on the given port. These names MUST be unique at the level of <kind>.

Each table MUST include a key "port" which provides the globally-unique (among all daemons) TCP port. Additional fields MAY be added, as needed for configuring the daemon. Specific implementations MAY have additional required configuration parameters. Fields MAY be included that are only used by the clients, and retrieved by get_config (see below).

ALL tables other than those that are disabled, and shared-settings MUST be started when invoking a daemon entry point with the config file. They MAY (and in many cases must for technical reasons) start several daemons listening in the same process.

The configuration file MUST NOT be written by the daemon. Any runtime dynamic fields SHOULD be written in the state file (see below) and have ways of detecting and/or expose setting over the TCP communication protocol described above.

Additional identifying information SHOULD be included, as applicable. Common identifying information include: make (manufacturer), model (identifies the kind as described by the manufacturer), serial (individual serial number of the device represented), units (units for numbers interpreted and sent). This limited subset (along with the <name> as defined by the table name and the <kind> as defined by the implementation) are returned by the id method (see below).

The configuration file MUST be read from the file at daemon startup ONLY (restarting is considered "startup", and MUST re-read the configuration file in case changes were made).

STATE SAVING

Dynamic fields are saved to a similar TOML file. Included fields SHOULD be of potential value to clients or needed across restarts of the daemon.

EACH daemon MUST SAVE a file at (unless that file is empty, in which case it MAY be omitted):

macOS "~/Library/Application Support/yaqd-state/<kind>/<name>-state.toml"

XDG Spec (e.g. Linux) "~/.local/share/yaqd-state/<kind>/<name>-state.toml"

Windows "C:\Users\<User>\AppData\Local\yaq\yaqd-state\<kind>\<name>-state.toml"

By default, there are no required keys in the state. The content saved MUST be the same as returned by the get_state method (see below).

If possible, recorded state SHOULD fully describe the hardware such that recovery from a shutdown (including unepected shutdown) will be seamless without any additional user input.

STANDARD COMMANDS

id

JSON object with information to identify the daemon, including name, kind, make, model, serial, units.

config_filepath

String representing the absolute filepath of the configuration file on the host machine.

get_config

JSON object with the full configuration for the individual daemon as defined in the TOML file. This includes defaults and shared settings not directly specified in the daemon-specific TOML table.

get_state

JSON object representing the current state, as saved in the <name>-state.toml file.

list_methods

Array of the (string) names of all known (public) methods.

help( method= None )

If method not given, return a human-readable string with information about the daemon as a whole. If method is given, return a human-readable string with the signature of the method on the first line and a description of the method on subsequent lines. The signature is not specified to be in any particular language. It is intended for usage by humans ONLY.