mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 10:21:53 +00:00
aed86e7e6c
* re-arrange the user docs * Minor description edit * update styles * fix service links Co-authored-by: kn0wmad <kn0wmad@protonmail.com> Co-authored-by: Lucy Cifferello <12953208+elvece@users.noreply.github.com>
112 lines
3.7 KiB
ReStructuredText
112 lines
3.7 KiB
ReStructuredText
|
||
.. _config_rules:
|
||
|
||
============
|
||
Config Rules
|
||
============
|
||
|
||
This file defines the configuration rules, or the rule-set that defines dependencies between config variables. In practice, config rules are for auto-configuring self dependencies. Self dependencies are internal dependencies of a service, such as if the setting of one config variable informs the option of another setting. These "dependencies" are configured as rules.
|
||
|
||
A rule is a boolean expression that we demand to be true. It is not true if the expression fails the rule parser. Set of predicates. xt
|
||
|
||
They follow the `Backus–Naur <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ meta-syntax for writing rules.
|
||
|
||
Rules are composed of two main concepts:
|
||
|
||
* Variables - accessor into a configuration
|
||
* Terms - either a variable or type literal (ie. a boolean term is a boolean variable, a boolean expression, or a comparison operation between numbers or strings)
|
||
|
||
Variables can be booleans, numbers, or strings, and have a different syntax depending on the type. These type annotations check your config rules against your config spec and throw an error if invalid.
|
||
|
||
- ``?`` - Casts to boolean value. If the value is not a boolean, this notes whether or not the value is null.
|
||
- ``#`` - Treat the value as a number. If it is not a number, the value will be parsed as NaN. String numbers are not currently supported.
|
||
- ``'`` - Cast the value into a string. Applies to any value except for an object or a list.
|
||
- ``!`` - Equals not.
|
||
|
||
.. note::
|
||
Config rules are processed in order.
|
||
|
||
If application does not satisfy a rule, a set of suggestions should be provided. These suggestions are in the form of the operation to preform:
|
||
|
||
- ``Set`` - set the value
|
||
|
||
- ``Push`` - add to the value (such as to a list)
|
||
|
||
- ``Delete`` - delete the value
|
||
|
||
.. code:: typescript
|
||
|
||
enum SuggestionVariant = Set | Delete | Push
|
||
|
||
interface Set {
|
||
var: String, // fully qualified path without typecast
|
||
// one of the following three variants are required
|
||
to: Option<String> // a string expression, use when tying another config value
|
||
to-value: Option<String>
|
||
to-entropy: Option<{
|
||
charset: String (eg. 'a-z,A-Z,0-9')
|
||
len: Number
|
||
}>
|
||
}
|
||
|
||
interface Delete {
|
||
src: String, // path to key - removes if in a list
|
||
}
|
||
|
||
interface Push {
|
||
to: String,
|
||
value: String, // string literal of value to be set
|
||
}
|
||
|
||
SET Examples
|
||
------------
|
||
|
||
.. code:: yaml
|
||
|
||
- SET:
|
||
# the key in config you want to set
|
||
var: 'users.[first(item => ''item.name = "c-lightning")].password'
|
||
# the value in config that you will set
|
||
to-entropy:
|
||
charset: "a-z,A-Z,0-9"
|
||
len: 22
|
||
|
||
- SET:
|
||
var: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks'
|
||
to-value: true
|
||
|
||
|
||
PUSH Examples
|
||
-------------
|
||
|
||
.. code:: yaml
|
||
|
||
- PUSH:
|
||
to: "users"
|
||
value:
|
||
name: c-lightning
|
||
allowed-calls: []
|
||
|
||
- PUSH:
|
||
to: 'users.[first(item => ''item.name = "c-lightning")].allowed-calls'
|
||
value: "getnetworkinfo"
|
||
|
||
Full example from `c-lightning manifest <https://github.com/Start9Labs/c-lightning-wrapper/blob/master/manifest.yaml>`_:
|
||
|
||
.. code:: yaml
|
||
|
||
config:
|
||
- rule: '''users.*.name = "c-lightning"'
|
||
description: 'Must have an RPC user named "c-lightning"'
|
||
suggestions:
|
||
- PUSH:
|
||
to: "users"
|
||
value:
|
||
name: c-lightning
|
||
allowed-calls: []
|
||
- SET:
|
||
var: 'users.[first(item => ''item.name = "c-lightning")].password'
|
||
to-entropy:
|
||
charset: "a-z,A-Z,0-9"
|
||
len: 22
|