docs/afb-application-writing.md

   1 # How to write an application on top of AGL FRAMEWORK
   2
   3 ## Programming Languages for Applications
   4
   5 ### Writing an HTML5 application
   6
   7 Developers of HTML5 applications (client side) can easily create
   8 applications for AGL framework using their preferred
   9 HTML5 framework.
  10
  11 Developers may also take advantage of powerful server side bindings to improve
  12 application behavior.
  13 Server side bindings return an application/json mine-type
  14 and can be accessed though either HTTP or Websockets.
  15
  16 In a near future, JSON-RPC protocol should be added to complete the current
  17 x-afb-json1 protocol.
  18
  19 Two examples of HTML5 applications are given:
  20
  21 - [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
  22
  23 - [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
  24
  25 ### Writing a Qt application
  26
  27 Writing Qt applications is also supported.
  28 Qt offers standard API to send request through HTTP or WebSockets.
  29
  30 It is also possible to write QML applications.
  31 A sample QML application [token-websock] is available:
  32
  33 - [token-websock](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=test/token-websock.qml)
  34
  35 A simple "hello world" application in QML
  36
  37 ### Writing a "C" application
  38
  39 C applications can use afb-daemon binder through a websocket connection.
  40
  41 The library **libafbwsc** is provided for C clients that need
  42 to connect with an afb-daemon binder.
  43
  44 The program **afb-client-demo** is the C example that uses the
  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).
  48
  49 Current implementation relies on libsystemd and file descriptors.
  50 This model may be reviewed in the future to support secure sockets
  51 and get rid of libsystemd dependency.
  52
  53 ### Handling sessions within applications
  54
  55 Applications should understand sessions and token management when interacting
  56 with afb-daemon binder.
  57
  58 Applications communicate with their private binder (afb-daemon) using
  59 a network connection or any other potential connection channel.
  60 While the current version does not yet implement Unix socket,
  61 this feature might be added in the near future.
  62 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.
  65
  66 For this reason, the binder should authenticate the application
  67 by using a shared secret.
  68 The secret is named "token" and the identification of client is named "session.”
  69
  70 The examples **token-websock.qml** and **afb-client** are demonstrating
  71 how authentication and sessions are managed.
  72
  73 ### Handling sessions
  74
  75 Bindings and other binder features need to keep track of client
  76 instances.
  77 This is especially important for bindings running as services
  78 as they may typically have to keep each client's data separated.
  79
  80 For HTML5 applications, the web runtime handles the cookie of the session
  81 that the binder afb-daemon automatically sets.
  82
  83 Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in
  84 URI requests.
  85 Within current version of the framework session UUID is supported
  86 by both HTTP requests and websocket negotiation.
  87
  88 ### Exchanging tokens
  89
  90 At application start, AGL framework communicates a shared secret to both binder
  91 and client application.
  92 This initial secret is called the "**initial token**".
  93
  94 For each of its client application, the binder manages a current active
  95 token for session management.
  96 This authentication token can be use to restrict the access to some binding's methods.
  97
  98 The token must be included in URI request on HTTP or during websockets
  99 connection using parameter **token** or **x-afb-token**.
 100
 101 To ensure security, tokens must be refreshed periodically.
 102
 103 ### Example of session management
 104
 105 In following examples, we suppose that **afb-daemon** is launched with something
 106 equivalent to:
 107
 108 ```bash
 109 afb-daemon --port=1234 --token=123456 [...]
 110 ```
 111
 112 making the expectation that **AuthLogin** binding is requested as default.
 113
 114 #### Using curl
 115
 116 First, connects with the initial token, 123456:
 117
 118 ```bash
 119 $ curl http://localhost:1234/api/auth/connect?token=123456
 120 {
 121   "jtype": "afb-reply",
 122   "request": {
 123      "status": "success",
 124      "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
 125      "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
 126   },
 127   "response": {"token": "A New Token and Session Context Was Created"}
 128 }
 129 ```
 130
 131 It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015,
 132 and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.
 133
 134 Check if session and token is valid:
 135
 136 ```bash
 137 $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 138 {
 139   "jtype": "afb-reply",
 140   "request": {"status":"success"},
 141   "response": {"isvalid":true}
 142 }
 143 ```
 144
 145 Refresh the token:
 146
 147 ```bash
 148 $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 149 {
 150   "jtype": "afb-reply",
 151   "request": {
 152      "status":"success",
 153      "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
 154   },
 155   "response": {"token":"Token was refreshed"}
 156 }
 157 ```
 158
 159 Close the session:
 160
 161 ```bash
 162 $ curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 163 {
 164   "jtype": "afb-reply",
 165   "request": {"status": "success"},
 166   "response": {"info":"Token and all resources are released"}
 167 }
 168 ```
 169
 170 Checking on closed session for uuid should be refused:
 171
 172 ```bash
 173 $ curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 174 {
 175   "jtype": "afb-reply",
 176   "request": {
 177     "status": "failed",
 178     "info": "invalid token's identity"
 179   }
 180 }
 181 ```
 182
 183 #### Using afb-client-demo
 184
 185 - The program is packaged within AGL in the rpm **libafbwsc-dev**
 186
 187 Here is an example of exchange using **afb-client-demo**:
 188
 189 ```bash
 190 $ afb-client-demo ws://localhost:1234/api?token=123456
 191 auth connect
 192 ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success",
 193    "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"},
 194    "response":{"token":"A New Token and Session Context Was Created"}}
 195 auth check
 196 ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 197 auth refresh
 198 ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 199    "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
 200 auth check
 201 ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 202 auth refresh
 203 ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 204    "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
 205 ```
 206
 207 After closing connection, reconnect as here after:
 208
 209 ```bash
 210 $ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check
 211 ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 212 ```
 213
 214 Same connection check using **curl**:
 215
 216 ```bash
 217 $ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1
 218 {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 219 ```
 220
 221 ### Format of replies
 222
 223 Replies use javascript object returned as serialized JSON.
 224
 225 This object contains at least 2 mandatory fields of name **jtype** and
 226 **request** and one optional field of name **response**.
 227
 228 #### Template of replies
 229
 230 This is a template of replies:
 231
 232 ```json
 233 {
 234    "jtype": "afb-reply",
 235    "request": {
 236       "status": "success",
 237       "info": "informationnal text",
 238       "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
 239       "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
 240       "reqid": "application-generated-id-23456"
 241    },
 242    "response": ....any response object....
 243 }
 244 ```
 245
 246 #### Field jtype of replies
 247
 248 The field **jtype** must have a value of type string equal to **"afb-reply"**.
 249
 250 #### Field request of replies
 251
 252 The field **request** must have a value of type object.
 253 This request object has at least one field named **status**
 254 and four optional fields named **info**, **token**, **uuid**, **reqid**.
 255
 256 ##### Subfield request.status
 257
 258 **status** must have a value of type string. This string is equal to **"success"**
 259 only in case of success.
 260
 261 ##### Subfield request.info
 262
 263 **info** is of type string and represent optional information added to the reply.
 264
 265 ##### Subfield request.token
 266
 267 **token** is of type string. It is sent either at session creation
 268 or when the token is refreshed.
 269
 270 ##### Subfield request.uuid
 271
 272 **uuid** is of type string. It is sent at session creation.
 273
 274 ##### Subfield request.reqid
 275
 276 **reqid** is of type string. It is sent in response to HTTP requests
 277 that added a parameter of name **reqid** or **x-afb-reqid** at request time.
 278 Value returns in the reply has the exact same value as the one received in the
 279 request.
 280
 281 #### Field response of replies
 282
 283 This field response optionally contains an object returned when request
 284 succeeded.
 285
 286 ### Format of events
 287
 288 Events are javascript object serialized as JSON.
 289
 290 This object contains at least 2 mandatory fields of name **jtype** and **event**
 291 and one optional field of name **data**.
 292
 293 #### Template of event
 294
 295 Here is a template of event:
 296
 297 ```json
 298 {
 299    "jtype": "afb-event",
 300    "event": "sample_api_name/sample_event_name",
 301    "data": ...any event data...
 302 }
 303 ```
 304
 305 #### Field jtype of event
 306
 307 The field **jtype** must have a value of type string equal to **"afb-event"**.
 308
 309 #### Field event of event
 310
 311 The field **event** carries the event's name.
 312
 313 The name of the event is made of two parts separated by a slash:
 314 the name of the name of the API that generated the event
 315 and the name of event within the API.
 316
 317 #### Field data of event
 318
 319 This field data if present holds the data carried by the event.