doc/afb-overview.html

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