1 How to write an application on top of AGL FRAMEWORK
2 ====================================================
4 Programming Languages for Applications
5 -----------------------------------------
7 ### Writing an HTML5 application
9 Developers of HTML5 applications (client side) can easily create
10 applications for AGL framework using their preferred
13 Developers may also take advantage of powerful server side bindings to improve
14 application behavior. Server side bindings return an application/json mine-type
15 and can be accessed though either HTTP or Websockets.
17 In a near future, JSON-RPC protocol should be added to complete the current
20 Two examples of HTML5 applications are given:
22 - [afb-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afb-client) a simple "hello world" application template
24 - [afm-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afm-client) a simple "Home screen" application template
26 ### Writing a Qt application
28 Writing Qt applications is also supported. Qt offers standard API to send
29 request through HTTP or WebSockets.
31 It is also possible to write QML applications. A sample QML application
32 [token-websock] is available:
34 - [token-websock](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=test/token-websock.qml)
35 a simple "hello world" application in QML
37 ### Writing a "C" application
39 C applications can use afb-daemon binder through a websocket connection.
41 The library **libafbwsc** is provided for C clients that need
42 to connect with an afb-daemon binder.
44 The program **afb-client-demo** is the C example that use
45 **libafbwsc** library.
46 Source code is available here
47 [src/afb-client-demo.c](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=src/afb-client-demo.c).
49 Current implementation relies on libsystemd and file descriptors.
50 This model might be review in the future to support secure sockets
51 and get rid of libsystemd dependency.
53 Handling sessions within applications
54 -------------------------------------
56 Applications should understand sessions and token management when interacting
57 with afb-daemon binder.
59 Applications communicate with their private binder(afb-daemon) using
60 a network connection or potentially any other connection channel. While the
61 current version does not yet implement Unix socket, this feature might be added
62 in the near future. Developers need to be warn that HTTP protocol is a none
63 connected protocol and that using HTTP socket connection to authenticate
64 clients is not supported.
66 For this reason, the binder should authenticate the application
67 by using a shared secret. The secret is named "token" and the identification
68 of client is named "session".
70 The examples **token-websock.qml** and **afb-client** are demonstrating
71 how authentication and sessions are managed.
75 Bindings and other binder features need to keep track of client
76 instances. This is especially important for bindings running as services
77 as they may typically have to keep each client's data separated.
79 For HTML5 applications, the web runtime handles the cookie of session
80 that the binder afb-daemon automatically sets.
82 Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in
83 URI requests. Within current version of the framework session UUID is supported
84 by both HTTP requests and websocket negotiation.
88 At application start, AGL framework communicates a shared secret to both binder
89 and client application. This initial secret is called the "**initial token**".
91 For each of its client application, the binder manages a current active
92 token for session management. This authentication token can be use to restrict
93 the access to some binding's methods.
95 The token must be included in URI request on HTTP or during websockets
96 connection using parameter **token** or **x-afb-token**.
98 To ensure security, tokens must be refreshed periodically.
100 ### Example of session management
102 In following examples, we suppose that **afb-daemon** is launched with something
105 $ afb-daemon --port=1234 --token=123456 [...]
107 making the expectation that **AuthLogin** binding is requested as default.
111 First, connects with the initial token, 123456:
113 $ curl http://localhost:1234/api/auth/connect?token=123456
115 "jtype": "afb-reply",
118 "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
119 "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
121 "response": {"token": "A New Token and Session Context Was Created"}
124 It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015,
125 and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.
127 Check if session and token is valid:
129 $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
131 "jtype": "afb-reply",
132 "request": {"status":"success"},
133 "response": {"isvalid":true}
138 $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
140 "jtype": "afb-reply",
143 "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
145 "response": {"token":"Token was refreshed"}
150 curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
152 "jtype": "afb-reply",
153 "request": {"status": "success"},
154 "response": {"info":"Token and all resources are released"}
157 Checking on closed session for uuid should be refused:
159 curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
161 "jtype": "afb-reply",
164 "info": "invalid token's identity"
168 #### Using afb-client-demo
170 > The program is packaged within AGL in the rpm **libafbwsc-dev**
172 Here is an example of exchange using **afb-client-demo**:
174 $ afb-client-demo ws://localhost:1234/api?token=123456
176 ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success",
177 "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"},
178 "response":{"token":"A New Token and Session Context Was Created"}}
180 ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
182 ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
183 "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
185 ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
187 ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
188 "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
190 After closing connection, reconnect as here after:
192 $ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check
193 ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
195 Same connection check using **curl**:
197 $ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1
198 {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
203 Replies use javascript object returned as serialized JSON.
205 This object contains at least 2 mandatory fields of name **jtype** and
206 **request** and one optional field of name **response**.
210 This is a template of replies:
214 "jtype": "afb-reply",
217 "info": "informationnal text",
218 "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
219 "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
220 "reqid": "application-generated-id-23456"
222 "response": ....any response object....
228 The field **jtype** must have a value of type string equal to **"afb-reply"**.
232 The field **request** must have a value of type object. This request object
233 has at least one field named **status** and four optional fields named
234 **info**, **token**, **uuid**, **reqid**.
236 #### Subfield request.status
238 **status** must have a value of type string. This string is equal to **"success"**
239 only in case of success.
241 #### Subfield request.info
243 **info** is of type string and represent optional information added to the reply.
245 #### Subfield request.token
247 **token** is of type string. It is sent either at session creation
248 or when the token is refreshed.
250 #### Subfield request.uuid
252 **uuid** is of type string. It is sent at session creation.
254 #### Subfield request.reqid
256 **reqid** is of type string. It is sent in response to HTTP requests
257 that added a parameter of name **reqid** or **x-afb-reqid** at request time.
258 Value returns in the reply has the exact same value as the one received in the
263 This field response optionally contains an object returned when request
269 Events are javascript object serialized as JSON.
271 This object contains at least 2 mandatory fields of name **jtype** and **event**
272 and one optional field of name **data**.
276 Here is a template of event:
280 "jtype": "afb-event",
281 "event": "sample_api_name/sample_event_name",
282 "data": ...any event data...
288 The field **jtype** must have a value of type string equal to **"afb-event"**.
292 The field **event** carries the event's name.
294 The name of the event is made of two parts separated by a slash:
295 the name of the name of the API that generated the event
296 and the name of event within the API.
300 This field data if present holds the data carried by the event.