diff --git a/packages/cultcache-rs/CHANGELOG.md b/packages/cultcache-rs/CHANGELOG.md index 0cbf6708..23e217e8 100644 --- a/packages/cultcache-rs/CHANGELOG.md +++ b/packages/cultcache-rs/CHANGELOG.md @@ -13,6 +13,7 @@ only in git history. ### Changed +- `is_stored_at_stamp(&str)` (new, public) is the one shape a peer's `storedAt` must parse as, pinned by `tests/vectors/stored-at-stamp` (RFC 3339 `YYYY-MM-DDThh:mm:ss`, a 1 to 9 digit fraction, `Z` or `+hh:mm`/`-hh:mm`; uppercase `T`/`Z`, a real date, seconds 00-59, years 0001-9999), hand-checked because `chrono`'s RFC 3339 reader takes other shapes. `put_raw_envelope` and `put_prepared_batch` refuse a `stored_at` that is not a stamp (before: only a blank one) and mint nothing (variants:ruling:raw-put-without-stamp-refused). - The single-file store's `push`, `push_all` and `commit_if` stamp a replacing write strictly later than the record it replaces at the same key (a staged stamp stands only when it parses and is strictly later; otherwise the stamp is minted as the replaced stamp plus one microsecond, or now if later), with no identical-content exception, as C# does. A stamp with no successor (the replaced stamp is at year 9999's last microsecond) refuses the write and writes nothing, as C# `MintStoredAt` does. `commit_if` replaces only the record of the entry's own type under the key, so a retype is refused as `push` refuses it. The cache holds the stamp the store wrote. The redb stores and the store-level exact-envelope writes (`compare_and_swap_entry` and its family) still write the caller's envelope unchanged. - The single-file store re-checks for a link once the store lock is held (every write and the try-exchange), so a link put at the path while a writer waited on the lock is refused with `StoreLinkedError` and the lock released, as C# does, instead of being replaced. Pinned by a test that puts the link while a second holder owns the lock. - `CultCache::is_writable` does not look at store paths: a link at a store path is not predicted, and the write refuses it with `StoreLinkedError`. Pinned by a test through a cache attached to a linked store. diff --git a/packages/cultcache-rs/src/lib.rs b/packages/cultcache-rs/src/lib.rs index cd18aea8..b41b9668 100644 --- a/packages/cultcache-rs/src/lib.rs +++ b/packages/cultcache-rs/src/lib.rs @@ -3761,12 +3761,7 @@ impl CultCache { entry.r#type )); } - if entry.stored_at.trim().is_empty() { - return Err(anyhow!( - "CultCache envelope stored_at for type {:?} must be non-empty", - entry.r#type - )); - } + require_stored_at_stamp(entry)?; require_record_payload(entry)?; self.refuse_unread_slots(&entry.r#type, &entry.key)?; self.refuse_claimed_id(entry)?; @@ -3843,12 +3838,7 @@ impl CultCache { entry.r#type )); } - if entry.stored_at.trim().is_empty() { - return Err(anyhow!( - "CultCache envelope stored_at for type {:?} must be non-empty", - entry.r#type - )); - } + require_stored_at_stamp(&entry)?; require_record_payload(&entry)?; self.refuse_unread_slots(&entry.r#type, &entry.key)?; self.refuse_claimed_id(&entry)?; @@ -4328,6 +4318,73 @@ fn restamped_over(entry: &CultCacheEnvelope, held: &[CultCacheEnvelope]) -> Resu Ok(entry) } +/// Whether `text` is a `stored_at` stamp: the one shape pinned in `tests/vectors/stored-at-stamp/`. An RFC 3339 date-time, +/// `YYYY-MM-DDThh:mm:ss`, an optional fraction of 1 to 9 digits, then `Z` or `+hh:mm` / `-hh:mm` (hours 00-23, minutes 00-59); +/// uppercase `T` and `Z`, ASCII digits, no surrounding whitespace, a real calendar date, seconds 00-59, and an instant (the +/// offset applied) within years 0001-9999. Checked by hand, not by `chrono`'s RFC 3339 reader, which takes other shapes +/// (lowercase `t`, a space, a leap second). A peer's `storedAt` is stored as it arrives, so one that is not a stamp is refused. +pub fn is_stored_at_stamp(text: &str) -> bool { + let b = text.as_bytes(); + let digits = |from: usize, count: usize| -> Option { + let part = b.get(from..from + count)?; + part.iter().all(u8::is_ascii_digit).then(|| part.iter().fold(0, |n, d| n * 10 + u32::from(d - b'0'))) + }; + let at = |index: usize, byte: u8| b.get(index) == Some(&byte); + let (Some(year), Some(month), Some(day), Some(hour), Some(minute), Some(second)) = + (digits(0, 4), digits(5, 2), digits(8, 2), digits(11, 2), digits(14, 2), digits(17, 2)) + else { + return false; + }; + if !(at(4, b'-') && at(7, b'-') && at(10, b'T') && at(13, b':') && at(16, b':')) { + return false; + } + let mut next = 19; + if at(next, b'.') { + let fraction = b[next + 1..].iter().take_while(|byte| byte.is_ascii_digit()).count(); + if !(1..=9).contains(&fraction) { + return false; + } + next += 1 + fraction; + } + let offset_seconds = if b.len() == next + 1 && at(next, b'Z') { + 0 + } else if b.len() == next + 6 && (at(next, b'+') || at(next, b'-')) && at(next + 3, b':') { + let (Some(hours), Some(minutes)) = (digits(next + 1, 2), digits(next + 4, 2)) else { + return false; + }; + if hours > 23 || minutes > 59 { + return false; + } + let magnitude = i64::from(hours * 3600 + minutes * 60); + if at(next, b'-') { -magnitude } else { magnitude } + } else { + return false; + }; + if second > 59 { + return false; + } + let Some(local) = chrono::NaiveDate::from_ymd_opt(year as i32, month, day) + .and_then(|date| date.and_hms_opt(hour, minute, second)) + else { + return false; + }; + use chrono::Datelike; + local + .checked_sub_signed(chrono::TimeDelta::seconds(offset_seconds)) + .is_some_and(|utc| (1..=9999).contains(&utc.year())) +} + +/// A raw envelope is stored under the stamp it carries, so one that is no stamp is refused and nothing is minted for it. +fn require_stored_at_stamp(entry: &CultCacheEnvelope) -> Result<()> { + if is_stored_at_stamp(&entry.stored_at) { + return Ok(()); + } + Err(anyhow!( + "CultCache envelope stored_at for type {:?} must be an RFC 3339 stamp", + entry.r#type + )) +} + fn now_utc_second() -> String { chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true) } @@ -6895,7 +6952,7 @@ mod tests { let (mut empty_stored_at, _) = cache.prepare_entry("n", &Note { title: "t".to_string(), body: "b".to_string() })?; empty_stored_at.stored_at = " ".to_string(); let error = cache.put_prepared_batch(vec![empty_stored_at]).unwrap_err(); - assert!(error.to_string().contains("stored_at for type \"note\" must be non-empty"), "{error}"); + assert!(error.to_string().contains("stored_at for type \"note\" must be an RFC 3339 stamp"), "{error}"); assert_eq!(cache.snapshot(), before); assert_eq!(fs::read(&store_path)?, store_bytes); diff --git a/packages/cultcache-rs/tests/stored_at_stamp_vector.rs b/packages/cultcache-rs/tests/stored_at_stamp_vector.rs new file mode 100644 index 00000000..d1ab7f9a --- /dev/null +++ b/packages/cultcache-rs/tests/stored_at_stamp_vector.rs @@ -0,0 +1,58 @@ +//! `tests/vectors/stored-at-stamp`: the one shape a peer's `storedAt` must parse as. Every row is walked against +//! `is_stored_at_stamp`, and each row that is no stamp against the cache's two raw doors, `put_raw_envelope` and +//! `put_prepared_batch`: refused, nothing stored or minted, the store still writable after +//! (`variants:ruling:raw-put-without-stamp-refused`). + +use std::path::PathBuf; + +use cultcache_rs::{CacheBackingStore, CultCache, DatabaseEntry, SingleFileMessagePackBackingStore, is_stored_at_stamp}; + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache(type = "tests.stamp_note", schema = "tests.stamp_note")] +struct Note { + #[cultcache(key = 0)] + text: String, +} + +fn rows() -> Vec<(String, bool)> { + let path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../tests/vectors/stored-at-stamp/stamps.msgpack"); + rmp_serde::from_slice(&std::fs::read(path).unwrap()).unwrap() +} + +#[test] +fn the_stamp_check_agrees_with_every_vector_row() { + let rows = rows(); + assert!(rows.len() > 30, "the vector was not read"); + for (text, parses) in rows { + assert_eq!(is_stored_at_stamp(&text), parses, "{text:?}"); + } +} + +#[test] +fn a_raw_envelope_that_is_no_stamp_is_refused_and_nothing_is_stored() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("stamps.cc"); + let mut cache = CultCache::new(); + cache.register_entry_type::().unwrap(); + cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap(); + cache.pull_all_backing_stores().unwrap(); + for (text, parses) in rows() { + if parses { + continue; + } + let (mut entry, _) = cache.prepare_entry("a", &Note { text: "peer".into() }).unwrap(); + entry.stored_at = text.clone(); + let error = cache.put_raw_envelope(entry.clone()).unwrap_err(); + assert!(format!("{error:#}").contains("stored_at"), "{text:?}: {error:#}"); + let error = cache.put_prepared_batch(vec![entry]).unwrap_err(); + assert!(format!("{error:#}").contains("stored_at"), "{text:?}: {error:#}"); + assert!(cache.get::("a").unwrap().is_none(), "{text:?} was stored"); + assert!(!path.exists() || SingleFileMessagePackBackingStore::new(&path).pull_all().unwrap().is_empty(), "{text:?} reached the file"); + } + // Refused writes left the store writable: a stamped one lands under the stamp it carries. + let (mut entry, _) = cache.prepare_entry("b", &Note { text: "stamped".into() }).unwrap(); + entry.stored_at = "2026-11-07T00:00:00Z".into(); + cache.put_raw_envelope(entry).unwrap(); + assert_eq!(cache.get::("b").unwrap().unwrap().text, "stamped"); + assert!(cache.get::("a").unwrap().is_none()); +}