oci: Add containers-storage integration with zero-copy import

Add a native containers-storage import path that bypasses skopeo's
tar streaming by reading layer content directly from the overlay diff
directories and using reflink/hardlink to avoid data copies.

The import path is gated by a new LocalFetchOpt enum on PullOptions:
- Disabled (default): fall through to skopeo like any other transport
- IfPossible: use native import with reflink/hardlink/copy fallback
- ZeroCopy: use native import but error if zero-copy is not possible

This is exposed via `cfsctl oci pull --local-fetch disabled|auto|zerocopy`.

The hardlink path enables fs-verity on source files in-place (permanent,
irreversible) and requires CAP_DAC_READ_SEARCH for linkat(AT_EMPTY_PATH);
try_hardlink_object now checks this upfront with a clear error message.

Integration tests cover the full {ext4,xfs} x {sha256,sha512} x
{auto,zerocopy} matrix using synthetic OCI images on loopback
filesystems.

Assisted-by: OpenCode (Claude Opus 4)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

.config/nextest.toml

@@ -14,6 +14,11 @@ failure-output = "immediate"
 success-output = "never"
 status-level = "pass"
 
+# Tests that pull OCI images need more time (especially on cold CI runners)
+[[profile.default.overrides]]
+filter = 'test(/digest_stability|oci_pull/)'
+slow-timeout = { period = "300s", terminate-after = 2 }
+
 # Profile for integration tests — run with limited parallelism due to QEMU/KVM resources
 [profile.integration]
 test-threads = 2
@@ -30,7 +35,12 @@ path = "junit.xml"
 store-success-output = true
 store-failure-output = true
 
-# VM tests boot an ephemeral QEMU instance per test, limit parallelism
+# Privileged tests boot an ephemeral QEMU instance per test — limit
+# parallelism to avoid OOM kills on 16 GB CI runners.
+# Requiring all 2 threads effectively serialises them.
+#
+# NOTE: use /regex/ syntax, not ~substring — the ~ operator treats ^ $ as
+# literal characters, so ~^foo never matches anything.
 [[profile.integration.overrides]]
-filter = 'test(~^vm_)'
-threads-required = 4
+filter = 'test(/^privileged_/)'
+threads-required = 2

.github/workflows/ci.yml

@@ -51,6 +51,7 @@ jobs:
       - uses: actions/checkout@v6
       - uses: bootc-dev/actions/bootc-ubuntu-setup@main
       - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@nextest
       - uses: Swatinem/rust-cache@v2
       - run: just test-integration
 
@@ -114,6 +115,7 @@ jobs:
           libvirt: true
 
       - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@nextest
 
       - uses: Swatinem/rust-cache@v2
 

Cargo.toml

@@ -1,5 +1,21 @@
 [workspace]
 members = ["crates/*"]
+# Exclude integration-tests from default `cargo test` — those require a
+# built cfsctl binary and (for privileged tests) a VM.  Run them via
+# `just test-integration` or `just test-integration-vm` instead.
+default-members = [
+    "crates/cfsctl",
+    "crates/composefs",
+    "crates/composefs-boot",
+    "crates/composefs-fuse",
+    "crates/composefs-http",
+    "crates/composefs-ioctls",
+    "crates/composefs-oci",
+    "crates/composefs-setup-root",
+    "crates/cstorage",
+    "crates/erofs-debug",
+    "crates/splitfdstream",
+]
 resolver = "2"
 
 [workspace.package]

Justfile

@@ -58,18 +58,37 @@ cfsctl_features := env("COMPOSEFS_CFSCTL_FEATURES", "pre-6.15")
 _test_image := if base_image =~ "debian" { "localhost/composefs-rs-test-debian:latest" } else if base_image =~ "stream9" { "localhost/composefs-rs-test-c9s:latest" } else { "localhost/composefs-rs-test:latest" }
 
 # Run unprivileged integration tests against the cfsctl binary (no root, no VM)
-test-integration: build
-    CFSCTL_PATH=$(pwd)/target/debug/cfsctl cargo run -p integration-tests --bin cfsctl-integration-tests -- --skip privileged_
+# Prefers nextest for parallelism control and better UX; falls back to direct harness.
+test-integration *ARGS: build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    export CFSCTL_PATH=$(pwd)/target/debug/cfsctl
+    if command -v cargo-nextest &> /dev/null; then
+        cargo nextest run -p integration-tests -E 'not test(/^privileged_/)' {{ ARGS }}
+    else
+        cargo test -p integration-tests --test cfsctl-integration-tests -- --skip privileged_ {{ ARGS }}
+    fi
 
 # Build the test container image for VM-based integration tests
 _integration-container-build:
     podman build --build-arg base_image={{base_image}} --build-arg cfsctl_features={{cfsctl_features}} -t {{_test_image}} .
 
 # Run all integration tests including privileged VM tests (requires podman + libvirt)
-test-integration-vm: build _integration-container-build
-    COMPOSEFS_TEST_IMAGE={{_test_image}} \
-        CFSCTL_PATH=$(pwd)/target/debug/cfsctl \
-        cargo run -p integration-tests --bin cfsctl-integration-tests
+# Uses nextest with the integration profile for parallelism control of VM tests.
+test-integration-vm *ARGS: build _integration-container-build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    export COMPOSEFS_TEST_IMAGE={{_test_image}}
+    export CFSCTL_PATH=$(pwd)/target/debug/cfsctl
+    if command -v cargo-nextest &> /dev/null; then
+        cargo nextest run -P integration -p integration-tests {{ ARGS }}
+    else
+        cargo test -p integration-tests --test cfsctl-integration-tests -- {{ ARGS }}
+    fi
+
+# Install cargo-nextest if not already installed
+install-nextest:
+    @which cargo-nextest > /dev/null 2>&1 || cargo install cargo-nextest --locked
 
 # Run everything: checks + full integration tests including VM
 ci: check test-integration-vm

crates/cfsctl/Cargo.toml

@@ -14,9 +14,10 @@ version.workspace = true
 path = "src/lib.rs"
 
 [features]
-default = ['pre-6.15', 'oci']
+default = ['pre-6.15', 'oci', 'containers-storage']
 http = ['composefs-http']
 oci = ['composefs-oci']
+containers-storage = ['composefs-oci/containers-storage', 'cstorage']
 rhel9 = ['composefs/rhel9']
 'pre-6.15' = ['composefs/pre-6.15']
 
@@ -29,8 +30,10 @@ composefs = { workspace = true }
 composefs-boot = { workspace = true }
 composefs-oci = { workspace = true, optional = true, features = ["boot"] }
 composefs-http = { workspace = true, optional = true }
+cstorage = { path = "../cstorage", version = "0.3.0", features = ["userns-helper"], optional = true }
 env_logger = { version = "0.11.0", default-features = false }
 hex = { version = "0.4.0", default-features = false }
+indicatif = { version = "0.17.0", default-features = false }
 rustix = { version = "1.0.0", default-features = false, features = ["fs", "process"] }
 serde = { version = "1.0", default-features = false, features = ["derive"] }
 serde_json = { version = "1.0", default-features = false, features = ["std"] }

crates/cfsctl/src/lib.rs

@@ -170,6 +170,30 @@ impl std::fmt::Display for OciReference {
     }
 }
 
+/// CLI representation of [`composefs_oci::LocalFetchOpt`].
+#[cfg(feature = "oci")]
+#[derive(Debug, Clone, Copy, Default, clap::ValueEnum)]
+enum LocalFetchCli {
+    /// Do not use native containers-storage import; use skopeo.
+    #[default]
+    Disabled,
+    /// Use native import with reflink/hardlink/copy fallback.
+    Auto,
+    /// Use native import; error if zero-copy is not possible.
+    Zerocopy,
+}
+
+#[cfg(feature = "oci")]
+impl From<LocalFetchCli> for composefs_oci::LocalFetchOpt {
+    fn from(cli: LocalFetchCli) -> Self {
+        match cli {
+            LocalFetchCli::Disabled => Self::Disabled,
+            LocalFetchCli::Auto => Self::IfPossible,
+            LocalFetchCli::Zerocopy => Self::ZeroCopy,
+        }
+    }
+}
+
 /// Common options for operations using OCI config manifest streams that may transform the image rootfs
 #[cfg(feature = "oci")]
 #[derive(Debug, Parser)]
@@ -226,6 +250,10 @@ enum OciCommand {
         /// Also generate a bootable EROFS image from the pulled OCI image
         #[arg(long)]
         bootable: bool,
+        /// Controls whether containers-storage: references use the native
+        /// import path with zero-copy reflink/hardlink support.
+        #[arg(long, value_enum, default_value_t = LocalFetchCli::Disabled)]
+        local_fetch: LocalFetchCli,
     },
     /// List all tagged OCI images in the repository
     #[clap(name = "images")]
@@ -925,23 +953,23 @@ where
                 ref image,
                 name,
                 bootable,
+                local_fetch,
             } => {
                 // If no explicit name provided, use the image reference as the tag
                 let tag_name = name.as_deref().unwrap_or(image);
-                let (result, stats) =
-                    composefs_oci::pull_image(&repo, image, Some(tag_name), None).await?;
+
+                let opts = composefs_oci::PullOptions {
+                    local_fetch: local_fetch.into(),
+                    ..Default::default()
+                };
+
+                let result = composefs_oci::pull(&repo, image, Some(tag_name), opts).await?;
 
                 println!("manifest {}", result.manifest_digest);
                 println!("config   {}", result.config_digest);
                 println!("verity   {}", result.manifest_verity.to_hex());
                 println!("tagged   {tag_name}");
-                println!(
-                    "objects  {} copied, {} already present, {} bytes copied, {} bytes inlined",
-                    stats.objects_copied,
-                    stats.objects_already_present,
-                    stats.bytes_copied,
-                    stats.bytes_inlined,
-                );
+                println!("objects  {}", result.stats);
 
                 if bootable {
                     let image_verity =

crates/cfsctl/src/main.rs

@@ -9,8 +9,20 @@ use cfsctl::App;
 use anyhow::Result;
 use clap::Parser;
 
-#[tokio::main]
-async fn main() -> Result<()> {
+fn main() -> Result<()> {
+    // If we were spawned as a userns helper process, handle that and exit.
+    // This MUST be called before the tokio runtime is created.
+    #[cfg(feature = "containers-storage")]
+    cstorage::init_if_helper();
+
+    // Now we can create the tokio runtime for the main application
+    tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()?
+        .block_on(async_main())
+}
+
+async fn async_main() -> Result<()> {
     env_logger::init();
 
     let args = App::parse();

crates/composefs-oci/Cargo.toml

@@ -11,17 +11,21 @@ rust-version.workspace = true
 version.workspace = true
 
 [features]
+default = ["containers-storage"]
 test = ["tar", "rand", "composefs/test"]
 boot = ["composefs-boot"]
+containers-storage = ["dep:cstorage", "dep:base64", "cstorage/userns-helper"]
 
 [dependencies]
 anyhow = { version = "1.0.87", default-features = false }
 fn-error-context = "0.2"
 async-compression = { version = "0.4.0", default-features = false, features = ["tokio", "zstd", "gzip"] }
+base64 = { version = "0.22", default-features = false, features = ["std"], optional = true }
 bytes = { version = "1", default-features = false }
 composefs = { workspace = true }
 composefs-boot = { workspace = true, optional = true }
 containers-image-proxy = { version = "0.9.2", default-features = false }
+cstorage = { path = "../cstorage", version = "0.3.0", optional = true }
 hex = { version = "0.4.0", default-features = false }
 indicatif = { version = "0.18.0", default-features = false, features = ["tokio"] }
 rustix = { version = "1.0.0", features = ["fs"] }
@@ -34,6 +38,7 @@ tar = { version = "0.4.38", default-features = false, optional = true }
 tar-core = "0.1.0"
 tokio = { version = "1.24.2", features = ["macros", "rt-multi-thread"] }
 tokio-util = { version = "0.7", default-features = false, features = ["io"] }
+tracing = { version = "0.1", default-features = false }
 
 [dev-dependencies]
 cap-std = { version = "4.0.0", default-features = false }