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