#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![doc = "Versioned distribution contract schema for release-time tooling."]
#![doc = ""]
#![doc = "A `DistributionContract` describes one product's release layout once:"]
#![doc = "target triples, platform aliases, asset file names, checksum sidecar"]
#![doc = "names, archive members, and install names. It does not fetch releases,"]
#![doc = "order versions, verify checksums, extract archives, generate installers,"]
#![doc = "or become a runtime dependency of ordinary consumers."]
use std::collections::{HashMap, HashSet};
use std::fmt;
pub const SCHEMA_V1: u32 = 1;
const MAX_ID_LEN: usize = 64;
const MAX_NAME_LEN: usize = 128;
const MAX_TEMPLATE_LEN: usize = 256;
const MAX_DETAIL_LEN: usize = 512;
pub const MAX_OBSERVED_ENTRIES: usize = 256;
const MAX_CONFORMANCE_FINDINGS: usize = MAX_OBSERVED_ENTRIES * 2;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NameNamespace {
ReleaseFiles,
InstallNames,
}
impl fmt::Display for NameNamespace {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::ReleaseFiles => f.write_str("release-file"),
Self::InstallNames => f.write_str("install-name"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum DistError {
InvalidInput(String),
UnsupportedVersion {
found: u32,
},
DuplicateTarget(String),
DuplicateAlias(String),
UnknownTarget(String),
UnknownPlaceholder(String),
MissingInput(String),
InvalidMemberPath(String),
NameCollision {
namespace: NameNamespace,
first: String,
second: String,
},
InvalidReleaseInventory(String),
InvalidArchiveMemberInventory(String),
}
impl DistError {
fn invalid(detail: impl Into<String>) -> Self {
Self::InvalidInput(bound(detail.into()))
}
}
impl fmt::Display for DistError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidInput(d) => write!(f, "invalid distribution contract: {d}"),
Self::UnsupportedVersion { found } => {
write!(f, "unsupported distribution schema version: {found}")
}
Self::DuplicateTarget(t) => write!(f, "duplicate distribution target: {t}"),
Self::DuplicateAlias(a) => write!(f, "duplicate distribution alias: {a}"),
Self::UnknownTarget(t) => write!(f, "unsupported distribution target: {t}"),
Self::UnknownPlaceholder(p) => {
write!(f, "unknown name-template placeholder: {p}")
}
Self::MissingInput(m) => write!(f, "missing template input: {m}"),
Self::InvalidMemberPath(p) => write!(f, "unsafe archive member path: {p}"),
Self::NameCollision {
namespace,
first,
second,
} => write!(
f,
"expanded {namespace} filename collision between {first} and {second}"
),
Self::InvalidReleaseInventory(detail) => {
write!(f, "invalid release inventory: {detail}")
}
Self::InvalidArchiveMemberInventory(detail) => {
write!(f, "invalid archive member inventory: {detail}")
}
}
}
}
impl std::error::Error for DistError {}
fn bound(mut s: String) -> String {
if s.len() > MAX_DETAIL_LEN {
s.truncate(char_boundary_floor(&s, MAX_DETAIL_LEN));
}
s
}
fn char_boundary_floor(s: &str, limit: usize) -> usize {
let mut cut = limit;
while !s.is_char_boundary(cut) {
cut -= 1;
}
cut
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ProductIdentity {
pub id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub display_name: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ChecksumSpec {
pub sidecar: String,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BundleEntry {
pub asset: String,
pub install: String,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ArchiveMember {
pub source: String,
pub install: String,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AssetForm {
Direct {
asset: String,
install: String,
},
Bundle {
entries: Vec<BundleEntry>,
},
Archive {
asset: String,
members: Vec<ArchiveMember>,
},
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TargetEntry {
pub triple: String,
pub aliases: Vec<String>,
pub asset: AssetForm,
pub checksum: ChecksumSpec,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DistributionContract {
pub schema_version: u32,
pub product: ProductIdentity,
pub targets: Vec<TargetEntry>,
}
#[derive(Debug, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct RawContract {
schema_version: u32,
product: ProductIdentity,
targets: Vec<RawTarget>,
}
#[derive(Debug, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct RawTarget {
triple: String,
#[serde(default)]
aliases: Vec<String>,
asset: RawAsset,
checksum: ChecksumSpec,
}
#[derive(Debug, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct RawAsset {
kind: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
asset: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
install: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
entries: Option<Vec<BundleEntry>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
members: Option<Vec<ArchiveMember>>,
}
impl DistributionContract {
pub fn parse_toml_str(s: &str) -> Result<Self, DistError> {
let raw: RawContract =
toml::from_str(s).map_err(|e| DistError::invalid(format!("TOML parse: {e}")))?;
Self::from_raw(raw)
}
pub fn to_toml_string(&self) -> Result<String, DistError> {
let raw = self.to_raw();
toml::to_string(&raw).map_err(|e| DistError::invalid(format!("TOML render: {e}")))
}
pub fn resolve(&self, target_or_alias: &str) -> Result<&TargetEntry, DistError> {
for t in &self.targets {
if t.triple == target_or_alias {
return Ok(t);
}
if t.aliases.iter().any(|a| a == target_or_alias) {
return Ok(t);
}
}
Err(DistError::UnknownTarget(bound(target_or_alias.to_string())))
}
pub fn expand(
&self,
target_or_alias: &str,
version: &str,
) -> Result<ExpandedTarget, DistError> {
validate_version(version)?;
let target = self.resolve(target_or_alias)?;
let alias_used: Option<&str> = if target.triple == target_or_alias {
None
} else {
Some(target_or_alias)
};
let ctx = ExpansionCtx {
product: &self.product.id,
version,
target: &target.triple,
alias: alias_used,
};
let assets = match &target.asset {
AssetForm::Direct { asset, install } => {
let asset_file = expand_template(asset, &ctx, None)?;
let install_name = expand_template(install, &ctx, None)?;
let sidecar_file =
expand_template(&target.checksum.sidecar, &ctx, Some(&asset_file))?;
ExpandedAssets::Direct(ExpandedDirect {
asset_file,
install_name,
sidecar_file,
})
}
AssetForm::Bundle { entries } => {
let mut out = Vec::with_capacity(entries.len());
for e in entries {
let asset_file = expand_template(&e.asset, &ctx, None)?;
let install_name = expand_template(&e.install, &ctx, None)?;
let sidecar_file =
expand_template(&target.checksum.sidecar, &ctx, Some(&asset_file))?;
out.push(ExpandedDirect {
asset_file,
install_name,
sidecar_file,
});
}
ExpandedAssets::Bundle(ExpandedBundle { entries: out })
}
AssetForm::Archive { asset, members } => {
let archive_file = expand_template(asset, &ctx, None)?;
let sidecar_file =
expand_template(&target.checksum.sidecar, &ctx, Some(&archive_file))?;
let mut expanded_members = Vec::with_capacity(members.len());
for m in members {
let install_name = expand_template(&m.install, &ctx, None)?;
expanded_members.push(ExpandedArchiveMember {
source: m.source.clone(),
install_name,
});
}
ExpandedAssets::Archive(ExpandedArchive {
archive_file,
sidecar_file,
members: expanded_members,
})
}
};
let expanded = ExpandedTarget {
triple: target.triple.clone(),
assets,
};
validate_expanded_names(&expanded)?;
Ok(expanded)
}
fn from_raw(raw: RawContract) -> Result<Self, DistError> {
if raw.schema_version != SCHEMA_V1 {
return Err(DistError::UnsupportedVersion {
found: raw.schema_version,
});
}
validate_product_id(&raw.product.id)?;
if let Some(display) = &raw.product.display_name {
validate_display_name(display)?;
}
if raw.targets.is_empty() {
return Err(DistError::invalid("contract declares no targets"));
}
let all_triples: HashSet<&str> = raw.targets.iter().map(|t| t.triple.as_str()).collect();
{
let mut seen: HashSet<&str> = HashSet::new();
for t in &raw.targets {
if !seen.insert(t.triple.as_str()) {
return Err(DistError::DuplicateTarget(bound(t.triple.clone())));
}
}
}
let mut alias_owner: HashMap<&str, &str> = HashMap::new();
for t in &raw.targets {
validate_triple(&t.triple)?;
for a in &t.aliases {
validate_alias(a)?;
if all_triples.contains(a.as_str()) {
return Err(DistError::DuplicateAlias(bound(format!(
"{a} collides with a target triple"
))));
}
if let Some(owner) = alias_owner.get(a.as_str()) {
if *owner != t.triple.as_str() {
return Err(DistError::DuplicateAlias(bound(a.clone())));
}
} else {
alias_owner.insert(a.as_str(), t.triple.as_str());
}
}
}
let mut out_targets = Vec::with_capacity(raw.targets.len());
for t in raw.targets {
let asset = convert_asset(t.asset)?;
validate_checksum_template(&asset, &t.checksum.sidecar)?;
out_targets.push(TargetEntry {
triple: t.triple,
aliases: t.aliases,
asset,
checksum: t.checksum,
});
}
Ok(Self {
schema_version: SCHEMA_V1,
product: raw.product,
targets: out_targets,
})
}
fn to_raw(&self) -> RawContract {
let targets = self
.targets
.iter()
.map(|t| {
let (kind, asset, install, entries, members) = match &t.asset {
AssetForm::Direct { asset, install } => (
"direct".to_string(),
Some(asset.clone()),
Some(install.clone()),
None,
None,
),
AssetForm::Bundle { entries } => (
"bundle".to_string(),
None,
None,
Some(entries.clone()),
None,
),
AssetForm::Archive { asset, members } => (
"archive".to_string(),
Some(asset.clone()),
None,
None,
Some(members.clone()),
),
};
RawTarget {
triple: t.triple.clone(),
aliases: t.aliases.clone(),
asset: RawAsset {
kind,
asset,
install,
entries,
members,
},
checksum: t.checksum.clone(),
}
})
.collect();
RawContract {
schema_version: self.schema_version,
product: self.product.clone(),
targets,
}
}
}
fn convert_asset(raw: RawAsset) -> Result<AssetForm, DistError> {
match raw.kind.as_str() {
"direct" => {
let asset = raw
.asset
.ok_or_else(|| DistError::invalid("direct asset requires `asset`"))?;
let install = raw
.install
.ok_or_else(|| DistError::invalid("direct asset requires `install`"))?;
if raw.entries.is_some() || raw.members.is_some() {
return Err(DistError::invalid(
"direct asset must not declare `entries` or `members`",
));
}
validate_file_template(&asset, false)?;
validate_file_template(&install, false)?;
Ok(AssetForm::Direct { asset, install })
}
"bundle" => {
let entries = raw
.entries
.ok_or_else(|| DistError::invalid("bundle asset requires `entries`"))?;
if raw.asset.is_some() || raw.install.is_some() || raw.members.is_some() {
return Err(DistError::invalid(
"bundle asset must declare only `entries`",
));
}
if entries.is_empty() {
return Err(DistError::invalid("bundle asset declares no entries"));
}
if entries.len() > 64 {
return Err(DistError::invalid("bundle asset declares too many entries"));
}
for e in &entries {
validate_file_template(&e.asset, false)?;
validate_file_template(&e.install, false)?;
}
ensure_unique_raw_templates(
NameNamespace::ReleaseFiles,
entries
.iter()
.enumerate()
.map(|(i, e)| (e.asset.as_str(), format!("entries[{i}].asset"))),
)?;
ensure_unique_raw_templates(
NameNamespace::InstallNames,
entries
.iter()
.enumerate()
.map(|(i, e)| (e.install.as_str(), format!("entries[{i}].install"))),
)?;
Ok(AssetForm::Bundle { entries })
}
"archive" => {
let asset = raw
.asset
.ok_or_else(|| DistError::invalid("archive asset requires `asset`"))?;
let members = raw
.members
.ok_or_else(|| DistError::invalid("archive asset requires `members`"))?;
if raw.install.is_some() || raw.entries.is_some() {
return Err(DistError::invalid(
"archive asset must declare only `asset` and `members`",
));
}
validate_file_template(&asset, false)?;
if members.is_empty() {
return Err(DistError::invalid("archive asset declares no members"));
}
if members.len() > 64 {
return Err(DistError::invalid(
"archive asset declares too many members",
));
}
let mut seen: HashSet<String> = HashSet::new();
for m in &members {
validate_member_source(&m.source)?;
validate_file_template(&m.install, false)?;
if !seen.insert(m.source.to_ascii_lowercase()) {
return Err(DistError::invalid(format!(
"duplicate or ASCII-case-colliding archive member: {}",
m.source
)));
}
}
ensure_unique_raw_templates(
NameNamespace::InstallNames,
members
.iter()
.enumerate()
.map(|(i, m)| (m.install.as_str(), format!("members[{i}].install"))),
)?;
Ok(AssetForm::Archive { asset, members })
}
other => Err(DistError::invalid(format!(
"unknown asset kind: {other} (expected direct|bundle|archive)"
))),
}
}
fn is_safe_name_char(c: char) -> bool {
c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.'
}
fn validate_product_id(id: &str) -> Result<(), DistError> {
if id.is_empty() || id.len() > MAX_ID_LEN {
return Err(DistError::invalid("product id is empty or overlong"));
}
if id.chars().any(|c| c.is_control()) {
return Err(DistError::invalid("product id has control characters"));
}
if !id.chars().all(is_safe_name_char) {
return Err(DistError::invalid(
"product id must use [A-Za-z0-9-_.] only",
));
}
if id == "." || id == ".." {
return Err(DistError::invalid("product id must name a product"));
}
Ok(())
}
fn validate_display_name(name: &str) -> Result<(), DistError> {
if name.is_empty() || name.len() > 256 {
return Err(DistError::invalid("display name is empty or overlong"));
}
if name.chars().any(|c| c.is_control()) {
return Err(DistError::invalid("display name has control characters"));
}
Ok(())
}
fn validate_triple(triple: &str) -> Result<(), DistError> {
if triple.is_empty() || triple.len() > MAX_NAME_LEN {
return Err(DistError::invalid("target triple is empty or overlong"));
}
if triple.chars().any(|c| c.is_control()) {
return Err(DistError::invalid("target triple has control characters"));
}
if triple.contains(['/', '\\', ' ', '@', '?', '#', ':']) {
return Err(DistError::invalid(
"target triple must be a bare triple without separators",
));
}
if !triple.chars().all(is_safe_name_char) {
return Err(DistError::invalid(
"target triple must use [A-Za-z0-9-_.] only",
));
}
if !triple.contains('-') {
return Err(DistError::invalid(
"target triple must contain '-' (canonical Rust triple)",
));
}
Ok(())
}
fn validate_alias(alias: &str) -> Result<(), DistError> {
if alias.is_empty() || alias.len() > MAX_NAME_LEN {
return Err(DistError::invalid("alias is empty or overlong"));
}
if alias.chars().any(|c| c.is_control()) {
return Err(DistError::invalid("alias has control characters"));
}
if alias.contains(['/', '\\', ' ', '@', '?', '#', ':']) {
return Err(DistError::invalid("alias must not contain separators"));
}
if !alias.chars().all(is_safe_name_char) {
return Err(DistError::invalid("alias must use [A-Za-z0-9-_.] only"));
}
Ok(())
}
fn validate_version(version: &str) -> Result<(), DistError> {
if version.is_empty() || version.len() > MAX_NAME_LEN {
return Err(DistError::invalid(
"version is empty or overlong (opaque but filesystem-safe)",
));
}
if version.chars().any(|c| c.is_control()) {
return Err(DistError::invalid("version has control characters"));
}
if !version.chars().all(|c| is_safe_name_char(c) || c == '+') {
return Err(DistError::invalid("version must use [A-Za-z0-9-_.+] only"));
}
Ok(())
}
fn validate_file_template(template: &str, allow_asset: bool) -> Result<(), DistError> {
if template.is_empty() || template.len() > MAX_TEMPLATE_LEN {
return Err(DistError::invalid("name template is empty or overlong"));
}
if template.chars().any(|c| c.is_control()) {
return Err(DistError::invalid("name template has control characters"));
}
if template.contains(['/', '\\']) {
return Err(DistError::invalid(
"name template must be a flat file name without directories",
));
}
parse_template(template, allow_asset)?;
Ok(())
}
fn validate_checksum_template(_asset: &AssetForm, sidecar: &str) -> Result<(), DistError> {
validate_file_template(sidecar, true)
}
fn validate_member_source(source: &str) -> Result<(), DistError> {
if source.is_empty() || source.len() > MAX_TEMPLATE_LEN {
return Err(DistError::InvalidMemberPath(bound(
"member path is empty or overlong".to_string(),
)));
}
if source.chars().any(|c| c.is_control()) {
return Err(DistError::InvalidMemberPath(bound(
"member path has control characters".to_string(),
)));
}
if source.contains('{') || source.contains('}') {
return Err(DistError::InvalidMemberPath(bound(
"member source must be literal (no templates)".to_string(),
)));
}
if source.contains('\\') {
return Err(DistError::InvalidMemberPath(bound(
"member path must use '/' separators".to_string(),
)));
}
if source.starts_with('/') {
return Err(DistError::InvalidMemberPath(bound(format!(
"absolute member path: {source}"
))));
}
if source.contains(':') {
return Err(DistError::InvalidMemberPath(bound(format!(
"member path must not contain drive prefixes: {source}"
))));
}
for comp in source.split('/') {
if comp.is_empty() {
return Err(DistError::InvalidMemberPath(bound(format!(
"empty member path component: {source}"
))));
}
if comp == "." || comp == ".." {
return Err(DistError::InvalidMemberPath(bound(format!(
"member path escapes root: {source}"
))));
}
}
Ok(())
}
#[derive(Debug, Clone, Copy)]
enum Placeholder {
Product,
Version,
Target,
Alias,
Asset,
}
enum TemplatePart<'a> {
Literal(&'a str),
Placeholder(Placeholder),
}
fn parse_template(template: &str, allow_asset: bool) -> Result<Vec<TemplatePart<'_>>, DistError> {
let bytes = template.as_bytes();
let mut parts = Vec::new();
let mut cursor = 0;
let mut i = 0;
while i < bytes.len() {
match bytes[i] {
b'{' => {
if cursor < i {
parts.push(TemplatePart::Literal(&template[cursor..i]));
}
let Some(relative_end) = template[i + 1..].find('}') else {
return Err(DistError::invalid(
"unmatched opening brace in name template",
));
};
let end = i + 1 + relative_end;
let name = &template[i + 1..end];
if name.is_empty() {
return Err(DistError::invalid("empty placeholder in name template"));
}
if name.contains(['{', '}']) {
return Err(DistError::invalid("nested braces in name template"));
}
if !name.bytes().all(|b| b.is_ascii_alphanumeric()) {
return Err(DistError::invalid("malformed placeholder in name template"));
}
let placeholder = match name {
"product" => Placeholder::Product,
"version" => Placeholder::Version,
"target" => Placeholder::Target,
"alias" => Placeholder::Alias,
"asset" if allow_asset => Placeholder::Asset,
_ => return Err(DistError::UnknownPlaceholder(bound(name.to_string()))),
};
parts.push(TemplatePart::Placeholder(placeholder));
i = end + 1;
cursor = i;
}
b'}' => return Err(DistError::invalid("stray closing brace in name template")),
byte => {
if !is_safe_name_char(char::from(byte)) {
return Err(DistError::invalid(
"name template literal must use [A-Za-z0-9-_.] only",
));
}
i += 1;
}
}
}
if cursor < bytes.len() {
parts.push(TemplatePart::Literal(&template[cursor..]));
}
Ok(parts)
}
struct ExpansionCtx<'a> {
product: &'a str,
version: &'a str,
target: &'a str,
alias: Option<&'a str>,
}
fn expand_template(
template: &str,
ctx: &ExpansionCtx<'_>,
asset: Option<&str>,
) -> Result<String, DistError> {
let parts = parse_template(template, asset.is_some())?;
let mut out = String::with_capacity(template.len());
for part in parts {
match part {
TemplatePart::Literal(literal) => out.push_str(literal),
TemplatePart::Placeholder(Placeholder::Product) => out.push_str(ctx.product),
TemplatePart::Placeholder(Placeholder::Version) => out.push_str(ctx.version),
TemplatePart::Placeholder(Placeholder::Target) => out.push_str(ctx.target),
TemplatePart::Placeholder(Placeholder::Alias) => {
let alias = ctx.alias.ok_or_else(|| {
DistError::MissingInput(bound(
"`{alias}` requires lookup via that alias".to_string(),
))
})?;
out.push_str(alias);
}
TemplatePart::Placeholder(Placeholder::Asset) => {
let asset = asset.ok_or_else(|| {
DistError::MissingInput(bound(
"`{asset}` requires a checksum context".to_string(),
))
})?;
out.push_str(asset);
}
}
}
if out.is_empty() || out.len() > MAX_TEMPLATE_LEN {
return Err(DistError::invalid("expanded name is empty or overlong"));
}
if out.contains(['{', '}']) {
return Err(DistError::invalid("expanded name contains reserved braces"));
}
if out.contains(['/', '\\']) {
return Err(DistError::invalid(
"expanded name must remain a flat file name",
));
}
Ok(out)
}
fn ensure_unique_names(
namespace: NameNamespace,
names: impl IntoIterator<Item = (String, String)>,
) -> Result<(), DistError> {
let mut seen: HashMap<String, String> = HashMap::new();
for (name, field) in names {
let key = name.to_ascii_lowercase();
if let Some(first) = seen.get(&key) {
return Err(DistError::NameCollision {
namespace,
first: bound(first.clone()),
second: bound(field),
});
}
seen.insert(key, field);
}
Ok(())
}
fn ensure_unique_raw_templates<'a>(
namespace: NameNamespace,
templates: impl IntoIterator<Item = (&'a str, String)>,
) -> Result<(), DistError> {
ensure_unique_names(
namespace,
templates
.into_iter()
.map(|(template, field)| (template.to_string(), field)),
)
}
fn validate_expanded_names(target: &ExpandedTarget) -> Result<(), DistError> {
let mut release_names = Vec::new();
let mut install_names = Vec::new();
match &target.assets {
ExpandedAssets::Direct(direct) => {
release_names.push((direct.asset_file.clone(), "asset_file".to_string()));
release_names.push((direct.sidecar_file.clone(), "sidecar_file".to_string()));
install_names.push((direct.install_name.clone(), "install_name".to_string()));
}
ExpandedAssets::Bundle(bundle) => {
for (index, entry) in bundle.entries.iter().enumerate() {
release_names.push((
entry.asset_file.clone(),
format!("entries[{index}].asset_file"),
));
release_names.push((
entry.sidecar_file.clone(),
format!("entries[{index}].sidecar_file"),
));
install_names.push((
entry.install_name.clone(),
format!("entries[{index}].install_name"),
));
}
}
ExpandedAssets::Archive(archive) => {
release_names.push((archive.archive_file.clone(), "archive_file".to_string()));
release_names.push((archive.sidecar_file.clone(), "sidecar_file".to_string()));
for (index, member) in archive.members.iter().enumerate() {
install_names.push((
member.install_name.clone(),
format!("members[{index}].install_name"),
));
}
}
}
ensure_unique_names(NameNamespace::ReleaseFiles, release_names)?;
ensure_unique_names(NameNamespace::InstallNames, install_names)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExpandedDirect {
pub asset_file: String,
pub install_name: String,
pub sidecar_file: String,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExpandedBundle {
pub entries: Vec<ExpandedDirect>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExpandedArchiveMember {
pub source: String,
pub install_name: String,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExpandedArchive {
pub archive_file: String,
pub sidecar_file: String,
pub members: Vec<ExpandedArchiveMember>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ExpandedAssets {
Direct(ExpandedDirect),
Bundle(ExpandedBundle),
Archive(ExpandedArchive),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExpandedTarget {
pub triple: String,
pub assets: ExpandedAssets,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum ExtrasPolicy {
#[default]
AllowExtras,
Exact,
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, serde::Serialize)]
pub struct ExpectedReleaseFile {
pub label: String,
pub file_name: String,
}
pub fn expected_release_files(
contract: &DistributionContract,
target_or_alias: &str,
version: &str,
) -> Result<Vec<ExpectedReleaseFile>, DistError> {
let expanded = contract.expand(target_or_alias, version)?;
let mut files = Vec::new();
match expanded.assets {
ExpandedAssets::Direct(direct) => {
files.push(expected_file("asset", direct.asset_file));
files.push(expected_file("sidecar", direct.sidecar_file));
}
ExpandedAssets::Bundle(bundle) => {
for (index, entry) in bundle.entries.into_iter().enumerate() {
files.push(expected_file(
&format!("entries[{index}].asset"),
entry.asset_file,
));
files.push(expected_file(
&format!("entries[{index}].sidecar"),
entry.sidecar_file,
));
}
}
ExpandedAssets::Archive(archive) => {
files.push(expected_file("archive", archive.archive_file));
files.push(expected_file("sidecar", archive.sidecar_file));
}
}
Ok(files)
}
fn expected_file(label: &str, file_name: String) -> ExpectedReleaseFile {
ExpectedReleaseFile {
label: label.to_string(),
file_name,
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReleaseInventory {
files: Vec<String>,
}
impl ReleaseInventory {
pub fn new<I, S>(files: I) -> Result<Self, DistError>
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
let mut names = Vec::new();
let mut seen = HashSet::new();
for value in files {
if names.len() == MAX_OBSERVED_ENTRIES {
return Err(DistError::InvalidReleaseInventory(bound(format!(
"more than {MAX_OBSERVED_ENTRIES} entries"
))));
}
let name = value.into();
validate_observed_flat_name(&name)
.map_err(|detail| DistError::InvalidReleaseInventory(bound(detail)))?;
let key = name.to_ascii_lowercase();
if !seen.insert(key) {
return Err(DistError::InvalidReleaseInventory(bound(format!(
"duplicate or ASCII-case-colliding filename: {name}"
))));
}
names.push(name);
}
names.sort();
Ok(Self { files: names })
}
pub fn files(&self) -> &[String] {
&self.files
}
}
fn validate_observed_flat_name(name: &str) -> Result<(), String> {
if name.is_empty() || name.len() > MAX_TEMPLATE_LEN {
return Err("filename is empty or overlong".to_string());
}
if name.chars().any(|c| c.is_control()) {
return Err("filename contains control characters".to_string());
}
if name.contains(['/', '\\']) {
return Err("filename must be flat and contain no path separators".to_string());
}
Ok(())
}
pub fn validate_release_inventory(
expected: &[ExpectedReleaseFile],
observed: &ReleaseInventory,
extras: ExtrasPolicy,
) -> ConformanceReport {
if expected.len() > MAX_OBSERVED_ENTRIES
|| expected.iter().any(|file| {
file.label.is_empty()
|| file.label.len() > MAX_DETAIL_LEN
|| validate_observed_flat_name(&file.file_name).is_err()
})
{
return ConformanceReport::new(vec![ConformanceFinding::new(
FindingKind::InvalidObservation,
"expected release files",
None,
Some("invalid or over limit"),
)]);
}
let mut expected_names = HashSet::new();
if expected
.iter()
.any(|file| !expected_names.insert(file.file_name.to_ascii_lowercase()))
{
return ConformanceReport::new(vec![ConformanceFinding::new(
FindingKind::InvalidObservation,
"expected release files",
None,
Some("duplicate or ASCII-case-colliding expected filename"),
)]);
}
let required: HashSet<&str> = expected.iter().map(|f| f.file_name.as_str()).collect();
let observed_set: HashSet<&str> = observed.files.iter().map(String::as_str).collect();
let mut findings = Vec::new();
for file in expected {
if !observed_set.contains(file.file_name.as_str()) {
findings.push(ConformanceFinding::new(
FindingKind::MissingReleaseFile,
&file.label,
Some(&file.file_name),
None,
));
}
}
if extras == ExtrasPolicy::Exact {
for name in &observed.files {
if !required.contains(name.as_str()) {
findings.push(ConformanceFinding::new(
FindingKind::UnexpectedReleaseFile,
"release inventory",
None,
Some(name),
));
}
}
}
ConformanceReport::new(findings)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArchiveMemberInventory {
members: Vec<String>,
}
impl ArchiveMemberInventory {
pub fn new<I, S>(members: I) -> Result<Self, DistError>
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
let mut paths = Vec::new();
let mut seen = HashSet::new();
for value in members {
if paths.len() == MAX_OBSERVED_ENTRIES {
return Err(DistError::InvalidArchiveMemberInventory(bound(format!(
"more than {MAX_OBSERVED_ENTRIES} entries"
))));
}
let path = value.into();
validate_member_source(&path).map_err(|error| {
DistError::InvalidArchiveMemberInventory(bound(error.to_string()))
})?;
let key = path.to_ascii_lowercase();
if !seen.insert(key) {
return Err(DistError::InvalidArchiveMemberInventory(bound(format!(
"duplicate or ASCII-case-colliding member path: {path}"
))));
}
paths.push(path);
}
paths.sort();
Ok(Self { members: paths })
}
pub fn members(&self) -> &[String] {
&self.members
}
}
pub fn validate_archive_member_inventory(
expected: &ExpandedTarget,
observed: &ArchiveMemberInventory,
extras: ExtrasPolicy,
) -> Result<ConformanceReport, DistError> {
let ExpandedAssets::Archive(archive) = &expected.assets else {
return Err(DistError::invalid(
"archive member validation requires an archive target",
));
};
if archive.members.len() > MAX_OBSERVED_ENTRIES
|| archive
.members
.iter()
.any(|member| validate_member_source(&member.source).is_err())
{
return Ok(ConformanceReport::new(vec![ConformanceFinding::new(
FindingKind::InvalidObservation,
"expected archive members",
None,
Some("invalid or over limit"),
)]));
}
let required: HashSet<&str> = archive.members.iter().map(|m| m.source.as_str()).collect();
let observed_set: HashSet<&str> = observed.members.iter().map(String::as_str).collect();
let mut findings = Vec::new();
for member in &archive.members {
if !observed_set.contains(member.source.as_str()) {
findings.push(ConformanceFinding::new(
FindingKind::MissingArchiveMember,
&member.source,
Some(&member.source),
None,
));
}
}
if extras == ExtrasPolicy::Exact {
for path in &observed.members {
if !required.contains(path.as_str()) {
findings.push(ConformanceFinding::new(
FindingKind::UnexpectedArchiveMember,
"archive inventory",
None,
Some(path),
));
}
}
}
Ok(ConformanceReport::new(findings))
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservedDirectMapping {
pub asset_file: String,
pub sidecar_file: String,
pub install_name: String,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservedArchiveMapping {
pub source: String,
pub install_name: String,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum ObservedTargetAssets {
Direct(ObservedDirectMapping),
Bundle {
entries: Vec<ObservedDirectMapping>,
},
Archive {
archive_file: String,
sidecar_file: String,
members: Vec<ObservedArchiveMapping>,
},
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ObservedTargetMapping {
pub target: String,
pub canonical_target: String,
pub assets: ObservedTargetAssets,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, serde::Serialize)]
#[serde(rename_all = "snake_case")]
pub enum FindingKind {
MissingReleaseFile,
UnexpectedReleaseFile,
TargetMismatch,
AssetMismatch,
SidecarMismatch,
InstallNameMismatch,
MissingArchiveMember,
UnexpectedArchiveMember,
ArchiveMappingMismatch,
InvalidObservation,
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, serde::Serialize)]
pub struct ConformanceFinding {
pub kind: FindingKind,
pub label: String,
pub expected: Option<String>,
pub observed: Option<String>,
}
impl ConformanceFinding {
fn new(kind: FindingKind, label: &str, expected: Option<&str>, observed: Option<&str>) -> Self {
Self {
kind,
label: bound(label.to_string()),
expected: expected.map(|value| bound(value.to_string())),
observed: observed.map(|value| bound(value.to_string())),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct ConformanceReport {
pub findings: Vec<ConformanceFinding>,
pub truncated: bool,
}
impl ConformanceReport {
fn new(mut findings: Vec<ConformanceFinding>) -> Self {
findings.sort();
let truncated = findings.len() > MAX_CONFORMANCE_FINDINGS;
findings.truncate(MAX_CONFORMANCE_FINDINGS);
Self {
findings,
truncated,
}
}
pub fn is_conformant(&self) -> bool {
self.findings.is_empty()
}
pub fn into_result(self) -> Result<(), Self> {
if self.is_conformant() {
Ok(())
} else {
Err(self)
}
}
}
pub fn validate_observed_mapping(
contract: &DistributionContract,
version: &str,
observed: &ObservedTargetMapping,
) -> ConformanceReport {
if !valid_observation(observed) {
return ConformanceReport::new(vec![ConformanceFinding::new(
FindingKind::InvalidObservation,
"observation",
None,
Some("invalid or over limit"),
)]);
}
let expected = match contract.expand(&observed.target, version) {
Ok(expanded) => expanded,
Err(DistError::UnknownTarget(_)) => {
return ConformanceReport::new(vec![ConformanceFinding::new(
FindingKind::TargetMismatch,
"target",
Some("declared target or alias"),
Some(&observed.target),
)]);
}
Err(error) => {
return ConformanceReport::new(vec![ConformanceFinding::new(
FindingKind::InvalidObservation,
"expansion",
Some(version),
Some(&error.to_string()),
)]);
}
};
let mut findings = Vec::new();
if expected.triple != observed.canonical_target {
findings.push(ConformanceFinding::new(
FindingKind::TargetMismatch,
"canonical target",
Some(&expected.triple),
Some(&observed.canonical_target),
));
}
compare_observed_assets(&expected.assets, &observed.assets, &mut findings);
ConformanceReport::new(findings)
}
fn valid_observation(observed: &ObservedTargetMapping) -> bool {
if observed.target.is_empty()
|| observed.target.len() > MAX_NAME_LEN
|| observed.canonical_target.is_empty()
|| observed.canonical_target.len() > MAX_NAME_LEN
|| observed.target.chars().any(char::is_control)
|| observed.canonical_target.chars().any(char::is_control)
{
return false;
}
let mut count = 0usize;
let valid_names = |count: &mut usize, names: &[&str]| {
*count = (*count).saturating_add(names.len());
*count <= MAX_OBSERVED_ENTRIES
&& names
.iter()
.all(|name| validate_observed_flat_name(name).is_ok())
};
match &observed.assets {
ObservedTargetAssets::Direct(entry) => {
valid_names(
&mut count,
&[&entry.asset_file, &entry.sidecar_file, &entry.install_name],
) && unique_ascii_names(&[&entry.asset_file, &entry.sidecar_file])
}
ObservedTargetAssets::Bundle { entries } => {
let fields_valid = entries.iter().all(|entry| {
valid_names(
&mut count,
&[&entry.asset_file, &entry.sidecar_file, &entry.install_name],
)
});
let release_files: Vec<&str> = entries
.iter()
.flat_map(|entry| [&entry.asset_file[..], &entry.sidecar_file[..]])
.collect();
fields_valid && unique_ascii_names(&release_files)
}
ObservedTargetAssets::Archive {
archive_file,
sidecar_file,
members,
} => {
if !valid_names(&mut count, &[archive_file, sidecar_file]) {
return false;
}
let mut seen = HashSet::new();
let fields_valid = members.iter().all(|member| {
count = count.saturating_add(2);
count <= MAX_OBSERVED_ENTRIES
&& validate_member_source(&member.source).is_ok()
&& validate_observed_flat_name(&member.install_name).is_ok()
&& seen.insert(member.source.to_ascii_lowercase())
});
fields_valid && unique_ascii_names(&[archive_file, sidecar_file])
}
}
}
fn unique_ascii_names(names: &[&str]) -> bool {
let mut seen = HashSet::new();
names
.iter()
.all(|name| seen.insert(name.to_ascii_lowercase()))
}
fn compare_observed_assets(
expected: &ExpandedAssets,
observed: &ObservedTargetAssets,
findings: &mut Vec<ConformanceFinding>,
) {
match (expected, observed) {
(ExpandedAssets::Direct(expected), ObservedTargetAssets::Direct(observed)) => {
compare_names(
FindingKind::AssetMismatch,
"asset",
&[expected.asset_file.as_str()],
&[observed.asset_file.as_str()],
findings,
);
compare_names(
FindingKind::SidecarMismatch,
"sidecar",
&[expected.sidecar_file.as_str()],
&[observed.sidecar_file.as_str()],
findings,
);
compare_names(
FindingKind::InstallNameMismatch,
"install",
&[expected.install_name.as_str()],
&[observed.install_name.as_str()],
findings,
);
}
(ExpandedAssets::Bundle(expected), ObservedTargetAssets::Bundle { entries }) => {
let mut expected = expected.entries.iter().collect::<Vec<_>>();
let mut observed = entries.iter().collect::<Vec<_>>();
expected.sort_by(|a, b| a.asset_file.cmp(&b.asset_file));
observed.sort_by(|a, b| a.asset_file.cmp(&b.asset_file));
for (index, (expected, observed)) in expected.iter().zip(observed.iter()).enumerate() {
let label = format!("bundle entries[{index}]");
compare_names(
FindingKind::AssetMismatch,
&format!("{label} asset"),
&[expected.asset_file.as_str()],
&[observed.asset_file.as_str()],
findings,
);
compare_names(
FindingKind::SidecarMismatch,
&format!("{label} sidecar"),
&[expected.sidecar_file.as_str()],
&[observed.sidecar_file.as_str()],
findings,
);
compare_names(
FindingKind::InstallNameMismatch,
&format!("{label} install"),
&[expected.install_name.as_str()],
&[observed.install_name.as_str()],
findings,
);
}
if expected.len() != observed.len() {
let expected_assets = expected
.iter()
.map(|entry| entry.asset_file.as_str())
.collect::<Vec<_>>();
let observed_assets = observed
.iter()
.map(|entry| entry.asset_file.as_str())
.collect::<Vec<_>>();
compare_names(
FindingKind::AssetMismatch,
"bundle entry count",
&expected_assets,
&observed_assets,
findings,
);
}
}
(
ExpandedAssets::Archive(expected),
ObservedTargetAssets::Archive {
archive_file,
sidecar_file,
members,
},
) => {
compare_names(
FindingKind::AssetMismatch,
"archive asset",
&[expected.archive_file.as_str()],
&[archive_file.as_str()],
findings,
);
compare_names(
FindingKind::SidecarMismatch,
"archive sidecar",
&[expected.sidecar_file.as_str()],
&[sidecar_file.as_str()],
findings,
);
let expected_members: HashMap<&str, &str> = expected
.members
.iter()
.map(|member| (member.source.as_str(), member.install_name.as_str()))
.collect();
let observed_members: HashMap<&str, &str> = members
.iter()
.map(|member| (member.source.as_str(), member.install_name.as_str()))
.collect();
let mut sources: Vec<&str> = expected_members
.keys()
.chain(observed_members.keys())
.copied()
.collect();
sources.sort_unstable();
sources.dedup();
for source in sources {
let expected_install = expected_members.get(source).copied();
let observed_install = observed_members.get(source).copied();
if expected_install != observed_install {
findings.push(ConformanceFinding::new(
FindingKind::ArchiveMappingMismatch,
source,
expected_install,
observed_install,
));
}
}
}
(expected, observed) => findings.push(ConformanceFinding::new(
FindingKind::AssetMismatch,
"asset form",
Some(asset_form_name(expected)),
Some(observed_form_name(observed)),
)),
}
}
fn compare_names(
kind: FindingKind,
label: &str,
expected: &[&str],
observed: &[&str],
findings: &mut Vec<ConformanceFinding>,
) {
let mut expected = expected.to_vec();
let mut observed = observed.to_vec();
expected.sort();
observed.sort();
for index in 0..expected.len().max(observed.len()) {
let expected_value = expected.get(index).copied();
let observed_value = observed.get(index).copied();
if expected_value != observed_value {
findings.push(ConformanceFinding::new(
kind,
label,
expected_value,
observed_value,
));
}
}
}
fn asset_form_name(assets: &ExpandedAssets) -> &'static str {
match assets {
ExpandedAssets::Direct(_) => "direct",
ExpandedAssets::Bundle(_) => "bundle",
ExpandedAssets::Archive(_) => "archive",
}
}
fn observed_form_name(assets: &ObservedTargetAssets) -> &'static str {
match assets {
ObservedTargetAssets::Direct(_) => "direct",
ObservedTargetAssets::Bundle { .. } => "bundle",
ObservedTargetAssets::Archive { .. } => "archive",
}
}
#[cfg(test)]
mod tests {
use super::*;
const SIMPLE: &str = r#"
schema_version = 1
[product]
id = "eggsact"
[[targets]]
triple = "x86_64-unknown-linux-gnu"
aliases = ["linux-x64"]
[targets.asset]
kind = "direct"
asset = "{product}-{version}-{target}"
install = "{product}"
[targets.checksum]
sidecar = "{asset}.sha256"
"#;
const BUNDLE: &str = r#"
schema_version = 1
[product]
id = "codegg"
[[targets]]
triple = "x86_64-unknown-linux-gnu"
aliases = []
[targets.asset]
kind = "bundle"
[[targets.asset.entries]]
asset = "{product}-{version}-{target}"
install = "{product}"
[[targets.asset.entries]]
asset = "{product}-helper-{version}-{target}"
install = "{product}-helper"
[[targets.asset.entries]]
asset = "{product}-manifest-{version}.json"
install = "{product}-manifest.json"
[targets.checksum]
sidecar = "{asset}.sha256"
"#;
const ARCHIVE: &str = r#"
schema_version = 1
[product]
id = "egress"
[[targets]]
triple = "aarch64-apple-darwin"
aliases = ["macos-arm64"]
[targets.asset]
kind = "archive"
asset = "{product}-{version}-{target}.tar.gz"
[[targets.asset.members]]
source = "egress"
install = "egress"
[[targets.asset.members]]
source = "bin/egress-helper"
install = "egress-helper"
[targets.checksum]
sidecar = "{asset}.sha256"
"#;
fn bundle_with(
asset0: &str,
asset1: &str,
install0: &str,
install1: &str,
sidecar: &str,
) -> Result<DistributionContract, DistError> {
let source = BUNDLE
.replacen(
"asset = \"{product}-{version}-{target}\"",
&format!("asset = \"{asset0}\""),
1,
)
.replacen(
"asset = \"{product}-helper-{version}-{target}\"",
&format!("asset = \"{asset1}\""),
1,
)
.replacen(
"install = \"{product}\"",
&format!("install = \"{install0}\""),
1,
)
.replacen(
"install = \"{product}-helper\"",
&format!("install = \"{install1}\""),
1,
)
.replace(
"sidecar = \"{asset}.sha256\"",
&format!("sidecar = \"{sidecar}\""),
);
DistributionContract::parse_toml_str(&source)
}
fn archive_with(install0: &str, install1: &str) -> Result<DistributionContract, DistError> {
let source = ARCHIVE
.replacen(
"install = \"egress\"",
&format!("install = \"{install0}\""),
1,
)
.replacen(
"install = \"egress-helper\"",
&format!("install = \"{install1}\""),
1,
);
DistributionContract::parse_toml_str(&source)
}
#[test]
fn parse_minimal_valid_v1() {
let c = DistributionContract::parse_toml_str(SIMPLE).unwrap();
assert_eq!(c.schema_version, 1);
assert_eq!(c.product.id, "eggsact");
assert_eq!(c.targets.len(), 1);
}
#[test]
fn unknown_schema_version_fails_typed() {
let s = SIMPLE.replace("schema_version = 1", "schema_version = 2");
let err = DistributionContract::parse_toml_str(&s).unwrap_err();
assert!(matches!(err, DistError::UnsupportedVersion { found: 2 }));
}
#[test]
fn duplicate_target_is_rejected() {
let s = format!("{SIMPLE}\n[[targets]]\ntriple = \"x86_64-unknown-linux-gnu\"\n[targets.asset]\nkind = \"direct\"\nasset = \"a\"\ninstall = \"b\"\n[targets.checksum]\nsidecar = \"{{asset}}.sha256\"\n");
let err = DistributionContract::parse_toml_str(&s).unwrap_err();
assert!(matches!(err, DistError::DuplicateTarget(_)));
}
#[test]
fn duplicate_alias_is_rejected() {
let s = r#"
schema_version = 1
[product]
id = "p"
[[targets]]
triple = "x86_64-unknown-linux-gnu"
aliases = ["same"]
[targets.asset]
kind = "direct"
asset = "a"
install = "b"
[targets.checksum]
sidecar = "{asset}.sha256"
[[targets]]
triple = "aarch64-apple-darwin"
aliases = ["same"]
[targets.asset]
kind = "direct"
asset = "a"
install = "b"
[targets.checksum]
sidecar = "{asset}.sha256"
"#;
let err = DistributionContract::parse_toml_str(s).unwrap_err();
assert!(matches!(err, DistError::DuplicateAlias(_)));
}
#[test]
fn alias_colliding_with_triple_is_rejected() {
let s = r#"
schema_version = 1
[product]
id = "p"
[[targets]]
triple = "x86_64-unknown-linux-gnu"
aliases = ["aarch64-apple-darwin"]
[targets.asset]
kind = "direct"
asset = "a"
install = "b"
[targets.checksum]
sidecar = "{asset}.sha256"
[[targets]]
triple = "aarch64-apple-darwin"
aliases = []
[targets.asset]
kind = "direct"
asset = "a"
install = "b"
[targets.checksum]
sidecar = "{asset}.sha256"
"#;
let err = DistributionContract::parse_toml_str(s).unwrap_err();
assert!(matches!(err, DistError::DuplicateAlias(_)));
}
#[test]
fn unsupported_target_lookup_fails_without_guessing() {
let c = DistributionContract::parse_toml_str(SIMPLE).unwrap();
let err = c.resolve("riscv64-unknown-linux-gnu").unwrap_err();
assert!(matches!(err, DistError::UnknownTarget(_)));
assert!(c.resolve("linux-x64").is_ok());
assert!(c.resolve("linux-arm64").is_err());
}
#[test]
fn bound_never_splits_a_character_or_panics() {
for padding in [
MAX_DETAIL_LEN - 1,
MAX_DETAIL_LEN,
MAX_DETAIL_LEN + 5,
MAX_DETAIL_LEN * 3,
] {
let detail = format!("{}é", "x".repeat(padding));
assert!(
detail.len() > MAX_DETAIL_LEN,
"fixture must exceed the bound"
);
let bounded = bound(detail.clone());
assert!(bounded.len() <= MAX_DETAIL_LEN, "bound is not a byte bound");
assert!(detail.starts_with(&bounded), "bound must be a prefix");
let rendered = DistError::invalid(detail).to_string();
assert!(rendered.starts_with("invalid distribution contract: "));
}
let c = DistributionContract::parse_toml_str(SIMPLE).unwrap();
let unknown = format!("{}é", "riscv64-unknown-linux-gnu-".repeat(12));
assert!(c.resolve(&unknown).is_err());
}
#[test]
fn unknown_placeholder_is_rejected() {
let s = SIMPLE.replace("{product}-{version}-{target}", "{product}-{env}-x");
let err = DistributionContract::parse_toml_str(&s).unwrap_err();
assert!(matches!(err, DistError::UnknownPlaceholder(_)));
}
#[test]
fn malformed_template_grammar_is_rejected_during_parse() {
for bad in [
"{product",
"product}",
"{}",
"{product{version}}",
"{ bad}",
"{{product}}",
"file name",
"{asset}",
] {
let source = SIMPLE.replace(
"asset = \"{product}-{version}-{target}\"",
&format!("asset = \"{bad}\""),
);
assert!(
DistributionContract::parse_toml_str(&source).is_err(),
"accepted malformed template {bad:?}"
);
}
}
#[test]
fn repeated_known_placeholders_remain_valid() {
let source = SIMPLE.replace(
"asset = \"{product}-{version}-{target}\"",
"asset = \"{product}-{product}-{version}\"",
);
let contract = DistributionContract::parse_toml_str(&source).unwrap();
let expanded = contract
.expand("x86_64-unknown-linux-gnu", "1.2.3")
.unwrap();
match expanded.assets {
ExpandedAssets::Direct(direct) => {
assert_eq!(direct.asset_file, "eggsact-eggsact-1.2.3")
}
_ => panic!("expected direct"),
}
}
#[test]
fn bundle_expansion_rejects_release_asset_and_sidecar_collisions() {
let contract = bundle_with("same", "same", "app", "helper", "{asset}.sha256")
.expect_err("identical raw assets should fail early");
assert!(matches!(
contract,
DistError::NameCollision {
namespace: NameNamespace::ReleaseFiles,
..
}
));
let contract =
bundle_with("{version}", "1.2.3", "app", "helper", "{asset}.sha256").unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "1.2.3"),
Err(DistError::NameCollision {
namespace: NameNamespace::ReleaseFiles,
..
})
));
let contract = bundle_with("one", "two", "app", "helper", "constant.sha256").unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "1.2.3"),
Err(DistError::NameCollision {
namespace: NameNamespace::ReleaseFiles,
..
})
));
let contract = bundle_with("first", "second", "app", "helper", "first").unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "1.2.3"),
Err(DistError::NameCollision {
namespace: NameNamespace::ReleaseFiles,
..
})
));
}
#[test]
fn direct_and_archive_asset_sidecar_collisions_are_rejected() {
let direct = SIMPLE.replace(
"sidecar = \"{asset}.sha256\"",
"sidecar = \"{product}-{version}-{target}\"",
);
let contract = DistributionContract::parse_toml_str(&direct).unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "1.2.3"),
Err(DistError::NameCollision {
namespace: NameNamespace::ReleaseFiles,
..
})
));
let archive = ARCHIVE.replace("sidecar = \"{asset}.sha256\"", "sidecar = \"{asset}\"");
let contract = DistributionContract::parse_toml_str(&archive).unwrap();
assert!(matches!(
contract.expand("aarch64-apple-darwin", "1.2.3"),
Err(DistError::NameCollision {
namespace: NameNamespace::ReleaseFiles,
..
})
));
}
#[test]
fn bundle_and_archive_install_names_must_be_unique_and_portable() {
let contract = bundle_with("one", "two", "same", "same", "{asset}.sha256")
.expect_err("identical raw install names should fail early");
assert!(matches!(
contract,
DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
}
));
let contract = bundle_with("one", "two", "App", "app", "{asset}.sha256")
.expect_err("ASCII case-only raw install names should fail early");
assert!(matches!(
contract,
DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
}
));
let contract = bundle_with("one", "two", "{version}", "APP", "{asset}.sha256").unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "app"),
Err(DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
})
));
let contract = bundle_with(
"one",
"two",
"member-{version}",
"member-1.2.3",
"{asset}.sha256",
)
.unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "1.2.3"),
Err(DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
})
));
let contract = archive_with("tool", "tool").expect_err("duplicate archive install name");
assert!(matches!(
contract,
DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
}
));
let contract = archive_with("Tool", "tool")
.expect_err("ASCII case-only raw archive install names should fail early");
assert!(matches!(
contract,
DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
}
));
let contract = archive_with("{version}", "TOOL").unwrap();
assert!(matches!(
contract.expand("aarch64-apple-darwin", "tool"),
Err(DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
})
));
}
#[test]
fn release_and_install_case_only_collisions_are_rejected() {
let source = SIMPLE.replace(
"sidecar = \"{asset}.sha256\"",
"sidecar = \"EGGSACT-1.2.3-X86_64-UNKNOWN-LINUX-GNU\"",
);
let contract = DistributionContract::parse_toml_str(&source).unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "1.2.3"),
Err(DistError::NameCollision {
namespace: NameNamespace::ReleaseFiles,
..
})
));
let contract = bundle_with("one", "two", "{version}", "APP", "{asset}.sha256").unwrap();
assert!(matches!(
contract.expand("x86_64-unknown-linux-gnu", "app"),
Err(DistError::NameCollision {
namespace: NameNamespace::InstallNames,
..
})
));
}
#[test]
fn missing_alias_input_fails() {
let c = DistributionContract::parse_toml_str(
&SIMPLE.replace("install = \"{product}\"", "install = \"{alias}\""),
)
.unwrap();
let err = c.expand("x86_64-unknown-linux-gnu", "1.0.0").unwrap_err();
assert!(matches!(err, DistError::MissingInput(_)));
let ok = c.expand("linux-x64", "1.0.0").unwrap();
match ok.assets {
ExpandedAssets::Direct(d) => assert_eq!(d.install_name, "linux-x64"),
_ => panic!("expected direct"),
}
}
#[test]
fn direct_single_member_expansion() {
let c = DistributionContract::parse_toml_str(SIMPLE).unwrap();
let e = c.expand("x86_64-unknown-linux-gnu", "1.2.6").unwrap();
match e.assets {
ExpandedAssets::Direct(d) => {
assert_eq!(d.asset_file, "eggsact-1.2.6-x86_64-unknown-linux-gnu");
assert_eq!(d.install_name, "eggsact");
assert_eq!(
d.sidecar_file,
"eggsact-1.2.6-x86_64-unknown-linux-gnu.sha256"
);
}
_ => panic!("expected direct"),
}
}
#[test]
fn multi_direct_bundle_expansion() {
let c = DistributionContract::parse_toml_str(BUNDLE).unwrap();
let e = c.expand("x86_64-unknown-linux-gnu", "0.9.0").unwrap();
match e.assets {
ExpandedAssets::Bundle(b) => {
assert_eq!(b.entries.len(), 3);
assert_eq!(
b.entries[0].asset_file,
"codegg-0.9.0-x86_64-unknown-linux-gnu"
);
assert_eq!(b.entries[1].install_name, "codegg-helper");
assert_eq!(b.entries[2].asset_file, "codegg-manifest-0.9.0.json");
assert!(b.entries[0].sidecar_file.ends_with(".sha256"));
}
_ => panic!("expected bundle"),
}
}
#[test]
fn archive_asset_expansion() {
let c = DistributionContract::parse_toml_str(ARCHIVE).unwrap();
let e = c.expand("macos-arm64", "2.1.0").unwrap();
assert_eq!(e.triple, "aarch64-apple-darwin");
match e.assets {
ExpandedAssets::Archive(a) => {
assert_eq!(a.archive_file, "egress-2.1.0-aarch64-apple-darwin.tar.gz");
assert_eq!(
a.sidecar_file,
"egress-2.1.0-aarch64-apple-darwin.tar.gz.sha256"
);
assert_eq!(a.members.len(), 2);
assert_eq!(a.members[0].source, "egress");
assert_eq!(a.members[1].source, "bin/egress-helper");
}
_ => panic!("expected archive"),
}
}
#[test]
fn archive_member_absolute_path_is_rejected() {
let s = ARCHIVE.replace("source = \"egress\"", "source = \"/egress\"");
let err = DistributionContract::parse_toml_str(&s).unwrap_err();
assert!(matches!(err, DistError::InvalidMemberPath(_)));
}
#[test]
fn archive_member_traversal_is_rejected() {
for bad in ["../evil", "a/../../b", "a/../b", "bin/..", ".", ".."] {
let s = ARCHIVE.replace("source = \"egress\"", &format!("source = \"{bad}\""));
let err = DistributionContract::parse_toml_str(&s).unwrap_err();
assert!(matches!(err, DistError::InvalidMemberPath(_)), "{bad}");
}
}
#[test]
fn duplicate_normalized_archive_members_rejected() {
let s = ARCHIVE.replace("source = \"bin/egress-helper\"", "source = \"egress\"");
let err = DistributionContract::parse_toml_str(&s).unwrap_err();
assert!(matches!(err, DistError::InvalidInput(_)));
let cased = ARCHIVE.replace("source = \"bin/egress-helper\"", "source = \"EGRESS\"");
let err = DistributionContract::parse_toml_str(&cased).unwrap_err();
assert!(
matches!(&err, DistError::InvalidInput(detail) if detail.contains("case-colliding")),
"{err}"
);
assert!(DistributionContract::parse_toml_str(ARCHIVE).is_ok());
}
#[test]
fn expanded_release_names_are_acceptable_to_every_supported_platform() {
let c = DistributionContract::parse_toml_str(SIMPLE).unwrap();
for good in [
"1.2.3",
"v1.2.3-rc.1",
"1.2.3-rc.1+build.5",
"nightly_2026-10-05",
] {
let e = c.expand("x86_64-unknown-linux-gnu", good).unwrap();
let ExpandedAssets::Direct(direct) = e.assets else {
panic!("expected direct");
};
for name in [
&direct.asset_file,
&direct.sidecar_file,
&direct.install_name,
] {
assert!(
name.chars().all(|c| is_safe_name_char(c) || c == '+'),
"release id {good} expanded to unportable name {name}"
);
}
}
for bad in [
"1.0.0:beta",
"1.0.0*",
"1.0.0?",
"1.0.0\"x",
"1.0.0<x",
"1.0.0>x",
"1.0.0|x",
"1.0.0 x",
"a/b",
"a\\b",
"",
"../evil",
] {
assert!(
c.expand("x86_64-unknown-linux-gnu", bad).is_err(),
"release id {bad:?} must fail closed"
);
}
}
#[test]
fn checksum_sidecar_naming_is_explicit() {
let c = DistributionContract::parse_toml_str(SIMPLE).unwrap();
let e = c.expand("linux-x64", "1.0.0").unwrap();
match e.assets {
ExpandedAssets::Direct(d) => {
assert!(d.sidecar_file.contains(&d.asset_file));
assert!(!d.sidecar_file.contains("signature"));
}
_ => panic!("expected direct"),
}
}
#[test]
fn product_version_is_opaque_but_filesystem_safe() {
let c = DistributionContract::parse_toml_str(SIMPLE).unwrap();
let e = c.expand("x86_64-unknown-linux-gnu", "1.2.6-rc.1").unwrap();
match e.assets {
ExpandedAssets::Direct(d) => assert!(d.asset_file.contains("1.2.6-rc.1")),
_ => panic!("expected direct"),
}
assert!(c.expand("x86_64-unknown-linux-gnu", "../evil").is_err());
assert!(c.expand("x86_64-unknown-linux-gnu", "a/b").is_err());
assert!(c.expand("x86_64-unknown-linux-gnu", "").is_err());
}
#[test]
fn deterministic_round_trip_golden() {
for fixture in [SIMPLE, BUNDLE, ARCHIVE] {
let c = DistributionContract::parse_toml_str(fixture).unwrap();
let rendered = c.to_toml_string().unwrap();
let reparsed = DistributionContract::parse_toml_str(&rendered).unwrap();
assert_eq!(c, reparsed);
assert_eq!(rendered, reparsed.to_toml_string().unwrap());
}
}
#[test]
fn unknown_fields_are_rejected() {
let s = SIMPLE.replace(
"[product]\nid = \"eggsact\"",
"[product]\nid = \"eggsact\"\ntypo_field = 1",
);
assert!(DistributionContract::parse_toml_str(&s).is_err());
}
}