Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-26 10:21:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

config spec updated

Browse Source
This commit is contained in:
Lucy Cifferello
2021-02-03 23:45:47 -07:00
parent 91ccd5564a
commit eb31531c7f
3 changed files with 455 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

675
source/contributing/services/config.rst
View File

@@ -1,35 +1,135 @@
.. _service_config:
**********************
Service Configurations
**********************
****************************
Service Config Specification
****************************
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.
Configuration options are a crucial component of any application. EmbassyOS requires a particular format to ensure your service integrates smoothly with the user interface. This enables clean handling of improper values and dependency management.
The outcome of this step is two files:
:ref:`config_spec.yaml <config_spec>`
:ref:`config_rules.yaml <config_rules>`
These files contain a detailed mapping of configuration options with acceptable values, defaults and relational rule-sets.
For example, if the user chooses config option A, then config option B must be between 5 and 10. This enables a simple GUI configuration experience, complete with validations and protections, for users. They do not have to worry about the consequences of a wrong value in a ``.conf`` file.
.. _config_spec:
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:
Overview
--------
TODO include screenshots
This file defines the structure of configuration options your service depends on to run. It additionally can include configuration options that users might want to enable for more advanced or customized usage. Ultimately, these values influence the UI elements for a user to interact with. Specifically, they evaluate to the options available when managing a service, such as:
- 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)
- When the user installs a service and the service is in the "Needs Config" state
- Whenever a user edits a service config
- 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``.
The neat part about this file is that each ValueSpec type gets translated into a specific front end component. For instance, boolean values display as a toggle button.
If null by default is true, nullable must be true.
If null by default is false, nullable could be either.
Another advantage is the ability to define default values. These values automatically get populated if the user selects the ``Default`` option when setting up a service in ``Needs Config`` state. This is super convenient for users who want to get up and running quickly.
Lists of any type do not contain the nullable/default for each item in list. The list *itself* can be nullable/have default.
Types
-----
Descriptions are encouraged but not required.
ConfigSpec Type:
``Tag`` is the key that will be rendered on the UI element.
.. code::
The ``Config`` type is written in the same syntax as the config rules:
key: ValueSpec
ValueSpec Type: Boolean | Enum | List | Number | Object | String | Union | Pointer (see below for details)
Implementation Guide
--------------------
The following section contains implementation specifications for the ``config_spec.yaml`` file.
- All keys are ``kebab-case`` strings
- keys correspond to the
- All values are one the following specs (ie. ValueSpec type):
- :ref:`boolean <boolean>`
- :ref:`enum <enum>`
- :ref:`list <list>`
- :ref:`number <number>`
- :ref:`object <object>`
- :ref:`string <string>`
- :ref:`union <union>`
- :ref:`pointer <pointer>`
- In the examples for each value spec type below, ``Option`` means the key is optional. Otherwise, the key is required.
- Descriptions are optional but recommended
- Name corresponds to the name of the config field
- Find a complete example :ref:`here <example_config_spec>`
- Change warning text displays when the value is altered
.. _boolean:
Boolean
^^^^^^^
Config value specification denoted as a boolean value. A default value is required.
ValueSpec Type:
.. code::
type: boolean
name: String
description: Option<String>
changeWarning: Option<String>
default: Boolean
Example:
.. code:: yaml
fetch-blocks:
type: boolean
name: Fetch Blocks
description: Fetch blocks from the network if pruned from disk
default: true
.. _enum:
Enum
^^^^
Config value specification denoted as an enum value. Enums values must be a unique set. If no default is provided, ``null`` will be the assumed value.
ValueSpec Type:
.. code::
type: enum
name: String
description: Option<String>
changeWarning: Option<String>
default: Option<Enum>
values: Set<String>
.. code:: yaml
theme-mode:
type: enum
name: Theme Mode
values:
- NIGHT
- DAY
valueNames:
NIGHT: Night
DAY: Day
default: NIGHT
.. _list:
List
^^^^
The list type describes an array of values. The values must consist of the same subtype, which can be any of the ValueSpec types available in the EmbassyOS config specification.
Lists of any type do not contain the default for each item in list. The list *itself* can be have a default. If no default is provided, ``null`` will be the assumed value.
Range is loosely based off mathematical range syntax, with infinity replaced with ``*``:
@@ -45,264 +145,359 @@ eg:
[0,*) - all numbers to infinity including 0
Types
-----
ValueSpec Type:
.. code:: typescript
.. code::
interface ConfigSpec {
serviceId: ValueSpecAny
}
type: list
name: String
description: Option<String>
subtype: enum || number || object || string || union
range: NumRange<unsigned integer>
spec: ValueSpec
default: ValueSpec
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:
Example:
.. code:: yaml
password:
type: string
allowed-calls:
type: list
name: Allowed Calls
description: The list of all RPC methods this user is allowed to make
subtype: enum
range: "[0, *)"
spec:
type: enum
values:
- item
- item
.. _number:
Number
^^^^^^
A number value within an optionally defined range. Nullable field is required. If ``nullable: true``, the default is assumed to be ``null`` if it is not provided.
ValueSpec Type:
.. code::
type: number
name: String
description: Option<String>
changeWarning: Option<String>
default: Boolean
nullable: Boolean
range: Option<NumRange<64 bit floating point>>
integral: Boolean
units: Option<String>
Example:
.. code:: yaml
type: number
name: Peer Message Timeout
description: How long to wait for a response from a peer before failing
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."
integral: true
units: Seconds
range: "[0, *)"
default: 30
.. _object:
Object Type
^^^^^^^^^^^
A nested representation of a ConfigSpec. The object type takes the same structure under the ``spec`` key as a ConfigSpec: a key indicates the field name, and the value denotes the ValueSpec type for that field.
There is no default option for the object type. Rather, the option ``null-by-default`` should be used to indicate the default as ``null``. If null by default is true, nullable must be true. If null by default is false, nullable could be either.
ValueSpec Type:
.. code::
type: object
name: String
description: Option<String>
changeWarning: Option<String>
nullable: Boolean
null-by-default: Boolean
display-as: Option<String>
unique-by: any | all | exactly | not unique
spec: ConfigSpec
Example:
.. code:: yaml
type: object
name: Advanced
description: Advanced settings for Bitcoin Proxy
nullable: false
spec:
tor-only:
type: boolean
name: Only Tor Peers
description: Use Tor for all peer connections
default: false
peer-timeout:
type: number
name: Peer Message Timeout
description: How long to wait for a response from a peer before failing
nullable: false
integral: true
units: Seconds
range: "[0, *)"
default: 30
max-peer-age:
type: number
name: Maximum Peer Age
description: How long to wait before refreshing the peer list
nullable: false
integral: true
units: Seconds
range: "[0, *)"
default: 300
max-peer-concurrency:
type: number
name: Maximum Peer Concurrency
description: How many peers to reach out to concurrently for block data
nullable: true
integral: true
range: "[1, *)"
default: 1
.. _string:
String
^^^^^^
There are various options for string values. They can optionally be marked as copyable or masked, such as for passwords, which will reflect the UI element display. A pattern, expressed in regex, can be denoted. If it exists, this field requires both the pattern type (ie. Regex) and pattern description (ie. an explanation of the pattern requirements).
If the default type is ``Entropy``, the charset can optionally specify an inclusive ranged character set (ie. "a-f,0-9").
ValueSpec Type:
.. code::
type: string
name: String
description: Option<String>
changeWarning: Option<String>
copyable: Option<boolean>
masked: Option<boolean>
nullable: Boolean
default: String | Entropy
pattern: Option<Regex>
pattern-description: Option<String>
Entropy Type:
.. code::
charset: Option<String>
len: integer
Examples:
.. code::
color:
type: string
name: Color
description: Color value for the Lightning Network
nullable: false
pattern: "[0-9a-fA-F]{6}"
patternDescription: |
Must be a valid 6 digit hexadecimal RGB value. The first two digits are red, middle two are green and final two are
blue
default:
charset: "a-f,0-9"
len: 6
password:
type: string
name: Password
description: The password for the RPC User
nullable: false
copyable: true
masked: true
default:
charset: "a-z,A-Z,0-9"
len: 22
.. _pointer:
Pointer
^^^^^^^
The pointer type *points* to a config value on another service installed on EmbassyOS (ie. app subtype) or to the EmbassyOS system (ie. system subtype). When pointing to another service, the ``index`` field indicates the path to the desired config variable.
ValueSpec Type:
.. code::
type: pointer
name: String
description: Option<String>
changeWarning: Option<String>
subtype: app | system
app-id: String (*always* kebab case)
target: AppPointerSpecVariants | SystemPointerSpecVariants
index: Option<String> (dependent on target being AppPointerSpecVariants)
AppPointerSpecVariants = LanAddress | TorAddress | TorKey | Config
SystemPointerSpecVariants = HostIp
Example:
.. code::
user:
type: pointer
name: RPC Username
description: The username for the RPC user for Bitcoin Core
subtype: app
app-id: bitcoind
target: config
index: "rpc.username"
.. _union:
Union
^^^^^
This type describes a necessary dependency. Multiple variants can be expressed to enable the user the option to connect to another service (internal dependency) or outside source (external dependency).
For example, the Bitcoin Proxy service is united with an instance of Bitcoin. Three variants are defined: internal, external, and a quick connect. In this case, internal refers to the Bitcoin Core instance running on EmbassyOS, and defines the RPC credentials necessary for connecting; external refers to a Bitcoin Core node running on a different device, and defines the RPC credentials necessary for connecting; quick connect refers to yet another method of connecting to a Bitcoin Core node, optimized for convenience.
Default is required and corresponds to one of the variants.
``Tag`` is the key that will be rendered on the UI element.
ValueSpec Type;
.. code::
type: union
name: String
description: Option<String>
changeWarning: Option<String>
default: Boolean
tag: Tag
variants: Map<String, ConfigSpec>
display-as: Option<String> TODO ask aiden if this should be exposed
unique-by: any | all | exactly | notUnique TODO ask aiden
Tag Type:
.. code::
id: String
name: String
description: Option<String>
variant-names: Map<String, String>
Example:
.. 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
description: The Bitcoin Core node to connect to
tag:
id: type
name: Type
description: |
- Internal: The Bitcoin Core service installed to your Embassy
- External: A Bitcoin Core node running on a different device
- Quick Connect: A Quick Connect URL for an unpruned Bitcoin Core node
variant-names:
internal: Internal
external: External
quick-connect: Quick Connect
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'
address:
type: pointer
name: Local Address
description: The LAN IP address of your Bitcoin Core service
subtype: app
app-id: bitcoind
target: lan-address
user:
type: pointer
name: RPC Username
description: The username for the RPC user for Bitcoin Core
subtype: app
app-id: bitcoind
target: config
index: "rpc.username"
password:
type: pointer
name: RPC Password
description: The password for the RPC user for Bitcoin Core
subtype: app
app-id: bitcoind
target: config
index: "rpc.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
addressext:
type: string
name: Public Address
description: The public address of your Bitcoin Core RPC server
nullable: false
userext:
type: string
name: RPC Username
description: The username for the RPC user on your Bitcoin Core RPC server
nullable: false
passwordext:
type: string
name: RPC Password
description: The password for the RPC user on your Bitcoin Core RPC server
nullable: false
quick-connect:
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
.. _config_rules:
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.
This file defines the configuration rules, or the rule-set that defines dependencies between config variables.
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.)
* 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:
Variables can be booleans, numbers, or strings, and have a different syntax depending on the type:
- 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
- ``?`` - 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.
If application does not satisfy a rule, give a set of suggestions, in the form of operation to preform:
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 - set the value
- Push
- Push - add to the value (such as with a list)
- Delete
- Delete - delete the value
.. code::typescript
.. code:: typescript
enum SuggestionVariant = Set | Delete | Push

28
source/contributing/services/index.rst
View File

@@ -1,20 +1,26 @@
.. _service_sdk:
***************************************
Services Software Development Kit Guide
***************************************
***********************
Service Packaging Guide
***********************
This guide serves as an introduction to the concepts and the technical details for developing a service for the Embassy.
The `File Browser wrapper repository <https://github.com/Start9Labs/filebrowser-wrapper>`_ should be used as an example.
This technical guide covers the necessary steps to package up a service for deployment to an Embassy. To start, you will need to acquire :ref:`EmbassyOS <purchasing>` for testing the packaged service.
TODO wrapper readme template
While you are waiting to assemble a device, you can begin the process of building your project in the format necessary to run on the Embassy. The sections below outline these steps in detail.
For reference, the `Hello world repository <https://github.com/Start9Labs/hello-world-wrapper>`_ should be used as an example. A project template can be cloned using the ``Use this template`` button in GitHub.
.. toctree::
:maxdepth: 2
dependencies
config
manifest
docker
overview
wrapper
overview
docker
manifest
config
dependencies
Submission process
------------------
When you have built and tested your project for EmbassyOS, please send us a submission with the project repository to `dev@start9labs.com`.

4
source/contributing/services/manifest.rst
View File

@@ -4,7 +4,9 @@
Service Manifest
****************
This file describes the service and it's requirements. Important to note is the dependencies key, which contains rules for optional or required other services that are depended on for the developed service to successfully run.
This file describes the service and it's requirements. It is used by the marketplace to create a service listing.
Important to note is the dependencies key, which contains rules for optional or required other services that are depended on for the developed service to successfully run.
Formatting:
- Serialization language:``.yaml``