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>

4 files changed, 65 insertions, 47 deletions

diff --git a/conf/unit/afm-unit-debug.conf.in b/conf/unit/afm-unit-debug.conf.in
index accf8ca..f7e37a2 100644
--- 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=tcp}}--ws-client=tcp:{{name}}{{/value=tcp}} \
 	{{/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}} \
+		{{#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}}
diff --git a/conf/unit/afm-unit.conf.in b/conf/unit/afm-unit.conf.in
index e1d2112..4672c98 100644
--- 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=tcp}}--ws-client=tcp:{{name}}{{/value=tcp}} \
 	{{/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}} \
+		{{#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}}
diff --git a/conf/unit/generate-unit-conf/binder.inc b/conf/unit/generate-unit-conf/binder.inc
index 57f4166..8f3bd7d 100644
--- 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(tcp,		--ws-client=tcp:{{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}}) \
+		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)
diff --git a/docs/2.2-config.xml.md b/docs/2.2-config.xml.md
index 2be9371..de0b8d7 100644
--- 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).
 
-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].
 
@@ -101,18 +101,18 @@ the features are of important use to:
 - 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,
-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
-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"
@@ -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.
-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.
 
@@ -153,7 +153,7 @@ the target main was specified.
 
 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 
@@ -162,19 +162,25 @@ It is either:
   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
 
-- ws:  
+- ws:
   The framework connect using internal websockets
 
-- dbus:  
+- dbus: [OBSOLETE, shouldn't be used currently]
   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"
@@ -215,7 +221,7 @@ The value describes how to connect to the required binding.
 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.
 
@@ -288,8 +294,8 @@ This will be *virtually* translated for mustaches to the JSON
 
 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.
 
@@ -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
-for the widget.  
+for the 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
-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.
 
-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"
@@ -402,8 +408,8 @@ This will be *virtually* translated for mustaches to the JSON
 
 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.
 
@@ -413,15 +419,21 @@ The name give the name of the api that is exported.
 
 The value is one of the following values:
 
-- ws:  
+- ws:
   export the api using UNIX websocket
 
-- dbus:  
+- dbus: [OBSOLETE, shouldn't be used currently]
   export the API using dbus
 
-- auto:  
+- auto:
   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.
@@ -451,20 +463,20 @@ how to create systemd units for widgets.
 
 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
 
-- ***application/vnd.agl.native***  
-  AGL compatible native,  
+- ***application/vnd.agl.native***
+  AGL compatible native,
   content.src designates the relative path of the binary.
 
-- ***application/vnd.agl.service***:  
+- ***application/vnd.agl.service***:
   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
@@ -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
-leveraging systemd.  
+leveraging systemd.
 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*
-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
@@ -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
-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.
 
@@ -519,9 +531,9 @@ extensions:
 - 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
@@ -534,7 +546,7 @@ The directives are:
   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
@@ -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
-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 public variables.  
+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.  
+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.