doc/afb-overview.md

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