docs/1-afm-daemons.md

   1 The application framework daemons
   2 =================================
   3
   4 Foreword
   5 --------
   6
   7 This document describes application framework daemons
   8 FCS (Fully Conform to Specification) implementation is still under development.
   9 It may happen that current implementation somehow diverges with specifications.
  10
  11 Introduction
  12 ------------
  13
  14 Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications
  15 life. Understand that they will manage operations like:
  16
  17  - ***installation***
  18  - ***uninstallation***
  19  - ***running***
  20  - ***suspend***
  21  - ***inventory***
  22  - ...
  23
  24 In addition, they ensure that operations use the security framework as needed
  25 and that applications are executed in the correct context.
  26
  27 ***D-Bus*** is in charge of transmitting orders to the appropriate daemon
  28 depending upon ***D-Bus*** destination.
  29
  30 The figure below summarizes the situation of both **afm-system-daemon** and
  31 **afm-user-daemon** in the system.
  32
  33 ![afm-daemons][afm-daemons]{style width:65%;}
  34
  35 The D-Bus interface
  36 -------------------
  37
  38 ### Overview of the dbus interface
  39
  40 The ***afm daemons*** takes theirs orders from the session instance
  41 of D-Bus. The use of D-Bus is great because it allows to implement
  42 discovery and signaling.
  43
  44 The dbus session is by default addressed by environment
  45 variable *DBUS_SESSION_BUS_ADDRESS*. Using **systemd**
  46 variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for
  47 user sessions.
  48
  49 They are listening with the destination name ***org.AGL.afm.[user|system]***
  50 at the object of path ***/org/AGL/afm/[user|system]*** on the interface
  51 ***org.AGL.afm.[user|system]***  for the below detailed members for the
  52 ***afm-system-daemon***:
  53
  54  - ***install***
  55  - ***uninstall***
  56
  57 And for ***afm-user-daemon***:
  58
  59  - ***runnables***
  60  - ***detail***
  61  - ***start***
  62  - ***once***
  63  - ***terminate***
  64  - ***pause***
  65  - ***resume***
  66  - ***runners***
  67  - ***state***
  68  - ***install***
  69  - ***uninstall***
  70
  71 D-Bus is mainly used for signaling and discovery. Its optimized
  72 typed protocol is not used except for transmitting only one string
  73 in both directions.
  74
  75 The client and the service are using JSON serialization to
  76 exchange data. Signature of any member of the D-Bus interface is
  77 ***string -> string*** for ***JSON -> JSON***. This is the normal case, if there
  78 is an error, current implementation returns a dbus error that is a string.
  79
  80 Here are examples using *dbus-send*, here to install an application from a
  81 widget file:
  82
  83     dbus-send --session --print-reply \
  84         --dest=org.AGL.afm.system \
  85         /org/AGL/afm/system \
  86         org.AGL.afm.system.install 'string:"/tmp/appli.wgt"
  87
  88
  89 And here, to query data on installed applications that can be run:
  90
  91     dbus-send --session --print-reply \
  92         --dest=org.AGL.afm.user \
  93         /org/AGL/afm/user \
  94         org.AGL.afm.user.runnables string:true
  95
  96 ### The protocol over D-Bus
  97
  98 On all following sub-chapters we assume that we talk about either
  99 ***afm-system-daemon*** or ***afm-user-daemon***. Method and D-Bus parameters
 100 are considered as self-explanatory.
 101
 102 The D-Bus interface is defined by:
 103
 104  * **DESTINATION**: org.AGL.afm.[user|system]
 105
 106  * **PATH**: /org/AGL/afm/[user|system]
 107
 108  * **INTERFACE**: org.AGL.afm.[user|system]
 109
 110 #### Method org.AGL.afm.system.install
 111
 112 **Description**: Install an application from a widget file.
 113
 114 When an application with the same *id* and *version* already exists. Outside of
 115 using *force=true* the application is not reinstalled.
 116
 117 Applications are installed the subdirectories of applications common directory.
 118 If *root* is specified, the application is installed under the
 119 sub-directories of the *root* defined.
 120
 121 Note that this methods is a simple accessor method of
 122 ***org.AGL.afm.system.install*** from ***afm-system-daemon***.
 123
 124 After the installation and before returning to the sender,
 125 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
 126
 127 **Input**: The *path* of the widget file to install and, optionally,
 128 a flag to *force* reinstallation, and, optionally, a *root* directory.
 129
 130 Either just a string being the absolute path of the widget file:
 131
 132     "/a/path/driving/to/the/widget"
 133
 134 Or an object:
 135
 136     {
 137       "wgt": "/a/path/to/the/widget",
 138       "force": false,
 139       "root": "/a/path/to/the/root"
 140     }
 141
 142 "wgt" and "root" must be absolute paths.
 143
 144 **output**: An object with the field "added" being the string for
 145 the id of the added application.
 146
 147     {"added":"appli@x.y"}
 148
 149 ---
 150
 151 #### Method org.AGL.afm.system.uninstall
 152
 153 **Description**: Uninstall an application from its id.
 154
 155
 156 Note that this methods is a simple method accessor of
 157 ***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***.
 158
 159 After the uninstallation and before returning to the sender,
 160 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
 161
 162 **Input**: the *id* of the application and optionally the application *root* path.
 163
 164 Either a string:
 165
 166     "appli@x.y"
 167
 168 Or an object:
 169
 170     {
 171       "id": "appli@x.y",
 172       "root": "/a/path/to/the/root"
 173     }
 174
 175 **output**: the value 'true'.
 176
 177 ---
 178
 179 #### Method org.AGL.afm.user.detail
 180
 181
 182 **Description**: Get details about an application from its id.
 183
 184 **Input**: the id of the application as below.
 185
 186 Either just a string:
 187
 188     "appli@x.y"
 189
 190 Or an object having the field "id" of type string:
 191
 192     {"id":"appli@x.y"}
 193
 194 **Output**: A JSON object describing the application containing
 195 the fields described below.
 196
 197     {
 198       "id":          string, the application id (id@version)
 199       "version":     string, the version of the application
 200       "width":       integer, requested width of the application
 201       "height":      integer, requested height of the application
 202       "name":        string, the name of the application
 203       "description": string, the description of the application
 204       "shortname":   string, the short name of the application
 205       "author":      string, the author of the application
 206     }
 207
 208 ---
 209
 210 #### Method org.AGL.afm.user.runnables
 211
 212 **Description**: Get the list of applications that can be run.
 213
 214 **Input**: any valid json entry, can be anything except null.
 215
 216 **output**: An array of description of the runnable applications.
 217 Each item of the array contains an object containing the detail of
 218 an application as described above for the method
 219 *org.AGL.afm.user.detail*.
 220
 221 ---
 222
 223 #### Method org.AGL.afm.user.install
 224
 225 **Description**: Install an application from its widget file.
 226
 227 If an application of the same *id* and *version* exists, it is not
 228 reinstalled except when *force=true*.
 229
 230 Applications are installed in the subdirectories of the common directory
 231 reserved for applications.
 232 If *root* is specified, the application is installed under
 233 sub-directories of defined *root*.
 234
 235 Note that this methods is a simple accessor to the method
 236 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
 237
 238 After the installation and before returning to the sender,
 239 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
 240
 241 **Input**: The *path* of widget file to be installed. Optionally,
 242 a flag to *force* reinstallation and/or a *root* directory.
 243
 244 Simple form a simple string containing the absolute widget path:
 245
 246     "/a/path/driving/to/the/widget"
 247
 248 Or an object:
 249
 250     {
 251       "wgt": "/a/path/to/the/widget",
 252       "force": false,
 253       "root": "/a/path/to/the/root"
 254     }
 255
 256 ***wgt*** and ***root*** MUST be absolute paths.
 257
 258 **output**: An object containing field "added" to use as application ID.
 259
 260     {"added":"appli@x.y"}
 261
 262 ---
 263
 264 #### Method org.AGL.afm.user.uninstall
 265
 266 **Description**: Uninstall an application from its id.
 267
 268
 269 Note that this methods is a simple accessor to
 270 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
 271
 272 After the uninstallation and before returning to the sender,
 273 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
 274
 275 **Input**: the *id* of the application and, optionally, the path to
 276 application *root*.
 277
 278 Either a string:
 279
 280     "appli@x.y"
 281
 282 Or an object:
 283
 284     {
 285       "id": "appli@x.y",
 286       "root": "/a/path/to/the/root"
 287     }
 288
 289 **output**: the value 'true'.
 290
 291 ---
 292
 293 #### Method org.AGL.afm.user.start
 294
 295 **Description**:
 296
 297 **Input**: the *id* of the application and, optionally, the
 298 start *mode* as below.
 299
 300 Either just a string:
 301
 302     "appli@x.y"
 303
 304 Or an object containing field "id" of type string and
 305 optionally a field mode:
 306
 307     {"id":"appli@x.y","mode":"local"}
 308
 309 The field "mode" is a string equal to either "local" or "remote".
 310
 311 [Currently the mode is not available in the systemd version]
 312
 313 **output**: The *runid* of the application launched. *runid* is an integer.
 314
 315 ---
 316
 317 #### Method org.AGL.afm.user.once
 318
 319 **Description**:
 320
 321 **Input**: the *id* of the application
 322
 323 Either just a string:
 324
 325     "appli@x.y"
 326
 327 Or an object containing field "id" of type string.
 328
 329     {"id":"appli@x.y"}
 330
 331 **output**: The *state* of the application retrieved or launched.
 332 See *org.AGL.afm.user.state* to get a description of the returned
 333 object.
 334
 335 ---
 336
 337 #### Method org.AGL.afm.user.terminate
 338
 339 **Description**: Terminates the application attached to *runid*.
 340
 341 **Input**: The *runid* (an integer) of running instance to terminate.
 342
 343 **output**: the value 'true'.
 344
 345 ---
 346
 347 #### Method org.AGL.afm.user.stop
 348
 349 Obsolete since 8th November 2016 (2016/11/08).
 350 Kept for compatibility.
 351
 352 Use **org.AGL.afm.user.pause** instead.
 353
 354 ---
 355
 356 #### Method org.AGL.afm.user.continue
 357
 358 Obsolete since 8th November 2016 (2016/11/08).
 359 Kept for compatibility.
 360
 361 Use **org.AGL.afm.user.resume** instead.
 362
 363 ---
 364
 365 #### Method org.AGL.afm.user.pause
 366
 367 [Currently not available in the systemd version]
 368
 369 **Description**: Pauses the application attached to *runid* until terminate or resume.
 370
 371 **Input**: The *runid* (integer) of the running instance to pause.
 372
 373 **output**: the value 'true'.
 374
 375 ---
 376
 377 #### Method org.AGL.afm.user.resume
 378
 379 [Currently not available in the systemd version]
 380
 381 **Description**: Resumes the application attached to *runid* previously paused.
 382
 383 **Input**: The *runid* (integer) of the running instance to resume.
 384
 385 **output**: the value 'true'.
 386
 387 ---
 388
 389 #### Method org.AGL.afm.user.state
 390
 391 **Description**: Get information about a running instance of *runid*.
 392
 393 **Input**: The *runid* (integer) of the running instance inspected.
 394
 395 **output**: An object describing instance state. It contains:
 396 the runid (integer), the pids of the processes as an array starting
 397 with the group leader, the id of the running application (string),
 398 the state of the application (string either: "starting", "running", "paused").
 399
 400 Example of returned state:
 401
 402     {
 403       "runid": 2,
 404       "pids": [ 435, 436 ],
 405       "state": "running",
 406       "id": "appli@x.y"
 407     }
 408
 409 ---
 410
 411 #### Method org.AGL.afm.user.runners
 412
 413 **Description**: Get the list of currently running instances.
 414
 415 **Input**: anything.
 416
 417 **output**: An array of states, one per running instance, as returned by
 418 the method ***org.AGL.afm.user.state***.
 419
 420 Starting **afm daemons**
 421 ----------------------
 422
 423 ***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd
 424 services attached to system and user respectively. Normally, service files are
 425 locatedat */lib/systemd/system/afm-system-daemon.service* and
 426 */usr/lib/systemd/user/afm-user-daemon.service*.
 427
 428 ### ***afm-system-daemon*** options
 429
 430 The options for launching **afm-system-daemon** are:
 431
 432     -r
 433     --root directory
 434
 435          Set the root application directory.
 436
 437          Note that the default root directory is defined
 438          to be /usr/share/afm/applications (may change).
 439
 440     -d
 441     --daemon
 442
 443          Daemonizes the process. It is not needed by systemd.
 444
 445     -q
 446     --quiet
 447
 448          Reduces the verbosity (can be repeated).
 449
 450     -v
 451     --verbose
 452
 453          Increases the verbosity (can be repeated).
 454
 455     -h
 456     --help
 457
 458          Prints a short help.
 459
 460 ### ***afm-user-daemon*** options
 461
 462 The options for launching **afm-user-daemon** are:
 463
 464     -a
 465     --application directory
 466
 467          [Currently not available in the systemd version]
 468
 469          Includes the given application directory to
 470          the database base of applications.
 471
 472          Can be repeated.
 473
 474     -r
 475     --root directory
 476
 477          [Currently not available in the systemd version]
 478
 479          Includes root application directory or directories when
 480          passing multiple rootdir to
 481          applications database.
 482
 483          Note that default root directory for
 484          applications is always added. In current version
 485          /usr/share/afm/applications is used as default.
 486
 487     -m
 488     --mode (local|remote)
 489
 490          [Currently not available in the systemd version]
 491
 492          Set the default launch mode.
 493          The default value is 'local'
 494
 495     -d
 496     --daemon
 497
 498          Daemonizes the process. It is not needed by systemd.
 499
 500     -q
 501     --quiet
 502
 503          Reduces the verbosity (can be repeated).
 504
 505     -v
 506     --verbose
 507
 508          Increases the verbosity (can be repeated).
 509
 510     -h
 511     --help
 512
 513          Prints a short help.
 514
 515 Tasks of **afm-user-daemon**
 516 ----------------------------
 517
 518 ### Maintaining list of applications
 519
 520 At start **afm-user-daemon** scans the directories containing
 521 applications and load in memory a list of available applications
 522 accessible by current user.
 523
 524 When **afm-system-daemon** installs or removes an application.
 525 On success it sends the signal *org.AGL.afm.system.changed*.
 526 When receiving such a signal, **afm-user-daemon** rebuilds its
 527 applications list.
 528
 529 **afm-user-daemon** provides the data it collects about
 530 applications to its clients. Clients may either request the full list
 531 of available applications or a more specific information about a
 532 given application.
 533
 534 ### Launching application
 535
 536 **afm-user-daemon** launches application by using systemd.
 537 Systemd builds a secure environment for the application
 538 before starting it.
 539
 540 Once launched, running instances of application receive
 541 a runid that identify them. To make interface with systemd
 542 evident, the pid is the runid.
 543
 544 ### Managing instances of running applications
 545
 546 **afm-user-daemon** manages the list of applications
 547 that it launched.
 548
 549 When owning the right permissions, a client can get the list
 550 of running instances and details about a specific
 551 running instance. It can also terminate a given application.
 552
 553 ### Installing and uninstalling applications
 554
 555 If the client own the right permissions,
 556 **afm-user-daemon** delegates that task
 557 to **afm-system-daemon**.
 558
 559 Using ***afm-util***
 560 --------------------
 561
 562 The command line tool ***afm-util*** uses dbus-send to send
 563 orders to **afm-user-daemon**. This small scripts allows to
 564 send command to ***afm-user-daemon*** either interactively
 565 at shell prompt or scriptically.
 566
 567 The syntax is simple: it accept a command and when requires attached arguments.
 568
 569 Here is the summary of ***afm-util***:
 570
 571  - **afm-util runnables      **:
 572
 573    list the runnable widgets installed
 574
 575  - **afm-util install    wgt **:
 576
 577    install the wgt file
 578
 579  - **afm-util uninstall  id  **:
 580
 581    remove the installed widget of id
 582
 583  - **afm-util detail     id  **:
 584
 585    print detail about the installed widget of id
 586
 587  - **afm-util runners        **:
 588
 589    list the running instance
 590
 591  - **afm-util start      id  **:
 592
 593    start an instance of the widget of id
 594
 595  - **afm-util once      id  **:
 596
 597    run once an instance of the widget of id
 598
 599  - **afm-util terminate  rid **:
 600
 601    terminate the running instance rid
 602
 603  - **afm-util state      rid **:
 604
 605    get status of the running instance rid
 606
 607
 608 Here is how to list applications using ***afm-util***:
 609
 610     afm-util runnables
 611
 612
 613 [afm-daemons]: pictures/afm-daemons.svg