yaq-yeps/103


Daemon State Files

Table of Contents

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.

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 unepected shutdown) will be seamless without any additional user input. If the file is not present, reasonable default behavior SHOULD be assumed, if possible. 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.

File Location

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

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. Clients may set information using the set_state mehod of the is-daemon trait. Values set using this method update the current state, but do MUST NOT remove values that are not provided.

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.

Fields Required By Traits

There are no keys required by default, however Traits MAY require State variables in their implementation.

Discussion

Discussion can be found on the gitlab issue for this YEP.

Copyright

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


built 2020-05-20 22:19:23                                      CC0: no copyright