docs/afm-daemons.md

   1 The application framework daemons
   2 =================================
   3
   4 Foreword
   5 --------
   6
   7 This document describes application framework daemons
   8 FCF (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]
  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, resqueted 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 **output**: The *runid* of the application launched. *runid* is an integer.
 312
 313 ---
 314
 315 #### Method org.AGL.afm.user.once
 316
 317 **Description**:
 318
 319 **Input**: the *id* of the application
 320
 321 Either just a string:
 322
 323     "appli@x.y"
 324
 325 Or an object containing field "id" of type string.
 326
 327     {"id":"appli@x.y"}
 328
 329 **output**: The *state* of the application retrieved or launched.
 330 See *org.AGL.afm.user.state* to get a description of the returned
 331 object.
 332
 333 ---
 334
 335 #### Method org.AGL.afm.user.terminate
 336
 337 **Description**: Terminates the application attached to *runid*.
 338
 339 **Input**: The *runid* (an integer) of running instance to terminate.
 340
 341 **output**: the value 'true'.
 342
 343 ---
 344
 345 #### Method org.AGL.afm.user.stop
 346
 347 Obsolete since 8th November 2016 (2016/11/08).
 348 Kept for compatibility.
 349
 350 Use **org.AGL.afm.user.pause** instead.
 351
 352 ---
 353
 354 #### Method org.AGL.afm.user.continue
 355
 356 Obsolete since 8th November 2016 (2016/11/08).
 357 Kept for compatibility.
 358
 359 Use **org.AGL.afm.user.resume** instead.
 360
 361 ---
 362
 363 #### Method org.AGL.afm.user.pause
 364
 365 **Description**: Pauses the application attached to *runid* until terminate or resume.
 366
 367 **Input**: The *runid* (integer) of the running instance to pause.
 368
 369 **output**: the value 'true'.
 370
 371 ---
 372
 373 #### Method org.AGL.afm.user.resume
 374
 375 **Description**: Resumes the application attached to *runid* previously paused.
 376
 377 **Input**: The *runid* (integer) of the running instance to resume.
 378
 379 **output**: the value 'true'.
 380
 381 ---
 382
 383 #### Method org.AGL.afm.user.state
 384
 385 **Description**: Get informations about a running instance of *runid*.
 386
 387 **Input**: The *runid* (integer) of the running instance inspected.
 388
 389 **output**: An object describing instance state. It contains:
 390 the runid (integer), the pids of the processes as an array starting
 391 with the group leader, the id of the running application (string),
 392 the state of the application (string either: "starting", "running", "paused").
 393
 394 Example of returned state:
 395
 396     {
 397       "runid": 2,
 398       "pids": [ 435, 436 ],
 399       "state": "running",
 400       "id": "appli@x.y"
 401     }
 402
 403 ---
 404
 405 #### Method org.AGL.afm.user.runners
 406
 407 **Description**: Get the list of currently running instances.
 408
 409 **Input**: anything.
 410
 411 **output**: An array of states, one per running instance, as returned by
 412 the method ***org.AGL.afm.user.state***.
 413
 414 Starting **afm daemons**
 415 ----------------------
 416
 417 ***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd
 418 services attached to system and user respectively. Normally, service files are
 419 locatedat */lib/systemd/system/afm-system-daemon.service* and
 420 */lib/systemd/user/afm-user-daemon.service*.
 421
 422 ### ***afm-system-daemon*** options
 423
 424 The options for launching **afm-system-daemon** are:
 425
 426     -r
 427     --root directory
 428
 429          Set the root application directory.
 430
 431          Note that the default root directory is defined
 432          to be /usr/share/afm/applications (may change).
 433
 434     -d
 435     --daemon
 436
 437          Daemonizes the process. It is not needed by sytemd.
 438
 439     -q
 440     --quiet
 441
 442          Reduces the verbosity (can be repeated).
 443
 444     -v
 445     --verbose
 446
 447          Increases the verbosity (can be repeated).
 448
 449     -h
 450     --help
 451
 452          Prints a short help.
 453
 454 ### ***afm-user-daemon*** options
 455
 456 The options for launching **afm-user-daemon** are:
 457
 458     -a
 459     --application directory
 460
 461          Includes the given application directory to
 462          the database base of applications.
 463
 464          Can be repeated.
 465
 466     -r
 467     --root directory
 468
 469          Includes root application directory or directories when
 470          passing multiple rootdir to
 471          applications database.
 472
 473          Note that default root directory for
 474          applications is always added. In current version
 475          /usr/share/afm/applications is used as default.
 476
 477     -m
 478     --mode (local|remote)
 479
 480          Set the default launch mode.
 481          The default value is 'local'
 482
 483     -d
 484     --daemon
 485
 486          Daemonizes the process. It is not needed by sytemd.
 487
 488     -q
 489     --quiet
 490
 491          Reduces the verbosity (can be repeated).
 492
 493     -v
 494     --verbose
 495
 496          Increases the verbosity (can be repeated).
 497
 498     -h
 499     --help
 500
 501          Prints a short help.
 502
 503 Tasks of **afm-user-daemon**
 504 ----------------------------
 505
 506 ### Maintaining list of applications
 507
 508 At start **afm-user-daemon** scans the directories containing
 509 applications and load in memory a list of avaliable applications
 510 accessible by current user.
 511
 512 When **afm-system-daemon** installs or removes an application.
 513 On success it sends the signal *org.AGL.afm.system.changed*.
 514 When receiving such a signal, **afm-user-daemon** rebuilds its
 515 applications list.
 516
 517 **afm-user-daemon** provides the data it collects about
 518 applications to its clients. Clients may either request the full list
 519 of avaliable applications or a more specific information about a
 520 given application.
 521
 522 ### Launching application
 523
 524 **afm-user-daemon** launches application. Its builds a secure
 525 environment for the application before starting it within a
 526 secured environment.
 527
 528 Different kind of applications can be launched.
 529
 530 This is set using a configuration file that describes
 531 how to launch an application of a given kind within a given
 532 mode.
 533
 534 There is two launching modes: local or remote.
 535
 536 Launching an application locally means that
 537 the application and its binder are launched together.
 538
 539 Launching application remotely translates in only launching
 540 the application binder. The UI by itself has to be activated
 541 remotely by the requested (ie: HTML5 homescreen in a browser)
 542
 543 Once launched, running instances of application receive
 544 a runid that identify them.
 545
 546 ### Managing instances of running applications
 547
 548 **afm-user-daemon** manages the list of applications
 549 that it launched.
 550
 551 When owning the right permissions, a client can get the list
 552 of running instances and details about a specific
 553 running instance. It can also terminate, pause or
 554 resume a given application.
 555
 556 ### Installing and uninstalling applications
 557
 558 If the client own the right permissions,
 559 **afm-user-daemon** delegates that task
 560 to **afm-system-daemon**.
 561
 562 Launcher Configuration
 563 ----------------------
 564
 565 It contains rules for launching applications.
 566 When **afm-user-daemon** has to launch an application,
 567 it looks for launch mode (local or remote), as well as
 568 for the type of application describe in ***config.xml***
 569 widget configuration file.
 570
 571 This tuple mode+type allows to select the adequate rule.
 572
 573 Configuration file is **/etc/afm/afm-launch.conf**.
 574
 575 It contains sections and rules. It can also contain comments
 576 and empty lines to improve readability.
 577
 578 The separators are space and tabulation, any other character
 579 should have a meaning.
 580
 581 The format is line oriented.
 582 The new line character separate the lines.
 583
 584 Lines having only separators are blank lines and ignored.
 585 Line having character #(sharp) at first position are comment
 586 lines and ignored.
 587
 588 Lines not starting with a separator are different
 589 from lines starting with a separator character.
 590
 591 The grammar of the configuration file is defined below:
 592
 593     CONF: *COMMENT *SECTION
 594
 595     SECTION: MODE *RULE
 596
 597     RULE: +TYPE VECTOR ?VECTOR
 598
 599     MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
 600
 601     TYPE: DATA *SEP EOL
 602
 603     VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
 604
 605     DATA: CHAR *NCHAR
 606     NDATA: +NCHAR
 607
 608     EOL: NL *COMMENT
 609     COMMENT: *SEP CMT *(SEP | NCHAR) NL
 610
 611     NL: '\x0a'
 612     SEP: '\x20' | '\x09'
 613     CMT: '#'
 614     CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
 615     NCHAR: CMT | CHAR
 616
 617 Here is a sample of configuration file for defining how
 618 to launch an application of types *application/x-executable*,
 619 *text/x-shellscript* and *text/html* in local mode:
 620
 621     mode local
 622
 623     application/x-executable
 624     text/x-shellscript
 625         %r/%c
 626
 627     text/html
 628         /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
 629         /usr/bin/web-runtime http://localhost:%P/%c?token=%S
 630
 631 This shows that:
 632
 633  - within a section, several rules can be defined
 634  - within a rule, several types can be defined
 635  - within a rule, one or two vectors can be defined
 636  - vectors are using %substitution
 637  - launched binaries must be defined with their full path
 638
 639 ### mode local
 640
 641 Within this mode, the launchers have either one or two description vectors.
 642 All of those vectors are treated as programs
 643 and are executed with 'execve' system call.
 644
 645 The first vector is the leader vector and it defines the process
 646 group. The second vector (if any) is attached to the group
 647 defined by this first vector.
 648
 649 ### mode remote
 650
 651 Within this mode, the launchers have either one or two vectors
 652 describing them.
 653
 654 The first vector is process as a program and is executed with
 655 system call 'execve'.
 656
 657 The second vector (if any) defines a text that is returned
 658 to the caller. This mechanism can be used to return a uri
 659 for remote UI to connect on the newly launched application.
 660
 661 The daemon ***afm-user-daemon*** allocates a port for each
 662 new remote application.
 663 The current implementation port allocation is incremental.
 664 A smarter (cacheable and discoverable) allocation should be defined.
 665
 666 ### %substitutions
 667
 668 Vectors can include sequences of 2 characters that have a special
 669 meaning. These sequences are named *%substitution* because their
 670 first character is the percent sign (%) and because each occurrence
 671 of the sequence is replaced, at launch time, by the value associated
 672 to sequences.
 673
 674 Here is the list of *%substitutions*:
 675
 676  - ***%%***: %.
 677
 678    This simply emits the percent sign %
 679
 680  - ***%a***: appid
 681
 682    Holds application Id of launched application.
 683
 684    Defined by the attribute **id** of the element **<widget>**
 685    of **config.xml**.
 686
 687  - ***%b***: bindings
 688
 689    In the future should represent the list of bindings and bindings directory separated by ','.
 690    Warning: not supported in current version.
 691
 692  - ***%c***: content
 693
 694    The file within the widget directory that is the entry point.
 695
 696    For HTML applications, it represents the relative path to main
 697    page (aka index.html).
 698
 699    Defined by attribute **src** of the element **<content>** within **config.xml**.
 700
 701  - ***%D***: datadir
 702
 703    Path of the directory where the application runs (cwd)
 704    and stores its data.
 705
 706    It is equal to %h/%a.
 707
 708  - ***%H***: height
 709
 710    Requested height for the widget.
 711
 712    Defined by the attribute **height** of the element **<widget>**
 713    of **config.xml**.
 714
 715  - ***%h***: homedir
 716
 717    Path of the home directory for all applications.
 718
 719    It is generally equal to $HOME/app-data
 720
 721  - ***%I***: icondir
 722
 723    Path of the directory were the icons of the applications can be found.
 724
 725  - ***%m***: mime-type
 726
 727    Mime type of the launched application.
 728
 729    Defined by the attribute **type** of the element **<content>**
 730    of **config.xml**.
 731
 732  - ***%n***: name
 733
 734    Name of the application as defined by the content of the
 735    element **<name>** of **config.xml**.
 736
 737  - ***%P***: port
 738
 739    A port to use. It is currently a kind of random port. The precise
 740    model is to be defined later.
 741
 742  - ***%R***: readyfd
 743
 744    Number of file descriptor to use for signaling
 745    readiness of launched process.
 746
 747  - ***%r***: rootdir
 748
 749    Path of directory containing the widget and its data.
 750
 751  - ***%S***: secret
 752
 753    An hexadecimal number that can be used to initialize pairing of client
 754    and application binder.
 755
 756  - ***%W***: width
 757
 758    Requested width for the widget.
 759
 760    Defined by the attribute **width** of the element **<widget>**
 761    of **config.xml**.
 762
 763 Using ***afm-util***
 764 --------------------
 765
 766 The command line tool ***afm-util*** uses dbus-send to send
 767 orders to **afm-user-daemon**. This small scripts allows to
 768 send command to ***afm-user-daemon*** either interactively
 769 at shell prompt or scriptically.
 770
 771 The syntax is simple: it accept a command and when requires attached arguments.
 772
 773 Here is the summary of ***afm-util***:
 774
 775  - **afm-util runnables      **:
 776
 777    list the runnable widgets installed
 778
 779  - **afm-util install    wgt **:
 780
 781    install the wgt file
 782
 783  - **afm-util uninstall  id  **:
 784
 785    remove the installed widget of id
 786
 787  - **afm-util detail     id  **:
 788
 789    print detail about the installed widget of id
 790
 791  - **afm-util runners        **:
 792
 793    list the running instance
 794
 795  - **afm-util start      id  **:
 796
 797    start an instance of the widget of id
 798
 799  - **afm-util once      id  **:
 800
 801    run once an instance of the widget of id
 802
 803  - **afm-util terminate  rid **:
 804
 805    terminate the running instance rid
 806
 807  - **afm-util pause       rid **:
 808
 809    pause the running instance rid
 810
 811  - **afm-util resume   rid **:
 812
 813    resume the previously paused rid
 814
 815  - **afm-util state      rid **:
 816
 817    get status of the running instance rid
 818
 819
 820 Here is how to list applications using ***afm-util***:
 821
 822     afm-util runnables
 823
 824
 825 [afm-daemons]: pictures/afm-daemons.svg "afm daemons location in the system"