use std::collections::BTreeMap;
use std::io::Write as _;
use std::path::{Path, PathBuf};
use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};
use sha2::{Digest as _, Sha256};
pub const MEDIA_TYPE_IMAGE_MANIFEST: &str = "application/vnd.oci.image.manifest.v1+json";
pub const ANNOTATION_REF_NAME: &str = "org.opencontainers.image.ref.name";
pub const ANNOTATION_TITLE: &str = "org.opencontainers.image.title";
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct Descriptor {
#[serde(rename = "mediaType")]
pub media_type: String,
pub digest: String,
pub size: i64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub urls: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub annotations: Option<BTreeMap<String, String>>,
#[serde(
rename = "artifactType",
default,
skip_serializing_if = "Option::is_none"
)]
pub artifact_type: Option<String>,
}
impl Descriptor {
pub fn annotation(&self, key: &str) -> Option<&str> {
self.annotations.as_ref()?.get(key).map(String::as_str)
}
}
#[derive(Debug, Serialize, Deserialize)]
pub struct Manifest {
#[serde(rename = "schemaVersion")]
pub schema_version: i32,
#[serde(rename = "mediaType")]
pub media_type: String,
#[serde(
rename = "artifactType",
default,
skip_serializing_if = "Option::is_none"
)]
pub artifact_type: Option<String>,
pub config: Descriptor,
pub layers: Vec<Descriptor>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub annotations: Option<BTreeMap<String, String>>,
}
pub const ARTIFACT_TYPE_MODEL_MANIFEST: &str = "application/vnd.cncf.model.manifest.v1+json";
pub const MEDIA_TYPE_MODEL_CONFIG: &str = "application/vnd.cncf.model.config.v1+json";
pub const MEDIA_TYPE_MODEL_WEIGHT_RAW: &str = "application/vnd.cncf.model.weight.v1.raw";
pub const MEDIA_TYPE_MODEL_WEIGHT_CONFIG_RAW: &str =
"application/vnd.cncf.model.weight.config.v1.raw";
pub const MEDIA_TYPE_MODEL_DOC_RAW: &str = "application/vnd.cncf.model.doc.v1.raw";
pub const MEDIA_TYPE_MODEL_CODE_RAW: &str = "application/vnd.cncf.model.code.v1.raw";
pub const ANNOTATION_FILEPATH: &str = "org.cncf.model.filepath";
#[derive(Serialize, Default)]
struct ModelDescriptor {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
licenses: Vec<String>,
#[serde(default, skip_serializing_if = "String::is_empty")]
revision: String,
}
#[derive(Serialize)]
struct ModelFS {
#[serde(rename = "type")]
kind: String,
#[serde(rename = "diffIds")]
diff_ids: Vec<String>,
}
#[derive(Serialize, Default)]
struct ModelCapabilities {
#[serde(rename = "inputTypes", default, skip_serializing_if = "Vec::is_empty")]
input_types: Vec<&'static str>,
#[serde(rename = "outputTypes", default, skip_serializing_if = "Vec::is_empty")]
output_types: Vec<&'static str>,
}
#[derive(Serialize, Default)]
struct ModelConfig {
#[serde(default, skip_serializing_if = "String::is_empty")]
format: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
capabilities: Option<ModelCapabilities>,
}
#[derive(Serialize)]
struct Model {
#[serde(rename = "descriptor")]
descriptor: ModelDescriptor,
modelfs: ModelFS,
#[serde(default, skip_serializing_if = "is_default_config")]
config: ModelConfig,
}
fn is_default_config(c: &ModelConfig) -> bool {
c.format.is_empty() && c.capabilities.is_none()
}
#[derive(Default)]
pub struct ModelMeta {
pub format: String,
pub licenses: Vec<String>,
pub vision: bool,
pub diffusion_outputs: Vec<&'static str>,
}
pub const ANNOTATION_ROLE: &str = "org.llmman.role";
pub const ANNOTATION_REVISION: &str = "org.llmman.revision";
pub fn build_cncf_manifest(
layout_dir: &Path,
meta: &ModelMeta,
model_repo: &str,
filepath_annotation: &str,
commit: &str,
layers: Vec<Descriptor>,
) -> Result<Descriptor> {
let model = Model {
descriptor: ModelDescriptor {
licenses: meta.licenses.clone(),
revision: commit.to_string(),
},
modelfs: ModelFS {
kind: "layers".to_string(),
diff_ids: layers.iter().map(|l| l.digest.clone()).collect(),
},
config: ModelConfig {
format: meta.format.clone(),
capabilities: if !meta.diffusion_outputs.is_empty() {
Some(ModelCapabilities {
input_types: vec!["text"],
output_types: meta.diffusion_outputs.clone(),
})
} else {
meta.vision.then(|| ModelCapabilities {
input_types: vec!["text", "image"],
output_types: vec!["text"],
})
},
},
};
let cfg_data = serde_json::to_vec(&model).context("marshal CNCF model config")?;
let config_desc = write_blob(layout_dir, MEDIA_TYPE_MODEL_CONFIG, &cfg_data)
.context("store CNCF model config")?;
let mut annotations = BTreeMap::new();
annotations.insert("ai.model.repo".to_string(), model_repo.to_string());
if !filepath_annotation.is_empty() {
annotations.insert(
ANNOTATION_FILEPATH.to_string(),
filepath_annotation.to_string(),
);
}
if !commit.is_empty() {
annotations.insert(ANNOTATION_REVISION.to_string(), commit.to_string());
}
let manifest = Manifest {
schema_version: 2,
media_type: MEDIA_TYPE_IMAGE_MANIFEST.to_string(),
artifact_type: Some(ARTIFACT_TYPE_MODEL_MANIFEST.to_string()),
config: config_desc,
layers,
annotations: Some(annotations),
};
let manifest_data = serde_json::to_vec(&manifest).context("marshal CNCF manifest")?;
write_blob(layout_dir, MEDIA_TYPE_IMAGE_MANIFEST, &manifest_data).context("store CNCF manifest")
}
fn next_counter() -> u64 {
static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
}
fn digest_to_path(layout_dir: &Path, digest: &str) -> Result<PathBuf> {
let (alg, hex) = digest
.split_once(':')
.with_context(|| format!("malformed digest {digest:?}"))?;
Ok(layout_dir.join("blobs").join(alg).join(hex))
}
pub fn blob_exists(layout_dir: &Path, desc: &Descriptor) -> bool {
match digest_to_path(layout_dir, &desc.digest) {
Ok(p) => std::fs::metadata(&p)
.map(|m| m.len() as i64 == desc.size)
.unwrap_or(false),
Err(_) => false,
}
}
pub fn read_blob(layout_dir: &Path, digest: &str) -> Result<Vec<u8>> {
std::fs::read(digest_to_path(layout_dir, digest)?).context("read blob")
}
pub fn write_blob(layout_dir: &Path, media_type: &str, data: &[u8]) -> Result<Descriptor> {
let digest = format!("sha256:{:x}", Sha256::digest(data));
let dir = layout_dir.join("blobs").join("sha256");
std::fs::create_dir_all(&dir)?;
let dest = dir.join(digest.trim_start_matches("sha256:"));
if let Ok(m) = std::fs::metadata(&dest) {
if m.len() as usize == data.len() {
return Ok(Descriptor {
media_type: media_type.to_string(),
digest,
size: data.len() as i64,
..Default::default()
});
}
}
let tmp = dir.join(format!("{}-{}.tmp", std::process::id(), next_counter()));
{
let mut f = std::fs::File::create(&tmp)?;
f.write_all(data)?;
}
std::fs::rename(&tmp, &dest)?;
Ok(Descriptor {
media_type: media_type.to_string(),
digest,
size: data.len() as i64,
..Default::default()
})
}
pub fn write_blob_from_file(
layout_dir: &Path,
media_type: &str,
path: &Path,
consume: bool,
) -> Result<Descriptor> {
let dir = layout_dir.join("blobs").join("sha256");
std::fs::create_dir_all(&dir)?;
let tmp = dir.join(format!("{}-{}.tmp", std::process::id(), next_counter()));
let mut source =
std::fs::File::open(path).with_context(|| format!("open {}", path.display()))?;
let ((size, hex), staged) = if consume {
let hashed = crate::fsutil::copy_hashing(&mut source, &mut std::io::sink())
.with_context(|| format!("hash {}", path.display()))?;
(hashed, path.to_path_buf())
} else {
let mut out = std::fs::File::create(&tmp)?;
let copied = crate::fsutil::copy_hashing(&mut source, &mut out)
.with_context(|| format!("copy {} into the blob store", path.display()));
drop(out);
match copied {
Ok(copied) => (copied, tmp.clone()),
Err(e) => {
let _ = std::fs::remove_file(&tmp);
return Err(e);
}
}
};
drop(source);
let digest = format!("sha256:{hex}");
let dest = dir.join(digest.trim_start_matches("sha256:"));
if dest.exists() {
let _ = std::fs::OpenOptions::new()
.write(true)
.open(&dest)
.and_then(|f| f.set_modified(std::time::SystemTime::now()));
} else {
match std::fs::rename(&staged, &dest) {
Ok(()) => {}
Err(_) if dest.exists() => {}
Err(e) => {
if !consume {
let _ = std::fs::remove_file(&tmp);
}
return Err(e).with_context(|| format!("publish blob for {}", path.display()));
}
}
}
if !consume {
let _ = std::fs::remove_file(&tmp);
}
Ok(Descriptor {
media_type: media_type.to_string(),
digest,
size: size as i64,
..Default::default()
})
}
fn manifest_ref_path(layout_dir: &Path, reference: &str) -> PathBuf {
crate::storage::oci::manifest_ref_path(layout_dir, reference)
}
pub fn read_manifest_ref(layout_dir: &Path, reference: &str) -> Result<Descriptor> {
for (i, path) in [
manifest_ref_path(layout_dir, reference),
crate::storage::oci::legacy_manifest_ref_path(layout_dir, reference),
]
.into_iter()
.enumerate()
{
match std::fs::read(path) {
Ok(data) => {
let desc: Descriptor = serde_json::from_slice(&data)?;
if desc
.annotations
.as_ref()
.and_then(|ann| ann.get(ANNOTATION_REF_NAME))
.is_some_and(|name| {
crate::storage::default_tag(name) == crate::storage::default_tag(reference)
})
{
return Ok(desc);
}
}
Err(err)
if err.kind() == std::io::ErrorKind::NotFound
|| (i == 1 && crate::storage::oci::missing_legacy_ref(&err)) =>
{
continue
}
Err(err) => return Err(err.into()),
}
}
Err(std::io::Error::from(std::io::ErrorKind::NotFound).into())
}
pub fn write_manifest_ref(
layout_dir: &Path,
reference: &str,
mut manifest_desc: Descriptor,
) -> Result<()> {
let mut ann = manifest_desc.annotations.clone().unwrap_or_default();
ann.insert(ANNOTATION_REF_NAME.to_string(), reference.to_string());
manifest_desc.annotations = Some(ann);
let path = manifest_ref_path(layout_dir, reference);
let dir = path.parent().context("manifest ref path has no parent")?;
std::fs::create_dir_all(dir)?;
let data = serde_json::to_vec_pretty(&manifest_desc)?;
let tmp = dir.join(format!(
"{}.{}-{}.tmp",
path.file_name().unwrap().to_string_lossy(),
std::process::id(),
next_counter()
));
std::fs::write(&tmp, &data)?;
std::fs::rename(&tmp, &path)?;
Ok(())
}
pub fn alias_manifest_ref(layout_dir: &Path, reference: &str, alias: &str) -> Result<()> {
if alias == reference {
return Ok(());
}
let desc = read_manifest_ref(layout_dir, reference)
.with_context(|| format!("read staged manifest for {reference}"))?;
write_manifest_ref(layout_dir, alias, desc)
}
pub fn ensure_layout(layout_dir: &Path) -> Result<()> {
std::fs::create_dir_all(layout_dir)?;
std::fs::create_dir_all(layout_dir.join("manifests-v2"))?;
let marker = layout_dir.join("oci-layout");
if !marker.exists() {
std::fs::write(marker, br#"{"imageLayoutVersion":"1.0.0"}"#)?;
}
Ok(())
}
pub fn cached_layer_name(layout_dir: &Path, reference: &str) -> Option<String> {
let m = read_manifest_ref(layout_dir, reference).ok()?;
if !blob_exists(layout_dir, &m) {
return None;
}
let data = read_blob(layout_dir, &m.digest).ok()?;
let manifest: Manifest = serde_json::from_slice(&data).ok()?;
for layer in &manifest.layers {
if !blob_exists(layout_dir, layer) {
return None;
}
}
if let Some(layer) = manifest.layers.first() {
for key in [ANNOTATION_FILEPATH, ANNOTATION_TITLE] {
if let Some(name) = layer.annotation(key) {
if !name.is_empty() {
return Path::new(name)
.file_name()
.map(|f| f.to_string_lossy().into_owned());
}
}
}
}
Some(reference.to_string())
}
pub fn report_cached(layout_dir: &Path, reference: &str) -> bool {
match cached_layer_name(layout_dir, reference) {
Some(name) => {
eprintln!("Cached {name}");
true
}
None => false,
}
}
#[cfg(test)]
pub(crate) fn read_manifest_and_config(
layout_dir: &Path,
reference: &str,
) -> (Manifest, serde_json::Value) {
let desc = read_manifest_ref(layout_dir, reference).unwrap();
let manifest: Manifest =
serde_json::from_slice(&read_blob(layout_dir, &desc.digest).unwrap()).unwrap();
let config: serde_json::Value =
serde_json::from_slice(&read_blob(layout_dir, &manifest.config.digest).unwrap()).unwrap();
(manifest, config)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn staged_manifest_is_visible_to_local_store() {
let dir = tempfile();
let reference = "reg.example:5000/ns/model:t";
let desc = Descriptor {
media_type: MEDIA_TYPE_IMAGE_MANIFEST.into(),
digest: "sha256:deadbeef".into(),
size: 12,
..Default::default()
};
write_manifest_ref(&dir, reference, desc).unwrap();
let store = crate::storage::oci::OciStore::open(&dir).unwrap();
assert_eq!(store.find(reference).unwrap().digest, "sha256:deadbeef");
}
#[test]
fn write_blob_then_read_blob_round_trips() {
let dir = tempfile();
let desc = write_blob(&dir, "text/plain", b"hello world").unwrap();
assert_eq!(desc.size, 11);
assert!(blob_exists(&dir, &desc));
assert_eq!(read_blob(&dir, &desc.digest).unwrap(), b"hello world");
}
#[test]
fn write_blob_from_file_moves_a_file_it_owns_and_copies_one_it_does_not() {
let dir = tempfile();
let src = dir.join("weights.safetensors");
std::fs::write(&src, b"weights").unwrap();
let copied = write_blob_from_file(&dir, MEDIA_TYPE_MODEL_WEIGHT_RAW, &src, false).unwrap();
assert_eq!(copied.size, 7);
assert!(
src.exists(),
"consume=false must leave a user's own file alone"
);
assert_eq!(read_blob(&dir, &copied.digest).unwrap(), b"weights");
let staged = dir.join("staged.part");
std::fs::write(&staged, b"weights").unwrap();
let moved = write_blob_from_file(&dir, MEDIA_TYPE_MODEL_WEIGHT_RAW, &staged, true).unwrap();
assert_eq!(moved.digest, copied.digest);
let staged2 = dir.join("staged2.part");
std::fs::write(&staged2, b"other weights").unwrap();
let moved2 =
write_blob_from_file(&dir, MEDIA_TYPE_MODEL_WEIGHT_RAW, &staged2, true).unwrap();
assert!(!staged2.exists(), "consume=true must move, not copy");
assert_eq!(read_blob(&dir, &moved2.digest).unwrap(), b"other weights");
std::fs::remove_dir_all(&dir).ok();
}
#[cfg(unix)]
#[test]
fn write_blob_from_file_leaves_no_staging_file_when_the_copy_fails() {
let dir = tempfile();
let src = dir.join("not-a-file");
std::fs::create_dir_all(&src).unwrap();
write_blob_from_file(&dir, MEDIA_TYPE_MODEL_WEIGHT_RAW, &src, false).unwrap_err();
let leftovers: Vec<_> = std::fs::read_dir(dir.join("blobs").join("sha256"))
.unwrap()
.map(|e| e.unwrap().file_name())
.collect();
assert!(leftovers.is_empty(), "{leftovers:?}");
std::fs::remove_dir_all(&dir).ok();
}
#[test]
fn alias_manifest_ref_makes_a_staged_pull_findable_under_another_name() {
let dir = tempfile();
ensure_layout(&dir).unwrap();
let desc = Descriptor {
media_type: MEDIA_TYPE_IMAGE_MANIFEST.to_string(),
digest: "sha256:abc".to_string(),
size: 3,
..Default::default()
};
write_manifest_ref(&dir, "s3://bucket/model:latest", desc).unwrap();
alias_manifest_ref(&dir, "s3://bucket/model:latest", "ghcr.io/me/model:v1").unwrap();
assert_eq!(
read_manifest_ref(&dir, "ghcr.io/me/model:v1")
.unwrap()
.digest,
"sha256:abc"
);
std::fs::remove_dir_all(&dir).ok();
}
#[test]
fn write_blob_is_idempotent() {
let dir = tempfile();
let d1 = write_blob(&dir, "text/plain", b"same content").unwrap();
let d2 = write_blob(&dir, "text/plain", b"same content").unwrap();
assert_eq!(d1.digest, d2.digest);
}
#[test]
fn manifest_ref_round_trips_and_records_ref_name_annotation() {
let dir = tempfile();
ensure_layout(&dir).unwrap();
let desc = Descriptor {
media_type: MEDIA_TYPE_IMAGE_MANIFEST.to_string(),
digest: "sha256:abc".to_string(),
size: 3,
..Default::default()
};
write_manifest_ref(&dir, "owner/repo:tag", desc).unwrap();
let got = read_manifest_ref(&dir, "owner/repo:tag").unwrap();
assert_eq!(got.annotation(ANNOTATION_REF_NAME), Some("owner/repo:tag"));
}
#[test]
fn legacy_ancestor_file_does_not_block_staged_ref() {
let dir = tempfile();
ensure_layout(&dir).unwrap();
let reference = "reg.example/ns/model/sub:t";
let ancestor =
crate::storage::oci::legacy_manifest_ref_path(&dir, "reg.example/ns/model:sub");
std::fs::create_dir_all(ancestor.parent().unwrap()).unwrap();
std::fs::write(&ancestor, b"another pointer").unwrap();
assert!(read_manifest_ref(&dir, reference).is_err());
let desc = Descriptor {
digest: "sha256:abc".into(),
..Default::default()
};
write_manifest_ref(&dir, reference, desc).unwrap();
assert_eq!(
read_manifest_ref(&dir, reference).unwrap().digest,
"sha256:abc"
);
assert_eq!(std::fs::read(&ancestor).unwrap(), b"another pointer");
std::fs::remove_dir_all(dir).unwrap();
}
#[cfg(unix)]
#[test]
fn long_opaque_key_ignores_unrepresentable_legacy_pointer() {
let dir = tempfile();
ensure_layout(&dir).unwrap();
let reference = format!("s3://bucket/{}", "a".repeat(256));
let legacy = crate::storage::oci::legacy_manifest_ref_path(&dir, &reference);
std::fs::create_dir_all(legacy.parent().unwrap().parent().unwrap()).unwrap();
assert!(read_manifest_ref(&dir, &reference).is_err());
write_manifest_ref(
&dir,
&reference,
Descriptor {
digest: "sha256:abc".into(),
..Default::default()
},
)
.unwrap();
assert_eq!(
read_manifest_ref(&dir, &reference).unwrap().digest,
"sha256:abc"
);
std::fs::remove_dir_all(dir).unwrap();
}
#[test]
fn cached_layer_name_is_none_when_nothing_cached() {
let dir = tempfile();
ensure_layout(&dir).unwrap();
assert!(cached_layer_name(&dir, "owner/repo:tag").is_none());
}
#[test]
fn cached_layer_name_returns_filename_once_fully_cached() {
let dir = tempfile();
ensure_layout(&dir).unwrap();
let layer = write_blob(&dir, MEDIA_TYPE_MODEL_WEIGHT_RAW, b"weights").unwrap();
let mut layer = layer;
layer.annotations = Some(BTreeMap::from([(
ANNOTATION_FILEPATH.to_string(),
"model.gguf".to_string(),
)]));
let manifest_desc = build_cncf_manifest(
&dir,
&ModelMeta {
format: "gguf".to_string(),
..Default::default()
},
"owner/repo",
"model.gguf",
"",
vec![layer],
)
.unwrap();
write_manifest_ref(&dir, "owner/repo:tag", manifest_desc).unwrap();
assert_eq!(
cached_layer_name(&dir, "owner/repo:tag").as_deref(),
Some("model.gguf")
);
}
fn manifest_and_config(dir: &Path, commit: &str) -> (Manifest, serde_json::Value) {
let layer = write_blob(dir, MEDIA_TYPE_MODEL_WEIGHT_RAW, b"weights").unwrap();
let desc = build_cncf_manifest(
dir,
&ModelMeta {
format: "gguf".to_string(),
..Default::default()
},
"owner/repo",
"model.gguf",
commit,
vec![layer],
)
.unwrap();
write_manifest_ref(dir, "owner/repo:tag", desc).unwrap();
read_manifest_and_config(dir, "owner/repo:tag")
}
#[test]
fn build_cncf_manifest_records_the_commit_in_config_and_annotation() {
let dir = tempfile();
ensure_layout(&dir).unwrap();
let commit = "7ae557604adf67be50417f59c2c2f167def9a775";
let (manifest, config) = manifest_and_config(&dir, commit);
assert_eq!(config["descriptor"]["revision"], commit);
assert_eq!(
manifest.annotations.as_ref().unwrap()[ANNOTATION_REVISION],
commit
);
let (manifest, config) = manifest_and_config(&dir, "");
assert!(config["descriptor"].get("revision").is_none());
assert!(!manifest
.annotations
.as_ref()
.unwrap()
.contains_key(ANNOTATION_REVISION));
std::fs::remove_dir_all(dir).unwrap();
}
fn tempfile() -> PathBuf {
let dir = std::env::temp_dir().join(format!(
"llmman-oci-test-{}-{}",
std::process::id(),
rand_suffix()
));
std::fs::create_dir_all(&dir).unwrap();
dir
}
fn rand_suffix() -> u64 {
use std::time::{SystemTime, UNIX_EPOCH};
SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos() as u64
}
}