Skip to main content

clm_rust_core/layer2/
uri.rs

1//! MCard URI parsing and canonicalization utilities (INV-552).
2
3use crate::layer0::vocabulary::{HANDLE_MCARD, URI_SCHEME_MCARD};
4use serde::{Deserialize, Serialize};
5
6#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
7pub enum McardUriType {
8    Hash,
9    Handle,
10}
11
12pub type McardUriKind = McardUriType;
13
14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
15pub struct ParsedMcardUri {
16    pub uri_type: McardUriType,
17    pub target: String,
18    pub fragment: Option<String>,
19    pub original: String,
20}
21
22pub type McardUri = ParsedMcardUri;
23
24#[derive(Debug, Clone, PartialEq, Eq)]
25pub struct TransclusionCycleError {
26    pub cycle_path: Vec<String>,
27}
28
29impl std::fmt::Display for TransclusionCycleError {
30    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
31        write!(f, "Transclusion cycle detected: {}", self.cycle_path.join(" -> "))
32    }
33}
34
35impl std::error::Error for TransclusionCycleError {}
36
37pub fn canonicalize_mcard_uri(path: &str, context_prefix: &str) -> String {
38    let clean = path.trim_start_matches('/');
39    let mut prefix = context_prefix.trim_matches('/');
40    if prefix == "mcard" {
41        prefix = "";
42    }
43    if let Some(rest) = clean.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD) {
44        let rest = rest.trim_start_matches('/');
45        if prefix.is_empty() || rest == prefix || rest.starts_with(&format!("{prefix}/")) {
46            return format!("{HANDLE_MCARD}{rest}");
47        }
48        return format!("{HANDLE_MCARD}{prefix}/{rest}");
49    }
50    if prefix.is_empty() {
51        format!("{HANDLE_MCARD}{clean}")
52    } else {
53        format!("{HANDLE_MCARD}{prefix}/{clean}")
54    }
55}
56
57const DIGEST_HEX_LENGTH: [(&str, usize); 8] = [
58    (crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3, 64),
59    (crate::layer0::vocabulary::HASH_ALGORITHM_SHA256, 64),
60    (crate::layer0::vocabulary::HASH_ALGORITHM_SHA3_256, 64),
61    (crate::layer0::vocabulary::HASH_ALGORITHM_SHA384, 96),
62    (crate::layer0::vocabulary::HASH_ALGORITHM_SHA512, 128),
63    (crate::layer0::vocabulary::HASH_ALGORITHM_SHA224, 56),
64    (crate::layer0::vocabulary::HASH_ALGORITHM_SHA1, 40),
65    (crate::layer0::vocabulary::HASH_ALGORITHM_MD5, 32),
66];
67
68/// Recognizes `<algo>:<exact-len-hex>` as an immutable digest target (INV-566).
69pub fn digest_target(value: &str) -> Option<String> {
70    let (algo, hex) = value.split_once(':')?;
71    let algo = algo.to_ascii_lowercase();
72    let hex = hex.to_ascii_lowercase();
73    let expected = DIGEST_HEX_LENGTH
74        .iter()
75        .find(|(name, _)| *name == algo.as_str())
76        .map(|(_, len)| *len)?;
77    if hex.len() != expected || !hex.chars().all(|c| c.is_ascii_hexdigit()) {
78        return None;
79    }
80    Some(format!("{algo}:{hex}"))
81}
82
83pub fn is_qualified_hash(value: &str) -> bool {
84    digest_target(value).is_some()
85}
86
87pub fn format_mcard_uri(parsed: &ParsedMcardUri) -> String {
88    let frag = parsed
89        .fragment
90        .as_ref()
91        .map(|f| format!("#{}", f.trim_start_matches('#')))
92        .unwrap_or_default();
93    let kind = match parsed.uri_type {
94        McardUriType::Hash => "hash",
95        McardUriType::Handle => "handle",
96    };
97    format!("{URI_SCHEME_MCARD}{kind}/{}{frag}", parsed.target)
98}
99
100pub fn parse_mcard_uri(uri: &str) -> std::result::Result<ParsedMcardUri, String> {
101    if uri.is_empty() {
102        return Err("Invalid MCard URI: expected non-empty string".to_string());
103    }
104    let (base, fragment) = match uri.split_once('#') {
105        Some((base, frag)) => (base, Some(frag.to_string())),
106        None => (uri, None),
107    };
108    if let Some(target) = base.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD_HASH_2) {
109        let target = target.trim_end_matches('/');
110        if !target.contains(':') {
111            return Err(format!("Malformed hash URI: expected '<algorithm>:<hex>', got '{target}'"));
112        }
113        return Ok(ParsedMcardUri {
114            uri_type: McardUriType::Hash,
115            target: target.to_string(),
116            fragment,
117            original: uri.to_string(),
118        });
119    }
120    if let Some(rest) = base.strip_prefix(crate::layer0::vocabulary::HANDLE_MCARD_HANDLE) {
121        let raw = rest.split('?').next().unwrap_or(rest).trim_end_matches('/');
122        return Ok(ParsedMcardUri {
123            uri_type: McardUriType::Handle,
124            target: canonicalize_mcard_uri(raw, ""),
125            fragment,
126            original: uri.to_string(),
127        });
128    }
129    if base.starts_with(crate::layer0::vocabulary::HANDLE_MCARD_RECEIPTS) || base.starts_with(crate::layer0::vocabulary::HANDLE_MCARD_SCHEMAS) {
130        let raw = base.trim_start_matches(crate::layer0::vocabulary::URI_SCHEME_MCARD).trim_end_matches('/');
131        return Ok(ParsedMcardUri {
132            uri_type: McardUriType::Handle,
133            target: canonicalize_mcard_uri(raw, ""),
134            fragment,
135            original: uri.to_string(),
136        });
137    }
138    if let Some(raw) = base.strip_prefix(crate::layer0::vocabulary::URI_SCHEME_MCARD) {
139        let raw = raw.trim_end_matches('/');
140        if let Some(target) = digest_target(raw) {
141            return Ok(ParsedMcardUri {
142                uri_type: McardUriType::Hash,
143                target,
144                fragment,
145                original: uri.to_string(),
146            });
147        }
148        return Ok(ParsedMcardUri {
149            uri_type: McardUriType::Handle,
150            target: canonicalize_mcard_uri(raw, ""),
151            fragment,
152            original: uri.to_string(),
153        });
154    }
155    let candidate = match base.get(..6) {
156        Some(prefix) if prefix.eq_ignore_ascii_case(crate::layer0::vocabulary::HANDLE_MCARD) => &base[6..],
157        _ => base,
158    };
159    if let Some(target) = digest_target(candidate) {
160        return Ok(ParsedMcardUri {
161            uri_type: McardUriType::Hash,
162            target,
163            fragment,
164            original: uri.to_string(),
165        });
166    }
167    Ok(ParsedMcardUri {
168        uri_type: McardUriType::Handle,
169        target: canonicalize_mcard_uri(base, ""),
170        fragment,
171        original: uri.to_string(),
172    })
173}
174
175pub fn validate_transclusion_chain(
176    chain: &[String],
177    next_ref: &str,
178) -> std::result::Result<(), TransclusionCycleError> {
179    let next = next_ref.to_lowercase();
180    if chain.iter().any(|ref_| ref_.to_lowercase() == next) {
181        let mut cycle_path = chain.to_vec();
182        cycle_path.push(next_ref.to_string());
183        return Err(TransclusionCycleError { cycle_path });
184    }
185    Ok(())
186}