Misc

Miscellaneous parts of festivald that can or cannot be relied on.

festival-cli

festivald and festival-cli's versions are tied together to represent their compatibility.

festivald will be able to respond to any 🟢 Stable festival-cli request as long as festivald's:

  • Major version is the same
  • Minor version is the same or greater

For example, festivald v1.2.x is compatible with:

  • festival-cli v1.2.x
  • festival-cli v1.1.x
  • festival-cli v1.0.x

but not necessarily with festival-cli v1.3.x and beyond.

Note that festivald will still be able to communicate with newer/older festival-cli's, however:

  • If a new festival-cli is requesting a method unknown to an old festivald, or
  • If a new festivald has additional output unknown to an old festival-cli (use of non-stable API)

there will be communication issues.

Config

  • config names are 🟢 Stable (max_connections will always be named max_connections)
  • Their expected inputs are 🟢 Stable (max_connections will always want an unsigned integer)
  • Their expected behavior is 🟡 Incomplete (direct_download may include song files someday)
  • Default config values may be changed (default port value may not always be 18425)
  • Additional fields may be added in the future

Referencing any JSON-RPC methods and/or REST resources that are 🔴 Unstable in options like no_auth_rpc & no_auth_rest will also make your configuration 🔴 Unstable.

In general, behavior for existing config options may be extended if it does not break current behavior too much.

For example, direct_download will most likely support showing inline audio files eventually.

Command Line

  • --flags and sub-command names are 🟢 Stable (festivald --path will always be festivald --path)
  • Their expected inputs/outputs are 🟢 Stable
  • Additional flags and/or sub-commands may be added in the future

Disk

All locations and filenames of all files written to disk by festivald are 🟢 Stable.

TypeExample
CacheArtist ZIP cache is always at ~/.cache/festival/daemon/zip/artist
ConfigConfig file is always at ~/.config/festival/daemon/festivald.toml
DataCollection file is always at ~/.local/share/festival/daemon/state/collection.bin

Documentation

🔴 Unstable.

Do not rely on the exact name or position of something within this documentation.

For example, this section API Stability may be renamed to API Reliability and/or moved to a different chapter.

Documentation may change at any given moment to provide the most accurate information.

Errors

🔴 Unstable.

Do not rely on the details of the JSON-RPC & REST API errors.

You can rely that an input that leads to OK/ERROR will always be the same.

Logs

🔴 Unstable.

Do not rely on the log output of festivald.

HTTP Headers

🔴 Unstable.

Do not rely on the specific HTTP headers festivald returns, or their values.

Protocol

  • Transports other than HTTP(s) may be supported in the future
  • Version 2.0 of JSON-RPC will always be used
  • JSON-RPC will always require HTTP POST requests
  • REST and documentation will always require HTTP GET requests