mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 10:21:53 +00:00
349 lines
10 KiB
ReStructuredText
349 lines
10 KiB
ReStructuredText
.. _service_config:
|
||
|
||
**********************
|
||
Service Configurations
|
||
**********************
|
||
|
||
These files define the configuration spec, a structure that defines the set of values the config can hold, and the configuration rules, the rule-set that define dependencies between config variables in order to coexist.
|
||
|
||
Config Spec
|
||
===========
|
||
|
||
This file defines the structure of the configuration of a service. Ultimately, these values influence the UI elements for a user to interact with. Specifically, they evaluate to the options available when:
|
||
|
||
TODO include screenshots
|
||
|
||
- Prior to service installation when the user needs to be made aware of any necessary dependency configurations
|
||
- The user installs a service and the service is in the "Needs Config" state
|
||
- Whenever a use edits a service config (ie. TODO)
|
||
- When config pointers get updated (TODO define)
|
||
|
||
All keys in Config Spec are in camelCase. Due to a backwards compatibility issue, ``app-id`` is an exception and will always be kebab case, as will the ``String`` value of ``app-id``.
|
||
|
||
If null by default is true, nullable must be true.
|
||
If null by default is false, nullable could be either.
|
||
|
||
Lists of any type do not contain the nullable/default for each item in list. The list *itself* can be nullable/have default.
|
||
|
||
Descriptions are encouraged but not required.
|
||
|
||
``Tag`` is the key that will be rendered on the UI element.
|
||
|
||
The ``Config`` type is written in the same syntax as the config rules:
|
||
|
||
Range is loosely based off mathematical range syntax, with infinity replaced with ``*``:
|
||
|
||
``[ || ]`` = inclusive
|
||
|
||
``( || )`` = noninclusive
|
||
|
||
``*`` = infinity on either end
|
||
|
||
eg:
|
||
|
||
.. code::
|
||
|
||
[0,*) - all numbers to infinity including 0
|
||
|
||
Types
|
||
-----
|
||
|
||
.. code:: typescript
|
||
|
||
interface ConfigSpec {
|
||
serviceId: ValueSpecAny
|
||
}
|
||
|
||
interface ListSpec<T> {
|
||
spec: T
|
||
range: NumRange<usize> TODO define Range
|
||
default: String
|
||
}
|
||
|
||
interface ValueSpec {
|
||
Boolean: {
|
||
type: String (ie. "boolean")
|
||
name: String
|
||
description?: String
|
||
changeWarning?: String
|
||
default: Boolean
|
||
}
|
||
Enum: {
|
||
type: String (ie. "enum")
|
||
name: String
|
||
description?: String
|
||
changeWarning?: String
|
||
default: Enum
|
||
values: new Set(String)
|
||
}
|
||
Number: {
|
||
type: String (ie. "number")
|
||
name: String
|
||
description?: String
|
||
changeWarning?: String
|
||
default: Boolean
|
||
nullable: Boolean
|
||
range?: Range
|
||
integral: Boolean
|
||
units?: String
|
||
}
|
||
Object: {
|
||
type: String (ie. "object")
|
||
name: String
|
||
description?: String
|
||
changeWarning?: String
|
||
nullable: Boolean
|
||
null-by-default: Boolean
|
||
spec: ConfigSpec
|
||
}
|
||
String: {
|
||
type: String (ie. "string")
|
||
name: String
|
||
description?: String
|
||
changeWarning?: String
|
||
nullable: Boolean
|
||
default: String | Entropy
|
||
pattern?: {
|
||
pattern: Regex
|
||
pattern-description: String
|
||
}
|
||
}
|
||
Union: {
|
||
type: String (ie. "union")
|
||
name: String
|
||
description?: String
|
||
changeWarning?: String
|
||
default: Boolean
|
||
variants: {
|
||
key: ConfigSpec
|
||
}
|
||
tag: {
|
||
id: String,
|
||
name: String,
|
||
description?: String,
|
||
variantNames: {
|
||
key: String
|
||
},
|
||
}
|
||
}
|
||
Pointer: {
|
||
type: String (ie. "pointer")
|
||
name: String
|
||
description?: String
|
||
changeWarning?: String
|
||
subtype: PointerType
|
||
app-id: String (*always* kebab case)
|
||
target: AppPointerSpecVariants | SystemPointerSpecVariants
|
||
index?: String (dependent on target being AppPointerSpecVariants)
|
||
}
|
||
List: {
|
||
name: String
|
||
type: String (ie. "list")
|
||
subtype: String
|
||
description?: String
|
||
changeWarning?: String
|
||
range: Range (ie. "[0,*)")
|
||
default: ListSpec || []
|
||
spec: {
|
||
type: String // can only be Enum | Number | Object | String
|
||
}
|
||
}
|
||
Map: {
|
||
name: String
|
||
type: String (ie. "map")
|
||
description?: String
|
||
changeWarning?: String
|
||
default: {}
|
||
range: Range
|
||
tag: {
|
||
name: String
|
||
description: String
|
||
}
|
||
spec: ConfigSpec
|
||
}
|
||
}
|
||
type Range = String
|
||
type PointerType = App | System
|
||
interface AppPointerSpecVariants { LanAddress | TorAddress | Config }
|
||
interface SystemPointerSpecVariants {}
|
||
interface Config {
|
||
index: String
|
||
}
|
||
|
||
|
||
Examples:
|
||
|
||
.. code:: yaml
|
||
|
||
password:
|
||
type: string
|
||
nullable: false
|
||
name: "Password"
|
||
description: "The password for connecting to the server."
|
||
default:
|
||
charset: "a-k,m-z,2-9"
|
||
len: 20
|
||
pattern: '^[^\n"]*$'
|
||
patternDescription: "Must not contain newline or quote characters."
|
||
|
||
.. code:: yaml
|
||
|
||
bitcoind:
|
||
type: union
|
||
name: Bitcoin Core
|
||
description: |
|
||
The Bitcoin Core node to connect to:
|
||
- internal: The Bitcoin Core RPC Proxy service installed to your Embassy
|
||
- external: An unpruned Bitcoin Core node running on a different device
|
||
tag: type
|
||
default: internal
|
||
variants:
|
||
internal:
|
||
address:
|
||
type: pointer
|
||
name: Local Address
|
||
description: The LAN IP address of your Bitcoin Core RPC Proxy service
|
||
subtype: app
|
||
app-id: btc-rpc-proxy
|
||
target: lan-address
|
||
user:
|
||
type: pointer
|
||
name: RPC Username
|
||
description: The username for the RPC user allocated to c-lightning
|
||
subtype: app
|
||
app-id: btc-rpc-proxy
|
||
target: config
|
||
index: 'users.[first(item => ''item.name = "c-lightning")].name'
|
||
password:
|
||
type: pointer
|
||
name: RPC Password
|
||
description: The password for the RPC user allocated to c-lightning
|
||
subtype: app
|
||
app-id: btc-rpc-proxy
|
||
target: config
|
||
index: 'users.[first(item => ''item.name = "c-lightning")].password'
|
||
external:
|
||
address:
|
||
type: string
|
||
name: Public Address
|
||
description: The public address of your Bitcoin Core RPC server
|
||
nullable: false
|
||
user:
|
||
type: string
|
||
name: RPC Username
|
||
description: The username for the RPC user on your Bitcoin Core RPC server
|
||
nullable: false
|
||
password:
|
||
type: string
|
||
name: RPC Password
|
||
description: The password for the RPC user on your Bitcoin Core RPC server
|
||
nullable: false
|
||
btc-standup:
|
||
quick-connect-url:
|
||
type: string
|
||
name: Quick Connect URL
|
||
description: The Quick Connect URL for your Bitcoin Core RPC server
|
||
nullable: false
|
||
pattern: 'btcstandup://[^:]*:[^@]*@[a-zA-Z0-9.-]+:[0-9]+(/(\?(label=.+)?)?)?'
|
||
patternDescription: Must be a valid Quick Connect URL. For help, check out https://github.com/BlockchainCommons/Gordian/blob/master/Docs/Quick-Connect-API.md
|
||
rpc:
|
||
type: object
|
||
name: RPC Options
|
||
description: Options for the HTTP RPC interface
|
||
nullable: false
|
||
nullByDefault: false
|
||
spec:
|
||
enabled:
|
||
type: boolean
|
||
name: Enable
|
||
description: Whether to enable the RPC webserver
|
||
default: true
|
||
user:
|
||
type: string
|
||
name: RPC Username
|
||
description: The username for the RPC user on your c-lightning node
|
||
nullable: false
|
||
default: lightning
|
||
password:
|
||
type: string
|
||
name: RPC Password
|
||
description: The password for the RPC user on your c-lightning node
|
||
nullable: false
|
||
default:
|
||
charset: 'a-z,A-Z,0-9'
|
||
len: 22
|
||
|
||
Config Rules
|
||
============
|
||
|
||
These rules define application level rules. A rule is a boolean expression that we demand to be true. If it is failing, it is not true.
|
||
|
||
They follow the `Backus–Naur <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ metasyntax 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, strings
|
||
- different syntax depending on what you want it to be
|
||
- ``?`` casts to boolean value. if not a boolean, whether or not its null
|
||
- ``#`` treat as a number. If not a number, will parse as NaN. String numbers are not currently supported.
|
||
- ``'`` cast into a string. Applies to any value except for an object or a list.
|
||
- ``!`` equals not
|
||
|
||
If application does not satisfy a rule, give a set of suggestions, in the form of operation to preform:
|
||
|
||
- Set
|
||
|
||
- Push
|
||
|
||
- Delete
|
||
|
||
.. code::typescript
|
||
|
||
enum SuggestionVariant = Set | Delete | Push
|
||
|
||
interface Set {
|
||
var: String,
|
||
to: SetVariant,
|
||
}
|
||
interface Delete {
|
||
src: String,
|
||
}
|
||
interface Push {
|
||
to: String,
|
||
value: Value,
|
||
}
|
||
|
||
enum SetVariant = To | ToValue | ToEntropy
|
||
|
||
type To = String
|
||
type ToValue = Value
|
||
interface ToEntropy {
|
||
charset: String (eg. 'a-z,A-Z,0-9')
|
||
len: Number
|
||
}
|
||
|
||
SetVariant Examples:
|
||
|
||
.. code:: yaml
|
||
|
||
to: 'users'
|
||
|
||
to-entropy: {
|
||
charset: 'a-z,A-Z,0-9'
|
||
len: 22
|
||
}
|
||
|
||
to: true
|
||
|
||
.. code:: yaml
|
||
|
||
- rule: 'rpc.enable? OR !(''advanced.pruning.mode = "manual")'
|
||
description: "RPC must be enabled for manual pruning."
|
||
|
||
|