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 <p>For this case, the binder afb-daemon takes care to attribute one single session
 202 context to each client instance. It allows plugins to store and retrieve data
 203 associated to each of its client.</p>
 204
 205 <a name="The.plugins.of.the.binder.afb-daemon"></a>
 206 <h2>The plugins of the binder afb-daemon</h2>
 207
 208 <p>The binder can instanciate plugins. The primary use of plugins
 209 is to add native methods that can be accessed by applications
 210 written with any language through web technologies ala JSON RPC.</p>
 211
 212 <p>This simple idea is declined to serves multiple purposes:</p>
 213
 214 <ol>
 215 <li><p>add native feature to applications</p></li>
 216 <li><p>add common API available by any applications</p></li>
 217 <li><p>provide customers services</p></li>
 218 </ol>
 219
 220
 221 <p>A specific document explains how to write an afb-daemon binder plugin:
 222 <a href="afb-plugin-writing.html">HOWTO WRITE a PLUGIN for AFB-DAEMON</a></p>
 223
 224 <a name="Launching.the.binder.afb-daemon"></a>
 225 <h2>Launching the binder afb-daemon</h2>
 226
 227 <p>The launch options for binder <strong>afb-daemon</strong> are:</p>
 228
 229 <pre><code>  --help
 230
 231         Prints help with available options
 232
 233   --version
 234
 235         Display version and copyright
 236
 237   --verbose
 238
 239         Increases the verbosity, can be repeated
 240
 241   --port=xxxx
 242
 243         HTTP listening TCP port  [default 1234]
 244
 245   --rootdir=xxxx
 246
 247         HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]
 248
 249   --rootbase=xxxx
 250
 251         Angular Base Root URL [default /opa]
 252
 253         This is used for any application of kind OPA (one page application).
 254         When set, any missing document whose url has the form /opa/zzz
 255         is translated to /opa/#!zzz
 256
 257   --rootapi=xxxx
 258
 259         HTML Root API URL [default /api]
 260
 261         The plugins are available within that url.
 262
 263   --alias=xxxx
 264
 265         Maps a path located anywhere in the file system to the
 266         a subdirectory. The syntax for mapping a PATH to the
 267         subdirectory NAME is: --alias=/NAME:PATH.
 268
 269         Example: --alias=/icons:/usr/share/icons maps the
 270         content of /usr/share/icons within the subpath /icons.
 271
 272         This option can be repeated.
 273
 274   --apitimeout=xxxx
 275
 276         Plugin API timeout in seconds [default 20]
 277
 278         Defines how many seconds maximum a method is allowed to run.
 279         0 means no limit.
 280
 281   --cntxtimeout=xxxx
 282
 283         Client Session Timeout in seconds [default 3600]
 284
 285   --cache-eol=xxxx
 286
 287         Client cache end of live [default 100000 that is 27,7 hours]
 288
 289   --sessiondir=xxxx
 290
 291         Sessions file path [default rootdir/sessions]
 292
 293   --session-max=xxxx
 294
 295         Maximum count of simultaneous sessions [default 10]
 296
 297   --ldpaths=xxxx
 298
 299         Load Plugins from given paths separated by colons
 300         as for dir1:dir2:plugin1.so:... [default = $libdir/afb]
 301
 302         You can mix path to directories and to plugins.
 303         The sub-directories of the given directories are searched
 304         recursively.
 305
 306         The plugins are the files terminated by '.so' (the extension
 307         so denotes shared object) that contain the public entry symbol.
 308
 309   --plugin=xxxx
 310
 311         Load the plugin of given path.
 312
 313   --token=xxxx
 314
 315         Initial Secret token to authenticate.
 316
 317         If not set, no client can authenticate.
 318
 319         If set to the empty string, then any initial token is accepted.
 320
 321   --mode=xxxx
 322
 323         Set the mode: either local, remote or global.
 324
 325         The mode indicate if the application is run locally on the host
 326         or remotely through network.
 327
 328   --readyfd=xxxx
 329
 330         Set the #fd to signal when ready
 331
 332         If set, the binder afb-daemon will write "READY=1\n" on the file
 333         descriptor whose number if given (/proc/self/fd/xxx).
 334
 335   --dbus-client=xxxx
 336
 337         Transparent binding to a binder afb-daemon service through dbus.
 338
 339         It creates an API of name xxxx that is implemented remotely
 340         and queried via DBUS.
 341
 342   --dbus-server=xxxx
 343
 344         Provides a binder afb-daemon service through dbus.
 345
 346         The name xxxx must be the name of an API defined by a plugin.
 347         This API is exported through DBUS.
 348
 349   --foreground
 350
 351         Get all in foreground mode (default)
 352
 353   --daemon
 354
 355         Get all in background mode
 356 </code></pre>
 357
 358 <a name="Future.development.of.afb-daemon"></a>
 359 <h2>Future development of afb-daemon</h2>
 360
 361 <ul>
 362 <li><p>The binder afb-daemon would launch the applications directly.</p></li>
 363 <li><p>The current setting of mode (local/remote/global) might be reworked to a
 364 mechanism for querying configuration variables.</p></li>
 365 <li><p>Implements &ldquo;one-shot&rdquo; initial token. It means that after its first
 366 authenticated use, the initial token is removed and no client can connect
 367 anymore.</p></li>
 368 <li><p>Creates some intrinsic APIs.</p></li>
 369 <li><p>Make the service connection using WebSocket not DBUS.</p></li>
 370 <li><p>Management of targetted events.</p></li>
 371 <li><p>Securisation of LOA.</p></li>
 372 <li><p>Integration of the protocol JSON-RPC for the websockets.</p></li>
 373 </ul>
 374 </body>
 375 </html>