yaq-yeps/102

Daemon Configuration Files

YEP:	102
Title:	Daemon Configuration Files
Authors:	Kyle Sunden
Status:	accepted
Tags:	standard
Post-History:	2020-04-14, 2020-07-02

Abstract ¶

This YEP describes the configuration file format for yaq daemons. This is a TOML file with some reserved and required keys. A single config file has a 1-to-1 relationship with an invocation of the entry point. This MAY be a 1-to-many relationship with individual daemons. Typically, there is ONE configuration per <kind> of daemon. For example, if you have multiple of the same make and model translation stage, you can configure all of them in a single configuration file.

Table of Contents ¶

Abstract
Table of Contents
Motivation
Specification
Copyright

Motivation ¶

A standard for configuration makes it easy to know how one configures their daemon. TOML is a well defined, human readable configuration file format. This provides a flexible configuration format, including the ability to share settings across multiple daemons.

Specification ¶

The configuration file is a TOML file.

File Location ¶

The default configuration file location SHALL be:

macOS: ~/Library/Application Support/yaqd/<kind>/config.toml
XDG Spec (e.g. Linux): $XDG_CONFIG_HOME/yaqd/<kind>/config.toml
Windows: C:\Users\<User>\AppData\Local\yaq\yaqd\<kind>\config.toml

Where <kind> is a lowercase name for the daemon with words separated by hyphens, as returned by the id method. <kind> SHOULD NOT begin with "yaq".

If the desired config file is located elsewhere, it MUST be explicitly provided.

Shared Settings ¶

An optional top level table, shared-settings, which (if present) provides defaults that apply to all other tables. These defaults are higher priority than protocol defined defaults, but lower than configuration for individual daemon ports.

Individual Daemon Configuration ¶

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>.

The keys which are expected for a given daemon are specified using the Avro protocol file as described in YEP-107.

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. Keys which are required (or optional) MAY be specified by the daemon protocol.

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. A special key, enable (defaults to true) allows you to selectively turn off individual daemons.

The configuration file MUST NOT be written by the daemon. Any runtime dynamic fields SHOULD be written in the state file 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).

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).

Copyright ¶

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.