[PATCH v3 proxmox-perl-rs 02/76] pve-rs: add PVE::RS::Multipath bindings for multipathd status parsing

[Thomas Lamprecht <t.lamprecht@proxmox.com>]

Expose the multipathd map parser and the health derivation of the
proxmox-multipath crate to Perl. The managed dm-multipath support in
pve-storage then only runs the daemon command and passes its output
on, instead of keeping a parser of its own. The parser takes the raw
command output, so map aliases with non-ASCII characters keep their
names without a decoding step on the Perl side.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 pve-rs/Cargo.toml                |  1 +
 pve-rs/Makefile                  |  2 +
 pve-rs/debian/control            |  1 +
 pve-rs/src/bindings/mod.rs       |  3 ++
 pve-rs/src/bindings/multipath.rs | 40 +++++++++++++++++
 pve-rs/test/Makefile             |  1 +
 pve-rs/test/multipath.pl         | 74 ++++++++++++++++++++++++++++++++
 7 files changed, 122 insertions(+)
 create mode 100644 pve-rs/src/bindings/multipath.rs
 create mode 100755 pve-rs/test/multipath.pl

diff --git a/pve-rs/Cargo.toml b/pve-rs/Cargo.toml
index ecedb1e..b89f91a 100644
--- a/pve-rs/Cargo.toml
+++ b/pve-rs/Cargo.toml
@@ -38,6 +38,7 @@ proxmox-frr = { version = "0.6.0" }
 proxmox-http = { version = "1.0.2", features = ["client-sync", "client-trait"] }
 proxmox-http-error = "1"
 proxmox-log = "1"
+proxmox-multipath = "0.1"
 proxmox-network-types = "1.1.2"
 proxmox-notify = { version = "2", features = ["pve-context", "legacy-matchers"] }
 proxmox-oci = "0.2.2"
diff --git a/pve-rs/Makefile b/pve-rs/Makefile
index 60f68c7..458ea68 100644
--- a/pve-rs/Makefile
+++ b/pve-rs/Makefile
@@ -27,6 +27,7 @@ PERLMOD_GENPACKAGE := /usr/lib/perlmod/genpackage.pl \
 
 PERLMOD_PACKAGES := \
 	  PVE::RS::Firewall::SDN \
+	  PVE::RS::Multipath \
 	  PVE::RS::Notify \
 	  PVE::RS::NVML \
 	  PVE::RS::OCI \
@@ -59,6 +60,7 @@ PROXMOX_DOC_CRATES := \
     proxmox-http \
     proxmox-http-error \
     proxmox-log \
+    proxmox-multipath \
     proxmox-notify \
     proxmox-openid \
     proxmox-resource-scheduling \
diff --git a/pve-rs/debian/control b/pve-rs/debian/control
index ad8611e..33a9bcb 100644
--- a/pve-rs/debian/control
+++ b/pve-rs/debian/control
@@ -26,6 +26,7 @@ Build-Depends: debhelper-compat (= 13),
                librust-proxmox-http-1+default-dev (>= 1.0.2-~~),
                librust-proxmox-http-error-1+default-dev,
                librust-proxmox-log-1+default-dev,
+               librust-proxmox-multipath-0.1+default-dev,
                librust-proxmox-network-types-1+default-dev (>= 1.1.2-~~),
                librust-proxmox-notify-2+default-dev,
                librust-proxmox-notify-2+legacy-matchers-dev,
diff --git a/pve-rs/src/bindings/mod.rs b/pve-rs/src/bindings/mod.rs
index 143a62b..c229327 100644
--- a/pve-rs/src/bindings/mod.rs
+++ b/pve-rs/src/bindings/mod.rs
@@ -1,5 +1,8 @@
 //! This contains all the perl bindings.
 
+mod multipath;
+pub use multipath::pve_rs_multipath;
+
 mod nvml;
 pub use nvml::pve_rs_nvml;
 
diff --git a/pve-rs/src/bindings/multipath.rs b/pve-rs/src/bindings/multipath.rs
new file mode 100644
index 0000000..447c4aa
--- /dev/null
+++ b/pve-rs/src/bindings/multipath.rs
@@ -0,0 +1,40 @@
+//! Device-mapper multipath status parsing and health derivation.
+
+#[perlmod::package(name = "PVE::RS::Multipath", lib = "pve_rs")]
+pub mod pve_rs_multipath {
+    //! The `PVE::RS::Multipath` package.
+    //!
+    //! Pure helpers around device-mapper multipath state. The Perl side queries the daemon and
+    //! passes its output here.
+    //!
+    //! See [`proxmox_multipath`].
+
+    use anyhow::Error;
+
+    use proxmox_multipath::{Health, Map};
+
+    /// Parse the output of `multipathd show maps json` into normalized maps, each with its LUN
+    /// WWID, path groups, member paths and derived health.
+    ///
+    /// Takes the raw command output. `multipathd` prints map aliases as configured, so bytes that
+    /// are not valid UTF-8 are replaced rather than failing the status of every map.
+    ///
+    /// See [`proxmox_multipath::parse_maps_json`].
+    #[export]
+    pub fn parse_maps_json(json: &[u8]) -> Result<Vec<Map>, Error> {
+        proxmox_multipath::parse_maps_json(&String::from_utf8_lossy(json))
+    }
+
+    /// Derive the health of a map from its active and total path counts, and the number of paths
+    /// it is expected to have when the transport configuration knows that.
+    ///
+    /// See [`proxmox_multipath::derive_health`].
+    #[export]
+    pub fn derive_health(
+        paths_active: u64,
+        paths_total: u64,
+        paths_expected: Option<u64>,
+    ) -> Health {
+        proxmox_multipath::derive_health(paths_active, paths_total, paths_expected)
+    }
+}
diff --git a/pve-rs/test/Makefile b/pve-rs/test/Makefile
index 29dc955..1ed3210 100644
--- a/pve-rs/test/Makefile
+++ b/pve-rs/test/Makefile
@@ -2,6 +2,7 @@
 test: Proxmox/Lib/PVE.pm
 	@echo "-- running pve-rs tests --"
 	perl -I. -I.. -I../.. ./resource_scheduling.pl
+	perl -I. -I.. -I../.. ./multipath.pl
 
 # The test stub, we don't know where to look for the library from in here!
 Proxmox/Lib/PVE.pm:
diff --git a/pve-rs/test/multipath.pl b/pve-rs/test/multipath.pl
new file mode 100755
index 0000000..2f30008
--- /dev/null
+++ b/pve-rs/test/multipath.pl
@@ -0,0 +1,74 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+use Test::More;
+
+use PVE::RS::Multipath;
+
+# a recorded `multipathd show maps json` reply: one healthy map, one with a failed path
+my $json = <<'JSON';
+{
+   "major_version": 0,
+   "minor_version": 1,
+   "maps": [
+      {
+         "name": "mpatha", "uuid": "3600140500a1b2c3d4e5f6a7b8c9d0e1f", "sysfs": "dm-0",
+         "dm_st": "active", "path_faults": 0,
+         "path_groups": [ { "group": 1, "dm_st": "active", "pri": 50, "paths": [
+            { "dev": "sdb", "dm_st": "active", "dev_st": "running", "chk_st": "ready", "pri": 50,
+              "host_wwpn": "0x21000024ff7d6a1c", "target_wwpn": "0x500a098000000001" },
+            { "dev": "sdc", "dm_st": "active", "dev_st": "running", "chk_st": "ready", "pri": 50,
+              "host_wwpn": "0x21000024ff7d6a1d", "target_wwpn": "0x500a098000000002" }
+         ] } ]
+      },
+      {
+         "name": "mpathb", "uuid": "360014050aabbccddeeff00112233445566", "sysfs": "dm-1",
+         "dm_st": "active", "path_faults": "3",
+         "path_groups": [
+            { "group": 1, "dm_st": "active", "pri": 10, "paths": [
+               { "dev": "sdd", "dm_st": "active", "chk_st": "ready", "pri": 10, "target_wwpn": "[undef]" } ] },
+            { "group": 2, "dm_st": "enabled", "pri": 0, "paths": [
+               { "dev": "sde", "dm_st": "failed", "chk_st": "faulty", "pri": 0 } ] }
+         ]
+      }
+   ]
+}
+JSON
+
+my $maps = PVE::RS::Multipath::parse_maps_json($json);
+is(scalar($maps->@*), 2, 'both maps parsed');
+
+my ($a, $b) = $maps->@*;
+is($a->{wwid}, '3600140500a1b2c3d4e5f6a7b8c9d0e1f', 'map keyed on the daemon uuid');
+is($a->{health}, 'optimal', 'all paths active is optimal');
+is($a->{'paths-active'}, 2, 'active path count');
+is($a->{'paths-total'}, 2, 'total path count');
+is($a->{'path-groups'}->[0]->{paths}->[0]->{transport}, 'fc', 'a target WWPN means FC');
+is($a->{'path-groups'}->[0]->{paths}->[0]->{'host-wwpn'}, '0x21000024ff7d6a1c', 'host WWPN kept');
+
+is($b->{health}, 'degraded', 'a failed path makes the map degraded');
+is($b->{'path-faults'}, 3, 'a string number is accepted');
+ok(!exists $b->{'path-groups'}->[0]->{paths}->[0]->{'target-wwpn'}, "'[undef]' is dropped");
+ok(!exists $b->{'path-groups'}->[0]->{paths}->[0]->{transport}, "'[undef]' does not imply FC");
+is($b->{'path-groups'}->[1]->{'dm-state'}, 'enabled', 'group state kept');
+
+is(PVE::RS::Multipath::derive_health(2, 2, undef), 'optimal', 'health without expectation');
+is(PVE::RS::Multipath::derive_health(1, 1, 2), 'degraded', 'a removed path counts against it');
+is(PVE::RS::Multipath::derive_health(0, 2, undef), 'failed', 'no active path is failed');
+
+# raw command output with a UTF-8 alias and one with an invalid byte, then the same reply decoded
+my $raw = qq({ "maps": [ { "name": "lun-\xc3\xa9", "uuid": "3600a", "path_groups": [] },
+    { "name": "bad-\xff", "uuid": "3600b", "path_groups": [] } ] });
+my $raw_maps = PVE::RS::Multipath::parse_maps_json($raw);
+is($raw_maps->[0]->{name}, "lun-\x{e9}", 'a UTF-8 alias in raw output is decoded');
+is($raw_maps->[1]->{name}, "bad-\x{fffd}", 'an invalid byte does not fail the reply');
+my $decoded = $raw =~ s/\xff//r;
+utf8::decode($decoded);
+is(PVE::RS::Multipath::parse_maps_json($decoded)->[0]->{name}, "lun-\x{e9}", 'decoded input');
+
+eval { PVE::RS::Multipath::parse_maps_json('not json') };
+like($@, qr/could not parse multipathd maps JSON/, 'invalid input dies with a clear error');
+
+done_testing();
-- 
2.47.3