Cylinder C1, first part: artifacts as trees of the repository's chunks, oxy artifact pack/list/show/unpack/verify, kept by gc (refs #108) 642da2636de2

[package]

name = "cylinder"

version.workspace = true

edition.workspace = true

license.workspace = true

description = "Cylinder: artifacts as trees of Oxygen chunks (docs/cylinder.md)"

[dependencies]

oxy-core = { path = "../oxy-core" }

blake3 = "1"

thiserror = "1"

[dev-dependencies]

tempfile = "3"

//! Cylinder, step C1 (docs/cylinder.md §4.1): an **artifact** is an

//! immutable, content-addressed object naming a tree of files, each kept as

//! an ordinary Oxygen blob of FastCDC BLAKE3 chunks. An image rebuilt with

//! one changed file moves only that file's changed chunks, and a binary in

//! a release archive and in a runner image is the same chunks.

//!

//! An artifact is its canonical CBOR (spec §5.1), named by the BLAKE3 of

//! that encoding. Until the artifact is an object type of its own (the rest

//! of C1), the encoding and its tree are kept as blobs in the repository's

//! store, and `.oxy/artifacts/NAME` holds the encoding's blob so the

//! artifact can be found and garbage collection keeps it ([`roots`]).

use oxy_core::cbor::{self, Value};

use oxy_core::hash::ObjectRef;

use oxy_core::repo::Repo;

use std::collections::BTreeMap;

use std::path::{Path, PathBuf};

/// The encoding's version this crate writes and reads.

pub const VERSION: u64 = 1;

#[derive(Debug, thiserror::Error)]

pub enum Error {

    #[error(transparent)]

    Repo(#[from] oxy_core::repo::RepoError),

    #[error("io: {0}")]

    Io(#[from] std::io::Error),

    #[error("not a canonical artifact encoding: {0}")]

    Cbor(#[from] oxy_core::cbor::CborError),

    #[error("{0}")]

    Bad(String),

}

pub type Result<T> = std::result::Result<T, Error>;

fn bad<T>(msg: impl Into<String>) -> Result<T> {

    Err(Error::Bad(msg.into()))

}

/// What an artifact is for.

#[derive(Clone, Copy, Debug, PartialEq, Eq)]

pub enum Kind {

    Container,

    RunnerImage,

    Package,

    Archive,

    Report,

}

impl Kind {

    pub const ALL: [Kind; 5] = [

        Kind::Container,

        Kind::RunnerImage,

        Kind::Package,

        Kind::Archive,

        Kind::Report,

    ];

    pub fn as_str(self) -> &'static str {

        match self {

            Kind::Container => "container",

            Kind::RunnerImage => "runner-image",

            Kind::Package => "package",

            Kind::Archive => "archive",

            Kind::Report => "report",

        }

    }

    pub fn parse(s: &str) -> Result<Kind> {

        Kind::ALL.into_iter().find(|k| k.as_str() == s).map_or_else(

            || {

                bad(format!(

                    "{s:?} is not a kind of artifact: {}",

                    Kind::ALL.map(|k| k.as_str()).join(", ")

                ))

            },

            Ok,

        )

    }

}

/// A file's mode in a tree: a regular file, an executable one, or a

/// symbolic link (whose blob is its target).

pub const MODE_FILE: u32 = 0o100644;

pub const MODE_EXEC: u32 = 0o100755;

pub const MODE_LINK: u32 = 0o120000;

/// A file of an artifact's tree.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Entry {

    /// `/`-separated, relative, never `.` or `..` parts.

    pub path: String,

    pub mode: u32,

    pub blob: ObjectRef,

    pub size: u64,

}

/// An artifact's files, in path order: paths, modes, blobs and sizes.

#[derive(Clone, Debug, Default, PartialEq, Eq)]

pub struct DirTree {

    pub entries: Vec<Entry>,

}

fn path_ok(p: &str) -> bool {

    !p.is_empty()

        && !p.starts_with('/')

        && p.split('/').all(|s| !s.is_empty() && s != "." && s != "..")

}

fn obj(r: &ObjectRef) -> Value {

    Value::Bytes(r.0.to_vec())

}

fn get_obj(v: &Value, what: &str) -> Result<ObjectRef> {

    match v.as_bytes() {

        Some(b) if b.len() == 32 => {

            let mut a = [0u8; 32];

            a.copy_from_slice(b);

            Ok(ObjectRef(a))

        }

        _ => bad(format!("{what} is not an object reference")),

    }

}

fn get_text(v: &Value, what: &str) -> Result<String> {

    v.as_text()

        .map(str::to_string)

        .map_or_else(|| bad(format!("{what} is not text")), Ok)

}

fn get_uint(v: &Value, what: &str) -> Result<u64> {

    v.as_uint()

        .map_or_else(|| bad(format!("{what} is not a number")), Ok)

}

impl DirTree {

    pub fn encode(&self) -> Vec<u8> {

        let entries = self

            .entries

            .iter()

            .map(|e| {

                Value::Array(vec![

                    Value::Text(e.path.clone()),

                    Value::Uint(e.mode as u64),

                    obj(&e.blob),

                    Value::Uint(e.size),

                ])

            })

            .collect();

        cbor::encode(&Value::map([

            (0, Value::Uint(VERSION)),

            (1, Value::Array(entries)),

        ]))

    }

    /// Read and check a tree: a known version, clean paths, each once, in

    /// order, with a known mode.

    pub fn decode(bytes: &[u8]) -> Result<DirTree> {

        let v = cbor::decode(bytes)?;

        let m = v.as_map().map_or_else(|| bad("a tree is a map"), Ok)?;

        if m.get(&0).and_then(Value::as_uint) != Some(VERSION) {

            return bad(format!(

                "tree version {:?} is not known; this reads {VERSION}",

                m.get(&0)

            ));

        }

        let mut entries = Vec::new();

        for item in m.get(&1).and_then(Value::as_array).unwrap_or_default() {

            let [p, mode, blob, size] = item.as_array().unwrap_or_default() else {

                return bad("a tree entry is [path, mode, blob, size]");

            };

            let path = get_text(p, "a path")?;

            let mode = get_uint(mode, "a mode")? as u32;

            if !path_ok(&path) {

                return bad(format!("{path:?} is not a clean relative path"));

            }

            if ![MODE_FILE, MODE_EXEC, MODE_LINK].contains(&mode) {

                return bad(format!(

                    "{path}: mode {mode:o} is not a file, an executable or a link"

                ));

            }

            if entries.last().is_some_and(|l: &Entry| l.path >= path) {

                return bad(format!(

                    "{path}: entries are not in path order, or one is there twice"

                ));

            }

            entries.push(Entry {

                path,

                mode,

                blob: get_obj(blob, "a blob")?,

                size: get_uint(size, "a size")?,

            });

        }

        Ok(DirTree { entries })

    }

}

/// An artifact (docs/cylinder.md §4.1).

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Artifact {

    pub kind: Kind,

    /// `x86_64`, `riscv64`, `aarch64`.

    pub arch: Option<String>,

    /// `linux`, `darwin`, `none`.

    pub os: Option<String>,

    /// The [`DirTree`]'s blob.

    pub tree: ObjectRef,

    /// The default command, for a container or an image.

    pub entrypoint: Option<Vec<String>>,

    pub env: BTreeMap<String, String>,

    pub labels: BTreeMap<String, String>,

    /// The files' bytes together.

    pub total_size: u64,

    /// The receipt of the Flow job that built it, when one did.

    pub receipt: Option<ObjectRef>,

}

fn pairs(m: &BTreeMap<String, String>) -> Value {

    if m.is_empty() {

        return Value::Null;

    }

    Value::Array(

        m.iter()

            .map(|(k, v)| Value::Array(vec![Value::Text(k.clone()), Value::Text(v.clone())]))

            .collect(),

    )

}

fn get_pairs(v: Option<&Value>, what: &str) -> Result<BTreeMap<String, String>> {

    let mut out = BTreeMap::new();

    let Some(v) = v.filter(|v| !v.is_null()) else {

        return Ok(out);

    };

    for p in v

        .as_array()

        .map_or_else(|| bad(format!("{what} is a list of pairs")), Ok)?

    {

        let [k, val] = p.as_array().unwrap_or_default() else {

            return bad(format!("{what}: a pair is [key, value]"));

        };

        let k = get_text(k, what)?;

        if out.insert(k.clone(), get_text(val, what)?).is_some() {

            return bad(format!("{what}: {k} is there twice"));

        }

    }

    Ok(out)

}

fn opt_text(v: &Option<String>) -> Value {

    v.as_ref().map_or(Value::Null, |s| Value::Text(s.clone()))

}

impl Artifact {

    /// Its canonical CBOR, keys as in docs/cylinder.md §4.1.

    pub fn encode(&self) -> Vec<u8> {

        let entry = self.entrypoint.as_ref().map_or(Value::Null, |a| {

            Value::Array(a.iter().cloned().map(Value::Text).collect())

        });

        cbor::encode(&Value::map([

            (0, Value::Uint(VERSION)),

            (1, Value::Text(self.kind.as_str().into())),

            (2, opt_text(&self.arch)),

            (3, opt_text(&self.os)),

            (4, obj(&self.tree)),

            (5, entry),

            (6, pairs(&self.env)),

            (7, pairs(&self.labels)),

            (8, Value::Uint(self.total_size)),

            (9, self.receipt.as_ref().map_or(Value::Null, obj)),

        ]))

    }

    pub fn decode(bytes: &[u8]) -> Result<Artifact> {

        let v = cbor::decode(bytes)?;

        let m = v.as_map().map_or_else(|| bad("an artifact is a map"), Ok)?;

        if m.get(&0).and_then(Value::as_uint) != Some(VERSION) {

            return bad(format!(

                "artifact version {:?} is not known; this reads {VERSION}",

                m.get(&0)

            ));

        }

        if let Some(k) = m.keys().find(|k| **k > 9) {

            return bad(format!("key {k} is not part of an artifact"));

        }

        let text = |k: u64, what: &str| -> Result<Option<String>> {

            match m.get(&k) {

                None | Some(Value::Null) => Ok(None),

                Some(v) => get_text(v, what).map(Some),

            }

        };

        let entrypoint = match m.get(&5) {

            None | Some(Value::Null) => None,

            Some(v) => Some(

                v.as_array()

                    .unwrap_or_default()

                    .iter()

                    .map(|a| get_text(a, "the entrypoint"))

                    .collect::<Result<_>>()?,

            ),

        };

        let receipt = match m.get(&9) {

            None | Some(Value::Null) => None,

            Some(v) => Some(get_obj(v, "the receipt")?),

        };

        Ok(Artifact {

            kind: Kind::parse(&text(1, "the kind")?.unwrap_or_default())?,

            arch: text(2, "the architecture")?,

            os: text(3, "the system")?,

            tree: get_obj(m.get(&4).unwrap_or(&Value::Null), "the tree")?,

            entrypoint,

            env: get_pairs(m.get(&6), "env")?,

            labels: get_pairs(m.get(&7), "labels")?,

            total_size: get_uint(m.get(&8).unwrap_or(&Value::Null), "the size")?,

            receipt,

        })

    }

    /// Its name: the BLAKE3 of its canonical encoding, hex.

    pub fn name(&self) -> String {

        blake3::hash(&self.encode()).to_hex().to_string()

    }

}

/// What to pack a directory as.

#[derive(Clone, Debug)]

pub struct Spec {

    pub kind: Kind,

    pub arch: Option<String>,

    pub os: Option<String>,

    pub entrypoint: Option<Vec<String>>,

    pub env: BTreeMap<String, String>,

    pub labels: BTreeMap<String, String>,

}

impl Spec {

    pub fn new(kind: Kind) -> Spec {

        Spec {

            kind,

            arch: None,

            os: None,

            entrypoint: None,

            env: BTreeMap::new(),

            labels: BTreeMap::new(),

        }

    }

}

/// An artifact kept in a repository, with its name.

#[derive(Clone, Debug)]

pub struct Kept {

    pub name: String,

    pub artifact: Artifact,

    /// The blob its encoding is kept in.

    pub blob: ObjectRef,

}

fn kept_dir(repo: &Repo) -> PathBuf {

    repo.oxy_dir().join("artifacts")

}

/// Every file under `dir`, by relative path: regular files and links, in

/// path order. `.oxy` and `.git` directories are not part of an artifact.

fn walk(dir: &Path) -> Result<Vec<(String, PathBuf, std::fs::Metadata)>> {

    let mut out = Vec::new();

    let mut stack = vec![(dir.to_path_buf(), String::new())];

    while let Some((d, rel)) = stack.pop() {

        for e in std::fs::read_dir(&d)? {

            let e = e?;

            let name = e

                .file_name()

                .into_string()

                .map_err(|n| Error::Bad(format!("{n:?} is not UTF-8")))?;

            let path = if rel.is_empty() {

                name.clone()

            } else {

                format!("{rel}/{name}")

            };

            let md = std::fs::symlink_metadata(e.path())?;

            if md.is_dir() {

                if name != ".oxy" && name != ".git" {

                    stack.push((e.path(), path));

                }

            } else if md.is_file() || md.file_type().is_symlink() {

                out.push((path, e.path(), md));

            }

        }

    }

    out.sort_by(|a, b| a.0.cmp(&b.0));

    Ok(out)

}

#[cfg(unix)]

fn mode_of(md: &std::fs::Metadata) -> u32 {

    use std::os::unix::fs::PermissionsExt;

    if md.file_type().is_symlink() {

        MODE_LINK

    } else if md.permissions().mode() & 0o111 != 0 {

        MODE_EXEC

    } else {

        MODE_FILE

    }

}

#[cfg(not(unix))]

fn mode_of(md: &std::fs::Metadata) -> u32 {

    if md.file_type().is_symlink() {

        MODE_LINK

    } else {

        MODE_FILE

    }

}

/// Pack the files under `dir` into an artifact of `spec`'s kind in

/// `repo`'s store: each file a blob, so files and chunks the store holds

/// already cost nothing; then its tree and its encoding, kept under its

/// name.

pub fn pack(repo: &Repo, dir: &Path, spec: &Spec) -> Result<Kept> {

    if !dir.is_dir() {

        return bad(format!("{} is not a directory", dir.display()));

    }

    let mut tree = DirTree::default();

    for (path, full, md) in walk(dir)? {

        let mode = mode_of(&md);

        let bytes = if mode == MODE_LINK {

            std::fs::read_link(&full)?

                .to_string_lossy()

                .into_owned()

                .into_bytes()

        } else {

            std::fs::read(&full)?

        };

        let blob = repo.store_blob(&bytes)?;

        tree.entries.push(Entry {

            path,

            mode,

            blob,

            size: bytes.len() as u64,

        });

    }

    let artifact = Artifact {

        kind: spec.kind,

        arch: spec.arch.clone(),

        os: spec.os.clone(),

        tree: repo.store_blob(&tree.encode())?,

        entrypoint: spec.entrypoint.clone(),

        env: spec.env.clone(),

        labels: spec.labels.clone(),

        total_size: tree.entries.iter().map(|e| e.size).sum(),

        receipt: None,

    };

    let bytes = artifact.encode();

    let blob = repo.store_blob(&bytes)?;

    let name = blake3::hash(&bytes).to_hex().to_string();

    std::fs::create_dir_all(kept_dir(repo))?;

    std::fs::write(kept_dir(repo).join(&name), blob.to_hex())?;

    Ok(Kept {

        name,

        artifact,

        blob,

    })

}

/// The names of the artifacts kept in `repo`, sorted.

pub fn list(repo: &Repo) -> Result<Vec<String>> {

    let mut out = Vec::new();

    match std::fs::read_dir(kept_dir(repo)) {

        Ok(rd) => {

            for e in rd {

                let n = e?.file_name().to_string_lossy().into_owned();

                if n.len() == 64 && n.bytes().all(|b| b.is_ascii_hexdigit()) {

                    out.push(n);

                }

            }

        }

        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}

        Err(e) => return Err(e.into()),

    }

    out.sort();

    Ok(out)

}

/// The kept artifact `name` names, or a unique prefix of it (at least six

/// characters), checked against its name.

pub fn open(repo: &Repo, name: &str) -> Result<Kept> {

    let name = name.to_ascii_lowercase();

    if name.len() < 6 {

        return bad("name an artifact by at least six characters of its name");

    }

    let found: Vec<String> = list(repo)?

        .into_iter()

        .filter(|n| n.starts_with(&name))

        .collect();

    let full = match found.as_slice() {

        [one] => one.clone(),

        [] => {

            return bad(format!(

                "no artifact {name} here; `oxy artifact list` shows them"

            ))

        }

        _ => {

            return bad(format!(

                "{name} names {} artifacts: give more of the name",

                found.len()

            ))

        }

    };

    let hex = std::fs::read_to_string(kept_dir(repo).join(&full))?;

    let blob = ObjectRef::from_hex(hex.trim()).map_or_else(

        || bad(format!("artifact {full}: its record is damaged")),

        Ok,

    )?;

    let bytes = repo.read_blob(&blob)?;

    if blake3::hash(&bytes).to_hex().as_str() != full {

        return bad(format!(

            "artifact {full}: its encoding no longer hashes to its name"

        ));

    }

    Ok(Kept {

        name: full,

        artifact: Artifact::decode(&bytes)?,

        blob,

    })

}

/// An artifact's tree.

pub fn tree(repo: &Repo, a: &Artifact) -> Result<DirTree> {

    DirTree::decode(&repo.read_blob(&a.tree)?)

}

/// Check that every file of `k` is in the store whole: its bytes read, at

/// the size its tree says. Answers how many files were read.

pub fn verify(repo: &Repo, k: &Kept) -> Result<usize> {

    let t = tree(repo, &k.artifact)?;

    let mut total = 0;

    for e in &t.entries {

        let n = repo.read_blob(&e.blob)?.len() as u64;

        if n != e.size {

            return bad(format!(

                "{}: {n} bytes, but the tree says {}",

                e.path, e.size

            ));

        }

        total += n;

    }

    if total != k.artifact.total_size {

        return bad(format!(

            "the files are {total} bytes together, but the artifact says {}",

            k.artifact.total_size

        ));

    }

    Ok(t.entries.len())

}

/// Write `k`'s files under `dest`, which must not exist or be empty.

pub fn unpack(repo: &Repo, k: &Kept, dest: &Path) -> Result<usize> {

    if dest.exists() && std::fs::read_dir(dest)?.next().is_some() {

        return bad(format!("{} is not empty", dest.display()));

    }

    let t = tree(repo, &k.artifact)?;

    for e in &t.entries {

        let out = dest.join(&e.path);

        if let Some(p) = out.parent() {

            std::fs::create_dir_all(p)?;

        }

        let bytes = repo.read_blob(&e.blob)?;

        if e.mode == MODE_LINK {

            #[cfg(unix)]

            std::os::unix::fs::symlink(String::from_utf8_lossy(&bytes).as_ref(), &out)?;

            #[cfg(not(unix))]

            std::fs::write(&out, &bytes)?;

            continue;

        }

        std::fs::write(&out, &bytes)?;

        #[cfg(unix)]

        if e.mode == MODE_EXEC {

            use std::os::unix::fs::PermissionsExt;

            std::fs::set_permissions(&out, std::fs::Permissions::from_mode(0o755))?;

        }

    }

    Ok(t.entries.len())

}

/// The blobs garbage collection must keep for the kept artifacts: each

/// one's encoding, its tree and its files (`Repo::gc_keeping`).

pub fn roots(repo: &Repo) -> Result<Vec<ObjectRef>> {

    let mut out = Vec::new();

    for name in list(repo)? {

        let k = open(repo, &name)?;

        out.push(k.blob);

        out.push(k.artifact.tree);

        out.extend(tree(repo, &k.artifact)?.entries.iter().map(|e| e.blob));

    }

    Ok(out)

}

#[cfg(test)]

mod tests {

    use super::*;

    fn repo(dir: &Path) -> Repo {

        Repo::init(&dir.join("repo")).unwrap()

    }

    #[test]

    fn a_directory_packs_into_an_artifact_and_back() {

        let t = tempfile::tempdir().unwrap();

        let r = repo(t.path());

        let src = t.path().join("out");

        std::fs::create_dir_all(src.join("bin")).unwrap();

        std::fs::write(src.join("README"), b"hello\n").unwrap();

        std::fs::write(src.join("bin/tool"), vec![7u8; 300_000]).unwrap();

        #[cfg(unix)]

        {

            use std::os::unix::fs::PermissionsExt;

            std::fs::set_permissions(src.join("bin/tool"), std::fs::Permissions::from_mode(0o755))

                .unwrap();

            std::os::unix::fs::symlink("bin/tool", src.join("tool")).unwrap();

        }

        let mut spec = Spec::new(Kind::Archive);

        spec.arch = Some("x86_64".into());

        spec.labels.insert("version".into(), "0.1.0".into());

        let k = pack(&r, &src, &spec).unwrap();

        assert_eq!(k.name, k.artifact.name());

        assert_eq!(

            k.artifact.total_size,

            300_006 + if cfg!(unix) { 8 } else { 0 }

        );

        assert_eq!(list(&r).unwrap(), vec![k.name.clone()]);

        let again = open(&r, &k.name[..10]).unwrap();

        assert_eq!(again.artifact, k.artifact);

        let paths: Vec<(String, u32)> = tree(&r, &again.artifact)

            .unwrap()

            .entries

            .into_iter()

            .map(|e| (e.path, e.mode))

            .collect();

        assert_eq!(paths[0], ("README".into(), MODE_FILE));

        assert_eq!(

            paths[1],

            (

                "bin/tool".into(),

                if cfg!(unix) { MODE_EXEC } else { MODE_FILE }

            )

        );

        assert_eq!(verify(&r, &again).unwrap(), paths.len());

        let dest = t.path().join("back");

        unpack(&r, &again, &dest).unwrap();

        assert_eq!(

            std::fs::read(dest.join("bin/tool")).unwrap(),

            vec![7u8; 300_000]

        );

        #[cfg(unix)]

        assert_eq!(

            std::fs::read_link(dest.join("tool")).unwrap(),

            Path::new("bin/tool")

        );

        assert!(unpack(&r, &again, &dest)

            .unwrap_err()

            .to_string()

            .contains("not empty"));

        // The same files pack to the same name; garbage collection keeps it.

        assert_eq!(pack(&r, &src, &spec).unwrap().name, k.name);

        let keep = roots(&r).unwrap();

        assert!(keep.contains(&k.blob) && keep.contains(&k.artifact.tree));

        r.gc_keeping(true, &keep, &mut |_| {}).unwrap();

        assert_eq!(

            verify(&r, &open(&r, &k.name).unwrap()).unwrap(),

            paths.len()

        );

    }

    #[test]

    fn encodings_are_canonical_and_checked() {

        let a = Artifact {

            kind: Kind::RunnerImage,

            arch: Some("riscv64".into()),

            os: Some("linux".into()),

            tree: ObjectRef([1; 32]),

            entrypoint: Some(vec!["/sbin/init".into()]),

            env: [("PATH".to_string(), "/bin".to_string())].into(),

            labels: BTreeMap::new(),

            total_size: 42,

            receipt: Some(ObjectRef([2; 32])),

        };

        let bytes = a.encode();

        assert_eq!(Artifact::decode(&bytes).unwrap(), a);

        assert_eq!(a.name(), blake3::hash(&bytes).to_hex().to_string());

        assert!(Kind::parse("tarball")

            .unwrap_err()

            .to_string()

            .contains("runner-image"));

        let wrong = |v: Value| Artifact::decode(&cbor::encode(&v)).unwrap_err().to_string();

        assert!(wrong(Value::map([(0, Value::Uint(2))])).contains("version"));

        assert!(wrong(Value::map([(0, Value::Uint(1)), (10, Value::Null)])).contains("key 10"));

        let t = DirTree {

            entries: vec![Entry {

                path: "a".into(),

                mode: MODE_FILE,

                blob: ObjectRef([3; 32]),

                size: 1,

            }],

        };

        assert_eq!(DirTree::decode(&t.encode()).unwrap(), t);

        let entry = |p: &str, mode: u32| {

            Value::Array(vec![

                Value::Text(p.into()),

                Value::Uint(mode as u64),

                Value::Bytes(vec![0; 32]),

                Value::Uint(0),

            ])

        };

        let tree = |items: Vec<Value>| {

            DirTree::decode(&cbor::encode(&Value::map([

                (0, Value::Uint(1)),

                (1, Value::Array(items)),

            ])))

            .unwrap_err()

            .to_string()

        };

        assert!(tree(vec![entry("../x", MODE_FILE)]).contains("clean"));

        assert!(tree(vec![entry("b", MODE_FILE), entry("a", MODE_FILE)]).contains("order"));

        assert!(tree(vec![entry("a", 0o040000)]).contains("mode"));

    }

}

//! `oxy artifact`: Cylinder's artifacts (docs/cylinder.md §4.1, step C1):

//! a directory packed into a tree of the repository's own chunks, named by

//! the BLAKE3 of its canonical encoding.

use super::json;

use super::open;

use super::ui;

use anyhow::Result;

use cylinder::{Kind, Spec};

use std::path::Path;

/// `KEY=VALUE` pairs, refused when one has no `=`.

fn pairs(list: &[String], what: &str) -> Result<std::collections::BTreeMap<String, String>> {

    list.iter()

        .map(|p| {

            p.split_once('=')

                .map(|(k, v)| (k.to_string(), v.to_string()))

                .ok_or_else(|| anyhow::anyhow!("{what} {p:?}: write it KEY=VALUE"))

        })

        .collect()

}

fn summary(k: &cylinder::Kept) -> String {

    let a = &k.artifact;

    let mut parts = vec![a.kind.as_str().to_string()];

    parts.extend(a.os.clone());

    parts.extend(a.arch.clone());

    format!(

        "{} {} {}",

        ui::hash(&k.name[..12]),

        parts.join(" "),

        ui::dim(format!("{} bytes", a.total_size))

    )

}

fn as_json(k: &cylinder::Kept, files: usize) -> String {

    let a = &k.artifact;

    let text = |v: &Option<String>| v.as_deref().map(json::s).unwrap_or_else(|| "null".into());

    let map = |m: &std::collections::BTreeMap<String, String>| {

        let inner: Vec<String> = m

            .iter()

            .map(|(k, v)| format!("{}:{}", json::s(k), json::s(v)))

            .collect();

        format!("{{{}}}", inner.join(","))

    };

    json::obj([

        ("name", json::s(&k.name)),

        ("kind", json::s(a.kind.as_str())),

        ("arch", text(&a.arch)),

        ("os", text(&a.os)),

        ("tree", json::s(&a.tree.to_hex())),

        ("files", json::n(files as u64)),

        ("total_size", json::n(a.total_size)),

        ("env", map(&a.env)),

        ("labels", map(&a.labels)),

    ])

}

#[allow(clippy::too_many_arguments)]

pub fn pack(

    dir: &Path,

    kind: &str,

    arch: Option<String>,

    os: Option<String>,

    entrypoint: Vec<String>,

    env: &[String],

    labels: &[String],

    as_json_out: bool,

) -> Result<i32> {

    let repo = open()?;

    let mut spec = Spec::new(Kind::parse(kind)?);

    spec.arch = arch;

    spec.os = os;

    spec.entrypoint = (!entrypoint.is_empty()).then_some(entrypoint);

    spec.env = pairs(env, "env")?;

    spec.labels = pairs(labels, "label")?;

    let sp = ui::spinner("Packing…");

    let k = cylinder::pack(&repo, dir, &spec)?;

    sp.clear();

    let files = cylinder::tree(&repo, &k.artifact)?.entries.len();

    if as_json_out {

        println!("{}", as_json(&k, files));

    } else {

        println!(

            "{} {} as {}",

            ui::done("Packed"),

            ui::path(dir.display()),

            summary(&k)

        );

        println!("{}", ui::kv("name", &k.name));

        println!("{}", ui::kv("files", files.to_string()));

    }

    Ok(0)

}

pub fn list(as_json_out: bool) -> Result<i32> {

    let repo = open()?;

    let names = cylinder::list(&repo)?;

    let kept: Vec<cylinder::Kept> = names

        .iter()

        .map(|n| cylinder::open(&repo, n))

        .collect::<std::result::Result<_, _>>()?;

    if as_json_out {

        let items: Vec<String> = kept

            .iter()

            .map(|k| {

                let files = cylinder::tree(&repo, &k.artifact)

                    .map(|t| t.entries.len())

                    .unwrap_or(0);

                as_json(k, files)

            })

            .collect();

        println!("[{}]", items.join(","));

        return Ok(0);

    }

    if kept.is_empty() {

        println!("No artifacts yet: oxy artifact pack DIR --kind archive");

    }

    for k in &kept {

        println!("{}", summary(k));

    }

    Ok(0)

}

pub fn show(name: &str, as_json_out: bool) -> Result<i32> {

    let repo = open()?;

    let k = cylinder::open(&repo, name)?;

    let t = cylinder::tree(&repo, &k.artifact)?;

    if as_json_out {

        println!("{}", as_json(&k, t.entries.len()));

        return Ok(0);

    }

    println!("{}", summary(&k));

    println!("{}", ui::kv("name", &k.name));

    if let Some(e) = &k.artifact.entrypoint {

        println!("{}", ui::kv("entrypoint", e.join(" ")));

    }

    for (key, v) in &k.artifact.labels {

        println!("{}", ui::kv("label", format!("{key}={v}")));

    }

    for (key, v) in &k.artifact.env {

        println!("{}", ui::kv("env", format!("{key}={v}")));

    }

    for e in &t.entries {

        let mode = match e.mode {

            cylinder::MODE_EXEC => "x",

            cylinder::MODE_LINK => "l",

            _ => " ",

        };

        println!("  {mode} {:>10}  {}", e.size, e.path);

    }

    Ok(0)

}

pub fn unpack(name: &str, dest: &Path) -> Result<i32> {

    let repo = open()?;

    let k = cylinder::open(&repo, name)?;

    let n = cylinder::unpack(&repo, &k, dest)?;

    println!(

        "{} {} files of {} into {}",

        ui::done("Unpacked"),

        n,

        ui::hash(&k.name[..12]),

        ui::path(dest.display())

    );

    Ok(0)

}

pub fn verify(name: &str) -> Result<i32> {

    let repo = open()?;

    let k = cylinder::open(&repo, name)?;

    let n = cylinder::verify(&repo, &k)?;

    println!(

        "{} {}: its name, tree and {} files check out",

        ui::done("Verified"),

        ui::hash(&k.name[..12]),

        n

    );

    Ok(0)

}

- **Added: artifacts (Cylinder, step C1, #108).** `oxy artifact pack DIR --kind archive|package|container|runner-image|report [--arch --os --entrypoint --env K=V --label K=V]` packs a directory into an artifact: each file an ordinary blob of the repository's store, so files and chunks it holds already cost nothing, under a tree and an artifact encoding in canonical CBOR, named by the BLAKE3 of that encoding (docs/cylinder.md §4.1). `oxy artifact list | show NAME | unpack NAME DEST | verify NAME` (any unique prefix of six characters or more; `--json` on list, show and pack), and `oxy gc` keeps every artifact's blobs. The new `cylinder` crate holds the model.

name = "cylinder"

version = "0.8.0"

dependencies = [

 "blake3",

 "oxy-core",

 "tempfile",

 "thiserror 1.0.69",

]

[[package]]

 "cylinder",

members = ["crates/oxy-core", "crates/oxy-server", "crates/oxy-strata", "crates/cylinder", "."]

cylinder = { path = "crates/cylinder" }

    /// The repository's `.oxy` directory (shared by its workspaces), for

    /// what other crates keep beside the store (Cylinder's artifacts).

    pub fn oxy_dir(&self) -> &Path {

        &self.oxy

    }

  *Started 2026-10-28 (oxygen#108):* `crates/cylinder` has the

  `Artifact` and `DirTree` encodings of §4.1 (canonical CBOR; a name is

  the BLAKE3 of the encoding; `env` and `labels` as sorted pairs, since

  the profile's maps take integer keys), packing a directory into the

  repository's own blobs and chunks, verifying and unpacking, and the

  roots garbage collection keeps; `oxy artifact pack | list | show |

  unpack | verify`. Until the artifact is an object type of its own, its

  encoding and tree are blobs and `.oxy/artifacts/NAME` records it. Next:

  the object type, then runner images as artifacts.

mod artifact;

    /// Artifacts: a directory packed into a tree of this repository's chunks (Cylinder, docs/cylinder.md)

    Artifact {

        #[command(subcommand)]

        cmd: ArtifactCmd,

    },

enum ArtifactCmd {

    /// Pack DIR into an artifact: each file a blob of this repository's store, so files and chunks it holds cost nothing

    Pack {

        /// The directory whose files make the artifact

        dir: std::path::PathBuf,

        /// container, runner-image, package, archive or report

        #[arg(long, default_value = "archive")]

        kind: String,

        /// x86_64, riscv64, aarch64…

        #[arg(long)]

        arch: Option<String>,

        /// linux, darwin, none…

        #[arg(long)]

        os: Option<String>,

        /// The default command, one word per flag

        #[arg(long = "entrypoint", value_name = "WORD")]

        entrypoint: Vec<String>,

        /// KEY=VALUE for the environment (repeatable)

        #[arg(long = "env", value_name = "KEY=VALUE")]

        env: Vec<String>,

        /// KEY=VALUE metadata (repeatable)

        #[arg(long = "label", value_name = "KEY=VALUE")]

        labels: Vec<String>,

        /// Machine-readable output: one JSON document on stdout

        #[arg(long)]

        json: bool,

    },

    /// The artifacts kept here

    List {

        /// Machine-readable output: one JSON document on stdout

        #[arg(long)]

        json: bool,

    },

    /// One artifact and its files

    Show {

        /// Its name, or a unique prefix of at least six characters

        name: String,

        /// Machine-readable output: one JSON document on stdout

        #[arg(long)]

        json: bool,

    },

    /// Write an artifact's files into DEST (missing or empty)

    Unpack {

        /// Its name, or a unique prefix of at least six characters

        name: String,

        /// Where to write its files

        dest: std::path::PathBuf,

    },

    /// Check an artifact's name, tree and every file against the store

    Verify {

        /// Its name, or a unique prefix of at least six characters

        name: String,

    },

}

#[derive(Subcommand)]

        },

        Cmd::Artifact { cmd } => match cmd {

            ArtifactCmd::Pack {

                dir,

                kind,

                arch,

                os,

                entrypoint,

                env,

                labels,

                json,

            } => artifact::pack(&dir, &kind, arch, os, entrypoint, &env, &labels, json),

            ArtifactCmd::List { json } => artifact::list(json),

            ArtifactCmd::Show { name, json } => artifact::show(&name, json),

            ArtifactCmd::Unpack { name, dest } => artifact::unpack(&name, &dest),

            ArtifactCmd::Verify { name } => artifact::verify(&name),

    // Cylinder's artifacts are named from outside the history: keep them.

    let artifacts = cylinder::roots(&repo)?;

    let r = repo.gc_keeping(now, &artifacts, &mut |phase| sp.set(&format!("{phase}…")))?;

/// Cylinder C1 (oxygen#108): a directory packs into an artifact of this

/// repository's chunks, lists and shows as JSON, survives gc, and unpacks.

#[test]

fn artifacts_pack_show_survive_gc_and_unpack() {

    let tmp = tempfile::tempdir().unwrap();

    let home = tmp.path().join("home");

    let dir = tmp.path().join("r");

    std::fs::create_dir_all(&dir).unwrap();

    assert_eq!(oxy(&dir, &home, &["init"]).0, 0);

    write(tmp.path(), "out/bin/tool", "#!/bin/sh\necho hi\n");

    write(tmp.path(), "out/README", "a tool\n");

    let out = tmp.path().join("out");

    let pack = [

        "artifact",

        "pack",

        out.to_str().unwrap(),

        "--kind",

        "package",

        "--arch",

        "x86_64",

        "--label",

        "version=0.1.0",

        "--json",

    ];

    let a = json(&dir, &home, &pack);

    let name = a["name"].as_str().unwrap().to_string();

    assert_eq!(

        (

            a["kind"].as_str(),

            a["files"].as_u64(),

            a["labels"]["version"].as_str()

        ),

        (Some("package"), Some(2), Some("0.1.0"))

    );

    let list = json(&dir, &home, &["artifact", "list", "--json"]);

    assert_eq!(list[0]["name"], name.as_str());

    let (code, _, err) = oxy(

        &dir,

        &home,

        &[

            "artifact",

            "pack",

            out.to_str().unwrap(),

            "--kind",

            "tarball",

        ],

    );

    assert_ne!(code, 0);

    assert!(err.contains("runner-image"), "{err}");

    assert_eq!(oxy(&dir, &home, &["gc", "--now"]).0, 0);

    let (code, verified, err) = oxy(&dir, &home, &["artifact", "verify", &name[..8]]);

    assert_eq!(code, 0, "{err}");

    assert!(String::from_utf8_lossy(&verified).contains("2 files check out"));

    let back = tmp.path().join("back");

    assert_eq!(

        oxy(

            &dir,

            &home,

            &["artifact", "unpack", &name, back.to_str().unwrap()]

        )

        .0,

        0

    );

    assert_eq!(

        std::fs::read_to_string(back.join("bin/tool")).unwrap(),

        "#!/bin/sh\necho hi\n"

    );

}