feat(kvp): add store trait and Hyper-V KVP storage crate

Cargo.toml

@@ -50,6 +50,7 @@ path = "tests/functional_tests.rs"
 [workspace]
 members = [
     "libazureinit",
+    "libazureinit-kvp",
 ]
 
 [features]

libazureinit-kvp/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "libazureinit-kvp"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.88"
+repository = "https://github.com/Azure/azure-init/"
+homepage = "https://github.com/Azure/azure-init/"
+license = "MIT"
+description = "Hyper-V KVP (Key-Value Pair) storage library for azure-init."
+
+[dependencies]
+libc = "0.2"
+tracing = "0.1.40"
+
+[dev-dependencies]
+rstest = { version = "0.23", default-features = false }
+tempfile = "3"
+
+[lib]
+name = "libazureinit_kvp"
+path = "src/lib.rs"

libazureinit-kvp/src/error.rs

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use std::fmt;
+use std::io;
+
+/// Errors returned by [`KvpPoolStore`](crate::KvpPoolStore) operations.
+#[derive(Debug)]
+pub enum KvpError {
+    /// The key was empty.
+    EmptyKey,
+    /// An underlying I/O error.
+    Io(io::Error),
+    /// The key contains a null byte, which is incompatible with the
+    /// on-disk format (null-padded fixed-width fields).
+    KeyContainsNull,
+    /// The key exceeds the store's maximum key size.
+    KeyTooLarge { max: usize, actual: usize },
+    /// The store already has the maximum allowed number of unique keys.
+    MaxUniqueKeysExceeded { max: usize },
+    /// The value exceeds the store's maximum value size.
+    ValueTooLarge { max: usize, actual: usize },
+    /// The value contains a null byte, which is incompatible with the
+    /// null-padded KVP wire format.
+    ValueContainsNull,
+}
+
+impl fmt::Display for KvpError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::EmptyKey => write!(f, "KVP key must not be empty"),
+            Self::Io(e) => write!(f, "{e}"),
+            Self::KeyContainsNull => {
+                write!(f, "KVP key must not contain null bytes")
+            }
+            Self::KeyTooLarge { max, actual } => {
+                write!(f, "KVP key length ({actual}) exceeds maximum ({max})")
+            }
+            Self::MaxUniqueKeysExceeded { max } => {
+                write!(f, "KVP unique key count exceeded maximum ({max})")
+            }
+            Self::ValueTooLarge { max, actual } => {
+                write!(f, "KVP value length ({actual}) exceeds maximum ({max})")
+            }
+            Self::ValueContainsNull => {
+                write!(f, "KVP value must not contain null bytes")
+            }
+        }
+    }
+}
+
+impl std::error::Error for KvpError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Io(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+impl From<io::Error> for KvpError {
+    fn from(err: io::Error) -> Self {
+        Self::Io(err)
+    }
+}

libazureinit-kvp/src/lib.rs

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! `libazureinit-kvp` provides a unified KVP pool file store for
+//! Hyper-V/Azure guests.
+//!
+//! - [`KvpPoolStore`]: KVP pool file store with
+//!   [`PoolMode`]-based policy.
+
+mod error;
+mod store;
+
+pub use error::KvpError;
+pub use store::{KvpPool, KvpPoolStore, PoolMode};