json: Add "options" array to JSON hooks

See the attached documentation. Note that defaults are missing,
so using this is not particularly easy so far.

3 files changed, 182 insertions, 4 deletions

diff --git a/apt-private/private-json-hooks.cc b/apt-private/private-json-hooks.cc
index 58185181e..6169488f6 100644
--- a/apt-private/private-json-hooks.cc
+++ b/apt-private/private-json-hooks.cc
@@ -350,11 +350,43 @@ static void NotifyHook(std::ostream &os, std::string const &method, const char *
    jsonWriter.endObject(); // main
 }
 
+static JsonWriter &BuildOptionsArray(JsonWriter &writer)
+{
+   const Configuration::Item *Top = _config->Tree(nullptr);
+   if (Top == 0)
+      return writer.beginArray().endArray();
+
+   writer.beginArray();
+   do
+   {
+      if (not Top->Value.empty())
+	 writer.beginObject().name("name").value(Top->FullTag()).name("value").value(Top->Value).endObject();
+      if (Top->Child != 0)
+      {
+	 Top = Top->Child;
+	 continue;
+      }
+
+      while (Top != 0 && Top->Next == 0)
+	 Top = Top->Parent;
+      if (Top != 0)
+	 Top = Top->Next;
+
+   } while (Top != 0);
+
+   writer.endArray();
+
+   return writer;
+}
+
 /// @brief Build the hello handshake message for 0.1 protocol
 static std::string BuildHelloMessage()
 {
    std::stringstream Hello;
-   JsonWriter(Hello).beginObject().name("jsonrpc").value("2.0").name("method").value("org.debian.apt.hooks.hello").name("id").value(0).name("params").beginObject().name("versions").beginArray().value("0.1").value("0.2").endArray().endObject().endObject();
+   auto writer = JsonWriter(Hello).beginObject().name("jsonrpc").value("2.0").name("method").value("org.debian.apt.hooks.hello").name("id").value(0).name("params").beginObject().name("versions").beginArray().value("0.1").value("0.2").endArray().name("options");
+
+   BuildOptionsArray(writer);
+   writer.endObject().endObject();
 
    return Hello.str();
 }
diff --git a/doc/json-hooks-protocol.md b/doc/json-hooks-protocol.md
index 2d8410c8d..4dcbced0d 100644
--- a/doc/json-hooks-protocol.md
+++ b/doc/json-hooks-protocol.md
@@ -38,13 +38,39 @@ started multiple times. Hooks should thus be stateless.
 
 APT performs a call to the method `org.debian.apt.hooks.hello` with
 the named parameter `versions` containing a list of supported protocol
-versions. The hook picks the version it supports. The current version
-is `"0.1"`, and support for that version is mandatory.
+versions, and an optional `options` array. The hook picks the version it supports. The current version
+is `"0.2"`, and support for "0.1" or "0.2" is mandatory.
+
+The `options` array is an optional list of all options currently set in the apt
+configuration object. Note that not all options are present, and the default can vary,
+you cannot rely on the default being `true` or `false` for example for a boolean option
+-- it depends on the context.
+
+APT options are internally stored as a tree leading to the awkward situation that a list
+item could have a name, e.g. `APT::Architectures "unused" { first "amd64"; "i386"; };`. This will
+be represented as
+
+```json
+[
+    {"name": "APT::Architectures", "value": "unused"},
+    {"name": "APT::Architectures::first", "amd64"},
+    {"name": "APT::Architectures::", ""}
+]
+```
+
+To interpret an option name as a list, with trailing `::`, for example, `APT::Architectures`, you
+will need to write a function similar to:
+
+```python
+def get_list(options, key):
+    """key includes trailing ::"""
+    return [value for name, value in options if name.startswith(key) and "::" not in name[len(key):]]
+```
 
 *Example*:
 
 1. APT:
-   ```{"jsonrpc":"2.0","method":"org.debian.apt.hooks.hello","id":0,"params":{"versions":["0.1"]}}```
+   ```{"jsonrpc":"2.0","method":"org.debian.apt.hooks.hello","id":0,"params":{"versions":["0.1", "0.2"], "options": [{"name": "APT::Architecture", "value": "amd64"}]}}```
 
 
 2. Hook:
diff --git a/test/integration/test-apt-cli-json-hooks b/test/integration/test-apt-cli-json-hooks
index d319265bb..ee936e116 100755
--- a/test/integration/test-apt-cli-json-hooks
+++ b/test/integration/test-apt-cli-json-hooks
@@ -81,6 +81,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -113,6 +119,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -142,6 +154,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -171,6 +189,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -204,6 +228,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -239,6 +269,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -308,6 +344,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -376,6 +418,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -445,6 +493,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -517,6 +571,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -553,6 +613,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -627,6 +693,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -700,6 +772,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -774,6 +852,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -854,6 +938,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -928,6 +1018,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -1001,6 +1097,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -1075,6 +1177,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -1155,6 +1263,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }
@@ -1168,6 +1282,12 @@ HOOK: request {
     "versions": [
       "0.1",
       "0.2"
+    ],
+    "options": [
+      {
+        "name": "APT::Architecture",
+        "value": "i386"
+      }
     ]
   }
 }