Skip to main content

clm_rust_core/layer0/
gtime.rs

1//! Layer 0: GTime formatting, parsing, and canonical timestamps.
2//! Canonical Path: kernel/clm_rust_core/src/layer0/gtime.rs
3//! Parity: TypeScript `src/layer0/gtime.ts`, Python `clm/layer0/gtime.py`
4
5use std::collections::BTreeMap;
6use serde::{Deserialize, Serialize};
7
8pub use super::gtime_attribution::*;
9
10pub const G_TIME_EXTENSIONS: &[&str] = &["did", "kid", "sig"];
11
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13pub enum GTimeForm {
14    Pipe,
15    LegacyTs,
16}
17
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19pub struct DeclaredGTime {
20    pub form: GTimeForm,
21    pub algorithm: String,
22    pub timestamp: String,
23    pub locale: String,
24    pub extensions: BTreeMap<String, String>,
25    pub raw: String,
26}
27
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29pub struct LegacyGTime {
30    pub timestamp: String,
31    pub raw: String,
32}
33
34#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
35pub struct MalformedGTime {
36    pub raw: String,
37    pub reason: String,
38}
39
40#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
41pub enum ParsedGTime {
42    Declared(DeclaredGTime),
43    Legacy(LegacyGTime),
44    Malformed(MalformedGTime),
45}
46
47impl ParsedGTime {
48    pub fn is_declared(&self) -> bool {
49        matches!(self, ParsedGTime::Declared(_))
50    }
51    pub fn is_legacy(&self) -> bool {
52        matches!(self, ParsedGTime::Legacy(_))
53    }
54    pub fn is_malformed(&self) -> bool {
55        matches!(self, ParsedGTime::Malformed(_))
56    }
57}
58
59pub fn normalize_g_time_timestamp(timestamp: &str) -> Result<String, String> {
60    let ts = timestamp.trim();
61    let parsed = match chrono::DateTime::parse_from_rfc3339(ts) {
62        Ok(dt) => dt,
63        Err(err) => {
64            if ts.len() < 5 {
65                return Err(format!("Invalid g_time timestamp: {err}"));
66            }
67            let offset_start = ts.len() - 5;
68            let offset = &ts[offset_start..];
69            if (offset.starts_with('+') || offset.starts_with('-'))
70                && offset[1..].chars().all(|ch| ch.is_ascii_digit())
71            {
72                let normalized = format!("{}{}:{}", &ts[..offset_start], &offset[..3], &offset[3..]);
73                chrono::DateTime::parse_from_rfc3339(&normalized)
74                    .map_err(|e| format!("Invalid g_time timestamp: {e}"))?
75            } else {
76                return Err(format!("Invalid g_time timestamp: {err}"));
77            }
78        }
79    };
80    Ok(parsed.to_rfc3339_opts(chrono::SecondsFormat::Millis, true))
81}
82
83fn is_supported_algorithm(algo: &str) -> bool {
84    let a = algo.trim().to_lowercase();
85    matches!(a.as_str(), crate::layer0::vocabulary::HASH_ALGORITHM_BLAKE3 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA256 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA_256 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA384 | crate::layer0::vocabulary::HASH_ALGORITHM_SHA512)
86}
87
88pub fn format_canonical_g_time(
89    algo: &str,
90    timestamp: &str,
91    locale: &str,
92    extensions: Option<&BTreeMap<String, String>>,
93) -> String {
94    let norm_algo = if algo.trim().eq_ignore_ascii_case(crate::layer0::vocabulary::HASH_ALGORITHM_SHA_256) {
95        crate::layer0::vocabulary::HASH_ALGORITHM_SHA256.to_string()
96    } else {
97        algo.trim().trim_end_matches(':').to_lowercase()
98    };
99    let norm_ts = normalize_g_time_timestamp(timestamp).unwrap_or_else(|_| timestamp.to_string());
100    let mut base = format!("{}|{}|{}", norm_algo, norm_ts, locale);
101    if let Some(exts) = extensions {
102        for (k, v) in exts.iter() {
103            if !v.is_empty() {
104                base.push_str(&format!("|{}={}", k, v));
105            }
106        }
107    }
108    base
109}
110
111pub fn stamp_g_time(
112    algo: &str,
113    timestamp: Option<&str>,
114    locale: Option<&str>,
115    extensions: Option<&BTreeMap<String, String>>,
116) -> String {
117    let now = chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true);
118    let ts = timestamp.unwrap_or(&now);
119    let loc = locale.unwrap_or("UTC");
120    format_canonical_g_time(algo, ts, loc, extensions)
121}
122
123fn is_valid_ext_key(key: &str) -> bool {
124    if key.is_empty() || key.len() > 32 {
125        return false;
126    }
127    let mut chars = key.chars();
128    match chars.next() {
129        Some(c) if c.is_ascii_lowercase() => {}
130        _ => return false,
131    }
132    chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_' || c == '-')
133}
134
135fn parse_extensions(
136    segments: &[&str],
137    separator: char,
138    require_registered: bool,
139) -> Result<BTreeMap<String, String>, String> {
140    let mut map = BTreeMap::new();
141    for seg in segments {
142        let s = seg.trim();
143        if s.is_empty() {
144            continue;
145        }
146        let Some((k_raw, v_raw)) = s.split_once(separator) else {
147            return Err(format!("Extension segment lacks a '{}' separator: \"{}\"", separator, s));
148        };
149        let key = k_raw.trim().to_lowercase();
150        let val = v_raw.trim().to_string();
151        if !is_valid_ext_key(&key) {
152            return Err(format!("Invalid extension key: \"{}\"", key));
153        }
154        if require_registered && !G_TIME_EXTENSIONS.contains(&key.as_str()) {
155            return Err(format!(
156                "Unregistered extension key: \"{}\" (registered: {})",
157                key,
158                G_TIME_EXTENSIONS.join(", ")
159            ));
160        }
161        if map.contains_key(&key) {
162            return Err(format!("Duplicate extension key: \"{}\"", key));
163        }
164        if val.is_empty() || val.contains('|') || val.contains(';') {
165            return Err(format!("Empty or delimiter-bearing extension value for \"{}\"", key));
166        }
167        map.insert(key, val);
168    }
169    Ok(map)
170}
171
172pub fn parse_g_time(raw: &str) -> ParsedGTime {
173    let s = raw.trim();
174    if s.is_empty() {
175        return ParsedGTime::Malformed(MalformedGTime {
176            raw: raw.to_string(),
177            reason: "Empty or non-string g_time".to_string(),
178        });
179    }
180
181    if s.contains('|') {
182        let parts: Vec<&str> = s.split('|').collect();
183        if parts.len() < 3 {
184            return ParsedGTime::Malformed(MalformedGTime {
185                raw: s.to_string(),
186                reason: format!("Pipe form requires at least 3 fields, found {}", parts.len()),
187            });
188        }
189        let algo = parts[0].trim().to_lowercase();
190        if !is_supported_algorithm(&algo) {
191            return ParsedGTime::Malformed(MalformedGTime {
192                raw: s.to_string(),
193                reason: format!("Unsupported algorithm in coordinate a: \"{}\"", parts[0]),
194            });
195        }
196        let ts_str = parts[1].trim();
197        if normalize_g_time_timestamp(ts_str).is_err() {
198            return ParsedGTime::Malformed(MalformedGTime {
199                raw: s.to_string(),
200                reason: format!("Invalid timestamp in coordinate t: \"{}\"", parts[1]),
201            });
202        }
203        let locale = parts[2].trim();
204        if locale.contains('=') {
205            return ParsedGTime::Malformed(MalformedGTime {
206                raw: s.to_string(),
207                reason: format!("Coordinate c must be a locale, not an extension: \"{}\"", locale),
208            });
209        }
210        match parse_extensions(&parts[3..], '=', true) {
211            Ok(exts) => ParsedGTime::Declared(DeclaredGTime {
212                form: GTimeForm::Pipe,
213                algorithm: algo,
214                timestamp: ts_str.to_string(),
215                locale: locale.to_string(),
216                extensions: exts,
217                raw: s.to_string(),
218            }),
219            Err(reason) => ParsedGTime::Malformed(MalformedGTime {
220                raw: s.to_string(),
221                reason,
222            }),
223        }
224    } else if s.starts_with("a:") {
225        let mut kv_map = BTreeMap::new();
226        for part in s.split(';') {
227            let trimmed = part.trim();
228            if trimmed.is_empty() {
229                continue;
230            }
231            let Some((k, v)) = trimmed.split_once(':') else {
232                return ParsedGTime::Malformed(MalformedGTime {
233                    raw: s.to_string(),
234                    reason: format!("Segment lacks key:value separator: \"{}\"", trimmed),
235                });
236            };
237            let k = k.trim().to_string();
238            let v = v.trim().to_string();
239            if k.is_empty() {
240                return ParsedGTime::Malformed(MalformedGTime {
241                    raw: s.to_string(),
242                    reason: format!("Empty key in segment: \"{}\"", trimmed),
243                });
244            }
245            if kv_map.contains_key(&k) {
246                return ParsedGTime::Malformed(MalformedGTime {
247                    raw: s.to_string(),
248                    reason: format!("Duplicate key in g_time: \"{}\"", k),
249                });
250            }
251            kv_map.insert(k, v);
252        }
253        let Some(algo_raw) = kv_map.remove("a") else {
254            return ParsedGTime::Malformed(MalformedGTime {
255                raw: s.to_string(),
256                reason: "Unsupported or missing algorithm 'a'".to_string(),
257            });
258        };
259        if !is_supported_algorithm(&algo_raw) {
260            return ParsedGTime::Malformed(MalformedGTime {
261                raw: s.to_string(),
262                reason: format!("Unsupported or missing algorithm 'a': \"{}\"", algo_raw),
263            });
264        }
265        let Some(ts_raw) = kv_map.remove("t") else {
266            return ParsedGTime::Malformed(MalformedGTime {
267                raw: s.to_string(),
268                reason: "Invalid or missing timestamp 't'".to_string(),
269            });
270        };
271        if normalize_g_time_timestamp(&ts_raw).is_err() {
272            return ParsedGTime::Malformed(MalformedGTime {
273                raw: s.to_string(),
274                reason: format!("Invalid or missing timestamp 't': \"{}\"", ts_raw),
275            });
276        }
277        let locale = kv_map.remove("c").unwrap_or_default();
278        ParsedGTime::Declared(DeclaredGTime {
279            form: GTimeForm::LegacyTs,
280            algorithm: algo_raw,
281            timestamp: ts_raw,
282            locale,
283            extensions: kv_map,
284            raw: s.to_string(),
285        })
286    } else if normalize_g_time_timestamp(s).is_ok() {
287        ParsedGTime::Legacy(LegacyGTime {
288            timestamp: s.to_string(),
289            raw: s.to_string(),
290        })
291    } else {
292        ParsedGTime::Malformed(MalformedGTime {
293            raw: s.to_string(),
294            reason: "Unrecognised g_time shape".to_string(),
295        })
296    }
297}