docs/afb-binding-writing.md

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