Add crucible-verify-raw and crucible-raw-extent packages (#1800)

This PR extracts the `crucible-verify-raw` tool from #1791. The on-disk
data structures for raw extents are moved to a new `crucible-raw-extent`
package, which is used by both `crucible-downstairs` and
`crucible-verify-raw`.

Author: mkeeter

Cargo.lock

@@ -32,6 +32,8 @@ members = [
     "workspace-hack",
     "xtask",
     "agent-antagonist",
+    "verify-raw",
+    "raw-extent",
 ]
 resolver = "2"
 
@@ -155,6 +157,8 @@ crucible-pantry-api = { path = "./pantry-api" }
 crucible-pantry-client = { path = "./pantry-client" }
 crucible-pantry-types = { path = "./pantry-types" }
 crucible-protocol = { path = "./protocol" }
+crucible-raw-extent = { path = "./raw-extent" }
+crucible-verify-raw = { path = "./verify-raw" }
 crucible-smf = { path = "./smf" }
 dsc-client = { path = "./dsc-client" }
 repair-client = { path = "./repair-client" }

Cargo.toml

@@ -17,6 +17,7 @@ crucible-common.workspace = true
 crucible-downstairs-api.workspace = true
 crucible-downstairs-types.workspace = true
 crucible-protocol.workspace = true
+crucible-raw-extent.workspace = true
 dropshot.workspace = true
 futures-core.workspace = true
 futures.workspace = true
@@ -42,7 +43,6 @@ ringbuffer.workspace = true
 rusqlite.workspace = true
 schemars.workspace = true
 semver.workspace = true
-serde.workspace = true
 serde_json.workspace = true
 sha2.workspace = true
 slog-async.workspace = true

downstairs/Cargo.toml

@@ -6,7 +6,6 @@ use std::fs::File;
 use anyhow::{anyhow, bail, Result};
 use nix::unistd::{sysconf, SysconfVar};
 
-use serde::{Deserialize, Serialize};
 use tracing::instrument;
 
 use crate::region::JobOrReconciliationId;
@@ -135,7 +134,7 @@ pub enum ExtentState {
     Closed,
 }
 
-#[derive(Debug, Deserialize, Serialize)]
+#[derive(Debug)]
 pub struct ExtentMeta {
     /**
      * Version information regarding the extent structure.
@@ -471,7 +470,8 @@ impl Extent {
                 Box::new(inner)
             } else {
                 match extent_inner_raw_common::OnDiskMeta::get_version_tag(
-                    dir, number,
+                    &extent_path(dir, number),
+                    number,
                 )? {
                     EXTENT_META_RAW => {
                         Box::new(extent_inner_raw::RawInner::open(

downstairs/src/extent.rs

@@ -10,14 +10,13 @@ use crate::{
     },
     integrity_hash, mkdir_for_file,
     region::JobOrReconciliationId,
-    Block, BlockContext, CrucibleError, ExtentReadRequest, ExtentReadResponse,
-    ExtentWrite, JobId, RegionDefinition,
+    Block, CrucibleError, ExtentReadRequest, ExtentReadResponse, ExtentWrite,
+    JobId, RegionDefinition,
 };
 use crucible_common::ExtentId;
 use crucible_protocol::ReadBlockContext;
 
 use itertools::Itertools;
-use serde::{Deserialize, Serialize};
 use slog::{error, Logger};
 
 use std::collections::HashSet;
@@ -26,19 +25,10 @@ use std::io::{BufReader, Read};
 use std::os::fd::{AsFd, AsRawFd};
 use std::path::Path;
 
-/// Equivalent to `DownstairsBlockContext`, but without one's own block number
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-struct OnDiskDownstairsBlockContext {
-    block_context: BlockContext,
-    on_disk_hash: u64,
-    flush_id: u16,
-}
-
-/// Size of backup data
-///
-/// This must be large enough to fit an `Option<OnDiskDownstairsBlockContext>`
-/// serialized using `bincode`.
-pub const BLOCK_CONTEXT_SLOT_SIZE_BYTES: u64 = 48;
+// Re-exports
+pub use crucible_raw_extent::{
+    OnDiskDownstairsBlockContext, BLOCK_CONTEXT_SLOT_SIZE_BYTES,
+};
 
 /// Number of extra syscalls per read / write that triggers defragmentation
 const DEFRAGMENT_THRESHOLD: u64 = 3;
@@ -1609,7 +1599,7 @@ mod test {
     use anyhow::Result;
     use bytes::{Bytes, BytesMut};
     use crucible_common::BlockOffset;
-    use crucible_protocol::EncryptionContext;
+    use crucible_protocol::{BlockContext, EncryptionContext};
     use tempfile::tempdir;
 
     const IOV_MAX_TEST: usize = 1000;

downstairs/src/extent_inner_raw.rs

@@ -1,62 +1,7 @@
-use crate::{extent::extent_path, CrucibleError};
-use crucible_common::ExtentId;
-use serde::{Deserialize, Serialize};
-use std::fs::OpenOptions;
-use std::io::{Read, Seek, SeekFrom};
 use std::os::fd::AsFd;
-use std::path::Path;
 
-/// Equivalent to `ExtentMeta`, but ordered for efficient on-disk serialization
-///
-/// In particular, the `dirty` byte is first, so it's easy to read at a known
-/// offset within the file.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub(super) struct OnDiskMeta {
-    pub dirty: bool,
-    pub gen_number: u64,
-    pub flush_number: u64,
-    pub ext_version: u32,
-
-    // Extra data added for debugging purposes
-    pub bonus_sync_count: u32,
-    pub defrag_count: u32,
-}
-
-impl OnDiskMeta {
-    /// Looks up the version tag
-    ///
-    /// Across all of our raw file formats, `OnDiskMeta` is guaranteed to be
-    /// placed at the end of the file in a `BLOCK_META_SIZE_BYTES`-length chunk,
-    /// so we can get a tag without knowing anything else about the file.
-    pub fn get_version_tag(
-        dir: &Path,
-        extent_number: ExtentId,
-    ) -> Result<u32, CrucibleError> {
-        let path = extent_path(dir, extent_number);
-        let mut f = OpenOptions::new()
-            .read(true)
-            .write(false)
-            .open(&path)
-            .map_err(|e| {
-                CrucibleError::IoError(format!(
-                    "extent {extent_number}: open of {path:?} failed: {e}",
-                ))
-            })?;
-
-        let mut buf = [0u8; BLOCK_META_SIZE_BYTES as usize];
-        f.seek(SeekFrom::End(-(BLOCK_META_SIZE_BYTES as i64)))?;
-        f.read_exact(&mut buf)?;
-        let meta: OnDiskMeta = bincode::deserialize(&buf)
-            .map_err(|e| CrucibleError::BadMetadata(e.to_string()))?;
-        Ok(meta.ext_version)
-    }
-}
-
-/// Size of metadata region
-///
-/// This must be large enough to contain an `OnDiskMeta` serialized using
-/// `bincode`.
-pub(super) const BLOCK_META_SIZE_BYTES: u64 = 32;
+// Re-export from `crucible_raw_extent`
+pub use crucible_raw_extent::{OnDiskMeta, BLOCK_META_SIZE_BYTES};
 
 /// Call `pread` repeatedly to read an entire buffer
 ///

downstairs/src/extent_inner_raw_common.rs

@@ -0,0 +1,12 @@
+[package]
+name = "crucible-raw-extent"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+serde.workspace = true
+crucible-common.workspace = true
+crucible-protocol.workspace = true
+bincode.workspace = true
+
+crucible-workspace-hack.workspace = true

raw-extent/Cargo.toml

@@ -0,0 +1,74 @@
+//! Data and on-disk structures for raw extent files
+use crucible_common::{CrucibleError, ExtentId};
+use crucible_protocol::BlockContext;
+use serde::{Deserialize, Serialize};
+use std::{
+    fs::OpenOptions,
+    io::{Read, Seek, SeekFrom},
+    path::Path,
+};
+
+/// Equivalent to `ExtentMeta`, but ordered for efficient on-disk serialization
+///
+/// In particular, the `dirty` byte is first, so it's easy to read at a known
+/// offset within the file.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OnDiskMeta {
+    pub dirty: bool,
+    pub gen_number: u64,
+    pub flush_number: u64,
+    pub ext_version: u32,
+
+    // Extra data added for debugging purposes
+    pub bonus_sync_count: u32,
+    pub defrag_count: u32,
+}
+
+impl OnDiskMeta {
+    /// Looks up the version tag
+    ///
+    /// Across all of our raw file formats, `OnDiskMeta` is guaranteed to be
+    /// placed at the end of the file in a `BLOCK_META_SIZE_BYTES`-length chunk,
+    /// so we can get a tag without knowing anything else about the file.
+    pub fn get_version_tag(
+        path: &Path,
+        extent_number: ExtentId,
+    ) -> Result<u32, CrucibleError> {
+        let mut f = OpenOptions::new()
+            .read(true)
+            .write(false)
+            .open(path)
+            .map_err(|e| {
+                CrucibleError::IoError(format!(
+                    "extent {extent_number}: open of {path:?} failed: {e}",
+                ))
+            })?;
+
+        let mut buf = [0u8; BLOCK_META_SIZE_BYTES as usize];
+        f.seek(SeekFrom::End(-(BLOCK_META_SIZE_BYTES as i64)))?;
+        f.read_exact(&mut buf)?;
+        let meta: OnDiskMeta = bincode::deserialize(&buf)
+            .map_err(|e| CrucibleError::BadMetadata(e.to_string()))?;
+        Ok(meta.ext_version)
+    }
+}
+
+/// Size of metadata region
+///
+/// This must be large enough to contain an `OnDiskMeta` serialized using
+/// `bincode`.
+pub const BLOCK_META_SIZE_BYTES: u64 = 32;
+
+/// Equivalent to `DownstairsBlockContext`, but without one's own block number
+#[derive(Debug, Copy, Clone, Serialize, Deserialize, PartialEq)]
+pub struct OnDiskDownstairsBlockContext {
+    pub block_context: BlockContext,
+    pub on_disk_hash: u64,
+    pub flush_id: u16,
+}
+
+/// Size of backup data
+///
+/// This must be large enough to fit an `Option<OnDiskDownstairsBlockContext>`
+/// serialized using `bincode`.
+pub const BLOCK_CONTEXT_SLOT_SIZE_BYTES: u64 = 48;

raw-extent/src/lib.rs

@@ -0,0 +1,14 @@
+[package]
+name = "crucible-verify-raw"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+anyhow.workspace = true
+bincode.workspace = true
+clap.workspace = true
+crucible-common.workspace = true
+crucible-raw-extent.workspace = true
+serde.workspace = true
+
+crucible-workspace-hack.workspace = true