use crate::layerspec::DocsFormat;
use crate::sdkexport::{Member, MemberBody, SdkExportError, read_members};
use std::path::Path;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DocsPayload {
pub name: String,
pub version: String,
pub format: DocsFormat,
pub entry: Option<String>,
pub title: Option<String>,
pub documents: Option<String>,
pub bytes: Vec<u8>,
}
impl DocsPayload {
pub fn from_signed(
annotations: &std::collections::BTreeMap<String, String>,
bytes: Vec<u8>,
) -> Result<DocsPayload, DocsExportError> {
let get = |k: &str| annotations.get(k).cloned();
let name = get("eu.pulseengine.tool").unwrap_or_else(|| "(unnamed)".into());
let format = match annotations.get(crate::deposit::ANN_DOCS_FORMAT) {
None => {
return Err(DocsExportError::Unreadable {
name,
detail: format!(
"it carries no {} annotation — it was deposited without the gate that \
requires one, so there is no way to tell how to open it",
crate::deposit::ANN_DOCS_FORMAT
),
});
}
Some(raw) => DocsFormat::parse(raw).ok_or_else(|| DocsExportError::Unreadable {
name: name.clone(),
detail: format!(
"it declares the documentation format {raw:?}, which this build does not \
know. The document is carried and verified; a newer varve may open it"
),
})?,
};
Ok(DocsPayload {
version: get("eu.pulseengine.tool.version").unwrap_or_default(),
format,
entry: get(crate::deposit::ANN_DOCS_ENTRY),
title: get(crate::deposit::ANN_DOCS_TITLE),
documents: get(crate::deposit::ANN_DOCS_DOCUMENTS),
name,
bytes,
})
}
}
#[derive(Debug, thiserror::Error)]
pub enum DocsExportError {
#[error("{name}: {source}")]
Archive {
name: String,
#[source]
source: SdkExportError,
},
#[error("cannot write {path}: {source}")]
Io {
path: String,
#[source]
source: std::io::Error,
},
#[error(
"this layer carries no documentation named {asked:?}. It carries: {carried}. \
`varve inspect` lists every payload."
)]
NoSuchDocument { asked: String, carried: String },
#[error(
"this layer carries {n} documents and none was named: {carried}. Name one — \
a selector is only optional where there is nothing to choose between."
)]
Ambiguous { n: usize, carried: String },
#[error(
"nothing in this layer documents {asked:?}. Documented: {documented}. \
`varve inspect` shows what each document documents."
)]
NothingDocuments { asked: String, documented: String },
#[error("{n} documents in this layer document {asked:?}: {carried}. Name one with --select.")]
AmbiguousFor {
asked: String,
n: usize,
carried: String,
},
#[error("docs payload {name:?} cannot be opened: {detail}")]
Unreadable { name: String, detail: String },
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct DocsExportReport {
pub files: usize,
pub dirs: usize,
pub entry_path: Option<String>,
}
pub fn select<'a>(
payloads: &'a [DocsPayload],
asked: Option<&str>,
) -> Result<&'a DocsPayload, DocsExportError> {
let carried = || {
let mut names: Vec<&str> = payloads.iter().map(|p| p.name.as_str()).collect();
names.sort_unstable();
if names.is_empty() {
"nothing".to_string()
} else {
names.join(", ")
}
};
match asked {
Some(name) => payloads.iter().find(|p| p.name == name).ok_or_else(|| {
DocsExportError::NoSuchDocument {
asked: name.to_string(),
carried: carried(),
}
}),
None => match payloads {
[only] => Ok(only),
many => Err(DocsExportError::Ambiguous {
n: many.len(),
carried: carried(),
}),
},
}
}
pub fn select_for<'a>(
payloads: &'a [DocsPayload],
asked: &str,
) -> Result<&'a DocsPayload, DocsExportError> {
let hits: Vec<&DocsPayload> = payloads
.iter()
.filter(|p| p.documents.as_deref() == Some(asked))
.collect();
match hits.as_slice() {
[only] => Ok(only),
[] => {
let mut documented: Vec<&str> = payloads
.iter()
.filter_map(|p| p.documents.as_deref())
.collect();
documented.sort_unstable();
documented.dedup();
Err(DocsExportError::NothingDocuments {
asked: asked.to_string(),
documented: if documented.is_empty() {
"nothing — no document in this layer names a payload".to_string()
} else {
documented.join(", ")
},
})
}
many => {
let mut names: Vec<&str> = many.iter().map(|p| p.name.as_str()).collect();
names.sort_unstable();
Err(DocsExportError::AmbiguousFor {
asked: asked.to_string(),
n: many.len(),
carried: names.join(", "),
})
}
}
}
pub fn read_one(payload: &DocsPayload, path: &str) -> Result<Option<Vec<u8>>, DocsExportError> {
if !payload.format.is_tree() {
return Ok(None);
}
let want = path.trim_start_matches('/');
let members = members_of(payload)?;
Ok(members.into_iter().find_map(|m| match m.body {
MemberBody::File { bytes, .. } if rel_path(&m.path, want) => Some(bytes),
_ => None,
}))
}
pub fn export(payload: &DocsPayload, out: &Path) -> Result<DocsExportReport, DocsExportError> {
let io = |path: &Path, source: std::io::Error| DocsExportError::Io {
path: path.display().to_string(),
source,
};
std::fs::create_dir_all(out).map_err(|e| io(out, e))?;
let mut report = DocsExportReport::default();
if !payload.format.is_tree() {
let ext = payload
.format
.file_extension()
.expect("a non-tree format names an extension");
let file = out.join(format!("{}-{}.{ext}", payload.name, payload.version));
std::fs::write(&file, &payload.bytes).map_err(|e| io(&file, e))?;
report.files = 1;
report.entry_path = Some(file.display().to_string());
return Ok(report);
}
for m in members_of(payload)? {
if matches!(m.body, MemberBody::Dir) && crate::sdkexport::names_archive_root(&m.path) {
continue;
}
let rel = crate::sdkexport::safe_member_path(&m.path).map_err(|source| {
DocsExportError::Archive {
name: payload.name.clone(),
source,
}
})?;
let dest = out.join(&rel);
match m.body {
MemberBody::Dir => {
std::fs::create_dir_all(&dest).map_err(|e| io(&dest, e))?;
report.dirs += 1;
}
MemberBody::File { bytes, .. } => {
if let Some(parent) = dest.parent() {
std::fs::create_dir_all(parent).map_err(|e| io(parent, e))?;
}
std::fs::write(&dest, &bytes).map_err(|e| io(&dest, e))?;
report.files += 1;
}
MemberBody::Symlink { .. } => {}
}
}
report.entry_path = payload
.entry
.as_deref()
.map(|e| out.join(e).display().to_string());
Ok(report)
}
pub fn members_of(payload: &DocsPayload) -> Result<Vec<Member>, DocsExportError> {
read_members(&payload.bytes).map_err(|source| DocsExportError::Archive {
name: payload.name.clone(),
source,
})
}
fn rel_path(member: &str, want: &str) -> bool {
let m = member.trim_start_matches("./");
m == want
}
#[cfg(test)]
mod tests {
use super::*;
fn payload(name: &str, format: DocsFormat) -> DocsPayload {
DocsPayload {
name: name.into(),
version: "0.1.0".into(),
format,
entry: Some("index.html".into()),
title: None,
documents: None,
bytes: Vec::new(),
}
}
fn documenting(name: &str, documents: &str) -> DocsPayload {
DocsPayload {
documents: Some(documents.into()),
..payload(name, DocsFormat::Rustdoc)
}
}
#[test]
fn a_reader_can_ask_for_the_documentation_of_a_payload() {
let docs = vec![
payload("varve-core", DocsFormat::Html),
documenting("varve-core-api", "varve-core"),
documenting("varve-api", "varve"),
];
assert_eq!(
select_for(&docs, "varve-core").expect("selects").name,
"varve-core-api"
);
assert_eq!(
select_for(&docs, "varve").expect("selects").name,
"varve-api"
);
}
#[test]
fn asking_for_an_undocumented_payload_names_what_is_documented() {
let docs = vec![
payload("handbook", DocsFormat::Pdf),
documenting("varve-core-api", "varve-core"),
];
let e = select_for(&docs, "serde").expect_err("must refuse");
assert!(
matches!(e, DocsExportError::NothingDocuments { .. }),
"{e:?}"
);
let msg = e.to_string();
assert!(msg.contains("serde"), "{msg}");
assert!(msg.contains("varve-core"), "{msg}");
assert!(
!msg.contains("handbook"),
"a document of nothing is not an answer: {msg}"
);
}
#[test]
fn two_documents_of_one_payload_refuse_rather_than_guess() {
let docs = vec![
documenting("varve-core-api", "varve-core"),
documenting("varve-core-guide", "varve-core"),
];
let e = select_for(&docs, "varve-core").expect_err("must refuse");
assert!(
matches!(e, DocsExportError::AmbiguousFor { n: 2, .. }),
"{e:?}"
);
assert!(e.to_string().contains("varve-core-api"), "{e}");
assert!(e.to_string().contains("varve-core-guide"), "{e}");
}
#[test]
fn a_payload_is_read_from_its_signed_annotations() {
let mut ann = std::collections::BTreeMap::new();
ann.insert(
"eu.pulseengine.tool".to_string(),
"varve-core-api".to_string(),
);
ann.insert(
"eu.pulseengine.tool.version".to_string(),
"0.36.0".to_string(),
);
ann.insert(
crate::deposit::ANN_DOCS_FORMAT.to_string(),
"rustdoc".to_string(),
);
ann.insert(
crate::deposit::ANN_DOCS_ENTRY.to_string(),
"varve_core/index.html".to_string(),
);
ann.insert(
crate::deposit::ANN_DOCS_TITLE.to_string(),
"API".to_string(),
);
ann.insert(
crate::deposit::ANN_DOCS_DOCUMENTS.to_string(),
"varve-core".to_string(),
);
let p = DocsPayload::from_signed(&ann, b"bytes".to_vec()).expect("reads");
assert_eq!(p.name, "varve-core-api");
assert_eq!(p.version, "0.36.0");
assert_eq!(p.format, DocsFormat::Rustdoc);
assert_eq!(p.entry.as_deref(), Some("varve_core/index.html"));
assert_eq!(p.title.as_deref(), Some("API"));
assert_eq!(p.documents.as_deref(), Some("varve-core"));
assert_eq!(p.bytes, b"bytes");
ann.insert(
crate::deposit::ANN_DOCS_FORMAT.to_string(),
"epub".to_string(),
);
let e = DocsPayload::from_signed(&ann, Vec::new()).expect_err("unknown format");
assert!(e.to_string().contains("epub"), "{e}");
ann.remove(crate::deposit::ANN_DOCS_FORMAT);
let e = DocsPayload::from_signed(&ann, Vec::new()).expect_err("no format");
assert!(e.to_string().contains("varve-core-api"), "{e}");
}
#[test]
fn a_single_document_needs_no_selector() {
let one = vec![payload("traceability", DocsFormat::Html)];
assert_eq!(select(&one, None).expect("selects").name, "traceability");
}
#[test]
fn several_documents_and_no_selector_refuses_rather_than_guessing() {
let many = vec![
payload("traceability", DocsFormat::Html),
payload("handbook", DocsFormat::Pdf),
];
let e = select(&many, None).expect_err("must refuse");
assert!(
matches!(e, DocsExportError::Ambiguous { n: 2, .. }),
"{e:?}"
);
assert!(e.to_string().contains("handbook"), "{e}");
assert!(e.to_string().contains("traceability"), "{e}");
}
#[test]
fn an_unknown_name_reports_what_the_layer_does_carry() {
let one = vec![payload("traceability", DocsFormat::Html)];
let e = select(&one, Some("handbok")).expect_err("must refuse");
assert!(e.to_string().contains("traceability"), "{e}");
}
#[test]
fn a_subdirectory_namesake_is_not_the_root_file() {
assert!(rel_path("./index.html", "index.html"));
assert!(!rel_path("./eu-ai-act/index.html", "index.html"));
assert!(rel_path("./eu-ai-act/index.html", "eu-ai-act/index.html"));
}
#[test]
fn a_tree_document_exports_and_names_its_starting_page() {
use std::io::Write;
let mut tar_bytes = Vec::new();
{
let mut b = tar::Builder::new(&mut tar_bytes);
{
let mut d = tar::Header::new_gnu();
d.set_size(0);
d.set_mode(0o755);
d.set_entry_type(tar::EntryType::Directory);
d.set_cksum();
b.append_data(&mut d, "./sub/", std::io::empty())
.expect("append dir");
}
{
let mut d = tar::Header::new_gnu();
d.set_size(0);
d.set_mode(0o755);
d.set_entry_type(tar::EntryType::Directory);
d.set_cksum();
b.append_data(&mut d, "./", std::io::empty())
.expect("append root");
}
for (path, body) in [
("./index.html", "<h1>root</h1>"),
("./eu-ai-act/index.html", "<h1>not the root</h1>"),
] {
let mut h = tar::Header::new_gnu();
h.set_size(body.len() as u64);
h.set_mode(0o644);
h.set_cksum();
b.append_data(&mut h, path, body.as_bytes())
.expect("append");
}
b.finish().expect("finish");
}
let mut gz = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast());
gz.write_all(&tar_bytes).expect("compress");
let bytes = gz.finish().expect("finish gz");
let doc = DocsPayload {
name: "traceability".into(),
version: "0.34.3".into(),
format: DocsFormat::Html,
entry: Some("index.html".into()),
title: None,
documents: None,
bytes,
};
let dir = std::env::temp_dir().join(format!("varve-docs-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
let report = export(&doc, &dir).expect("exports");
assert_eq!(report.files, 2);
assert_eq!(
report.dirs, 1,
"the tar carries one directory entry (./sub/), and it must be counted"
);
let entry = report.entry_path.expect("names an entry");
assert!(entry.ends_with("index.html"), "{entry}");
assert_eq!(
std::fs::read_to_string(&entry).expect("entry exists on disk"),
"<h1>root</h1>",
"the entry must be the ROOT page, not the namesake one directory down"
);
let served = read_one(&doc, "index.html")
.expect("reads")
.expect("present");
assert_eq!(served, b"<h1>root</h1>");
assert_eq!(
read_one(&doc, "nope.html").expect("reads"),
None,
"a missing page is None, not an error"
);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_single_file_document_has_no_inner_paths() {
let pdf = payload("handbook", DocsFormat::Pdf);
assert_eq!(read_one(&pdf, "index.html").expect("no error"), None);
}
}