You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

json-hooks-protocol.md 5.1 KiB

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