doc/afb-overview.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="doc.css">
   4   <meta charset="UTF-8">
   5 </head>
   6 <body>
   7 <a name="Overview.of.AFB-DAEMON"></a>
   8 <h1>Overview of AFB-DAEMON</h1>
   9
  10 <pre><code>version: 1
  11 Date:    30 mai 2016
  12 Author:  José Bollo
  13 </code></pre>
  14
  15 <p><ul>
  16  <li><a href="#Overview.of.AFB-DAEMON">Overview of AFB-DAEMON</a>
  17  <ul>
  18   <li><a href="#Roles.of.afb-daemon">Roles of afb-daemon</a></li>
  19   <li><a href="#Use.cases.of.the.binder.afb-daemon">Use cases of the binder afb-daemon</a>
  20   <ul>
  21    <li><a href="#Remotely.running.application">Remotely running application</a></li>
  22    <li><a href="#Adding.native.features.to.HTML5.QML.applications">Adding native features to HTML5/QML applications</a></li>
  23    <li><a href="#Offering.services.to.the.system">Offering services to the system</a></li>
  24   </ul>
  25   </li>
  26   <li><a href="#The.plugins.of.the.binder.afb-daemon">The plugins of the binder afb-daemon</a></li>
  27   <li><a href="#Launching.the.binder.afb-daemon">Launching the binder afb-daemon</a></li>
  28   <li><a href="#Future.development.of.afb-daemon">Future development of afb-daemon</a></li>
  29  </ul>
  30  </li>
  31 </ul></p>
  32
  33 <a name="Roles.of.afb-daemon"></a>
  34 <h2>Roles of afb-daemon</h2>
  35
  36 <p>The name <strong>afb-daemon</strong> stands for <em>Application
  37 Framework Binder Daemon</em>. That is why afb-daemon
  38 is also named <strong><em>the binder</em></strong>.</p>
  39
  40 <p><strong>Afb-daemon</strong> is in charge to bind one instance of
  41 an application to the AGL framework and AGL system.</p>
  42
  43 <p>On the following figure, you can use a typical use
  44 of afb-daemon:</p>
  45
  46 <p><a id="binder-fig-basis"><h4>Figure: binder afb-daemon, basis</h4></a></p>
  47
  48 <pre><code>. . . . . . . . . . . . . . . . . . . . . . . . . .
  49 .        Isolated security context                .
  50 .                                                 .
  51 .        +------------------------------+         .
  52 .        |                              |         .
  53 .        |    A P P L I C A T I O N     |         .
  54 .        |                              |         .
  55 .        +--------------+---------------+         .
  56 .                       |                         .
  57 .                       |                         .
  58 .   +-------------------+----------------------+  .
  59 .   |                            :             |  .
  60 .   |        b i n d e r         :             |  .
  61 .   |    A F B - D A E M O N     :   PLUGINS   |  .
  62 .   |                            :             |  .
  63 .   +-------------------+----------------------+  .
  64 .                       |                         .
  65 . . . . . . . . . . . . | . . . . . . . . . . . . .
  66                         |
  67                         v
  68                    AGL SYSTEM
  69 </code></pre>
  70
  71 <p>The application and its companion binder run in secured and isolated
  72 environment set for them. Applications are intended to access to AGL
  73 system through the binder.</p>
  74
  75 <p>The binder afb-daemon serves multiple purposes:</p>
  76
  77 <ol>
  78 <li><p>It acts as a gateway for the application to access the system;</p></li>
  79 <li><p>It acts as an HTTP server for serving files to HTML5 applications;</p></li>
  80 <li><p>It allows HTML5 applications to have native extensions subject
  81 to security enforcement for accessing hardware ressources or
  82 for speeding parts of algorithm.</p></li>
  83 </ol>
  84
  85
  86 <a name="Use.cases.of.the.binder.afb-daemon"></a>
  87 <h2>Use cases of the binder afb-daemon</h2>
  88
  89 <p>This section tries to give a better understanding of the binder
  90 usage through several use cases.</p>
  91
  92 <a name="Remotely.running.application"></a>
  93 <h3>Remotely running application</h3>
  94
  95 <p>One of the most interresting aspect of using the binder afb-daemon
  96 is the ability to run applications remotely. This feature is
  97 possible because the binder afb-daemon implements native web
  98 protocols.</p>
  99
 100 <p>So the <a href="#binder-fig-1">figure binder, basis</a> would become
 101 when the application is run remotely:</p>
 102
 103 <p><a id="binder-fig-remote"><h4>Figure: binder afb-daemon and remotely running application</h4></a></p>
 104
 105 <pre><code>             +------------------------------+
 106              |                              |
 107              |    A P P L I C A T I O N     |
 108              |                              |
 109              +--------------+---------------+
 110                             |
 111                        ~ ~ ~ ~ ~ ~
 112                       :  NETWORK  :
 113                        ~ ~ ~ ~ ~ ~
 114                             |
 115 . . . . . . . . . . . . . . | . . . . . . . . . . . . . .
 116 . Isolated security         |                           .
 117 .   context                 |                           .
 118 .                           |                           .
 119 .     . . . . . . . . . . . . . . . . . . . . . . . .   .
 120 .     .                                             .   .
 121 .     .               F I R E W A L L               .   .
 122 .     .                                             .   .
 123 .     . . . . . . . . . . . . . . . . . . . . . . . .   .
 124 .                           |                           .
 125 .       +-------------------+----------------------+    .
 126 .       |                            :             |    .
 127 .       |    A F B - D A E M O N     :   PLUGINS   |    .
 128 .       |                            :             |    .
 129 .       +-------------------+----------------------+    .
 130 .                           |                           .
 131 . . . . . . . . . . . . . . | . . . . . . . . . . . . . .
 132                             |
 133                             v
 134                        AGL SYSTEM
 135 </code></pre>
 136
 137 <a name="Adding.native.features.to.HTML5.QML.applications"></a>
 138 <h3>Adding native features to HTML5/QML applications</h3>
 139
 140 <p>Applications can provide with their packaged delivery a plugin.
 141 That plugin will be instanciated for each application instance.
 142 The methods of the plugin will be accessible by applications and
 143 will be excuted within the security context.</p>
 144
 145 <a name="Offering.services.to.the.system"></a>
 146 <h3>Offering services to the system</h3>
 147
 148 <p>It is possible to run the binder afb-daemon as a daemon that provides the
 149 API of its plugins.</p>
 150
 151 <p>This will be used for:</p>
 152
 153 <ol>
 154 <li><p>offering common APIs</p></li>
 155 <li><p>provide application&rsquo;s services (services provided as application)</p></li>
 156 </ol>
 157
 158
 159 <p>In that case, the figure showing the whole aspects is</p>
 160
 161 <p><a id="binder-fig-remote"><h4>Figure: binder afb-daemon for services</h4></a></p>
 162
 163 <pre><code>. . . . . . . . . . . . . . . . . . . . . .
 164 .  Isolated security context application  .
 165 .                                         .
 166 .    +------------------------------+     .
 167 .    |                              |     .
 168 .    |    A P P L I C A T I O N     |     .
 169 .    |                              |     .
 170 .    +--------------+---------------+     .     . . . . . . . . . . . . . . . . . . . . . .
 171 .                   |                     .     .        Isolated security context A      .
 172 .                   |                     .     .                                         .
 173 . +-----------------+------------------+  .     . +------------------------------------+  .
 174 . |                        :           |  .     . |                        :           |  .
 175 . |      b i n d e r       :           |  .     . |      b i n d e r       :  service  |  .
 176 . |  A F B - D A E M O N   :  PLUGINS  |  .     . |  A F B - D A E M O N   :  PLUGINS  |  .
 177 . |                        :           |  .     . |                        :     A     |  .
 178 . +-----------------+------------------+  .     . +-----------------+------------------+  .
 179 .                   |                     .     .                   |                     .
 180 . . . . . . . . . . | . . . . . . . . . . .     . . . . . . . . . . | . . . . . . . . . . .
 181                     |                                               |
 182                     v                                               v
 183          ================================================================================
 184                                      D - B U S   &amp;   C Y N A R A
 185          ================================================================================
 186                     ^                                               ^
 187                     |                                               |
 188 . . . . . . . . . . | . . . . . . . . . . .     . . . . . . . . . . | . . . . . . . . . . .
 189 .                   |                     .     .                   |                     .
 190 . +-----------------+------------------+  .     . +-----------------+------------------+  .
 191 . |                        :           |  .     . |                        :           |  .
 192 . |      b i n d e r       :  service  |  .     . |      b i n d e r       :  service  |  .
 193 . |  A F B - D A E M O N   :  PLUGINS  |  .     . |  A F B - D A E M O N   :  PLUGINS  |  .
 194 . |                        :     B     |  .     . |                        :     C     |  .
 195 . +------------------------------------+  .     . +------------------------------------+  .
 196 .                                         .     .                                         .
 197 .        Isolated security context B      .     .        Isolated security context C      .
 198 . . . . . . . . . . . . . . . . . . . . . .     . . . . . . . . . . . . . . . . . . . . . .
 199 </code></pre>
 200
 201 <a name="The.plugins.of.the.binder.afb-daemon"></a>
 202 <h2>The plugins of the binder afb-daemon</h2>
 203
 204 <p>The binder can instanciate plugins. The primary use of plugins
 205 is to add native methods that can be accessed by applications
 206 written with any language through web technologies ala JSON RPC.</p>
 207
 208 <p>This simple idea is declined to serves multiple purposes:</p>
 209
 210 <ol>
 211 <li><p>add native feature to applications</p></li>
 212 <li><p>add common API available by any applications</p></li>
 213 <li><p>provide customers services</p></li>
 214 </ol>
 215
 216
 217 <p>A specific document shows</p>
 218
 219 <a name="Launching.the.binder.afb-daemon"></a>
 220 <h2>Launching the binder afb-daemon</h2>
 221
 222 <p>The launch options for binder <strong>afb-daemon</strong> are:</p>
 223
 224 <pre><code>  --help
 225
 226         Prints help with available options
 227
 228   --version
 229
 230         Display version and copyright
 231
 232   --verbose
 233
 234         Increases the verbosity, can be repeated
 235
 236   --port=xxxx
 237
 238         HTTP listening TCP port  [default 1234]
 239
 240   --rootdir=xxxx
 241
 242         HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]
 243
 244   --rootbase=xxxx
 245
 246         Angular Base Root URL [default /opa]
 247
 248         This is used for any application of kind OPA (one page application).
 249         When set, any missing document whose url has the form /opa/zzz
 250         is translated to /opa/#!zzz
 251
 252   --rootapi=xxxx
 253
 254         HTML Root API URL [default /api]
 255
 256         The plugins are available within that url.
 257
 258   --alias=xxxx
 259
 260         Maps a path located anywhere in the file system to the
 261         a subdirectory. The syntax for mapping a PATH to the
 262         subdirectory NAME is: --alias=/NAME:PATH.
 263
 264         Example: --alias=/icons:/usr/share/icons maps the
 265         content of /usr/share/icons within the subpath /icons.
 266
 267         This option can be repeated.
 268
 269   --apitimeout=xxxx
 270
 271         Plugin API timeout in seconds [default 20]
 272
 273         Defines how many seconds maximum a method is allowed to run.
 274         0 means no limit.
 275
 276   --cntxtimeout=xxxx
 277
 278         Client Session Timeout in seconds [default 3600]
 279
 280   --cache-eol=xxxx
 281
 282         Client cache end of live [default 100000 that is 27,7 hours]
 283
 284   --sessiondir=xxxx
 285
 286         Sessions file path [default rootdir/sessions]
 287
 288   --session-max=xxxx
 289
 290         Maximum count of simultaneous sessions [default 10]
 291
 292   --ldpaths=xxxx
 293
 294         Load Plugins from given paths separated by colons
 295         as for dir1:dir2:plugin1.so:... [default = $libdir/afb]
 296
 297         You can mix path to directories and to plugins.
 298         The sub-directories of the given directories are searched
 299         recursively.
 300
 301         The plugins are the files terminated by '.so' (the extension
 302         so denotes shared object) that contain the public entry symbol.
 303
 304   --plugin=xxxx
 305
 306         Load the plugin of given path.
 307
 308   --token=xxxx
 309
 310         Initial Secret token to authenticate.
 311
 312         If not set, no client can authenticate.
 313
 314         If set to the empty string, then any initial token is accepted.
 315
 316   --mode=xxxx
 317
 318         Set the mode: either local, remote or global.
 319
 320         The mode indicate if the application is run locally on the host
 321         or remotely through network.
 322
 323   --readyfd=xxxx
 324
 325         Set the #fd to signal when ready
 326
 327         If set, the binder afb-daemon will write "READY=1\n" on the file
 328         descriptor whose number if given (/proc/self/fd/xxx).
 329
 330   --dbus-client=xxxx
 331
 332         Transparent binding to a binder afb-daemon service through dbus.
 333
 334         It creates an API of name xxxx that is implemented remotely
 335         and queried via DBUS.
 336
 337   --dbus-server=xxxx
 338
 339         Provides a binder afb-daemon service through dbus.
 340
 341         The name xxxx must be the name of an API defined by a plugin.
 342         This API is exported through DBUS.
 343
 344   --foreground
 345
 346         Get all in foreground mode (default)
 347
 348   --daemon
 349
 350         Get all in background mode
 351 </code></pre>
 352
 353 <a name="Future.development.of.afb-daemon"></a>
 354 <h2>Future development of afb-daemon</h2>
 355
 356 <ul>
 357 <li><p>The binder afb-daemon would launch the applications directly.</p></li>
 358 <li><p>The current setting of mode (local/remote/global) might be reworked to a
 359 mechanism for querying configuration variables.</p></li>
 360 <li><p>Implements &ldquo;one-shot&rdquo; initial token. It means that after its first
 361 authenticated use, the initial token is removed and no client can connect
 362 anymore.</p></li>
 363 <li><p>Creates some intrinsic APIs.</p></li>
 364 <li><p>Make the service connection using WebSocket not DBUS.</p></li>
 365 <li><p>Management of targetted events.</p></li>
 366 <li><p>Securisation of LOA.</p></li>
 367 <li><p>Integration of the protocol JSON-RPC for the websockets.</p></li>
 368 </ul>
 369 </body>
 370 </html>