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 ![binder-basis][binder-basis]
  21
  22 The application and its companion binder run in secured and isolated
  23 environment set for them. Applications are intended to access to AGL
  24 system through the binder.
  25
  26 The binder afb-daemon serves multiple purposes:
  27
  28 1. It acts as a gateway for the application to access the system;
  29
  30 2. It acts as an HTTP server for serving files to HTML5 applications;
  31
  32 3. It allows HTML5 applications to have native extensions subject
  33 to security enforcement for accessing hardware ressources or
  34 for speeding parts of algorithm.
  35
  36 Use cases of the binder afb-daemon
  37 ----------------------------------
  38
  39 This section tries to give a better understanding of the binder
  40 usage through several use cases.
  41
  42 ### Remotely running application
  43
  44 One of the most interesting aspect of using the binder afb-daemon
  45 is the ability to run applications remotely. This feature is
  46 possible because the binder afb-daemon implements native web
  47 protocols.
  48
  49 So the [figure binder, basis](#binder-fig-basis) would become
  50 when the application is run remotely:
  51
  52 <a id="binder-fig-remote"><h4>Figure: binder afb-daemon and remotely running application</h4></a>
  53
  54
  55 ### Adding native features to HTML5/QML applications
  56
  57 Applications can provide with their packaged delivery a binding.
  58 That binding will be instantiated for each application instance.
  59 The methods of the binding will be accessible by applications and
  60 will be executed within the security context.
  61
  62 ### Offering services to the system
  63
  64 It is possible to run the binder afb-daemon as a daemon that provides the
  65 API of its bindings.
  66
  67 This will be used for:
  68
  69 1. offering common APIs
  70
  71 2. provide application's services (services provided as application)
  72
  73 In that case, the figure showing the whole aspects is
  74
  75 <a id="binder-fig-remote"><h4>Figure: binder afb-daemon for services</h4></a>
  76
  77 ![afb-for-services][afb-for-services]
  78
  79 For this case, the binder afb-daemon takes care to attribute one single session
  80 context to each client instance. It allows bindings to store and retrieve data
  81 associated to each of its client.
  82
  83 The bindings of the binder afb-daemon
  84 ------------------------------------
  85
  86 The binder can instantiate bindings. The primary use of bindings
  87 is to add native methods that can be accessed by applications
  88 written with any language through web technologies ala JSON RPC.
  89
  90 This simple idea is declined to serves multiple purposes:
  91
  92 1. add native feature to applications
  93
  94 2. add common API available by any applications
  95
  96 3. provide customers services
  97
  98 A specific document explains how to write an afb-daemon binder binding:
  99 [HOWTO WRITE a BINDING for AFB-DAEMON](afb-binding-writing.html)
 100
 101
 102 Launching the binder afb-daemon
 103 -------------------------------
 104
 105 The launch options for binder **afb-daemon** are:
 106
 107           --help
 108
 109                 Prints help with available options
 110
 111           --version
 112
 113                 Display version and copyright
 114
 115           --verbose
 116
 117                 Increases the verbosity, can be repeated
 118
 119           --port=xxxx
 120
 121                 HTTP listening TCP port  [default 1234]
 122
 123           --rootdir=xxxx
 124
 125                 HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]
 126
 127           --rootbase=xxxx
 128
 129                 Angular Base Root URL [default /opa]
 130
 131                 This is used for any application of kind OPA (one page application).
 132                 When set, any missing document whose url has the form /opa/zzz
 133                 is translated to /opa/#!zzz
 134
 135           --rootapi=xxxx
 136
 137                 HTML Root API URL [default /api]
 138
 139                 The bindings are available within that url.
 140
 141           --alias=xxxx
 142
 143                 Maps a path located anywhere in the file system to the
 144                 a subdirectory. The syntax for mapping a PATH to the
 145                 subdirectory NAME is: --alias=/NAME:PATH.
 146
 147                 Example: --alias=/icons:/usr/share/icons maps the
 148                 content of /usr/share/icons within the subpath /icons.
 149
 150                 This option can be repeated.
 151
 152           --apitimeout=xxxx
 153
 154                 binding API timeout in seconds [default 20]
 155
 156                 Defines how many seconds maximum a method is allowed to run.
 157                 0 means no limit.
 158
 159           --cntxtimeout=xxxx
 160
 161                 Client Session Timeout in seconds [default 3600]
 162
 163           --cache-eol=xxxx
 164
 165                 Client cache end of live [default 100000 that is 27,7 hours]
 166
 167           --sessiondir=xxxx
 168
 169                 Sessions file path [default rootdir/sessions]
 170
 171           --session-max=xxxx
 172
 173                 Maximum count of simultaneous sessions [default 10]
 174
 175           --ldpaths=xxxx
 176
 177                 Load bindings from given paths separated by colons
 178                 as for dir1:dir2:binding1.so:... [default = $libdir/afb]
 179
 180                 You can mix path to directories and to bindings.
 181                 The sub-directories of the given directories are searched
 182                 recursively.
 183
 184                 The bindings are the files terminated by '.so' (the extension
 185                 so denotes shared object) that contain the public entry symbol.
 186
 187           --binding=xxxx
 188
 189                 Load the binding of given path.
 190
 191           --token=xxxx
 192
 193                 Initial Secret token to authenticate.
 194
 195                 If not set, no client can authenticate.
 196
 197                 If set to the empty string, then any initial token is accepted.
 198
 199           --mode=xxxx
 200
 201                 Set the mode: either local, remote or global.
 202
 203                 The mode indicate if the application is run locally on the host
 204                 or remotely through network.
 205
 206           --readyfd=xxxx
 207
 208                 Set the #fd to signal when ready
 209
 210                 If set, the binder afb-daemon will write "READY=1\n" on the file
 211                 descriptor whose number if given (/proc/self/fd/xxx).
 212
 213           --dbus-client=xxxx
 214
 215                 Transparent binding to a binder afb-daemon service through dbus.
 216
 217                 It creates an API of name xxxx that is implemented remotely
 218                 and queried via DBUS.
 219
 220           --dbus-server=xxxx
 221
 222                 Provides a binder afb-daemon service through dbus.
 223
 224                 The name xxxx must be the name of an API defined by a binding.
 225                 This API is exported through DBUS.
 226
 227           --foreground
 228
 229                 Get all in foreground mode (default)
 230
 231           --daemon
 232
 233                 Get all in background mode
 234
 235
 236 Future development of afb-daemon
 237 --------------------------------
 238
 239 - The binder afb-daemon would launch the applications directly.
 240
 241 - The current setting of mode (local/remote/global) might be reworked to a
 242 mechanism for querying configuration variables.
 243
 244 - Implements "one-shot" initial token. It means that after its first
 245 authenticated use, the initial token is removed and no client can connect
 246 anymore.
 247
 248 - Creates some intrinsic APIs.
 249
 250 - Make the service connection using WebSocket not DBUS.
 251
 252 - Management of targeted events.
 253
 254 - Securing LOA.
 255
 256 - Integration of the protocol JSON-RPC for the websockets.
 257
 258 [binder-basis]: pictures/AFB_overview.svg (Binder AFB daemon basis)
 259 [afb-for-services]: pictures/AFB_for_services.svg (Binder AFB daemon for services)