Provide unit in config.xml and documentation

This commit remove urn:AGL:widget:provided-application
in favour of urn:AGL:widget:provided-unit.
In the same time, the feature urn:AGL:widget:provided-api
must be attached to a unit. This will enable to export
more than one API for a unit if needed.

Change-Id: I17ade3651db2cd61402875333d063ee05cf57a10
Signed-off-by: José Bollo <jose.bollo@iot.bzh>

1 files changed, 296 insertions, 96 deletions

diff --git a/docs/config.xml.md b/docs/config.xml.md
index 7eac552..7939ebe 100644
--- 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
-'_' (underscore).
+'\_' (underscore).
 
 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
-'_' (underscore).
+'\_' (underscore).
 
 Version values are dot separated fields MAJOR.MINOR.REVISION.
 Such version would preferabily follow guidelines of
@@ -96,10 +96,26 @@ AGL features
 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
+
+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.
+
+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.
 
 ### feature name="urn:AGL:widget:required-api"
 
@@ -110,48 +126,105 @@ Each required api must be explicited using a <param> entry.
 Example:
 ```xml
 <feature name="urn:AGL:widget:required-api">
-  <param name="urn:AGL:permission:A" value="required" />
-  <param name="urn:AGL:permission:B" value="optional" />
+  <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
-"required-api": {
-  "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"
 
-Declares the name of the component requiring the listed bindings.
-Only one instance of the param "#target" is allowed.
-When there is not instance of the param
-The value is either:
+OPTIONAL
 
-- 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
+Declares the name of the unit requiring 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.
 
 #### param name=[required api name]
 
-The value is either:
+The name is the name of the required API.
 
-- 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
+The value describes how to connect to the required api.
+It is either:
+
+ - 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"
 
-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.
 
+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:
@@ -160,79 +233,139 @@ The value is either:
 isn't required (required="false") and in that case it is optional.
 - optional: the permission is optional
 
-### feature name="urn:AGL:widget:provided-api"
 
-Use this feature for each provided api 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
 
-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.
 
-#### param name="src"
+Only one instance of the param "#target" is allowed.
+The value can't be "main".
+
+#### param name="content.type"
 
 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"
+
+Use this feature for exporting one or more API of a unit
+to other widgets of the platform.
 
-- 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+++)
+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
 
-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"
+#### param name=[name of exported api]
 
-Each required permission must be explicited using a <param> entry.
+The name give the name of the api that is exported.
+
+The value is one of the following values:
 
-#### param name=[defined permission name]
+ - ws:
 
-The value is the level of the defined permission.
-Standard levels are: 
+   export the api using UNIX websocket
 
-- system
-- platform
-- partner
-- tiers
-- public
+ - dbus:
+
+   export the API using dbus
+
+ - 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
 -------------------
 
-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,
@@ -242,41 +375,108 @@ Known types for the type of content are (for version 2.x, blowfish):
    Native application,
    content.src designates the relative path of the binary
 
-- ***application/vnd.agl.url***:
-   Internet url,
-   content.src designates the url to be used
-
 - ***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
+   AGL service, content.src is not used.
+
+Adding more types is easy, it just need to edit the configuration
+file ***afm-unit.conf***.
+
+### 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***
+- ***application/vnd.agl.native***
+- ***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"