Allows or in mustache instanciation

[src/app-framework-main.git] / docs / config.xml.md

diff --git a/docs/config.xml.md b/docs/config.xml.md
index 7f413d5..8894667 100644 (file)
--- a/docs/config.xml.md
+++ b/docs/config.xml.md
@@ -61,7 +61,7 @@ The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
 
 Values for *id* are any non empty string containing only latin letters,
 arabic digits, and the three characters '.' (dot), '-' (dash) and
 
 Values for *id* are any non empty string containing only latin letters,
 arabic digits, and the three characters '.' (dot), '-' (dash) and

-'_' (underscore).
+'\_' (underscore).

 
 Authors can use a mnemonic id or can pick a unique id using
 command **uuid** or **uuidgen**.
 
 Authors can use a mnemonic id or can pick a unique id using
 command **uuid** or **uuidgen**.


@@ -72,7 +72,7 @@ The attribute *version* is mandatory (for version 2.x, blowfish).
 
 Values for *version* are any non empty string containing only latin letters,
 arabic digits, and the three characters '.' (dot), '-' (dash) and
 
 Values for *version* are any non empty string containing only latin letters,
 arabic digits, and the three characters '.' (dot), '-' (dash) and

-'_' (underscore).
+'\_' (underscore).

 
 Version values are dot separated fields MAJOR.MINOR.REVISION.
 Such version would preferabily follow guidelines of
 
 Version values are dot separated fields MAJOR.MINOR.REVISION.
 Such version would preferabily follow guidelines of


@@ -96,62 +96,135 @@ AGL features
 The AGL framework uses the feature tag for specifying security and binding
 requirement of the widget.
 
 The AGL framework uses the feature tag for specifying security and binding
 requirement of the widget.
 

-The current version of AGL (up to 2.0.1, blowfish) has no fully implemented
-features.
+Since the migration of the framework to leverage systemd power,
+the features are of important use to:

 
 

-The features planned to be implemented are described below.
+ - declare more than just an application
+ - declare the expected dependencies
+ - declare the expected permissions
+ - declare the exported apis

 
 

-### feature name="urn:AGL:widget:required-binding"
+The specification of [widgets][widgets] is intentded to describe
+only one application. In the present case, we expect to describe
+more than just an application. For example, a publisher could
+provide a widget containing a service, an application for tuning
+that service, an application that leverage the service.
+Here, the term of service means a background application that
+runs without IHM and whose public api can be accessed by other
+applications.

 
 

-List of the bindings required by the widget.
+So the features are used to describe each of the possible
+units of widgets. The "standard" unit in the
+meaning of [widgets][widgets] is called the "main" unit.

 
 

-Each required binding must be explicited using a <param> entry.
+### feature name="urn:AGL:widget:required-api"
+
+List of the api required by the widget.
+
+Each required api must be explicited using a <param> entry.

 
 Example:
 ```xml
 
 Example:
 ```xml

-<feature name="urn:AGL:widget:required-binding">
-  <param name="urn:AGL:permission:A" value="required" />
-  <param name="urn:AGL:permission:B" value="optional" />
+<feature name="urn:AGL:widget:required-api">
+  <param name="#target" value="main" />>
+  <param name="gps" value="auto" />
+  <param name="afm-main" value="link" />

 </feature>
 ```
 
 This will be *virtually* translated for mustaches to the JSON
 ```json
 </feature>
 ```
 
 This will be *virtually* translated for mustaches to the JSON
 ```json

-"required-binding": {
-  "param": [
-      { "name": "urn:AGL:permission:A", "value": "required", "required": true },
-      { "name": "urn:AGL:permission:A", "value": "optional", "optional": true }
-    ],
-  "urn:AGL:permission:A": { "name": "urn:AGL:permission:A", "value": "required", "required": true },
-  "urn:AGL:permission:B": { "name": "urn:AGL:permission:B", "value": "optional", "optional": true }
-}
+"required-api": [
+   { "name": "gps", "value": "auto" },
+   { "name": "afm-main", "value": "link" }
+ ]

 ```
 
 #### param name="#target"
 
 ```
 
 #### param name="#target"
 

-Declares the name of the component requiring the listed bindings.
+OPTIONAL
+
+Declares the name of the unit requiring the listed apis.

 Only one instance of the param "#target" is allowed.
 Only one instance of the param "#target" is allowed.

-When there is not instance of the param
-The value is either:
+When there is not instance of this param, it behave as if
+the target main was specified.

 
 

-- required: the binding is mandatorily needed except if the feature
-isn't required (required="false") and in that case it is optional.
-- optional: the binding is optional
+#### param name=[required api name]

 
 

-#### param name=[required binding name]
+The name is the name of the required API.

 
 

-The value is either:
+The value describes how to connect to the required api.
+It is either:

 
 

-- required: the binding is mandatorily needed except if the feature
-isn't required (required="false") and in that case it is optional.
-- optional: the binding is optional
+ - local:
+
+   The binding is a local shared object.
+   In that case, the name is the relative path of the
+   shared object to be loaded.
+
+ - auto:
+
+   The framework set automatically the kind of
+   the connection to the API
+
+ - ws:
+
+   The framework connect using internal websockets
+
+ - dbus:
+
+   The framework connect using internal dbus
+
+ - link:
+
+   The framework connect in memory by dinamically linking
+
+ - cloud: [PROPOSAL - NOT IMPLEMENTED]
+
+   The framework connect externally using websock.
+   In that case, the name includes data to access the service.
+   Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`

 
 ### feature name="urn:AGL:widget:required-permission"
 
 
 ### feature name="urn:AGL:widget:required-permission"
 

-List of the permissions required by the widget.
+List of the permissions required by the unit.

 
 Each required permission must be explicited using a <param> entry.
 
 
 Each required permission must be explicited using a <param> entry.
 

+Example:
+
+```xml
+  <feature name="urn:AGL:widget:required-permission">
+    <param name="#target" value="geoloc" />
+    <param name="urn:AGL:permission:real-time" value="required" />
+    <param name="urn:AGL:permission:syscall:*" value="required" />
+  </feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+
+```json
+"required-permission":{
+  "urn:AGL:permission:real-time":{
+    "name":"urn:AGL:permission:real-time",
+    "value":"required"
+  },
+  "urn:AGL:permission:syscall:*":{
+    "name":"urn:AGL:permission:syscall:*",
+    "value":"required"
+  }
+}
+```
+
+#### param name="#target"
+
+OPTIONAL
+
+Declares the name of the unit requiring the listed permissions.
+Only one instance of the param "#target" is allowed.
+When there is not instance of this param, it behave as if
+the target main was specified.
+

 #### param name=[required permission name]
 
 The value is either:
 #### param name=[required permission name]
 
 The value is either:


@@ -160,123 +233,254 @@ The value is either:
 isn't required (required="false") and in that case it is optional.
 - optional: the permission is optional
 
 isn't required (required="false") and in that case it is optional.
 - optional: the permission is optional
 

-### feature name="urn:AGL:widget:provided-binding"

 
 

-Use this feature for each provided binding of the widget.
-The parameters are:
+### feature name="urn:AGL:widget:provided-unit"

 
 

-#### param name="subid"
+This feature is made for declaring new units
+for the widget. Using this feature, a software publisher
+can provide more than one application in the same widget.

 
 

-REQUIRED
+Example:
+```xml
+  <feature name="urn:AGL:widget:provided-unit">
+    <param name="#target" value="geoloc" />
+    <param name="description" value="binding of name geoloc" />
+    <param name="content.src" value="index.html" />
+    <param name="content.type" value="application/vnd.agl.service" />
+  </feature>
+```

 
 

-The value is the string that must match the binding prefix.
-It must be unique.
+This will be *virtually* translated for mustaches to the JSON
+```json
+    {
+      "#target":"geoloc",
+      "description":"binding of name geoloc",
+      "content":{
+        "src":"index.html",
+        "type":"application\/vnd.agl.service"
+      },
+      ...
+    }
+```

 
 

-#### param name="name"
+#### param name="#target"

 
 REQUIRED
 
 
 REQUIRED
 

-The value is the string that must match the binding prefix.
-It must be unique.
+Declares the name of the unit. The default unit, the unit
+of the main of the widget, has the name "main". The value
+given here must be unique within the widget file. It will
+be used in other places of the widget config.xml file to
+designate the unit.
+
+Only one instance of the param "#target" is allowed.
+The value can't be "main".

 
 

-#### param name="src"
+#### param name="content.type"

 
 REQUIRED
 
 
 REQUIRED
 

-The value is the path of the shared library for the binding.
+The mimetype of the provided unit.

 
 

-#### param name="type"
+#### param name="content.src"

 
 

-REQUIRED
+A path to the 

 
 

-Currently it must be ***application/vnd.agl.binding.v1***.
+#### other parameters

 
 

+The items that can be set for the main unit
+can also be set using the params if needed.

 
 

-#### param name="scope"
+ - description
+ - name.content
+ - name.short
+ - ...

 
 

-REQUIRED

 
 

-The value indicate the availability of the binidng:
+### feature name="urn:AGL:widget:provided-api"

 
 

-- private: used only by the widget
-- public: available to allowed clients as a remote service (requires permission+)
-- inline: available to allowed clients inside their binding (unsafe, requires permission+++)
+Use this feature for exporting one or more API of a unit
+to other widgets of the platform.
+
+This feature is an important feature of the framework.
+
+Example:
+
+```xml
+  <feature name="urn:AGL:widget:provided-api">
+    <param name="#target" value="geoloc" />
+    <param name="geoloc" value="auto" />
+    <param name="moonloc" value="auto" />
+  </feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+
+```json
+      "provided-api":[
+        {
+          "name":"geoloc",
+          "value":"auto"
+        },
+        {
+          "name":"moonloc",
+          "value":"auto"
+        }
+      ],
+```
+
+#### param name="#target"

 
 

-#### param name="needed-binding"

 
 OPTIONAL
 
 
 OPTIONAL
 

-The value is a space separated list of binding's names that the binding needs.
+Declares the name of the unit exporting the listed apis.
+Only one instance of the param "#target" is allowed.
+When there is not instance of this param, it behave as if
+the target main was specified.

 
 

-### feature name="urn:AGL:widget:defined-permission"

 
 

-Each required permission must be explicited using a <param> entry.
+#### param name=[name of exported api]
+
+The name give the name of the api that is exported.
+
+The value is one of the following values:
+
+ - ws:
+
+   export the api using UNIX websocket

 
 

-#### param name=[defined permission name]
+ - dbus:

 
 

-The value is the level of the defined permission.
-Standard levels are: 
+   export the API using dbus

 
 

-- system
-- platform
-- partner
-- tiers
-- public
+ - auto:
+
+   export the api using the default method(s).

 
 

-This level defines the level of accreditation required to get the given
-permission. The accreditions are given by signatures of widgets.

 
 Known content types
 -------------------
 
 
 Known content types
 -------------------
 

-The configuration file ***/etc/afm/afm-unit.conf*** defines the types
-of widget known and how to launch it.
+The configuration file ***/etc/afm/afm-unit.conf*** defines
+how to create systemd units for widgets.

 
 

-Known types for the type of content are (for version 2.x, blowfish):
+Known types for the type of content are:

 
 - ***text/html***: 
    HTML application,
    content.src designates the home page of the application
 
 
 - ***text/html***: 
    HTML application,
    content.src designates the home page of the application
 

+- ***application/vnd.agl.native***
+   AGL compatible native,
+   content.src designates the relative path of the binary.
+
+- ***application/vnd.agl.service***:
+   AGL service, content.src is not used.
+

 - ***application/x-executable***:
    Native application,
 - ***application/x-executable***:
    Native application,

-   content.src designates the relative path of the binary
+   content.src designates the relative path of the binary.
+   For such application, only security setup is made.

 
 

-- ***application/vnd.agl.url***:
-   Internet url,
-   content.src designates the url to be used
+Adding more types is easy, it just need to edit the configuration
+file ***afm-unit.conf***.

 
 

-- ***application/vnd.agl.service***:
-   AGL service defined as a binder,
-   content.src designates the directory of provided binders,
-   http content, if any, must be put in the subdirectory ***htdocs*** of the widget
-
-- ***application/vnd.agl.native***:
-   Native application with AGL service defined as a binder,
-   content.src designates the relative path of the binary,
-   bindings, if any must be put in the subdirectory ***lib*** of the widget,
-   http content, if any, must be put in the subdirectory ***htdocs*** of the widget
-
-- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***:
-   QML application,
-   content.src designate the relative path of the QML root,
-   imports must be put in the subdirectory ***imports*** of the widget
-
-- ***application/vnd.agl.qml.hybrid***:
-   QML application with bindings,
-   content.src designate the relative path of the QML root,
-   bindings, if any must be put in the subdirectory ***lib*** of the widget,
-   imports must be put in the subdirectory ***imports*** of the widget
-
-- ***application/vnd.agl.html.hybrid***:
-   HTML application,
-   content.src designates the home page of the application,
-   bindings, if any must be put in the subdirectory ***lib*** of the widget,
-   http content must be put in the subdirectory ***htdocs*** of the widget
+### Older content type currently not supported at the moment.
+
+This types were defined previously when the framework was not
+leveraging systemd. The transition to systemd let these types
+out at the moment.
+
+- ***application/vnd.agl.url***
+- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
+- ***application/vnd.agl.qml.hybrid***
+- ***application/vnd.agl.html.hybrid***
+
+
+The configuration file afm-unit.conf
+====================================
+
+The integration of the framework with systemd
+mainly consists of creating the systemd unit
+files corresponding to the need and requirements
+of the installed widgets.
+
+This configuration file named `afm-unit.conf` installed
+on the system wiht the path `/etc/afm/afm-unit.conf`
+describes how to generate all units from the *config.xml*
+configuration files of widgets. The description uses an extended
+version of the templating formalism of [mustache][]
+to describes all the units.
+
+Let present how it works using the following diagram that
+describes graphically the workflow of creating the unit
+files for systemd `afm-unit.conf` from the configuration
+file of the widget `config.xml`:
+
+![make-units][make-units]
+
+In a first step, and because [mustache][] is intended
+to work on JSON representations, the configuration file is
+translated to an internal JSON representation. This
+representation is shown along the examples of the documentation
+of the config files of widgets.
+
+In a second step, the mustache template `afm-unit.conf`
+is instanciated using the C library [mustach][] that follows
+the rules of [mustache][mustache] and with all its available
+extensions:
+
+ - use of colon (:) for explicit substitution
+ - test of values with = or =!
+
+In a third step, the result of instanciating `afm-unit.conf`
+for the widget is splited in units. To achieve that goal,
+the lines containing specific directives are searched.
+Any directive occupy one full line. The directives are:
+
+  - %nl
+
+    Produce an empty line at the end
+
+  - %begin systemd-unit
+  - %end systemd-unit
+
+    Delimit the produced unit, its begin and its end
+
+  - %systemd-unit user
+  - %systemd-unit system
+
+    Tells the kind of unit (user/system)
+
+  - %systemd-unit service NAME
+  - %systemd-unit socket NAME
+
+    Gives the name and type (service or socket) of the unit.
+    The extension is automatically computed from the type
+    and must not be set in the name.
+
+  - %systemd-unit wanted-by NAME
+
+    Tells to install a link to the unit in the wants of NAME
+
+Then the computed units are then written to the filesystem
+and inserted in systemd.
+
+The generated unit files will contain variables for internal
+use of the framework. These variables are starting with `X-AFM-`.
+The variables starting with `X-AFM-` but not with `X-AFM--` are
+the public variables. These variables will be returned by the
+framework as the details of an application (see **afm-util detail ...**).

 
 

----
+Variables starting with `X-AFM--` are private to the framework.
+By example, the variable  `X-AFM--http-port` is used to
+record the allocated port for applications.

 
 
 
 

+[mustach]:          https://gitlab.com/jobol/mustach                                "basic C implementation of mustache"
+[mustache]:         http://mustache.github.io/mustache.5.html                       "mustache - Logic-less templates"
+[make-units]:       pictures/make-units.svg

 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"