1 HOWTO WRITE an APPLICATION above AGL FRAMEWORK
2 ==============================================
9 Programmation Languages for Applications
10 -----------------------------------------
12 ### Writing an HTML5 application
14 Developers of HTML5 applications (client side) can easily create
15 applications for AGL framework using their preferred
18 Developers may also take advantage of powerful server side plugins to improve
19 application behavior. Server side plugins return an application/json mine-type
20 and can be accessed though either HTTP or Websockets.
22 In a near future, JSON-RPC protocol should be added to complete current x-afb-json1 protocol.
24 Two examples of HTML5 applications are given:
26 - [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
28 - [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
30 ### Writing a Qt application
32 Writing Qt applications is also supported. Qt offers standard API to send request through HTTP or WebSockets.
34 It is also possible to write QML applications. A sample QML application [token-websock] is avaliable..
36 - [token-websock](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=test/token-websock.qml)
37 a simple "hello world" application in QML
39 ### Writing "C" application
41 C applications can use afb-daemon binder through a websocket connection.
43 The library **libafbwsc** is provided for C clients that need
44 to connect with an afb-daemon binder.
46 The program **afb-client-demo** is the C example that use
47 **libafbwsc** library.
48 Source code is available here
49 [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).
51 Current implementation relies on libsystemd and file descriptors.
52 This model might be review in the future to support secure sockets
53 and free the dependency with libsystemd.
55 Handling sessions within applications
56 -------------------------------------
58 Applications should understand sessions and tokens management when interacting with afb-daemon binder.
60 Applications are communicating with their private binder(afb-daemon) using
61 a network connection or potentially any other connection channel. While current version
62 does not yet implement unix domain this feature might be added in a near future.
63 Developers need to be warn that HTTP protocol is a none connected protocol. This prevents
64 from using HTTP socket connection to authenticate clients.
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 Plugins and other binder feature need to keep track of client
76 instances. This is especially important for plugins 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
83 **uuid** or **x-afb-uuid** in URI requests. Within current version of the
84 framework session UUID is supported 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 access to some plugin'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 equivalent to:
104 $ afb-daemon --port=1234 --token=123456 [...]
106 making the expectation that **AuthLogin** plugin is requested as default.
110 First, connects with the initial token, 123456:
112 $ curl http://localhost:1234/api/auth/connect?token=123456
114 "jtype": "afb-reply",
117 "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
118 "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
120 "response": {"token": "A New Token and Session Context Was Created"}
123 It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015,
124 and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.
126 Check if session and token is valid:
128 $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
130 "jtype": "afb-reply",
131 "request": {"status":"success"},
132 "response": {"isvalid":true}
137 $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
139 "jtype": "afb-reply",
142 "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
144 "response": {"token":"Token was refreshed"}
149 curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
151 "jtype": "afb-reply",
152 "request": {"status": "success"},
153 "response": {"info":"Token and all resources are released"}
156 Checking on closed session for uuid should be refused:
158 curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
160 "jtype": "afb-reply",
163 "info": "invalid token's identity"
167 #### Using afb-client-demo
169 > The program is packaged within AGL in the rpm **libafbwsc-dev**
171 Here is an example of exchange using **afb-client-demo**:
173 $ afb-client-demo ws://localhost:1234/api?token=123456
175 ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success",
176 "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"},
177 "response":{"token":"A New Token and Session Context Was Created"}}
179 ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
181 ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
182 "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
184 ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
186 ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
187 "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
189 After closing connection, reconnect as here after:
191 $ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check
192 ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
194 Same connection check using **curl**:
196 $ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1
197 {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
202 Replies use javascript object returned as serialized JSON.
204 This object contains at least 2 mandatory fields of name **jtype** and **request**
205 and one optional field of name **response**.
209 This is a template of replies:
213 "jtype": "afb-reply",
216 "info": "informationnal text",
217 "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
218 "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
219 "reqid": "application-generated-id-23456"
221 "response": ....any response object....
227 The field **jtype** must have a value of type string equal to **"afb-reply"**.
231 The field **request** must have a value of type object. This request object
232 has at least one field named **status** and four optional fields named
233 **info**, **token**, **uuid**, **reqid**.
235 #### Subfield request.status
237 **status** must have a value of type string. This string is equal to **"success"**
238 only in case of success.
240 #### Subfield request.info
242 **info** is of type string and represent optional information added to the reply.
244 #### Subfield request.token
246 **token** is of type string. It is sent either at session creation
247 or when the token is refreshed.
249 #### Subfield request.uuid
251 **uuid** is of type string. It is sent at session creation.
253 #### Subfield request.reqid
255 **reqid** is of type string. It is sent in response to HTTP requests
256 that added a parameter of name **reqid** or **x-afb-reqid** at request time.
257 Value returns in the reply has the exact same value as the one received in the request.
261 This field response optionally contains an object returned when request succeeded.
266 Events are javascript object serialized as JSON.
268 This object contains at least 2 mandatory fields of name **jtype** and **event**
269 and one optional field of name **data**.
273 Here is a template of event:
277 "jtype": "afb-event",
278 "event": "sample_api_name/sample_event_name",
279 "data": ...any event data...
285 The field **jtype** must have a value of type string equal to **"afb-event"**.
289 The field **event** carries the event's name.
291 The name of the event is made of two parts separated by a slash:
292 the name of the name of the API that generated the event
293 and the name of event within the API.
297 This field data if present holds the data carried by the event.