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 bytes: Vec<u8>,
}
#[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 },
}
#[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 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)? {
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,
bytes: Vec::new(),
}
}
#[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");
}
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,
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);
}
}