afb-api-js: first step for javascript bindings
[src/app-framework-binder.git] / old-docs / 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 <h4><a id="binder-fig-basis">Figure: binder afb-daemon, basis</a></h4>
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 resources 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 <h4><a id="binder-fig-remote">Figure: binder afb-daemon and remotely running application</a></h4>
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 <h4><a id="binder-fig-remote">Figure: binder afb-daemon for services</a></h4>
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-bindings-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           --quiet
120
121                 Decreases the verbosity, can be repeated
122
123           --port=xxxx
124
125                 HTTP listening TCP port  [default 1234]
126
127           --workdir=xxxx
128
129                 Directory where the daemon must run [default: $PWD if defined
130                 or the current working directory]
131
132           --uploaddir=xxxx
133
134                 Directory where uploaded files are temporarily stored [default: workdir]
135
136           --rootdir=xxxx
137
138                 Root directory of the application to serve [default: workdir]
139
140           --roothttp=xxxx
141
142                 Directory of HTTP served files. If not set, files are not served
143                 but apis are still accessibles.
144
145           --rootbase=xxxx
146
147                 Angular Base Root URL [default /opa]
148
149                 This is used for any application of kind OPA (one page application).
150                 When set, any missing document whose url has the form /opa/zzz
151                 is translated to /opa/#!zzz
152
153           --rootapi=xxxx
154
155                 HTML Root API URL [default /api]
156
157                 The bindings are available within that url.
158
159           --alias=xxxx
160
161                 Maps a path located anywhere in the file system to the
162                 a subdirectory. The syntax for mapping a PATH to the
163                 subdirectory NAME is: --alias=/NAME:PATH.
164
165                 Example: --alias=/icons:/usr/share/icons maps the
166                 content of /usr/share/icons within the subpath /icons.
167
168                 This option can be repeated.
169
170           --no-httpd
171
172                 Tells to not start the HTTP server.
173
174           --apitimeout=xxxx
175
176                 binding API timeout in seconds [default 20]
177
178                 Defines how many seconds maximum a method is allowed to run.
179                 0 means no limit.
180
181           --cntxtimeout=xxxx
182
183                 Client Session Timeout in seconds [default 3600]
184
185           --cache-eol=xxxx
186
187                 Client cache end of live [default 100000 that is 27,7 hours]
188
189           --session-max=xxxx
190
191                 Maximum count of simultaneous sessions [default 10]
192
193           --ldpaths=xxxx
194
195                 Load bindings from given paths separated by colons
196                 as for dir1:dir2:binding1.so:... [default = $libdir/afb]
197
198                 You can mix path to directories and to bindings.
199                 The sub-directories of the given directories are searched
200                 recursively.
201
202                 The bindings are the files terminated by '.so' (the extension
203                 so denotes shared object) that contain the public entry symbol.
204
205           --binding=xxxx
206
207                 Load the binding of given path.
208
209           --token=xxxx
210
211                 Initial Secret token to authenticate.
212
213                 If not set, no client can authenticate.
214
215                 If set to the empty string, then any initial token is accepted.
216
217           --random-token
218
219                 Generate a random starting token. See option --exec.
220
221           --mode=xxxx
222
223                 Set the mode: either local, remote or global.
224
225                 The mode indicate if the application is run locally on the host
226                 or remotely through network.
227
228           --readyfd=xxxx
229
230                 Set the #fd to signal when ready
231
232                 If set, the binder afb-daemon will write "READY=1\n" on the file
233                 descriptor whose number if given (/proc/self/fd/xxx).
234
235           --dbus-client=xxxx
236
237                 Transparent binding to a binder afb-daemon service through dbus.
238
239                 It creates an API of name xxxx that is implemented remotely
240                 and queried via DBUS.
241
242           --dbus-server=xxxx
243
244                 Provides a binder afb-daemon service through dbus.
245
246                 The name xxxx must be the name of an API defined by a binding.
247                 This API is exported through DBUS.
248
249           --ws-client=xxxx
250
251                 Transparent binding to a binder afb-daemon service through a WebSocket.
252
253                 The value of xxxx is either a unix naming socket, of the form "unix:path/api",
254                 or an internet socket, of the form "host:port/api".
255
256           --ws-server=xxxx
257
258                 Provides a binder afb-daemon service through WebSocket.
259
260                 The value of xxxx is either a unix naming socket, of the form "unix:path/api",
261                 or an internet socket, of the form "host:port/api".
262
263           --foreground
264
265                 Get all in foreground mode (default)
266
267           --daemon
268
269                 Get all in background mode
270
271           --no-httpd
272
273                 Forbids HTTP serve
274
275           --exec
276
277                 Must be the last option for afb-daemon. The remaining
278                 arguments define a command that afb-daemon will launch.
279                 The sequences @p, @t and @@ of the arguments are replaced
280                 with the port, the token and @.
281
282           --tracereq=xxxx
283
284                 Trace the processing of requests in the log file.
285
286                 Valid values are 'no' (default), 'common', 'extra' or 'all'.
287
288
289
290
291
292 Future development of afb-daemon
293 --------------------------------
294
295 - The binder afb-daemon would launch the applications directly.
296
297 - The current setting of mode (local/remote/global) might be reworked to a
298 mechanism for querying configuration variables.
299
300 - Implements "one-shot" initial token. It means that after its first
301 authenticated use, the initial token is removed and no client can connect
302 anymore.
303
304 - Creates some intrinsic APIs.
305
306 - Make the service connection using WebSocket not DBUS.
307
308 - Management of targeted events.
309
310 - Securing LOA.
311
312 - Integration of the protocol JSON-RPC for the websockets.
313
314 [binder-basis]: pictures/AFB_overview.svg
315 [afb-for-services]: pictures/AFB_for_services.svg