yaq-yeps/103

Daemon State Files

YEP:	103
Title:	Daemon State Files
Authors:	Kyle Sunden
Status:	accepted
Tags:	standard
Post-History:	2020-04-14, 2020-07-02, 2021-01-15

Abstract ¶

This YEP describes the configuration file format for yaq daemons. This is a TOML file, with some traits defining required keys. The TOML file contains dynamic information needed to properly restart a daemon.

Table of Contents ¶

Abstract
Table of Contents
Motivation
Specification
Copyright

Motivation ¶

This TOML format provides an easy, general place to store daemon state which is robust from shutdown/restart cycles. This format is human readable, and therefore verifiable/editable if needed. However, it is NOT expected that human intervention is an expected course of normal usage.

Specification ¶

The state file is a TOML file. Dynamic fields, either of infrequent (but possible) use to clients or required for restarting the daemon,may be saved in the state TOML.

If possible, recorded state SHOULD fully describe the hardware such that recovery from a shutdown (including unexpected shutdown) will be seamless without any additional user input. If the file is not present, reasonable default behavior SHOULD be assumed, if possible. Defaults are specified in the daemon's protocol. When reasonable defaults are not possible, Daemons SHOULD return Error states over RPC calls for calls which require state information. A missing file MUST NOT cause the daemon to fail to start up and accept client connections.

Because yaq uses a simple text file to store state, it's not recommended to treat the state file as an active datastore. Daemons SHOULD use the state file as a periodically-written backup. Active state information will typically be kept in-memory. In most cases, the content of a state file will only be read by the daemon at startup.

File Location ¶

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): $XDG_DATA_DIR/yaqd-state/<kind>/<name>-state.toml
Windows: C:\Users\<User>\AppData\Local\yaq\yaqd-state\<kind>\<name>-state.toml

Where <kind> is a lowercase name for the daemon with words separated by hyphens and <name> is the name of the individual daemon.

Access Via Clients ¶

Clients may access the information in the state file via the get_state method in the is-daemon trait, returned as the TOML contents of the state file.

As such the get_state method MUST return only information that is valid TOML types: Boolean, Integer, Float, String, RFC 3339 timestamps, Arrays and Tables.

In general, use of get_state for normal operation (i.e. not debugging) is discouraged.

Fields Required By Traits ¶

There are no keys required by default, however Traits or individual daemons MAY require State variables. All such keys will be listed in the daemon Avro protocol.

Copyright ¶

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