use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum McardUriType {
Hash,
Handle,
}
pub type McardUriKind = McardUriType;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ParsedMcardUri {
pub uri_type: McardUriType,
pub target: String,
pub fragment: Option<String>,
pub original: String,
}
pub type McardUri = ParsedMcardUri;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransclusionCycleError {
pub cycle_path: Vec<String>,
}
impl std::fmt::Display for TransclusionCycleError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "Transclusion cycle detected: {}", self.cycle_path.join(" -> "))
}
}
impl std::error::Error for TransclusionCycleError {}
pub fn canonicalize_mcard_uri(path: &str, context_prefix: &str) -> String {
let clean = path.trim_start_matches('/');
let mut prefix = context_prefix.trim_matches('/');
if prefix == "mcard" {
prefix = "";
}
if let Some(rest) = clean.strip_prefix("mcard:") {
let rest = rest.trim_start_matches('/');
if prefix.is_empty() || rest == prefix || rest.starts_with(&format!("{prefix}/")) {
return format!("mcard:{rest}");
}
return format!("mcard:{prefix}/{rest}");
}
if prefix.is_empty() {
format!("mcard:{clean}")
} else {
format!("mcard:{prefix}/{clean}")
}
}
const DIGEST_HEX_LENGTH: [(&str, usize); 8] = [
("blake3", 64),
("sha256", 64),
("sha3-256", 64),
("sha384", 96),
("sha512", 128),
("sha224", 56),
("sha1", 40),
("md5", 32),
];
pub fn digest_target(value: &str) -> Option<String> {
let (algo, hex) = value.split_once(':')?;
let algo = algo.to_ascii_lowercase();
let hex = hex.to_ascii_lowercase();
let expected = DIGEST_HEX_LENGTH
.iter()
.find(|(name, _)| *name == algo.as_str())
.map(|(_, len)| *len)?;
if hex.len() != expected || !hex.chars().all(|c| c.is_ascii_hexdigit()) {
return None;
}
Some(format!("{algo}:{hex}"))
}
pub fn is_qualified_hash(value: &str) -> bool {
digest_target(value).is_some()
}
pub fn format_mcard_uri(parsed: &ParsedMcardUri) -> String {
let frag = parsed
.fragment
.as_ref()
.map(|f| format!("#{}", f.trim_start_matches('#')))
.unwrap_or_default();
let kind = match parsed.uri_type {
McardUriType::Hash => "hash",
McardUriType::Handle => "handle",
};
format!("mcard://{kind}/{}{frag}", parsed.target)
}
pub fn parse_mcard_uri(uri: &str) -> std::result::Result<ParsedMcardUri, String> {
if uri.is_empty() {
return Err("Invalid MCard URI: expected non-empty string".to_string());
}
let (base, fragment) = match uri.split_once('#') {
Some((base, frag)) => (base, Some(frag.to_string())),
None => (uri, None),
};
if let Some(target) = base.strip_prefix("mcard://hash/") {
let target = target.trim_end_matches('/');
if !target.contains(':') {
return Err(format!("Malformed hash URI: expected '<algorithm>:<hex>', got '{target}'"));
}
return Ok(ParsedMcardUri {
uri_type: McardUriType::Hash,
target: target.to_string(),
fragment,
original: uri.to_string(),
});
}
if let Some(rest) = base.strip_prefix("mcard://handle/") {
let raw = rest.split('?').next().unwrap_or(rest).trim_end_matches('/');
return Ok(ParsedMcardUri {
uri_type: McardUriType::Handle,
target: canonicalize_mcard_uri(raw, ""),
fragment,
original: uri.to_string(),
});
}
if base.starts_with("mcard://receipts/") || base.starts_with("mcard://schemas/") {
let raw = base.trim_start_matches("mcard://").trim_end_matches('/');
return Ok(ParsedMcardUri {
uri_type: McardUriType::Handle,
target: canonicalize_mcard_uri(raw, ""),
fragment,
original: uri.to_string(),
});
}
if let Some(raw) = base.strip_prefix("mcard://") {
let raw = raw.trim_end_matches('/');
if let Some(target) = digest_target(raw) {
return Ok(ParsedMcardUri {
uri_type: McardUriType::Hash,
target,
fragment,
original: uri.to_string(),
});
}
return Ok(ParsedMcardUri {
uri_type: McardUriType::Handle,
target: canonicalize_mcard_uri(raw, ""),
fragment,
original: uri.to_string(),
});
}
let candidate = match base.get(..6) {
Some(prefix) if prefix.eq_ignore_ascii_case("mcard:") => &base[6..],
_ => base,
};
if let Some(target) = digest_target(candidate) {
return Ok(ParsedMcardUri {
uri_type: McardUriType::Hash,
target,
fragment,
original: uri.to_string(),
});
}
Ok(ParsedMcardUri {
uri_type: McardUriType::Handle,
target: canonicalize_mcard_uri(base, ""),
fragment,
original: uri.to_string(),
})
}
pub fn validate_transclusion_chain(
chain: &[String],
next_ref: &str,
) -> std::result::Result<(), TransclusionCycleError> {
let next = next_ref.to_lowercase();
if chain.iter().any(|ref_| ref_.to_lowercase() == next) {
let mut cycle_path = chain.to_vec();
cycle_path.push(next_ref.to_string());
return Err(TransclusionCycleError { cycle_path });
}
Ok(())
}