feat(checkpoint)!: hard-link snapshot for PITR backup (V5 storage)

src/abstract_tree.rs

@@ -15,6 +15,27 @@ pub type RangeItem = crate::Result<KvPair>;
 
 type FlushToTablesResult = (Vec<Table>, Option<Vec<BlobFile>>);
 
+/// Summary of a checkpoint produced by
+/// [`AbstractTree::create_checkpoint`].
+///
+/// All byte counts are *logical* file sizes — hard links share the
+/// underlying inode storage, so a checkpoint's marginal disk usage is
+/// typically zero until the original files are compacted away.
+#[derive(Debug, Clone, Copy)]
+pub struct CheckpointInfo {
+    /// Number of SST files captured.
+    pub sst_files: usize,
+    /// Number of blob (value-log) files captured. Always `0` for a
+    /// standard [`Tree`].
+    pub blob_files: usize,
+    /// Sum of the logical file sizes of every captured SST + blob.
+    pub total_bytes: u64,
+    /// The version ID embedded in the checkpoint's `current` pointer.
+    pub version_id: u64,
+    /// The maximum visible sequence number at checkpoint time.
+    pub seqno: SeqNo,
+}
+
 // Sealed on purpose: this trait is still public as a consumer-side bound
 // (`&impl AbstractTree`), but external implementations are no longer part of
 // the supported extension surface. Internal flush/version hooks keep evolving
@@ -62,6 +83,56 @@ pub trait AbstractTree: sealed::Sealed {
     #[doc(hidden)]
     fn get_version_history_lock(&self) -> RwLockWriteGuard<'_, crate::version::SuperVersions>;
 
+    /// Creates a hard-linked checkpoint of the tree's on-disk state in
+    /// `target_path` for point-in-time recovery (PITR) backup.
+    ///
+    /// The checkpoint is a fully functional tree that can be opened
+    /// independently via [`Config::open`](crate::Config::open). For the
+    /// common single-filesystem case all SST files (and blob files, for
+    /// [`BlobTree`]) are hard-linked rather than copied, so the operation
+    /// is O(1) per file and consumes zero additional disk space until the
+    /// original files are compacted away — at which point the inode is
+    /// kept alive by the checkpoint link.
+    ///
+    /// # Cross-filesystem / cross-backend fall-back
+    ///
+    /// When a source file lives on a different filesystem than the
+    /// checkpoint target — e.g. an SST routed to a hot tier via
+    /// [`level_routes`](crate::Config::level_routes) on a separate volume,
+    /// or a backup directory on a foreign mount — the hard link cannot
+    /// be created (Unix `EXDEV`). In that case the checkpoint silently
+    /// falls back to a streamed byte copy, which:
+    ///
+    /// - takes time linear in the file size instead of O(1), and
+    /// - consumes disk space equal to the copied bytes on the target
+    ///   volume (no inode sharing across filesystems).
+    ///
+    /// The fall-back is logged via [`log::warn`] so operators using
+    /// tiered storage or detached backup volumes can spot it. Same applies
+    /// when the source and target use entirely different [`Fs`](crate::fs::Fs)
+    /// backends (e.g. [`MemFs`](crate::fs::MemFs) → [`StdFs`](crate::fs::StdFs)
+    /// in tests).
+    ///
+    /// # Concurrency
+    ///
+    /// While the checkpoint is being built, compaction continues normally
+    /// but the physical removal of obsolete files is deferred until the
+    /// checkpoint hard-links are in place. This is implemented by an
+    /// internal reference-counted deletion gate; callers do not have to
+    /// pause compaction themselves.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - the active memtable could not be flushed,
+    /// - `target_path` already exists (to prevent accidental overwrites),
+    /// - a hard link / copy fall-back could not be created, or
+    /// - the manifest / version pointer files could not be replicated.
+    ///
+    /// On error any partial checkpoint files are removed automatically
+    /// (best-effort) so callers can safely retry against the same path.
+    fn create_checkpoint(&self, target_path: &std::path::Path) -> crate::Result<CheckpointInfo>;
+
     /// Seals the active memtable and flushes to table(s).
     ///
     /// If there are already other sealed memtables lined up, those will be flushed as well.

src/blob_tree/mod.rs

@@ -225,6 +225,24 @@ impl BlobTree {
 impl crate::abstract_tree::sealed::Sealed for BlobTree {}
 
 impl AbstractTree for BlobTree {
+    fn create_checkpoint(
+        &self,
+        target_path: &std::path::Path,
+    ) -> crate::Result<crate::CheckpointInfo> {
+        crate::checkpoint::run_checkpoint(
+            self,
+            &crate::checkpoint::CheckpointParams {
+                target_root: target_path,
+                target_fs: &self.index.config.fs,
+                src_root: &self.index.config.path,
+                src_fs: &self.index.config.fs,
+                deletion_pause: &self.index.deletion_pause,
+                visible_seqno: &self.index.config.visible_seqno,
+                include_blobs: true,
+            },
+        )
+    }
+
     fn print_trace(&self, key: &[u8]) -> crate::Result<()> {
         self.index.print_trace(key)
     }