[antlir2][cad_stack] content-based tracking of stacks of objects

Summary:
Build a new library crate `cad_stack` that is a simple object storage mechanism
that uses a stack of directories as the store backend with only the top being
mutable.

This crate is generic, but is meant to serve as a friendly storage mechanism to
bridge the gap between how buck2/RE stores action inputs+outputs and how
antlir2 needs to have full BTRFS subvolumes that have historically been
snapshots of other local-only subvolumes.

The following diff stack uses this to build an RE-capable image build backend.

Test Plan:
```
❯ buck2 test fbcode//antlir/antlir2/cad_stack/...
Buck UI: https://www.internalfb.com/buck2/ff7a9cd6-94e6-470b-af77-5ddbaa20c796
Tests finished: Pass 6. Fail 0. Fatal 0. Skip 0. Omit 0. Infra Failure 0. Build failure 0
```
https://www.internalfb.com/intern/testinfra/testrun/11540474199761526

Reviewed By: sergeyfd

Differential Revision: D92884086

fbshipit-source-id: c8540aa724a9cc9d5416297aafc166d6fa8ea05f

Author: vmagro

antlir/antlir2/cad_stack/BUCK

@@ -0,0 +1,17 @@
+load("//antlir/bzl:build_defs.bzl", "rust_library")
+
+oncall("antlir")
+
+rust_library(
+    name = "cad_stack",
+    srcs = glob(["src/**/*.rs"]),
+    test_deps = ["tempfile"],
+    deps = [
+        "blake3",
+        "cap-std",
+        "nonempty",
+        "serde",
+        "serde_json",
+        "thiserror",
+    ],
+)

antlir/antlir2/cad_stack/src/checksum.rs

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+use std::fmt::Debug;
+use std::marker::PhantomData;
+
+use serde::Deserialize;
+use serde::Serialize;
+
+use crate::Object;
+use crate::Result;
+
+/// All [Object]s are uniquely identified by a [Checksum]
+pub struct Checksum<T: Object> {
+    hash: blake3::Hash,
+    _phantom: PhantomData<fn() -> T>,
+}
+
+// Manual Copy/Clone impls to avoid unnecessary `T: Copy/Clone` bounds
+// that #[derive] would add. The fields (blake3::Hash and PhantomData) are
+// unconditionally Copy regardless of T.
+impl<T: Object> Copy for Checksum<T> {}
+
+impl<T: Object> Clone for Checksum<T> {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl<T: Object> PartialEq<Checksum<T>> for Checksum<T> {
+    fn eq(&self, other: &Checksum<T>) -> bool {
+        self.hash == other.hash
+    }
+}
+
+impl<T: Object> Eq for Checksum<T> {}
+
+impl<T: Object> std::hash::Hash for Checksum<T> {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.hash.hash(state);
+    }
+}
+
+impl<T: Object> Checksum<T> {
+    pub fn new(hash: blake3::Hash) -> Self {
+        Self {
+            hash,
+            _phantom: PhantomData,
+        }
+    }
+
+    pub(crate) fn hex(&self) -> String {
+        self.hash.to_hex().to_string()
+    }
+}
+
+impl<T: Object> Debug for Checksum<T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_tuple(&format!("Checksum<{}>", std::any::type_name::<T>()))
+            .field(&self.hash.to_hex())
+            .finish()
+    }
+}
+
+impl<'de, T: Object> Deserialize<'de> for Checksum<T> {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let hex = String::deserialize(deserializer)?;
+        let hash = blake3::Hash::from_hex(hex)
+            .map_err(|e| serde::de::Error::custom(format!("invalid hash: {e}")))?;
+        Ok(Self {
+            hash,
+            _phantom: PhantomData,
+        })
+    }
+}
+
+impl<T: Object> Serialize for Checksum<T> {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(&self.hash.to_hex())
+    }
+}

antlir/antlir2/cad_stack/src/lib.rs

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+mod checksum;
+mod object;
+mod object_store;
+
+pub use checksum::Checksum;
+pub use object::Object;
+pub use object_store::ObjectStore;
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("no such object '{0}'")]
+    NotFound(String),
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+    #[error(transparent)]
+    Json(#[from] serde_json::Error),
+}
+
+pub type Result<T, E = Error> = std::result::Result<T, E>;
+
+#[doc(hidden)]
+pub mod __deps {
+    pub use serde_json;
+}

antlir/antlir2/cad_stack/src/object.rs

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+use std::fs::File;
+
+use crate::Checksum;
+use crate::Result;
+
+pub trait Object: Sized {
+    fn from_file(file: File) -> Result<Self>;
+
+    fn to_file(&self, file: &mut File) -> Result<()>;
+
+    fn checksum(&self) -> Result<Checksum<Self>>;
+}
+
+#[macro_export]
+macro_rules! json_object {
+    ($t:ty) => {
+        impl $crate::Object for $t {
+            fn from_file(file: std::fs::File) -> $crate::Result<Self> {
+                $crate::__deps::serde_json::from_reader(std::io::BufReader::new(file))
+                    .map_err($crate::Error::from)
+            }
+
+            fn to_file(&self, file: &mut std::fs::File) -> $crate::Result<()> {
+                use std::io::Write;
+                let mut w = std::io::BufWriter::new(file);
+                $crate::__deps::serde_json::to_writer_pretty(&mut w, &self)
+                    .map_err($crate::Error::from)?;
+                w.flush().map_err($crate::Error::from)
+            }
+
+            fn checksum(&self) -> $crate::Result<$crate::Checksum<Self>> {
+                let bytes = $crate::__deps::serde_json::to_vec_pretty(&self)?;
+                Ok($crate::Checksum::new(blake3::hash(&bytes)))
+            }
+        }
+    };
+}