Docker daemon, docker save (#26)

Author: jssblck

CLAUDE.md

@@ -21,14 +21,19 @@ cargo nextest run --package circe_lib path::to::module
 ## Code Style Guidelines
 - **Formatting**: Use rustfmt, consistent with surrounding code
 - **Naming**: snake_case for functions/variables, CamelCase for types
+- **Variable Shadowing**: Prefer shadowing variables rather than using Hungarian notation (e.g., use `let path = path.to_string_lossy()` instead of `let path_str = path.to_string_lossy()`)
 - **Imports**: Group std lib, external crates, internal modules (alphabetically)
 - **Error Handling**: Use color-eyre with context(), ensure!(), bail!()
 - **Types**: Prefer Builder pattern, derive common traits, use strong types
-- **Documentation**: Comments explain "why" not "what", use proper sentences
+- **Documentation**: Comments explain "why" not "what", use proper sentences. Avoid redundant comments that merely describe what code does - good code should be self-explanatory
 - **Organization**: Modular approach, named module files (not mod.rs)
 - **Testing**: Add integration tests in tests/it/, use test_case macro
 - **Functional Style**: Avoid mutation, prefer functional patterns when possible
 - **Cargo**: Never edit Cargo.toml directly, use cargo edit commands
 - **Conversions**: Use Type::from(value) not let x: Type = value.into()
+- **String Formatting**: 
+  - For simple variables, use direct interpolation: `"Value: {variable}"` instead of `"Value: {}", variable`
+  - For expressions (method calls, etc.), use traditional formatting: `"Value: {}", expression.method()`
+  - This project enforces `clippy::uninlined_format_args` for simple variables
 
 Set `RUST_LOG=debug` or `RUST_LOG=trace` for detailed logs during development.

bin/src/extract.rs

@@ -1,14 +1,17 @@
 use circe_lib::{
-    extract::{extract, Strategy},
+    docker::{Daemon, Tarball},
+    extract::{extract, Report, Strategy},
     registry::Registry,
-    Authentication, Filters, Platform, Reference,
+    Authentication, Filters, Platform, Reference, Source,
 };
 use clap::{Args, Parser, ValueEnum};
 use color_eyre::eyre::{bail, Context, Result};
 use derive_more::Debug;
 use std::{path::PathBuf, str::FromStr};
 use tracing::{debug, info};
 
+use crate::{try_strategies, Outcome};
+
 #[derive(Debug, Parser)]
 pub struct Options {
     /// Target to extract
@@ -80,6 +83,30 @@ pub struct Options {
     file_regex: Option<Vec<String>>,
 }
 
+impl Options {
+    /// Combined filters for layers.
+    pub fn layer_filters(&self) -> Result<Filters> {
+        let layer_globs = Filters::parse_glob(self.layer_glob.iter().flatten())?;
+        let layer_regexes = Filters::parse_regex(self.layer_regex.iter().flatten())?;
+        Ok(layer_globs + layer_regexes)
+    }
+
+    /// Combined filters for files.
+    pub fn file_filters(&self) -> Result<Filters> {
+        let file_globs = Filters::parse_glob(self.file_glob.iter().flatten())?;
+        let file_regexes = Filters::parse_regex(self.file_regex.iter().flatten())?;
+        Ok(file_globs + file_regexes)
+    }
+
+    /// Registry authentication.
+    pub async fn auth(&self, reference: &Reference) -> Result<Authentication> {
+        Ok(match (&self.target.username, &self.target.password) {
+            (Some(username), Some(password)) => Authentication::basic(username, password),
+            _ => Authentication::docker(reference).await?,
+        })
+    }
+}
+
 /// Shared options for any command that needs to work with the OCI registry for a given image.
 #[derive(Debug, Args)]
 pub struct Target {
@@ -130,6 +157,22 @@ pub struct Target {
     pub password: Option<String>,
 }
 
+impl Target {
+    /// Check if the image appears to be a path.
+    /// The validation is performed simply by attempting to canonicalize the path, then checking if a file exists.
+    /// If either operation fails or the file does not exist, the image is not considered a path.
+    pub async fn is_path(&self) -> bool {
+        // We could make this nicer with `futures::future::AndThen`, but we don't currently import `futures`.
+        match tokio::fs::canonicalize(&self.image).await {
+            Ok(path) => match tokio::fs::try_exists(path).await {
+                Ok(exists) => exists,
+                Err(_) => false,
+            },
+            Err(_) => false,
+        }
+    }
+}
+
 #[derive(Copy, Clone, Debug, Default, ValueEnum)]
 pub enum Mode {
     /// Squash all layers into a single output directory, resulting in a file system equivalent to a running container.
@@ -152,28 +195,91 @@ pub enum Mode {
 #[tracing::instrument]
 pub async fn main(opts: Options) -> Result<()> {
     info!("extracting image");
+    try_strategies!(&opts; strategy_tarball, strategy_daemon, strategy_registry)
+}
+
+async fn strategy_registry(opts: &Options) -> Result<Outcome> {
+    if opts.target.is_path().await {
+        debug!("input appears to be a file path, skipping strategy");
+        return Ok(Outcome::Skipped);
+    }
 
     let reference = Reference::from_str(&opts.target.image)?;
-    let layer_globs = Filters::parse_glob(opts.layer_glob.into_iter().flatten())?;
-    let file_globs = Filters::parse_glob(opts.file_glob.into_iter().flatten())?;
-    let layer_regexes = Filters::parse_regex(opts.layer_regex.into_iter().flatten())?;
-    let file_regexes = Filters::parse_regex(opts.file_regex.into_iter().flatten())?;
-    let auth = match (opts.target.username, opts.target.password) {
-        (Some(username), Some(password)) => Authentication::basic(username, password),
-        _ => Authentication::docker(&reference).await?,
-    };
+    let layer_filters = opts.layer_filters()?;
+    let file_filters = opts.file_filters()?;
+    let auth = opts.auth(&reference).await?;
 
-    let output = canonicalize_output_dir(&opts.output_dir, opts.overwrite)?;
     let registry = Registry::builder()
-        .maybe_platform(opts.target.platform)
+        .maybe_platform(opts.target.platform.as_ref())
         .reference(reference)
         .auth(auth)
-        .layer_filters(layer_globs + layer_regexes)
-        .file_filters(file_globs + file_regexes)
+        .layer_filters(layer_filters)
+        .file_filters(file_filters)
         .build()
         .await
         .context("configure remote registry")?;
 
+    extract_layers(opts, registry)
+        .await
+        .context("extract layers")
+        .map(|_| Outcome::Success)
+}
+
+async fn strategy_daemon(opts: &Options) -> Result<Outcome> {
+    if opts.target.is_path().await {
+        debug!("input appears to be a file path, skipping strategy");
+        return Ok(Outcome::Skipped);
+    }
+
+    let layer_filters = opts.layer_filters()?;
+    let file_filters = opts.file_filters()?;
+    let daemon = Daemon::builder()
+        .reference(&opts.target.image)
+        .layer_filters(layer_filters)
+        .file_filters(file_filters)
+        .build()
+        .await
+        .context("build daemon reference")?;
+
+    tracing::info!("pulled image from daemon");
+    extract_layers(opts, daemon)
+        .await
+        .context("extract layers")
+        .map(|_| Outcome::Success)
+}
+
+async fn strategy_tarball(opts: &Options) -> Result<Outcome> {
+    let path = PathBuf::from(&opts.target.image);
+    if matches!(tokio::fs::try_exists(&path).await, Err(_) | Ok(false)) {
+        bail!("path does not exist: {path:?}");
+    }
+
+    let layer_filters = opts.layer_filters()?;
+    let file_filters = opts.file_filters()?;
+    let name = path
+        .file_name()
+        .map(|name| name.to_string_lossy())
+        .unwrap_or_else(|| opts.target.image.clone().into())
+        .to_string();
+
+    let tarball = Tarball::builder()
+        .path(path)
+        .name(name)
+        .file_filters(file_filters)
+        .layer_filters(layer_filters)
+        .build()
+        .await
+        .context("build tarball reference")?;
+
+    tracing::info!("extracting layers from tarball");
+    extract_layers(opts, tarball)
+        .await
+        .context("extract layers")
+        .map(|_| Outcome::Success)
+}
+
+#[tracing::instrument]
+async fn extract_layers(opts: &Options, registry: impl Source) -> Result<()> {
     let layers = registry.layers().await.context("list layers")?;
     if layers.is_empty() {
         bail!("no layers to extract found in image");
@@ -194,16 +300,24 @@ pub async fn main(opts: Options) -> Result<()> {
         },
     };
 
-    let report = extract(&registry, &output, strategies)
+    let output = canonicalize_output_dir(&opts.output_dir, opts.overwrite)?;
+    let digest = registry.digest().await.context("fetch digest")?;
+    let layers = extract(&registry, &output, strategies)
         .await
         .context("extract image")?;
 
+    let report = Report::builder()
+        .digest(digest.to_string())
+        .layers(layers)
+        .build();
+
     report
         .write(&output)
         .await
         .context("write report to disk")?;
 
     println!("{}", report.render()?);
+
     Ok(())
 }
 

bin/src/list.rs

@@ -1,12 +1,16 @@
-use circe_lib::{registry::Registry, Authentication, Reference};
+use circe_lib::{
+    docker::{Daemon, Tarball},
+    registry::Registry,
+    Authentication, Reference, Source,
+};
 use clap::Parser;
-use color_eyre::eyre::{Context, Result};
+use color_eyre::eyre::{bail, Context, Result};
 use derive_more::Debug;
 use pluralizer::pluralize;
-use std::{collections::HashMap, str::FromStr};
+use std::{collections::HashMap, path::PathBuf, str::FromStr};
 use tracing::{debug, info};
 
-use crate::extract::Target;
+use crate::{extract::Target, try_strategies, Outcome};
 
 #[derive(Debug, Parser)]
 pub struct Options {
@@ -18,23 +22,84 @@ pub struct Options {
 #[tracing::instrument]
 pub async fn main(opts: Options) -> Result<()> {
     info!("extracting image");
+    try_strategies!(&opts; strategy_tarball, strategy_daemon, strategy_registry)
+}
+
+async fn strategy_registry(opts: &Options) -> Result<Outcome> {
+    if opts.target.is_path().await {
+        debug!("input appears to be a file path, skipping strategy");
+        return Ok(Outcome::Skipped);
+    }
 
     let reference = Reference::from_str(&opts.target.image)?;
-    let auth = match (opts.target.username, opts.target.password) {
+    let auth = match (&opts.target.username, &opts.target.password) {
         (Some(username), Some(password)) => Authentication::basic(username, password),
         _ => Authentication::docker(&reference).await?,
     };
 
     let registry = Registry::builder()
-        .maybe_platform(opts.target.platform)
+        .maybe_platform(opts.target.platform.as_ref())
         .reference(reference)
         .auth(auth)
         .build()
         .await
         .context("configure remote registry")?;
 
+    list_files(registry)
+        .await
+        .context("list files")
+        .map(|_| Outcome::Success)
+}
+
+async fn strategy_daemon(opts: &Options) -> Result<Outcome> {
+    if opts.target.is_path().await {
+        debug!("input appears to be a file path, skipping strategy");
+        return Ok(Outcome::Skipped);
+    }
+
+    let daemon = Daemon::builder()
+        .reference(&opts.target.image)
+        .build()
+        .await
+        .context("build daemon reference")?;
+
+    tracing::info!("pulled image from daemon");
+    list_files(daemon)
+        .await
+        .context("list files")
+        .map(|_| Outcome::Success)
+}
+
+async fn strategy_tarball(opts: &Options) -> Result<Outcome> {
+    let path = PathBuf::from(&opts.target.image);
+    if matches!(tokio::fs::try_exists(&path).await, Err(_) | Ok(false)) {
+        bail!("path does not exist: {path:?}");
+    }
+
+    let name = path
+        .file_name()
+        .map(|name| name.to_string_lossy())
+        .unwrap_or_else(|| opts.target.image.clone().into())
+        .to_string();
+    let tarball = Tarball::builder()
+        .path(path)
+        .name(name)
+        .build()
+        .await
+        .context("build tarball reference")?;
+
+    tracing::info!("listing files in tarball");
+    list_files(tarball)
+        .await
+        .context("list files")
+        .map(|_| Outcome::Success)
+}
+
+#[tracing::instrument]
+async fn list_files(registry: impl Source) -> Result<()> {
     let layers = registry.layers().await.context("list layers")?;
     let count = layers.len();
+    debug!(?count, ?layers, "listed layers");
     info!("enumerated {}", pluralize("layer", count as isize, true));
 
     let mut listing = HashMap::new();

bin/src/main.rs

@@ -1,3 +1,8 @@
+#![deny(clippy::uninlined_format_args)]
+#![deny(clippy::unwrap_used)]
+#![deny(unsafe_code)]
+#![warn(rust_2018_idioms)]
+
 use clap::{
     builder::{styling::AnsiColor, Styles},
     Parser,
@@ -95,3 +100,30 @@ fn style() -> Styles {
         .invalid(AnsiColor::Red.on_default())
         .valid(AnsiColor::Blue.on_default())
 }
+
+/// Try a list of asynchronous strategies in sequence.
+///
+/// The first strategy to succeed with [`Outcome::Success`] stops executing the rest.
+/// If all strategies fail, an error is returned
+///
+/// Note: this macro returns from the calling context, not from the current expression.
+#[macro_export]
+#[doc(hidden)]
+macro_rules! try_strategies {
+    ($opts:expr; $($strategy:expr),*) => {{
+        $(match $strategy(&$opts).await {
+            Ok($crate::Outcome::Success) => return Ok(()),
+            Ok($crate::Outcome::Skipped) => {},
+            Err(err) => tracing::warn!(?err, "strategy failed"),
+        })*
+
+        color_eyre::eyre::bail!("all strategies failed")
+    }}
+}
+
+/// The result of executing a strategy.
+/// When executing multiple strategies, the first successful one stops the sequence.
+pub enum Outcome {
+    Success,
+    Skipped,
+}