old-docs/afb-application-writing.md

   1 How to write an application on top of AGL FRAMEWORK
   2 ====================================================
   3
   4 Programming Languages for Applications
   5 -----------------------------------------
   6
   7 ### Writing an HTML5 application
   8
   9 Developers of HTML5 applications (client side) can easily create
  10 applications for AGL framework using their preferred
  11 HTML5 framework.
  12
  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.
  16
  17 In a near future, JSON-RPC protocol should be added to complete the current
  18 x-afb-json1 protocol.
  19
  20 Two examples of HTML5 applications are given:
  21
  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
  23
  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
  25
  26 ### Writing a Qt application
  27
  28 Writing Qt applications is also supported. Qt offers standard API to send
  29 request through HTTP or WebSockets.
  30
  31 It is also possible to write QML applications. A sample QML application
  32 [token-websock] is available:
  33
  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
  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 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).
  48
  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.
  52
  53 Handling sessions within applications
  54 -------------------------------------
  55
  56 Applications should understand sessions and token management when interacting
  57 with afb-daemon binder.
  58
  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.
  65
  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".
  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. This is especially important for bindings running as services
  77 as they may typically have to keep each client's data separated.
  78
  79 For HTML5 applications, the web runtime handles the cookie of session
  80 that the binder afb-daemon automatically sets.
  81
  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.
  85
  86 ### Exchanging tokens
  87
  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**".
  90
  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.
  94
  95 The token must be included in URI request on HTTP or during websockets
  96 connection using parameter **token** or **x-afb-token**.
  97
  98 To ensure security, tokens must be refreshed periodically.
  99
 100 ### Example of session management
 101
 102 In following examples, we suppose that **afb-daemon** is launched with something
 103 equivalent to:
 104
 105     $ afb-daemon --port=1234 --token=123456 [...]
 106
 107 making the expectation that **AuthLogin** binding is requested as default.
 108
 109 #### Using curl
 110
 111 First, connects with the initial token, 123456:
 112
 113     $ curl http://localhost:1234/api/auth/connect?token=123456
 114     {
 115       "jtype": "afb-reply",
 116       "request": {
 117          "status": "success",
 118          "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
 119          "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
 120       },
 121       "response": {"token": "A New Token and Session Context Was Created"}
 122     }
 123
 124 It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015,
 125 and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.
 126
 127 Check if session and token is valid:
 128
 129     $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 130     {
 131       "jtype": "afb-reply",
 132       "request": {"status":"success"},
 133       "response": {"isvalid":true}
 134     }
 135
 136 Refresh the token:
 137
 138     $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 139     {
 140       "jtype": "afb-reply",
 141       "request": {
 142          "status":"success",
 143          "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
 144       },
 145       "response": {"token":"Token was refreshed"}
 146     }
 147
 148 Close the session:
 149
 150     curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 151     {
 152       "jtype": "afb-reply",
 153       "request": {"status": "success"},
 154       "response": {"info":"Token and all resources are released"}
 155     }
 156
 157 Checking on closed session for uuid should be refused:
 158
 159     curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 160     {
 161       "jtype": "afb-reply",
 162       "request": {
 163          "status": "failed",
 164          "info": "invalid token's identity"
 165       }
 166     }
 167
 168 #### Using afb-client-demo
 169
 170 > The program is packaged within AGL in the rpm **libafbwsc-dev**
 171
 172 Here is an example of exchange using **afb-client-demo**:
 173
 174     $ afb-client-demo ws://localhost:1234/api?token=123456
 175     auth connect
 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"}}
 179     auth check
 180     ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 181     auth refresh
 182     ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 183        "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
 184     auth check
 185     ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 186     auth refresh
 187     ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 188        "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
 189
 190 After closing connection, reconnect as here after:
 191
 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}}
 194
 195 Same connection check using **curl**:
 196
 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}}
 199
 200 Format of replies
 201 -----------------
 202
 203 Replies use javascript object returned as serialized JSON.
 204
 205 This object contains at least 2 mandatory fields of name **jtype** and
 206 **request** and one optional field of name **response**.
 207
 208 ### Template
 209
 210 This is a template of replies:
 211
 212 ```json
 213 {
 214    "jtype": "afb-reply",
 215    "request": {
 216       "status": "success",
 217       "info": "informationnal text",
 218       "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
 219       "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
 220       "reqid": "application-generated-id-23456"
 221    },
 222    "response": ....any response object....
 223 }
 224 ```
 225
 226 ### Field jtype
 227
 228 The field **jtype** must have a value of type string equal to **"afb-reply"**.
 229
 230 ### Field request
 231
 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**.
 235
 236 #### Subfield request.status
 237
 238 **status** must have a value of type string. This string is equal to **"success"**
 239 only in case of success.
 240
 241 #### Subfield request.info
 242
 243 **info** is of type string and represent optional information added to the reply.
 244
 245 #### Subfield request.token
 246
 247 **token** is of type string. It is sent either at session creation
 248 or when the token is refreshed.
 249
 250 #### Subfield request.uuid
 251
 252 **uuid** is of type string. It is sent at session creation.
 253
 254 #### Subfield request.reqid
 255
 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
 259 request.
 260
 261 ### Field response
 262
 263 This field response optionally contains an object returned when request
 264 succeeded.
 265
 266 Format of events
 267 ----------------
 268
 269 Events are javascript object serialized as JSON.
 270
 271 This object contains at least 2 mandatory fields of name **jtype** and **event**
 272 and one optional field of name **data**.
 273
 274 ### Template
 275
 276 Here is a template of event:
 277
 278 ```json
 279 {
 280    "jtype": "afb-event",
 281    "event": "sample_api_name/sample_event_name",
 282    "data": ...any event data...
 283 }
 284 ```
 285
 286 ### Field jtype
 287
 288 The field **jtype** must have a value of type string equal to **"afb-event"**.
 289
 290 ### Field event
 291
 292 The field **event** carries the event's name.
 293
 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.
 297
 298 ### Field data
 299
 300 This field data if present holds the data carried by the event.
 301