doc/afb-application-writing.html

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