clm_rust_core/layer2/
uri.rs1use serde::{Deserialize, Serialize};
4
5#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
6pub enum McardUriType {
7 Hash,
8 Handle,
9}
10
11pub type McardUriKind = McardUriType;
12
13#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
14pub struct ParsedMcardUri {
15 pub uri_type: McardUriType,
16 pub target: String,
17 pub fragment: Option<String>,
18 pub original: String,
19}
20
21pub type McardUri = ParsedMcardUri;
22
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct TransclusionCycleError {
25 pub cycle_path: Vec<String>,
26}
27
28impl std::fmt::Display for TransclusionCycleError {
29 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
30 write!(f, "Transclusion cycle detected: {}", self.cycle_path.join(" -> "))
31 }
32}
33
34impl std::error::Error for TransclusionCycleError {}
35
36pub fn canonicalize_mcard_uri(path: &str, context_prefix: &str) -> String {
37 let clean = path.trim_start_matches('/');
38 let mut prefix = context_prefix.trim_matches('/');
39 if prefix == "mcard" {
40 prefix = "";
41 }
42 if let Some(rest) = clean.strip_prefix("mcard:") {
43 let rest = rest.trim_start_matches('/');
44 if prefix.is_empty() || rest == prefix || rest.starts_with(&format!("{prefix}/")) {
45 return format!("mcard:{rest}");
46 }
47 return format!("mcard:{prefix}/{rest}");
48 }
49 if prefix.is_empty() {
50 format!("mcard:{clean}")
51 } else {
52 format!("mcard:{prefix}/{clean}")
53 }
54}
55
56pub fn is_qualified_hash(value: &str) -> bool {
57 let Some((algo, hex)) = value.split_once(':') else {
58 return false;
59 };
60 matches!(algo, "blake3" | "sha256" | "sha512" | "sha3-256" | "sha1" | "md5")
61 && (32..=128).contains(&hex.len())
62 && hex.chars().all(|c| c.is_ascii_hexdigit())
63}
64
65pub fn format_mcard_uri(parsed: &ParsedMcardUri) -> String {
66 let frag = parsed
67 .fragment
68 .as_ref()
69 .map(|f| format!("#{}", f.trim_start_matches('#')))
70 .unwrap_or_default();
71 let kind = match parsed.uri_type {
72 McardUriType::Hash => "hash",
73 McardUriType::Handle => "handle",
74 };
75 format!("mcard://{kind}/{}{frag}", parsed.target)
76}
77
78pub fn parse_mcard_uri(uri: &str) -> std::result::Result<ParsedMcardUri, String> {
79 if uri.is_empty() {
80 return Err("Invalid MCard URI: expected non-empty string".to_string());
81 }
82 let (base, fragment) = match uri.split_once('#') {
83 Some((base, frag)) => (base, Some(frag.to_string())),
84 None => (uri, None),
85 };
86 if let Some(target) = base.strip_prefix("mcard://hash/") {
87 let target = target.trim_end_matches('/');
88 if !target.contains(':') {
89 return Err(format!("Malformed hash URI: expected '<algorithm>:<hex>', got '{target}'"));
90 }
91 return Ok(ParsedMcardUri {
92 uri_type: McardUriType::Hash,
93 target: target.to_string(),
94 fragment,
95 original: uri.to_string(),
96 });
97 }
98 if let Some(rest) = base.strip_prefix("mcard://handle/") {
99 let raw = rest.split('?').next().unwrap_or(rest).trim_end_matches('/');
100 return Ok(ParsedMcardUri {
101 uri_type: McardUriType::Handle,
102 target: canonicalize_mcard_uri(raw, ""),
103 fragment,
104 original: uri.to_string(),
105 });
106 }
107 if base.starts_with("mcard://receipts/") || base.starts_with("mcard://schemas/") {
108 let raw = base.trim_start_matches("mcard://").trim_end_matches('/');
109 return Ok(ParsedMcardUri {
110 uri_type: McardUriType::Handle,
111 target: canonicalize_mcard_uri(raw, ""),
112 fragment,
113 original: uri.to_string(),
114 });
115 }
116 if let Some(raw) = base.strip_prefix("mcard://") {
117 let raw = raw.trim_end_matches('/');
118 if is_qualified_hash(raw) {
119 return Ok(ParsedMcardUri {
120 uri_type: McardUriType::Hash,
121 target: raw.to_lowercase(),
122 fragment,
123 original: uri.to_string(),
124 });
125 }
126 return Ok(ParsedMcardUri {
127 uri_type: McardUriType::Handle,
128 target: canonicalize_mcard_uri(raw, ""),
129 fragment,
130 original: uri.to_string(),
131 });
132 }
133 Ok(ParsedMcardUri {
134 uri_type: McardUriType::Handle,
135 target: canonicalize_mcard_uri(base, ""),
136 fragment,
137 original: uri.to_string(),
138 })
139}
140
141pub fn validate_transclusion_chain(
142 chain: &[String],
143 next_ref: &str,
144) -> std::result::Result<(), TransclusionCycleError> {
145 let next = next_ref.to_lowercase();
146 if chain.iter().any(|ref_| ref_.to_lowercase() == next) {
147 let mut cycle_path = chain.to_vec();
148 cycle_path.push(next_ref.to_string());
149 return Err(TransclusionCycleError { cycle_path });
150 }
151 Ok(())
152}