doc/afb-application-writing.md

   1 HOWTO WRITE an APPLICATION above AGL FRAMEWORK
   2 ==============================================
   3     version: 1
   4     Date:    09 juin 2016
   5     Author:  José Bollo
   6
   7
   8
   9 Programmation Languages for Applications
  10 -----------------------------------------
  11
  12 ### Writing an HTML5 application
  13
  14 Developers of HTML5 applications (client side) can easily create
  15 applications for AGL framework using their preferred
  16 HTML5 framework.
  17
  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.
  21
  22 In a near future, JSON-RPC protocol should be added to complete current x-afb-json1 protocol.
  23
  24 Two examples of HTML5 applications are given:
  25
  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
  27
  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
  29
  30 ### Writing a Qt application
  31
  32 Writing Qt applications is also supported. Qt offers standard API to send request through HTTP or WebSockets.
  33
  34 It is also possible to write QML applications. A sample QML application [token-websock] is avaliable..
  35
  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
  38
  39 ### Writing "C" application
  40
  41 C applications can use afb-daemon binder through a websocket connection.
  42
  43 The library **libafbwsc** is provided for C clients that need
  44 to connect with an afb-daemon binder.
  45
  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).
  50
  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.
  54
  55 Handling sessions within applications
  56 -------------------------------------
  57
  58 Applications should understand sessions and tokens management when interacting with afb-daemon binder.
  59
  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.
  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 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.
  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
  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.
  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 access to some plugin'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 equivalent to:
 103
 104     $ afb-daemon --port=1234 --token=123456 [...]
 105
 106 making the expectation that **AuthLogin** plugin is requested as default.
 107
 108 #### Using curl
 109
 110 First, connects with the initial token, 123456:
 111
 112     $ curl http://localhost:1234/api/auth/connect?token=123456
 113     {
 114       "jtype": "afb-reply",
 115       "request": {
 116          "status": "success",
 117          "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
 118          "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
 119       },
 120       "response": {"token": "A New Token and Session Context Was Created"}
 121     }
 122
 123 It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015,
 124 and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.
 125
 126 Check if session and token is valid:
 127
 128     $ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 129     {
 130       "jtype": "afb-reply",
 131       "request": {"status":"success"},
 132       "response": {"isvalid":true}
 133     }
 134
 135 Refresh the token:
 136
 137     $ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 138     {
 139       "jtype": "afb-reply",
 140       "request": {
 141          "status":"success",
 142          "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
 143       },
 144       "response": {"token":"Token was refreshed"}
 145     }
 146
 147 Close the session:
 148
 149     curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 150     {
 151       "jtype": "afb-reply",
 152       "request": {"status": "success"},
 153       "response": {"info":"Token and all resources are released"}
 154     }
 155
 156 Checking on closed session for uuid should be refused:
 157
 158     curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
 159     {
 160       "jtype": "afb-reply",
 161       "request": {
 162          "status": "failed",
 163          "info": "invalid token's identity"
 164       }
 165     }
 166
 167 #### Using afb-client-demo
 168
 169 > The program is packaged within AGL in the rpm **libafbwsc-dev**
 170
 171 Here is an example of exchange using **afb-client-demo**:
 172
 173     $ afb-client-demo ws://localhost:1234/api?token=123456
 174     auth connect
 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"}}
 178     auth check
 179     ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 180     auth refresh
 181     ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 182        "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
 183     auth check
 184     ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
 185     auth refresh
 186     ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
 187        "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
 188
 189 After closing connection, reconnect as here after:
 190
 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}}
 193
 194 Same connection check using **curl**:
 195
 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}}
 198
 199 Format of replies
 200 -----------------
 201
 202 Replies use javascript object returned as serialized JSON.
 203
 204 This object contains at least 2 mandatory fields of name **jtype** and **request**
 205 and one optional field of name **response**.
 206
 207 ### Template
 208
 209 This is a template of replies:
 210
 211 ```json
 212 {
 213    "jtype": "afb-reply",
 214    "request": {
 215       "status": "success",
 216       "info": "informationnal text",
 217       "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
 218       "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
 219       "reqid": "application-generated-id-23456"
 220    },
 221    "response": ....any response object....
 222 }
 223 ```
 224
 225 ### Field jtype
 226
 227 The field **jtype** must have a value of type string equal to **"afb-reply"**.
 228
 229 ### Field request
 230
 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**.
 234
 235 #### Subfield request.status
 236
 237 **status** must have a value of type string. This string is equal to **"success"**
 238 only in case of success.
 239
 240 #### Subfield request.info
 241
 242 **info** is of type string and represent optional information added to the reply.
 243
 244 #### Subfield request.token
 245
 246 **token** is of type string. It is sent either at session creation
 247 or when the token is refreshed.
 248
 249 #### Subfield request.uuid
 250
 251 **uuid** is of type string. It is sent at session creation.
 252
 253 #### Subfield request.reqid
 254
 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.
 258
 259 ### Field response
 260
 261 This field response optionally contains an object returned when request succeeded.
 262
 263 Format of events
 264 ----------------
 265
 266 Events are javascript object serialized as JSON.
 267
 268 This object contains at least 2 mandatory fields of name **jtype** and **event**
 269 and one optional field of name **data**.
 270
 271 ### Template
 272
 273 Here is a template of event:
 274
 275 ```json
 276 {
 277    "jtype": "afb-event",
 278    "event": "sample_api_name/sample_event_name",
 279    "data": ...any event data...
 280 }
 281 ```
 282
 283 ### Field jtype
 284
 285 The field **jtype** must have a value of type string equal to **"afb-event"**.
 286
 287 ### Field event
 288
 289 The field **event** carries the event's name.
 290
 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.
 294
 295 ### Field data
 296
 297 This field data if present holds the data carried by the event.
 298