Add integration tests, lib refactor, MIT license, and CI

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - name: cargo test
+        run: cargo test --verbose
+
+      - name: cargo clippy
+        run: cargo clippy -- -D warnings

Cargo.toml

@@ -3,9 +3,20 @@ name = "blockdiff"
 version = "0.1.0"
 edition = "2021"
 
+[lib]
+name = "blockdiff"
+path = "src/lib.rs"
+
+[[bin]]
+name = "blockdiff"
+path = "src/main.rs"
+
 [dependencies]
 fiemap = "0.1.1"
 nix = "0.26.0"
 clap = { version = "4.4", features = ["derive"] }
 serde = { version = "1.0", features = ["derive"] }
 bincode = "1.3"
+
+[dev-dependencies]
+tempfile = "3.14"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cognition AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -2,6 +2,23 @@
 
 Fast block-level file diffs (e.g. for VM disk images) using CoW filesystem metadata
 
+Check out the technical writeup [here](https://cognition.ai/blog/blockdiff).
+
+## Requirements
+
+- **Linux only** — uses `fiemap` and `copy_file_range` (ext4/xfs/btrfs, etc.)
+- Rust 1.70+
+
+## Build & test
+
+```bash
+cargo build --release
+cargo test
+cargo clippy -- -D warnings
+```
+
+Integration tests exercise `create → apply` roundtrips on a Linux filesystem with fiemap support.
+
 ## Usage
 
 ### File snapshots

src/lib.rs

@@ -0,0 +1,145 @@
+use serde::{Deserialize, Serialize};
+use std::io::{Error, Read, Write};
+
+/// Magic string for bdiff files ("BDIFFv1\0")
+pub const MAGIC: &[u8; 8] = b"BDIFFv1\0";
+
+/// Standard block size used for alignment (4 KiB)
+pub const BLOCK_SIZE: usize = 4096;
+
+/// Represents a range in the target file that's different from the base file.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DiffRange {
+    pub logical_offset: u64,
+    pub length: u64,
+}
+
+/// Header for a `.bdiff` file.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BDiffHeader {
+    pub magic: [u8; 8],
+    pub target_size: u64,
+    pub base_size: u64,
+    pub ranges: Vec<DiffRange>,
+}
+
+impl BDiffHeader {
+    pub fn new(target_size: u64, base_size: u64, ranges: Vec<DiffRange>) -> Self {
+        Self {
+            magic: *MAGIC,
+            target_size,
+            base_size,
+            ranges,
+        }
+    }
+
+    pub fn write_to(&self, writer: impl Write) -> Result<(), Error> {
+        bincode::serialize_into(writer, self).map_err(|e| Error::new(std::io::ErrorKind::Other, e))
+    }
+
+    pub fn read_from(reader: impl Read) -> Result<Self, Error> {
+        let header: Self =
+            bincode::deserialize_from(reader).map_err(|e| Error::new(std::io::ErrorKind::Other, e))?;
+
+        if header.magic != *MAGIC {
+            return Err(Error::new(
+                std::io::ErrorKind::InvalidData,
+                "Invalid bdiff file format",
+            ));
+        }
+
+        Ok(header)
+    }
+
+    pub fn serialized_size(&self) -> Result<usize, Error> {
+        bincode::serialized_size(self)
+            .map(|size| size as usize)
+            .map_err(|e| Error::new(std::io::ErrorKind::Other, e))
+    }
+}
+
+/// Zero-padding bytes needed to align a serialized header to `BLOCK_SIZE`.
+pub fn block_padding_size(serialized_header_len: usize) -> usize {
+    (BLOCK_SIZE - (serialized_header_len % BLOCK_SIZE)) % BLOCK_SIZE
+}
+
+pub fn format_size(bytes: u64) -> String {
+    const UNITS: [&str; 6] = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+
+    if bytes == 0 {
+        return "0 B".to_string();
+    }
+
+    let exp = (bytes as f64).ln() / 1024_f64.ln();
+    let exp = exp.floor() as usize;
+    let exp = exp.min(UNITS.len() - 1);
+
+    let bytes = bytes as f64 / (1024_u64.pow(exp as u32) as f64);
+
+    if exp == 0 {
+        format!("{} {}", bytes.round(), UNITS[exp])
+    } else {
+        format!("{:.1} {}", bytes, UNITS[exp])
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Cursor;
+
+    #[test]
+    fn block_padding_size_aligns_to_block_boundary() {
+        assert_eq!(block_padding_size(0), 0);
+        assert_eq!(block_padding_size(1), BLOCK_SIZE - 1);
+        assert_eq!(block_padding_size(BLOCK_SIZE), 0);
+        assert_eq!(block_padding_size(BLOCK_SIZE + 1), BLOCK_SIZE - 1);
+    }
+
+    #[test]
+    fn format_size_units() {
+        assert_eq!(format_size(0), "0 B");
+        assert_eq!(format_size(512), "512 B");
+        assert_eq!(format_size(1024), "1.0 KiB");
+        assert_eq!(format_size(1536), "1.5 KiB");
+    }
+
+    #[test]
+    fn header_roundtrip_preserves_fields() {
+        let header = BDiffHeader::new(
+            8192,
+            4096,
+            vec![DiffRange {
+                logical_offset: 4096,
+                length: 4096,
+            }],
+        );
+
+        let mut buffer = Vec::new();
+        header.write_to(&mut buffer).unwrap();
+
+        let restored = BDiffHeader::read_from(Cursor::new(buffer)).unwrap();
+        assert_eq!(restored, header);
+    }
+
+    #[test]
+    fn header_rejects_invalid_magic() {
+        let bad = BDiffHeader::new(1, 1, vec![]);
+        let mut bad = bad;
+        bad.magic = *b"NOTBDIFF";
+
+        let mut buffer = Vec::new();
+        bad.write_to(&mut buffer).unwrap();
+
+        let err = BDiffHeader::read_from(Cursor::new(buffer)).unwrap_err();
+        assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
+    }
+
+    #[test]
+    fn padding_plus_header_is_block_aligned() {
+        let header = BDiffHeader::new(1_048_576, 1_048_576, vec![]);
+        let header_size = header.serialized_size().unwrap();
+        let padding = block_padding_size(header_size);
+        assert_eq!((header_size + padding) % BLOCK_SIZE, 0);
+    }
+}