diff options
Diffstat (limited to 'docs/config.xml.md')
| -rw-r--r-- | docs/config.xml.md | 392 |
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" |