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**.
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
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"
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:
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,
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"
Code Review / src / app-framework-main.git / blobdiff