Add the ability to access binding through tcp

This commit introduce "tcp", a new type of
provided/required api. It appears in the config.xml
as below:

  <urn:AGL:widget:provided-api>
    <param "name"="HOST:PORT/API" "value"="tcp">

  <urn:AGL:widget:required-api>
    <param "name"="HOST:PORT/API" "value"="tcp">

This implementation is a draft. The service
exposed can not start automatically. Use it
with the permission urn:AGL:permission::system:run-by-default.

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

diff --git a/conf/unit/afm-unit-debug.conf.in b/conf/unit/afm-unit-debug.conf.in
index accf8ca..f7e37a2 100644 (file)
--- a/conf/unit/afm-unit-debug.conf.in
+++ b/conf/unit/afm-unit-debug.conf.in
@@ -182,6 +182,7 @@ ExecStart=/usr/bin/afb-daemon \
                {{#value=dbus}}--dbus-client={{name}}{{/value=dbus}} \
                {{#value=cloud}}--cloud-client={{name}}{{/value=cloud}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \
                {{#value=dbus}}--dbus-client={{name}}{{/value=dbus}} \
                {{#value=cloud}}--cloud-client={{name}}{{/value=cloud}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \

+               {{#value=tcp}}--ws-client=tcp:{{name}}{{/value=tcp}} \

        {{/required-api}} \
        {{#required-binding}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \
        {{/required-api}} \
        {{#required-binding}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \


@@ -190,6 +191,7 @@ ExecStart=/usr/bin/afb-daemon \
        {{#provided-api}} \
                {{#value=auto|ws}}--ws-server=sd:{{name}}{{/value=auto|ws}} \
                {{#value=dbus}}--dbus-server={{name}}{{/value=dbus}} \
        {{#provided-api}} \
                {{#value=auto|ws}}--ws-server=sd:{{name}}{{/value=auto|ws}} \
                {{#value=dbus}}--dbus-server={{name}}{{/value=dbus}} \

+               {{#value=tcp}}--ws-server=tcp:{{name}}{{/value=tcp}} \

        {{/provided-api}} \
        {{#content.type=text/html}}--exec /usr/bin/web-runtime http://localhost:@p/{{content.src}}?token=@t{{/content.type=text/html}} \
        {{#content.type=application/vnd.agl.native}}--exec {{:#metadata.install-dir}}/{{content.src}} @p @t{{/content.type=application/vnd.agl.native}}
        {{/provided-api}} \
        {{#content.type=text/html}}--exec /usr/bin/web-runtime http://localhost:@p/{{content.src}}?token=@t{{/content.type=text/html}} \
        {{#content.type=application/vnd.agl.native}}--exec {{:#metadata.install-dir}}/{{content.src}} @p @t{{/content.type=application/vnd.agl.native}}

diff --git a/conf/unit/afm-unit.conf.in b/conf/unit/afm-unit.conf.in
index e1d2112..4672c98 100644 (file)
--- a/conf/unit/afm-unit.conf.in
+++ b/conf/unit/afm-unit.conf.in
@@ -182,6 +182,7 @@ ExecStart=/usr/bin/afb-daemon \
                {{#value=dbus}}--dbus-client={{name}}{{/value=dbus}} \
                {{#value=cloud}}--cloud-client={{name}}{{/value=cloud}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \
                {{#value=dbus}}--dbus-client={{name}}{{/value=dbus}} \
                {{#value=cloud}}--cloud-client={{name}}{{/value=cloud}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \

+               {{#value=tcp}}--ws-client=tcp:{{name}}{{/value=tcp}} \

        {{/required-api}} \
        {{#required-binding}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \
        {{/required-api}} \
        {{#required-binding}} \
                {{#value=local}}--binding={{:#metadata.install-dir}}/{{name}}{{/value=local}} \


@@ -190,6 +191,7 @@ ExecStart=/usr/bin/afb-daemon \
        {{#provided-api}} \
                {{#value=auto|ws}}--ws-server=sd:{{name}}{{/value=auto|ws}} \
                {{#value=dbus}}--dbus-server={{name}}{{/value=dbus}} \
        {{#provided-api}} \
                {{#value=auto|ws}}--ws-server=sd:{{name}}{{/value=auto|ws}} \
                {{#value=dbus}}--dbus-server={{name}}{{/value=dbus}} \

+               {{#value=tcp}}--ws-server=tcp:{{name}}{{/value=tcp}} \

        {{/provided-api}} \
        {{#content.type=text/html}}--exec /usr/bin/web-runtime http://localhost:@p/{{content.src}}?token=@t{{/content.type=text/html}} \
        {{#content.type=application/vnd.agl.native}}--exec {{:#metadata.install-dir}}/{{content.src}} @p @t{{/content.type=application/vnd.agl.native}}
        {{/provided-api}} \
        {{#content.type=text/html}}--exec /usr/bin/web-runtime http://localhost:@p/{{content.src}}?token=@t{{/content.type=text/html}} \
        {{#content.type=application/vnd.agl.native}}--exec {{:#metadata.install-dir}}/{{content.src}} @p @t{{/content.type=application/vnd.agl.native}}

diff --git a/conf/unit/generate-unit-conf/binder.inc b/conf/unit/generate-unit-conf/binder.inc
index 57f4166..8f3bd7d 100644 (file)
--- a/conf/unit/generate-unit-conf/binder.inc
+++ b/conf/unit/generate-unit-conf/binder.inc
@@ -35,6 +35,7 @@ ENDIF \
                ON_VALUE(dbus,          --dbus-client={{name}}) \
                ON_VALUE(cloud,         --cloud-client={{name}}) \
                ON_VALUE(local,         --binding={{:#metadata.install-dir}}/{{name}}) \
                ON_VALUE(dbus,          --dbus-client={{name}}) \
                ON_VALUE(cloud,         --cloud-client={{name}}) \
                ON_VALUE(local,         --binding={{:#metadata.install-dir}}/{{name}}) \

+               ON_VALUE(tcp,           --ws-client=tcp:{{name}}) \

        {{/required-api}} \
        {{#required-binding}} \
                ON_VALUE(local,         --binding={{:#metadata.install-dir}}/{{name}}) \
        {{/required-api}} \
        {{#required-binding}} \
                ON_VALUE(local,         --binding={{:#metadata.install-dir}}/{{name}}) \


@@ -43,6 +44,7 @@ ENDIF \
        {{#provided-api}} \
                ON_VALUE(auto|ws,       --ws-server=sd:{{name}}) \
                ON_VALUE(dbus,          --dbus-server={{name}}) \
        {{#provided-api}} \
                ON_VALUE(auto|ws,       --ws-server=sd:{{name}}) \
                ON_VALUE(dbus,          --dbus-server={{name}}) \

+               ON_VALUE(tcp,           --ws-server=tcp:{{name}}) \

        {{/provided-api}} \
        ON_CONTENT(text/html,                   --exec /usr/bin/web-runtime http://localhost:@p/{{content.src}}?token=@t) \
        ON_CONTENT(application/vnd.agl.native,  --exec {{:#metadata.install-dir}}/{{content.src}} @p @t)
        {{/provided-api}} \
        ON_CONTENT(text/html,                   --exec /usr/bin/web-runtime http://localhost:@p/{{content.src}}?token=@t) \
        ON_CONTENT(application/vnd.agl.native,  --exec {{:#metadata.install-dir}}/{{content.src}} @p @t)

diff --git a/docs/2.2-config.xml.md b/docs/2.2-config.xml.md
index 2be9371..de0b8d7 100644 (file)
--- a/docs/2.2-config.xml.md
+++ b/docs/2.2-config.xml.md
@@ -71,7 +71,7 @@ Values for *version* are any non empty string containing only latin letters,
 arabic digits, and the three characters '.' (dot), '-' (dash) and
 '\_' (underscore).
 
 arabic digits, and the three characters '.' (dot), '-' (dash) and
 '\_' (underscore).
 

-Version values are dot separated fields MAJOR.MINOR.REVISION.  
+Version values are dot separated fields MAJOR.MINOR.REVISION.

 Such version would preferably follow guidelines of
 [semantic versioning][semantic-version].
 
 Such version would preferably follow guidelines of
 [semantic versioning][semantic-version].
 


@@ -101,18 +101,18 @@ the features are of important use to:
 - declare the exported apis
 
 The specification of [widgets][widgets] is intended to describe
 - declare the exported apis
 
 The specification of [widgets][widgets] is intended to describe

-only one application.  
-In the present case, we expect to describe more than just an application.  
+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,
 For example, a publisher could provide a widget containing a service,

-an application for tuning that service, an application that 
-leverage the 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
 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] 
+units of widgets.
+The "standard" unit in the meaning of [widgets][widgets]

 is called the "main" unit.
 
 ### required-api: feature name="urn:AGL:widget:required-api"
 is called the "main" unit.
 
 ### required-api: feature name="urn:AGL:widget:required-api"


@@ -145,7 +145,7 @@ This will be *virtually* translated for mustaches to the JSON
 OPTIONAL
 
 Declares the name of the unit requiring the listed apis.
 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 this param, it behave as if
 the target main was specified.
 
 When there is not instance of this param, it behave as if
 the target main was specified.
 


@@ -153,7 +153,7 @@ the target main was specified.
 
 The name is the name of the required API.
 
 
 The name is the name of the required API.
 

-The value describes how to connect to the required api.  
+The value describes how to connect to the required api.

 It is either:
 
 - local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY 
 It is either:
 
 - local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY 


@@ -162,19 +162,25 @@ It is either:
   In that case, the name is the relative path of the
   shared object to be loaded.
 
   In that case, the name is the relative path of the
   shared object to be loaded.
 

-- auto:  
+- auto:

   The framework set automatically the kind of
   the connection to the API
 
   The framework set automatically the kind of
   the connection to the API
 

-- ws:  
+- ws:

   The framework connect using internal websockets
 
   The framework connect using internal websockets
 

-- dbus:  
+- dbus: [OBSOLETE, shouldn't be used currently]

   The framework connect using internal dbus
 
   The framework connect using internal dbus
 

-- cloud: [PROPOSAL - NOT IMPLEMENTED]  
-  The framework connect externally using websock.  
-  In that case, the name includes data to access the service.  
+- tcp:
+  In that case, the name is the URI to access the service.
+  The framework connect using a URI of type
+   HOST:PORT/API
+  API gives the name of the imported api.
+
+- 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" />`
 
 ### required-binding: feature name="urn:AGL:widget:required-binding"
   Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`
 
 ### required-binding: feature name="urn:AGL:widget:required-binding"


@@ -215,7 +221,7 @@ The value describes how to connect to the required binding.
 It is either:
 
 - local:
 It is either:
 
 - local:

-  The binding is a local shared object.  
+  The binding is a local shared object.

   In that case, the name is the relative path of the
   shared object to be loaded.
 
   In that case, the name is the relative path of the
   shared object to be loaded.
 


@@ -288,8 +294,8 @@ This will be *virtually* translated for mustaches to the JSON
 
 OPTIONAL
 
 
 OPTIONAL
 

-Declares the name of the unit requiring the listed permissions.  
-Only one instance of the param "#target" is allowed.  
+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.
 
 When there is not instance of this param, it behave as if
 the target main was specified.
 


@@ -304,7 +310,7 @@ The value is either:
 ### provided-unit: feature name="urn:AGL:widget:provided-unit"
 
 This feature is made for declaring new units
 ### provided-unit: feature name="urn:AGL:widget:provided-unit"
 
 This feature is made for declaring new units

-for the widget.  
+for the widget.

 Using this feature, a software publisher
 can provide more than one application in the same widget.
 
 Using this feature, a software publisher
 can provide more than one application in the same widget.
 


@@ -338,12 +344,12 @@ This will be *virtually* translated for mustaches to the JSON
 REQUIRED
 
 Declares the name of the unit. The default unit, the unit
 REQUIRED
 
 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.  
+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.
 
 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.  
+Only one instance of the param "#target" is allowed.

 The value can't be "main".
 
 #### provided-unit: param name="content.type"
 The value can't be "main".
 
 #### provided-unit: param name="content.type"


@@ -402,8 +408,8 @@ This will be *virtually* translated for mustaches to the JSON
 
 OPTIONAL
 
 
 OPTIONAL
 

-Declares the name of the unit exporting the listed apis.  
-Only one instance of the param "#target" is allowed.  
+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.
 
 When there is not instance of this param, it behave as if
 the target main was specified.
 


@@ -413,15 +419,21 @@ The name give the name of the api that is exported.
 
 The value is one of the following values:
 
 
 The value is one of the following values:
 

-- ws:  
+- ws:

   export the api using UNIX websocket
 
   export the api using UNIX websocket
 

-- dbus:  
+- dbus: [OBSOLETE, shouldn't be used currently]

   export the API using dbus
 
   export the API using dbus
 

-- auto:  
+- auto:

   export the api using the default method(s).
 
   export the api using the default method(s).
 

+- tcp:
+  In that case, the name is the URI used for exposing the service.
+  The URI is of type
+   HOST:PORT/API
+  API gives the name of the exported api.
+

 ### file-properties: feature name="urn:AGL:widget:file-properties"
 
 Use this feature for setting properties to files of the widget.
 ### file-properties: feature name="urn:AGL:widget:file-properties"
 
 Use this feature for setting properties to files of the widget.


@@ -451,20 +463,20 @@ how to create systemd units for widgets.
 
 Known types for the type of content are:
 
 
 Known types for the type of content are:
 

-- ***text/html***:  
-  HTML application,  
+- ***text/html***:
+  HTML application,

   content.src designates the home page of the application
 
   content.src designates the home page of the application
 

-- ***application/vnd.agl.native***  
-  AGL compatible native,  
+- ***application/vnd.agl.native***
+  AGL compatible native,

   content.src designates the relative path of the binary.
 
   content.src designates the relative path of the binary.
 

-- ***application/vnd.agl.service***:  
+- ***application/vnd.agl.service***:

   AGL service, content.src is not used.
 
   AGL service, content.src is not used.
 

-- ***application/x-executable***:  
-  Native application,  
-  content.src designates the relative path of the binary.  
+- ***application/x-executable***:
+  Native application,
+  content.src designates the relative path of the binary.

   For such application, only security setup is made.
 
 Adding more types is easy, it just need to edit the configuration
   For such application, only security setup is made.
 
 Adding more types is easy, it just need to edit the configuration


@@ -473,7 +485,7 @@ file ***afm-unit.conf***.
 ### Older content type currently not supported at the moment
 
 This types were defined previously when the framework was not
 ### Older content type currently not supported at the moment
 
 This types were defined previously when the framework was not

-leveraging systemd.  
+leveraging systemd.

 The transition to systemd let these types out at the moment.
 
 - ***application/vnd.agl.url***
 The transition to systemd let these types out at the moment.
 
 - ***application/vnd.agl.url***


@@ -493,8 +505,8 @@ of the installed widgets.
 This configuration file named `afm-unit.conf` installed
 on the system with the path `/etc/afm/afm-unit.conf`
 describes how to generate all units from the *config.xml*
 This configuration file named `afm-unit.conf` installed
 on the system with 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 
+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
 formalism of [mustache][] to describes all the units.
 
 Let present how it works using the following diagram that


@@ -506,7 +518,7 @@ file of the widget `config.xml`:
 
 In a first step, and because [mustache][] is intended
 to work on JSON representations, the configuration file is
 
 In a first step, and because [mustache][] is intended
 to work on JSON representations, the configuration file is

-translated to an internal JSON representation.  
+translated to an internal JSON representation.

 This representation is shown along the examples of the documentation
 of the config files of widgets.
 
 This representation is shown along the examples of the documentation
 of the config files of widgets.
 


@@ -519,9 +531,9 @@ extensions:
 - test of values with = or =!
 
 In a third step, the result of instantiating `afm-unit.conf`
 - test of values with = or =!
 
 In a third step, the result of instantiating `afm-unit.conf`

-for the widget is split in units.  
-To achieve that goal, the lines containing specific directives are searched.  
-Any directive occupy one full line.  
+for the widget is split in units.
+To achieve that goal, the lines containing specific directives are searched.
+Any directive occupy one full line.

 The directives are:
 
 - %nl
 The directives are:
 
 - %nl


@@ -534,7 +546,7 @@ The directives are:
   Tells the kind of unit (user/system)
 - %systemd-unit service NAME
 - %systemd-unit socket NAME
   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.  
+  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
   The extension is automatically computed from the type
   and must not be set in the name.
 - %systemd-unit wanted-by NAME


@@ -544,14 +556,14 @@ Then the computed units are then written to the filesystem
 and inserted in systemd.
 
 The generated unit files will contain variables for internal
 and inserted in systemd.
 
 The generated unit files will contain variables for internal

-use of the framework.  
-These variables are starting with `X-AFM-`.  
+use of the framework.
+These variables are starting with `X-AFM-`.

 The variables starting with `X-AFM-` but not with `X-AFM--` are
 The variables starting with `X-AFM-` but not with `X-AFM--` are

-the public variables.  
+the public variables.

 These variables will be returned by the
 framework as the details of an application (see **afm-util detail ...**).
 
 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.  
+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.
 
 By example, the variable  `X-AFM--http-port` is used to
 record the allocated port for applications.