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