[pve-devel] [PATCH installer v2] post-hook: add `$hook` field describing document schema version

[Christoph Heiss]

This adds a metadata-field `$hook` containing a single key `version`
(for now) to the post-hook json, indicating which schema version (and
thus structure) this document uses.

In the resulting JSON, this will look like this:
{
    "$hook": {
	"version": "1.0"
    },
    "debian-version": ..,
    ..
}

The field follows the format "<major>.<minor>" and applies semantic
versioning meaning for both the major and minor number. A patch version
is left out here, as it doesn't make much sense in this context.

This was suggested by Thomas when originally introducing the post-hook
functionality in [0].

[0] https://lore.proxmox.com/pve-devel/00019f8d-e4f2-420e-892a-b89e8b886748@proxmox.com/

Suggested-by: Thomas Lamprecht <t.lamprecht at proxmox.com>
Signed-off-by: Christoph Heiss <c.heiss at proxmox.com>
---
v1: https://lore.proxmox.com/pve-devel/20241112131815.670475-2-c.heiss@proxmox.com/

Changes v1 -> v2:
  * introduced `$hook` top-level field, nesting `version` under it

 proxmox-post-hook/src/main.rs | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/proxmox-post-hook/src/main.rs b/proxmox-post-hook/src/main.rs
index 8558da2..e2ae0ca 100644
--- a/proxmox-post-hook/src/main.rs
+++ b/proxmox-post-hook/src/main.rs
@@ -129,10 +129,40 @@ struct CpuInfo {
     sockets: usize,
 }
 
+/// Metadata of the hook, such as schema version of the document.
+#[derive(Serialize)]
+#[serde(rename_all = "kebab-case")]
+struct PostHookInfoMeta {
+    /// major.minor version describing the schema version of this document, in a semanticy-version
+    /// way.
+    ///
+    /// major: Incremented for incompatible/breaking API changes, e.g. removing an existing
+    /// field.
+    /// minor: Incremented when adding functionality in a backwards-compatible matter, e.g.
+    /// adding a new field.
+    version: String,
+}
+
+impl PostHookInfoMeta {
+    const SCHEMA_VERSION: &str = "1.0";
+}
+
+impl Default for PostHookInfoMeta {
+    fn default() -> Self {
+        Self {
+            version: Self::SCHEMA_VERSION.to_owned(),
+        }
+    }
+}
+
 /// All data sent as request payload with the post-hook POST request.
 #[derive(Serialize)]
 #[serde(rename_all = "kebab-case")]
 struct PostHookInfo {
+    // This field is prefixed by `$` on purpose, to indicate that it is document metadata and not
+    // part of the actual content itself. (E.g. JSON Schema uses a similar naming scheme)
+    #[serde(rename = "$hook")]
+    hook_meta: PostHookInfoMeta,
     /// major.minor version of Debian as installed, retrieved from /etc/debian_version
     debian_version: String,
     /// PVE/PMG/PBS version as reported by `pveversion`, `pmgversion` or
@@ -215,6 +245,7 @@ impl PostHookInfo {
         };
 
         Ok(Self {
+            hook_meta: PostHookInfoMeta::default(),
             debian_version: read_file("/etc/debian_version")?,
             product: Self::gather_product_info(&setup_info, &run_cmd)?,
             iso: setup_info.iso_info.clone(),
-- 
2.47.0