feat(api): reflection types for hardlink types

Author: KSXGitHub

src/hardlink/hardlink_list.rs

@@ -1,10 +1,18 @@
+pub mod reflection;
+
+pub use reflection::Reflection;
+
 use crate::{hardlink::LinkPathList, inode::InodeNumber, size};
 use dashmap::{iter::Iter as DashIter, mapref::multiple::RefMulti, DashMap};
 use derive_more::{Display, Error};
 use pipe_trait::Pipe;
 use std::{fmt::Debug, path::Path};
 
 /// Storage to be used by [`crate::hook::RecordHardlink`].
+///
+/// **Serialization and deserialization:** _(feature: `json`)_ `HardlinkList` does not implement
+/// `Serialize` and `Deserialize` traits directly, instead, it can be converted into/from a
+/// [`Reflection`] which implements these traits.
 #[derive(Debug, Clone)]
 pub struct HardlinkList<Size>(
     /// Map an inode number to its size and detected paths.

src/hardlink/hardlink_list/reflection.rs

@@ -0,0 +1,65 @@
+use super::HardlinkList;
+use crate::{
+    hardlink::{link_path_list, LinkPathList},
+    inode::InodeNumber,
+};
+use dashmap::DashMap;
+use derive_more::{From, Into, IntoIterator};
+use pipe_trait::Pipe;
+use std::collections::HashMap;
+
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+
+/// Intermediate format used for construction and inspection of
+/// [`HardlinkList`]'s internal content.
+///
+/// **Serialization and deserialization:** _(feature: `json`)_ `Reflection` implements
+/// `Serialize` and `Deserialize` traits, this allows functions in `serde_json` to convert
+/// a `Reflection` into/from JSON.
+#[derive(Debug, Clone, PartialEq, Eq, From, Into, IntoIterator)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+pub struct Reflection<Size>(pub HashMap<InodeNumber, Value<Size>>);
+
+/// Size and list of link paths corresponding to an [`InodeNumber`] in [`Reflection`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+pub struct Value<Size> {
+    pub size: Size,
+    pub links: link_path_list::Reflection,
+}
+
+impl<Size> Value<Size> {
+    /// Create a new value.
+    fn new(size: Size, links: LinkPathList) -> Self {
+        let links = links.into();
+        Value { size, links }
+    }
+
+    /// Convert the internal [`link_path_list::Reflection`] into a [`LinkPathList`].
+    fn into_list(self) -> (Size, LinkPathList) {
+        let Value { size, links } = self;
+        (size, links.into())
+    }
+}
+
+impl<Size> From<HardlinkList<Size>> for Reflection<Size> {
+    fn from(value: HardlinkList<Size>) -> Self {
+        value
+            .0
+            .into_iter()
+            .map(|(ino, (size, links))| (ino, Value::new(size, links)))
+            .collect::<HashMap<_, _>>()
+            .pipe(Reflection)
+    }
+}
+
+impl<Size> From<Reflection<Size>> for HardlinkList<Size> {
+    fn from(value: Reflection<Size>) -> Self {
+        value
+            .into_iter()
+            .map(|(ino, value)| (ino, value.into_list()))
+            .collect::<DashMap<_, _>>()
+            .pipe(HardlinkList)
+    }
+}

src/hardlink/link_path_list.rs

@@ -1,7 +1,15 @@
+mod reflection;
+
+pub use reflection::Reflection;
+
 use pipe_trait::Pipe;
 use std::{iter::FusedIterator, path::PathBuf, slice};
 
 /// List of different hardlinks to the same file.
+///
+/// **Serialization and deserialization:** _(feature: `json`)_ `LinkPathList` does not implement
+/// `Serialize` and `Deserialize` traits directly, instead, it can be converted into/from a
+/// [`Reflection`] which implements these traits.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct LinkPathList(
     Vec<PathBuf>, // TODO: benchmark against LinkedList<PathBuf>

src/hardlink/link_path_list/reflection.rs

@@ -0,0 +1,29 @@
+use super::LinkPathList;
+use derive_more::{From, Into, IntoIterator};
+use pipe_trait::Pipe;
+use std::{collections::HashSet, path::PathBuf};
+
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+
+/// Intermediate format used for construction and inspection of
+/// [`LinkPathList`]'s internal content.
+///
+/// **Serialization and deserialization:** _(feature: `json`)_ `Reflection` implements
+/// `Serialize` and `Deserialize` traits, this allows functions in `serde_json` to convert
+/// a `Reflection` into/from JSON.
+#[derive(Debug, Clone, PartialEq, Eq, From, Into, IntoIterator)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+pub struct Reflection(pub HashSet<PathBuf>);
+
+impl From<LinkPathList> for Reflection {
+    fn from(value: LinkPathList) -> Self {
+        value.0.into_iter().collect::<HashSet<_>>().pipe(Reflection)
+    }
+}
+
+impl From<Reflection> for LinkPathList {
+    fn from(value: Reflection) -> Self {
+        value.0.into_iter().collect::<Vec<_>>().pipe(LinkPathList)
+    }
+}

src/inode.rs

@@ -1,9 +1,13 @@
 use derive_more::{Display, From, Into, LowerHex, Octal, UpperHex};
 
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+
 /// The inode number of a file or directory.
 #[derive(
     Debug, Display, LowerHex, UpperHex, Octal, Clone, Copy, PartialEq, Eq, Hash, From, Into,
 )]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
 pub struct InodeNumber(u64);
 
 /// POSIX-exclusive functions.