doc/afb-overview.md

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