config rules clarification

source/contributing/services/config.rst

@@ -514,7 +514,7 @@ 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:
+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. 
@@ -534,43 +534,74 @@ If application does not satisfy a rule, a set of suggestions should be provided.
     enum SuggestionVariant = Set | Delete | Push
 
     interface Set {
-        var: String,
+        var: String, // fully qualified path without typecast
-        to: SetVariant,
+        // 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,
+        src: String, // path to key - removes if in a list
     }
+
     interface Push {
         to: String,
-        value: Value,
+        value: String, // string literal of value to be set
     }
 
-    enum SetVariant = To | ToValue | ToEntropy
+Set Examples:
-
-    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'
+    - 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
 
-    to-entropy: {
+    - SET:
-        charset: 'a-z,A-Z,0-9'
+        var: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks'
-        len: 22
+        to-value: true
-    }
 
-    to: true
+
+Push Examples:
 
 .. code:: yaml
 
-    - rule: 'rpc.enable? OR !(''advanced.pruning.mode = "manual")'
+    - PUSH:
-      description: "RPC must be enabled for manual pruning."
+        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
 
 .. role:: raw-html(raw)
     :format: html

source/contributing/services/index.rst

@@ -4,7 +4,11 @@
 Service Packaging Guide
 ***********************
 
-This technical guide covers the necessary steps to package up a service for deployment to the EmbassyOS platform. To start, you will need to acquire :ref:`EmbassyOS <purchasing>` for testing the packaged service.
+This technical guide covers the necessary steps to package up a service for deployment to the EmbassyOS platform. To start, you will need to acquire EmbassyOS for testing the packaged service. This can be done by:
+
+- building from `source <https://github.com/Start9Labs/embassy-os/blob/master/CONTRIBUTING.md#setting-up-your-development-environment>`_
+- :ref:`DIY <diy>`
+- :ref:`purchasing <purchasing>`
 
 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.
 
@@ -15,9 +19,9 @@ For reference, the `Hello world <https://github.com/Start9Labs/hello-world-wrapp
 
   Overview <overview>
   Wrapper <wrapper>
+  Manifest <manifest>
   Docker <docker>
   Makefile <makefile>
-  Manifest <manifest>
   Config <config>
   Properties <properties>
   Docs <docs>

source/contributing/services/manifest.rst

@@ -39,19 +39,19 @@ Example
         short: String
         long: String
     # a link to the release tag notes in GitHub, or a short description TODO character length
-    release_notes: String
+    release-notes: String
     # a notification message that should caution the user with any service particularities, eg. beta tech
-    install_alert: Option<String>
+    install-alert: Option<String>
     # a notification message warning users of potential problems with uninstalling, such as dependency failures or data loss
-    uninstall_alert: Option<String>
+    uninstall-alert: Option<String>
     # a notification message containing warning or details about backup restoration
-    restore_alert: Option<String>
+    restore-alert: Option<String>
     # denoting the existence of instructions.md
-    has_instructions: Boolean
+    has-instructions: Boolean
     # required semver version range of EmbassyOS to run service eg. ">=1.0.0"
-    os_version_required: VersionReq
+    os-version-required: VersionReq
     # recommended semver version range of EmbassyOS to run service eg."^1.0.0"
-    os_version_recommended: VersionReq
+    os-version-recommended: VersionReq
     # a list of objects of ports to run the service on localhost and tor
     ports:
         - internal: String
@@ -60,22 +60,17 @@ Example
     image:
         type: String
     # shared memory container size
-    shm_size_mb: Option<usize>
+    shm-size-mb: Option<usize>
     # path to mount the image on the volume, ie: /root/bitcoind
     mount: String
-    # public directory path
+    # read only data exposed to dependencies (path is relevant to mount)
     public: Option<String>
-    # shared directory path
+    # shared filesystem segment with each of your dependencies (path is relevant to mount)
     shared: Option<String>
-    # a list of objecting containing the source and destination directories of persistent assets, either that should be copied over during build, or to persist when service started, and if the volume directory should be overwritten when the release is copied over
+    # deprecated - will default to an empty vector
-    # src: path to file within the assets directory that is in the build directory
+    assets: []
-    # dst: path within volume to place it
+    # version of tor support, eg. v2, v3
-    assets:
+    hidden-service-version: String
-      - src: String TODO confirm type
-        dst: String TODO confirm type
-        overwrite: Boolean
-    # version of tor support, eg. v1, v2, v3
-    hidden_service_version: String
     # A map of dependent services, see below for more details
     dependencies: Dependencies
 
@@ -132,7 +127,7 @@ Types for ``manifest.yaml`` fields:
     }
 
     interface ConfigRule {
-        rule: String, // ie. '''users.*.name = "lnd"'
+        rule: String, // ie. 'users.*.name = "lnd"
         description: String,
         suggestions: [SuggestionVariant]
     }