docs/afb-binding-writing.md

   1 # Overview of the bindings
   2
   3 The ***binder*** serves files through HTTP protocol and offers to
   4 developers the capability to offer application API methods through HTTP or
   5 WebSocket protocol.
   6
   7 The ***bindings*** are used to add **API** to ***binders***.
   8 This part describes how to write a ***binding*** for ***binder***
   9 or in other words how to add a new **API** to the system.
  10
  11 Excepting this summary, this section target developers.
  12
  13 This section shortly explain how to write a binding
  14 using the C programming language.
  15
  16 It is convenient to install the ***binder*** on the
  17 desktop used for writing the binding.
  18 It allows easy debug and test.
  19
  20 ## Nature of a binding
  21
  22 A ***binding*** is an independent piece of software compiled as a shared
  23 library and dynamically loaded by a ***binder***.
  24 It is intended to provide one **API** (**A**pplication **P**rogramming
  25 **I**nterface).
  26
  27 The **API** is designated and accessed through its name.
  28 It contains several **verbs** that implement the ***binding***
  29 functionalities.
  30 Each of these **verbs** is a **method** that
  31 processes requests of applications and sends result.
  32
  33 The ***binding***'s methods are invoked by HTTP or websocket
  34 requests.
  35
  36 The **methods** of the ***bindings*** are noted **api/verb**
  37 where **api** is the **API** name of the binding and **verb** is
  38 the **method**'s name within the **API**.
  39 This notation comes from HTTP invocations that rely on URL path terminated
  40 with **api/verb**.
  41
  42 The name of an **API** can be made of any characters except:
  43
  44 - the control characters (\u0000 .. \u001f)
  45 - the characters of the set { ' ', '"', '#', '%', '&',
  46    '\'', '/', '?', '`', '\x7f' }
  47
  48 The names of the **verbs** can be any character.
  49
  50 The binder makes no distinctions between upper case and lower case
  51 latin letters.
  52 So **API/VERB** matches **Api/Verb** or **api/verb**.
  53
  54 ## Versions of the bindings
  55
  56 Since introduction of the binder, the way how bindings are written
  57 evolved a little. While changing, attention was made to ensure binary
  58 compatibility between the different versions.
  59
  60 Actually it exists 3 ways of writing ***bindings***.
  61 You can either write:
  62
  63 - a binding version 1 (not more supported);
  64 - a binding version 2 (not recommended);
  65 - a binding version 3 (RECOMMENDED).
  66
  67 A ***binder*** loads and runs any of these version in any combination.
  68 This document explain how to write bindings version 3.
  69
  70 <!-- pagebreak -->
  71
  72 ## Sample binding: tuto-1
  73
  74 This is the code of the binding **tuto-1.c**:
  75
  76 ```C
  77   1 #define AFB_BINDING_VERSION 3
  78   2 #include <afb/afb-binding.h>
  79   3
  80   4 void hello(afb_req_t req)
  81   5 {
  82   6         AFB_REQ_DEBUG(req, "hello world");
  83   7         afb_req_reply(req, NULL, NULL, "hello world");
  84   8 }
  85   9
  86  10 const afb_verb_t verbs[] = {
  87  11         { .verb="hello", .callback=hello },
  88  12         { .verb=NULL }
  89  13 };
  90  14
  91  15 const afb_binding_t afbBindingExport = {
  92  16         .api = "tuto-1",
  93  17         .verbs = verbs
  94  18 };
  95 ```
  96
  97 Compiling:
  98
  99 ```bash
 100 gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon)
 101 ```
 102
 103 > Note: the variable environment variable PKG_CONFIG_PATH might be necessary
 104 > tuned to get **pkg-config** working properly
 105
 106 Running:
 107
 108 ```bash
 109 afb-daemon --binding tuto-1.so --port 3333 --token ''
 110 ```
 111
 112 At this point, afb-daemon has started, it loaded the binding tuto-1.so and now
 113 listen at localhost on the port 3333.
 114
 115 Testing using **curl**:
 116
 117 ```bash
 118 $ curl http://localhost:3333/api/tuto-1/hello
 119 {"jtype":"afb-reply","request":{"status":"success","info":"hello world","uuid":"1e587b54-900b-49ab-9940-46141bc2e1d6"}}
 120 ```
 121
 122 Testing using **afb-client-demo** (with option -H for
 123 getting a human readable output):
 124
 125 ```bash
 126 $ afb-client-demo -H ws://localhost:3333/api?token=x tuto-1 hello
 127 ON-REPLY 1:tuto-1/hello: OK
 128 {
 129   "jtype":"afb-reply",
 130   "request":{
 131     "status":"success",
 132     "info":"hello world",
 133     "uuid":"03a84ad1-458a-4ace-af74-b1da917391b9"
 134   }
 135 }
 136 ```
 137
 138 This shows basic things:
 139
 140 - The include to get for creating a binding
 141 - How to declare the API offered by the binding
 142 - How to handle request made to the binding
 143
 144 ### Getting declarations for the binding
 145
 146 The lines 1 and 2 show how to get the include file **afb-binding.h**.
 147
 148 ```C
 149   1 #define AFB_BINDING_VERSION 3
 150   2 #include <afb/afb-binding.h>
 151 ```
 152
 153 You must define the version of ***binding*** that you are using.
 154 This is done line 1 where we define that this is the version 3 (earlier
 155 versions 1 and 2 are deprecated).
 156
 157 If you don't define it, an error is reported and the compilation aborts.
 158
 159 To include **afb-binding.h** successfully, the include search path
 160 should be set correctly if needed (not needed only if installed in
 161 /usr/include/afb directory that is the default).
 162
 163 Setting the include path is easy using **pkg-config**:
 164
 165 ```bash
 166 pkg-config --cflags-only-I afb-daemon
 167 ```
 168
 169 > Note for **C++** developers:
 170 >
 171 > The ***binder*** currently expose a draft version of **C++** api.
 172 > To get it include the file <**afb/afb-binding**> (without **.h**).
 173
 174
 175 ### Declaring the API of the binding
 176
 177 Lines 10 to 18 show the declaration of the ***binding***.
 178
 179 The ***binder*** knows that this is a ***binding*** because
 180 it finds the exported symbol **afbBindingExport** that is expected to be
 181 a structure of type **afb_binding_t**.
 182
 183 ```C
 184  10 const afb_verb_t verbs[] = {
 185  11         { .verb="hello", .callback=hello },
 186  12         { .verb=NULL }
 187  13 };
 188  14
 189  15 const afb_binding_t afbBindingExport = {
 190  16         .api = "tuto-1",
 191  17         .verbs = verbs
 192  18 };
 193 ```
 194
 195 The structure **afbBindingExport** actually tells that:
 196
 197 - the exported **API** name is **tuto-1** (line 16)
 198 - the array of verbs is the above defined one
 199
 200 The exported list of verb is specified by an array of structures of
 201 type **afb_verb_t**, each describing a verb, ended with a verb NULL (line 12).
 202
 203 The only defined verb here (line 11) is named **hello** (field **.verb**)
 204 and the function that handle the related request is **hello**
 205 (field **.callback**).
 206
 207 ### Handling binder's requests
 208
 209 As shown above this is by default the common include directory where
 210 the AGL stuff is installed.
 211
 212 ```C
 213   4 void hello(afb_req_t req)
 214   5 {
 215   6         AFB_REQ_DEBUG(req, "hello world");
 216   7         afb_req_reply(req, NULL, NULL, "hello world");
 217   8 }
 218 ```
 219
 220 When the ***binder*** receives a request for the verb **hello** of
 221 of the api **tuto-1**, it invoke the callback **hello** of the **binding**
 222 with the argument **req** that handles the client request.
 223
 224 The callback has to treat synchronously or asynchronously the request and
 225 should at the end emit a reply for the request.
 226
 227 At the line 7, the callback for **tuto-1/hello** replies to the request **req**.
 228 Parameters of the reply are:
 229
 230  1. The first parameter is the replied request
 231  2. The second parameter is a json object (here NULL)
 232  3. The third parameter is the error string indication (here NULL: no error)
 233  4. The fourth parameter is an informative string (that can be NULL) that can be used to provide meta data.
 234
 235 The 3 last parameters are sent back to the client as the reply content.
 236
 237 <!-- pagebreak -->
 238
 239 ## Sample binding: tuto-2
 240
 241 The second tutorial shows many important feature that can
 242 commonly be used when writing a ***binding***:
 243
 244 - initialization, getting arguments, sending replies, pushing events.
 245
 246 This is the code of the binding **tuto-2.c**:
 247
 248 ```C
 249       1 #include <string.h>
 250       2 #include <json-c/json.h>
 251       3
 252       4 #define AFB_BINDING_VERSION 3
 253       5 #include <afb/afb-binding.h>
 254       6
 255       7 afb_event_t event_login, event_logout;
 256       8
 257       9 void login(afb_req_t req)
 258      10 {
 259      11         json_object *args, *user, *passwd;
 260      12         char *usr;
 261      13
 262      14         args = afb_req_json(req);
 263      15         if (!json_object_object_get_ex(args, "user", &user)
 264      16          || !json_object_object_get_ex(args, "password", &passwd)) {
 265      17                 AFB_REQ_ERROR(req, "login, bad request: %s", json_object_get_string(args));
 266      18                 afb_req_reply(req, NULL, "bad-request", NULL);
 267      19         } else if (afb_req_context_get(req)) {
 268      20                 AFB_REQ_ERROR(req, "login, bad state, logout first");
 269      21                 afb_req_reply(req, NULL, "bad-state", NULL);
 270      22         } else if (strcmp(json_object_get_string(passwd), "please")) {
 271      23                 AFB_REQ_ERROR(req, "login, unauthorized: %s", json_object_get_string(args));
 272      24                 afb_req_reply(req, NULL, "unauthorized", NULL);
 273      25         } else {
 274      26                 usr = strdup(json_object_get_string(user));
 275      27                 AFB_REQ_NOTICE(req, "login user: %s", usr);
 276      28                 afb_req_session_set_LOA(req, 1);
 277      29                 afb_req_context_set(req, usr, free);
 278      30                 afb_req_reply(req, NULL, NULL, NULL);
 279      31                 afb_event_push(event_login, json_object_new_string(usr));
 280      32         }
 281      33 }
 282      34
 283      35 void action(afb_req_t req)
 284      36 {
 285      37         json_object *args, *val;
 286      38         char *usr;
 287      39
 288      40         args = afb_req_json(req);
 289      41         usr = afb_req_context_get(req);
 290      42         AFB_REQ_NOTICE(req, "action for user %s: %s", usr, json_object_get_string(args));
 291      43         if (json_object_object_get_ex(args, "subscribe", &val)) {
 292      44                 if (json_object_get_boolean(val)) {
 293      45                         AFB_REQ_NOTICE(req, "user %s subscribes to events", usr);
 294      46                         afb_req_subscribe(req, event_login);
 295      47                         afb_req_subscribe(req, event_logout);
 296      48                 } else {
 297      49                         AFB_REQ_NOTICE(req, "user %s unsubscribes to events", usr);
 298      50                         afb_req_unsubscribe(req, event_login);
 299      51                         afb_req_unsubscribe(req, event_logout);
 300      52                 }
 301      53         }
 302      54         afb_req_reply(req, json_object_get(args), NULL, NULL);
 303      55 }
 304      56
 305      57 void logout(afb_req_t req)
 306      58 {
 307      59         char *usr;
 308      60
 309      61         usr = afb_req_context_get(req);
 310      62         AFB_REQ_NOTICE(req, "login user %s out", usr);
 311      63         afb_event_push(event_logout, json_object_new_string(usr));
 312      64         afb_req_session_set_LOA(req, 0);
 313      65         afb_req_context_clear(req);
 314      66         afb_req_reply(req, NULL, NULL, NULL);
 315      67 }
 316      68
 317      69 int preinit(afb_api_t api)
 318      70 {
 319      71         AFB_API_NOTICE(api, "preinit");
 320      72         return 0;
 321      73 }
 322      74
 323      75 int init(afb_api_t api)
 324      76 {
 325      77         AFB_API_NOTICE(api, "init");
 326      78         event_login = afb_api_make_event(api, "login");
 327      79         event_logout = afb_api_make_event(api, "logout");
 328      80         if (afb_event_is_valid(event_login) && afb_event_is_valid(event_logout))
 329      81                 return 0;
 330      82         AFB_API_ERROR(api, "Can't create events");
 331      83         return -1;
 332      84 }
 333      85
 334      86 const afb_verb_t verbs[] = {
 335      87         { .verb="login", .callback=login },
 336      88         { .verb="action", .callback=action, .session=AFB_SESSION_LOA_1 },
 337      89         { .verb="logout", .callback=logout, .session=AFB_SESSION_LOA_1 },
 338      90         { .verb=NULL }
 339      91 };
 340      92
 341      93 const afb_binding_t afbBindingExport = {
 342      94         .api = "tuto-2",
 343      95         .specification = NULL,
 344      96         .verbs = verbs,
 345      97         .preinit = preinit,
 346      98         .init = init,
 347      99         .noconcurrency = 0
 348     100 };
 349 ```
 350
 351 Compiling:
 352
 353 ```bash
 354 gcc -fPIC -shared tuto-2.c -o tuto-2.so $(pkg-config --cflags --libs afb-daemon)
 355 ```
 356
 357 Running:
 358
 359 ```bash
 360 afb-daemon --binding tuto-2.so --port 3333 --token ''
 361 ```
 362
 363 Testing:
 364
 365 ```bash
 366 $ afb-client-demo -H localhost:3333/api?token=toto
 367 tuto-2 login {"help":true}
 368 ON-REPLY 1:tuto-2/login: ERROR
 369 {
 370   "jtype":"afb-reply",
 371   "request":{
 372     "status":"bad-request",
 373     "uuid":"e2b24a13-fc43-487e-a5f4-9266dd1e60a9"
 374   }
 375 }
 376 tuto-2 login {"user":"jose","password":"please"}
 377 ON-REPLY 2:tuto-2/login: OK
 378 {
 379   "jtype":"afb-reply",
 380   "request":{
 381     "status":"success"
 382   }
 383 }
 384 tuto-2 login {"user":"jobol","password":"please"}
 385 ON-REPLY 3:tuto-2/login: ERROR
 386 {
 387   "jtype":"afb-reply",
 388   "request":{
 389     "status":"bad-state"
 390   }
 391 }
 392 tuto-2 action {"subscribe":true}
 393 ON-REPLY 4:tuto-2/action: OK
 394 {
 395   "response":{
 396     "subscribe":true
 397   },
 398   "jtype":"afb-reply",
 399   "request":{
 400     "status":"success"
 401   }
 402 }
 403 ```
 404
 405 In an other terminal:
 406
 407 ```bash
 408 $ afb-client-demo -H localhost:3333/api?token=toto
 409 tuto-2 login {"user":"jobol","password":"please"}
 410 ON-REPLY 1:tuto-2/login: OK
 411 {
 412   "jtype":"afb-reply",
 413   "request":{
 414     "status":"success",
 415     "uuid":"a09f55ff-0e89-4f4e-8415-c6e0e7f439be"
 416   }
 417 }
 418 tuto-2 logout true
 419 ON-REPLY 2:tuto-2/logout: OK
 420 {
 421   "jtype":"afb-reply",
 422   "request":{
 423     "status":"success"
 424   }
 425 }
 426 ```
 427
 428 It produced in the first terminal:
 429
 430 ```bash
 431 ON-EVENT tuto-2/login:
 432 {
 433   "event":"tuto-2\/login",
 434   "data":"jobol",
 435   "jtype":"afb-event"
 436 }
 437 ON-EVENT tuto-2/logout:
 438 {
 439   "event":"tuto-2\/logout",
 440   "data":"jobol",
 441   "jtype":"afb-event"
 442 }
 443 ```