"Fossies" - the Fresh Open Source Software Archive

Member "apt-2.2.4/doc/json-hooks-protocol.md" (10 Jun 2021, 5204 Bytes) of package /linux/misc/apt-2.2.4.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) GitHub Flavored Markdown source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 ## JSON Hooks
    2 
    3 APT 1.6 introduces support for hooks that talk JSON-RPC 2.0. Hooks act
    4 as a server, and APT as a client.
    5 
    6 ## Wire protocol
    7 
    8 APT communicates with hooks via a UNIX domain socket in file descriptor
    9 `$APT_HOOK_SOCKET`. The transport is a byte stream (SOCK_STREAM).
   10 
   11 The byte stream contains multiple JSON objects, each representing a
   12 JSON-RPC request or response, and each terminated by an empty line
   13 (`\n\n`). Therefore, JSON objects containing empty lines may not be
   14 used.
   15 
   16 For protocol version `0.1`, each JSON object must be encoded on a single
   17 line.
   18 
   19 ## Lifecycle
   20 
   21 The general life of a hook is as following.
   22 
   23 1. Hook is started
   24 2. Hello handshake is exchanged
   25 3. One or more calls or notifications are sent from apt to the hook
   26 4. Bye notification is sent
   27 
   28 It is unspecified whether a hook is sent one or more messages. For
   29 example, a hook may be started only once for the lifetime of the apt
   30 process and receive multiple notifications, but a hook may also be
   31 started multiple times. Hooks should thus be stateless.
   32 
   33 ## JSON messages
   34 
   35 ### Hello handshake
   36 
   37 APT performs a call to the method `org.debian.apt.hooks.hello` with
   38 the named parameter `versions` containing a list of supported protocol
   39 versions. The hook picks the version it supports. The current version
   40 is `"0.1"`, and support for that version is mandatory.
   41 
   42 *Example*:
   43 
   44 1. APT:
   45    ```{"jsonrpc":"2.0","method":"org.debian.apt.hooks.hello","id":0,"params":{"versions":["0.1"]}}```
   46 
   47 
   48 2. Hook:
   49    ```{"jsonrpc":"2.0","id":0,"result":{"version":"0.1"}}```
   50 
   51 ### Bye notification
   52 
   53 Before closing the connection, APT sends a notification for the
   54 method `org.debian.apt.hooks.bye`.
   55 
   56 ### Hook notification
   57 
   58 The following methods are supported:
   59 
   60 1. `org.debian.apt.hooks.install.pre-prompt` - Run before the y/n prompt
   61 1. `org.debian.apt.hooks.install.post` - Run after success
   62 1. `org.debian.apt.hooks.install.fail` - Run after failed install
   63 1. `org.debian.apt.hooks.search.pre` - Run before search
   64 1. `org.debian.apt.hooks.search.post` - Run after successful search
   65 1. `org.debian.apt.hooks.search.fail` - Run after search without results
   66 
   67 They can be registered by adding them to the list:
   68 
   69 ```AptCli::Hooks::<name>```
   70 
   71 where `<name>` is the name of the hook. It is recommended that these
   72 option names are prefixed with `Binary::apt`, so that they only take
   73 effect for the `apt` binary. Otherwise, there may be compatibility issues
   74 with scripts and alike.
   75 
   76 #### Parameters
   77 
   78 *command*: The command used on the command-line. For example, `"purge"`.
   79 
   80 *search-terms*: Any non-option arguments given to the command.
   81 
   82 *unknown-packages*: For non-search hooks, a subset of *search-terms*
   83 that APT could not find packages in the cache for.
   84 
   85 *packages*: An array of modified packages. This is mostly useful for
   86 install. Each package has the following attributes:
   87 
   88 - *id*: An unsigned integer describing the package
   89 - *name*: The name of the package
   90 - *architecture*: The architecture of the package. For `"all"` packages, this will be the native architecture;
   91                   use per-version architecture fields to see `"all"`.
   92 
   93 - *mode*: One of `install`, `deinstall`, `purge`, or `keep`. `keep`
   94           is not exposed in 0.1. To determine an upgrade, check
   95           that a current version is installed.
   96 - *automatic*: Whether the package is/will be automatically installed
   97 - *versions*: An array with up to 3 fields:
   98 
   99   - *candidate*: The candidate version
  100   - *install*: The version to be installed
  101   - *current*: The version currently installed
  102 
  103   Each version is represented as an object with the following fields:
  104 
  105   - *id*: An unsigned integer
  106   - *version*: The version as a string
  107   - *architecture*: Architecture of the version
  108   - *pin*: The pin priority (optional)
  109 
  110 #### Example
  111 
  112 ```json
  113 {
  114     "jsonrpc": "2.0",
  115     "method": "org.debian.apt.hooks.install.pre",
  116     "params": {
  117         "command": "purge",
  118         "search-terms": [
  119             "petname-",
  120             "lxd+"
  121         ],
  122         "packages": [
  123             {
  124                 "id": 1500,
  125                 "name": "ebtables",
  126                 "architecture": "amd64",
  127                 "mode": "install",
  128                 "automatic": 1,
  129                 "versions": {
  130                     "candidate": {
  131                         "id": 376,
  132                         "version": "2.0.10.4-3.5ubuntu2",
  133                         "architecture": "amd64",
  134                         "pin": 990
  135                     },
  136                     "install": {
  137                         "id": 376,
  138                         "version": "2.0.10.4-3.5ubuntu2",
  139                         "architecture": "amd64",
  140                         "pin": 990
  141                     }
  142                 }
  143             }
  144         ]
  145     }
  146 }
  147 ```
  148 
  149 #### Compatibility note
  150 Future versions of APT might make these calls instead of notifications.
  151 
  152 ## Evolution of this protocol
  153 New incompatible versions may be introduced with each new feature
  154 release of apt (1.7, 1.8, etc). No backward compatibility is promised
  155 until protocol 1.0: New stable feature releases may support a newer
  156 protocol version only (for example, 1.7 may only support 0.2).
  157 
  158 Additional fields may be added to objects without bumping the protocol
  159 version.