jmap_types/id.rs
1//! RFC 8620 §1.2/§1.4 opaque string newtypes: [`Id`], [`UTCDate`], [`Date`], [`State`].
2
3use serde::{Deserialize, Serialize};
4use std::fmt;
5
6/// Error returned by the fallible constructors [`Id::new_validated`],
7/// [`UTCDate::new_validated`], and [`State::new_validated`].
8///
9/// The message is reachable only through [`fmt::Display`]; the inner
10/// field is private, like the other newtypes in this module:
11///
12/// ```compile_fail
13/// let err = jmap_types::Id::new_validated("").unwrap_err();
14/// let _ = err.0;
15/// ```
16#[non_exhaustive]
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub struct ValidationError(String);
19
20impl fmt::Display for ValidationError {
21 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
22 f.write_str(&self.0)
23 }
24}
25
26impl std::error::Error for ValidationError {}
27
28/// Opaque non-empty server-assigned identifier (RFC 8620 §1.2).
29///
30/// Character set: URL-safe base64 alphabet (A-Za-z0-9, `-`, `_`), max 255 octets.
31/// Clients MUST treat Id values as opaque strings — no parsing of structure.
32///
33/// # Deserialization is validated
34///
35/// Deserializing an `Id` applies the same check as [`Id::new_validated`],
36/// so a wire value outside the RFC 8620 §1.2 syntax is a deserialization
37/// error rather than an unchecked `Id`:
38///
39/// ```
40/// use jmap_types::Id;
41/// assert!(serde_json::from_str::<Id>("\"abc-_123\"").is_ok());
42/// assert!(serde_json::from_str::<Id>("\"has space\"").is_err());
43/// ```
44///
45/// [`Id::from`] remains an unchecked constructor for values the caller
46/// already trusts.
47// #[non_exhaustive] prevents callers from pattern-matching the inner field
48// (e.g. `let Id(s) = id;`), preserving semver freedom to add fields later.
49#[non_exhaustive]
50#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
51#[serde(transparent)]
52pub struct Id(String);
53
54// A manual impl rather than `#[serde(try_from = "String")]`: the existing
55// `From<String>` makes the blanket `TryFrom<String>` infallible, so a
56// fallible `TryFrom<String>` cannot be added (see the note above
57// `validate_id`).
58impl<'de> Deserialize<'de> for Id {
59 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
60 let s = String::deserialize(deserializer)?;
61 Self::new_validated(s).map_err(serde::de::Error::custom)
62 }
63}
64
65/// RFC 3339 UTC timestamp string (RFC 8620 §1.4).
66///
67/// Format: `YYYY-MM-DDTHH:MM:SS[.fff…]Z` — time-offset MUST be `Z`, letters
68/// uppercase, fractional seconds omitted if zero. Examples:
69/// `"2014-10-30T06:12:00Z"`, `"2014-10-30T06:12:00.123Z"`.
70///
71/// # Deserialization is NOT validated
72///
73/// `UTCDate` is `#[serde(transparent)]` over `String`. Any string that
74/// deserializes into a `String` deserializes into a `UTCDate` — including
75/// `"not-a-date"`, `"2024-01-19T18:00:00"` (no `Z` suffix), or any other
76/// shape that violates RFC 8620 §1.4. The newtype carries the
77/// **type-level intent** of "RFC 8620 UTC timestamp" but does NOT enforce
78/// it at the wire boundary.
79///
80/// Use [`UTCDate::new_validated`] when constructing from untrusted input,
81/// or call [`UTCDate::to_epoch_seconds`] when consuming a deserialized
82/// value: the latter re-validates structural format AND semantic ranges
83/// (month, day, hour, minute, second) and returns [`ValidationError`] on
84/// any deviation. Treat any field of type `Option<UTCDate>` arriving
85/// from a peer as "RFC 8620 timestamp by convention, not by contract".
86// #[non_exhaustive] prevents callers from pattern-matching the inner field,
87// preserving semver freedom to add fields later.
88#[non_exhaustive]
89#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
90#[serde(transparent)]
91pub struct UTCDate(String);
92
93/// RFC 3339 date-time string with any timezone offset (RFC 8620 §1.4).
94///
95/// Format: `YYYY-MM-DDTHH:MM:SS±HH:MM` or `Z` suffix — any valid RFC 3339 offset,
96/// letters uppercase, fractional seconds omitted if zero.
97/// Example: `"2014-10-30T14:12:00+08:00"`.
98///
99/// Distinct from [`UTCDate`], which requires the time-offset to be `Z`.
100/// Use `Date` for fields derived from RFC 5322 email headers (e.g. `sentAt`),
101/// which commonly carry non-UTC offsets.
102///
103/// # Deserialization is NOT validated
104///
105/// `Date` is `#[serde(transparent)]` over `String`. Any string that
106/// deserializes into a `String` deserializes into a `Date`, including
107/// values that violate RFC 8620 §1.4 / RFC 3339. The newtype carries
108/// the **type-level intent** but does NOT enforce it at the wire
109/// boundary. Treat any field of type `Option<Date>` arriving from a
110/// peer as "RFC 8620 timestamp by convention, not by contract".
111// #[non_exhaustive] prevents callers from pattern-matching the inner field,
112// preserving semver freedom to add fields later.
113#[non_exhaustive]
114#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
115#[serde(transparent)]
116pub struct Date(String);
117
118/// Opaque server state token (RFC 8620 §1.2).
119///
120/// Returned by `/get` and `/changes` methods. Clients echo it back in
121/// `sinceState` / `ifInState` parameters. Treat as opaque — no structure assumed.
122///
123/// # Migrating from `String`-typed code
124///
125/// Earlier revisions of this crate exposed state fields as
126/// `pub session_state: String` on [`crate::JmapResponse`] and similar
127/// shapes. The current revision uses the `State` newtype for type
128/// safety. The wire format is unchanged (`State` is
129/// `#[serde(transparent)]` over `String`). The Rust API conversions
130/// available to callers migrating from `String`:
131///
132/// - Read as `&str`: `state.as_ref()` (via `AsRef<str>`) or
133/// `format!("{state}")` (via `Display`).
134/// - Compare to a literal: `state == "abc"` (via `PartialEq<str>`).
135/// - Move into an owned `String`: `state.into_inner()`.
136/// - Borrow as `&String`: not directly available; use `as_ref()` to
137/// get `&str` instead.
138/// - Build from `&str` or `String`: `State::from("abc")` or
139/// `State::from(my_string)` (via `From<&str>` / `From<String>`).
140///
141/// Callers passing a `State` to a function that takes `String` should
142/// either change the signature to `impl AsRef<str>` or call
143/// `state.into_inner()` at the boundary. Callers keying a
144/// `HashMap<String, _>` by state token can either rekey by
145/// `HashMap<State, _>` (`State` implements `Hash + Eq`) or call
146/// `state.into_inner()` at insertion / lookup time.
147// #[non_exhaustive] prevents callers from pattern-matching the inner field,
148// preserving semver freedom to add fields later.
149#[non_exhaustive]
150#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
151#[serde(transparent)]
152pub struct State(String);
153
154/// Generates `Display`, `From<String>`, `From<&str>`, `AsRef<str>`,
155/// `PartialEq<str>`, `PartialEq<&str>`, and `into_inner` for a transparent
156/// `String` newtype.
157macro_rules! impl_string_newtype {
158 ($T:ident) => {
159 impl fmt::Display for $T {
160 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
161 f.write_str(&self.0)
162 }
163 }
164 impl From<String> for $T {
165 fn from(s: String) -> Self {
166 Self(s)
167 }
168 }
169 impl From<&str> for $T {
170 fn from(s: &str) -> Self {
171 Self(s.to_owned())
172 }
173 }
174 impl AsRef<str> for $T {
175 fn as_ref(&self) -> &str {
176 &self.0
177 }
178 }
179 impl PartialEq<str> for $T {
180 fn eq(&self, other: &str) -> bool {
181 self.0 == other
182 }
183 }
184 impl PartialEq<&str> for $T {
185 fn eq(&self, other: &&str) -> bool {
186 self.0 == *other
187 }
188 }
189 impl std::borrow::Borrow<str> for $T {
190 fn borrow(&self) -> &str {
191 &self.0
192 }
193 }
194 impl $T {
195 /// Consumes the value and returns the inner `String`.
196 pub fn into_inner(self) -> String {
197 self.0
198 }
199 }
200 };
201}
202
203impl_string_newtype!(Id);
204impl_string_newtype!(UTCDate);
205impl_string_newtype!(Date);
206impl_string_newtype!(State);
207
208// ---------------------------------------------------------------------------
209// Fallible constructors — validate RFC 8620 constraints at the boundary.
210//
211// These are named constructors (not TryFrom impls) because Id/UTCDate/State
212// already implement From<String> and From<&str>. Rust's blanket impl
213// `impl<T,U> TryFrom<U> where U: Into<T>` would make TryFrom<String>
214// infallible (Error = Infallible) via the existing From impl, making it
215// impossible to add a second, fallible TryFrom<String>. Named constructors
216// achieve the same goal without the conflict.
217// ---------------------------------------------------------------------------
218
219/// Validate an [`Id`] string per RFC 8620 §1.2.
220///
221/// RFC 8620 §1.2 requires Ids to use the "URL and Filename Safe" base64
222/// alphabet defined in RFC 4648 §5, excluding the pad character `=`.
223/// That is: ASCII alphanumeric characters (`A-Z`, `a-z`, `0-9`), hyphen
224/// (`-`), and underscore (`_`). The string must also be non-empty and
225/// at most 255 bytes.
226fn validate_id(s: &str) -> Result<(), ValidationError> {
227 if s.is_empty() {
228 return Err(ValidationError("Id must not be empty".into()));
229 }
230 if s.len() > 255 {
231 return Err(ValidationError(format!(
232 "Id exceeds 255 bytes (got {})",
233 s.len()
234 )));
235 }
236 for ch in s.chars() {
237 // RFC 4648 §5 URL-safe base64 alphabet, minus the pad `=`:
238 // A-Z, a-z, 0-9, '-', '_'.
239 if !ch.is_ascii_alphanumeric() && ch != '-' && ch != '_' {
240 return Err(ValidationError(format!(
241 "Id contains invalid character {:?} (U+{:04X})",
242 ch, ch as u32
243 )));
244 }
245 }
246 Ok(())
247}
248
249/// Validate a [`UTCDate`] string per RFC 8620 §1.4.
250///
251/// Validation has two layers:
252///
253/// 1. **Shape**: the `YYYY-MM-DDTHH:MM:SS` layout with ASCII digits in
254/// every numeric position, an optional RFC 3339 `time-secfrac`
255/// (`.` followed by one or more digits, not all zero, because RFC 8620
256/// §1.4 says it "MUST always be omitted if zero"), then `Z`.
257/// 2. **Values**: month in `1..=12`, day in `1..=days_in_month(year,
258/// month)` (proleptic Gregorian, exact leap-year rules), hour in
259/// `0..=23`, minute in `0..=59`, second in `0..=59` (RFC 8620 §1.4
260/// does not permit leap seconds even though RFC 3339 §5.6 does).
261///
262/// No external crate needed.
263fn validate_utcdate(s: &str) -> Result<(), ValidationError> {
264 if s.len() < 20 {
265 return Err(ValidationError(format!(
266 "UTCDate must be at least 20 characters (YYYY-MM-DDTHH:MM:SSZ), got {:?}",
267 s
268 )));
269 }
270 let b = s.as_bytes();
271 // Tail after the seconds: `Z`, or `.` + non-zero digit run + `Z`.
272 let tail_ok = match &b[19..] {
273 [b'Z'] => true,
274 [b'.', frac @ .., b'Z'] => {
275 !frac.is_empty()
276 && frac.iter().all(u8::is_ascii_digit)
277 && frac.iter().any(|&d| d != b'0')
278 }
279 _ => false,
280 };
281 // Fixed separators: dashes, T, colons.
282 if !tail_ok || b[4] != b'-' || b[7] != b'-' || b[10] != b'T' || b[13] != b':' || b[16] != b':' {
283 return Err(ValidationError(format!(
284 "UTCDate has wrong structure, expected YYYY-MM-DDTHH:MM:SS[.fff]Z, got {:?}",
285 s
286 )));
287 }
288 // Digit positions: 0-3 (year), 5-6 (month), 8-9 (day),
289 // 11-12 (hour), 14-15 (min), 17-18 (sec).
290 for &pos in &[0, 1, 2, 3, 5, 6, 8, 9, 11, 12, 14, 15, 17, 18] {
291 if !b[pos].is_ascii_digit() {
292 return Err(ValidationError(format!(
293 "UTCDate position {} is not a digit in {:?}",
294 pos, s
295 )));
296 }
297 }
298
299 // Value-range checks. Shape is now confirmed, so digit positions
300 // are guaranteed ASCII digits and the parses are infallible.
301 let parse = |start: usize, end: usize| -> i64 {
302 let mut n: i64 = 0;
303 for &byte in &b[start..end] {
304 n = n * 10 + (byte - b'0') as i64;
305 }
306 n
307 };
308 let year = parse(0, 4);
309 let month = parse(5, 7) as u32;
310 let day = parse(8, 10) as u32;
311 let hour = parse(11, 13) as u32;
312 let minute = parse(14, 16) as u32;
313 let second = parse(17, 19) as u32;
314
315 if !(1..=12).contains(&month) {
316 return Err(ValidationError(format!(
317 "UTCDate month must be 1..=12, got {month} in {s:?}"
318 )));
319 }
320 let max_day = days_in_month(year, month);
321 if !(1..=max_day).contains(&day) {
322 return Err(ValidationError(format!(
323 "UTCDate day must be 1..={max_day} for {year:04}-{month:02}, got {day} in {s:?}"
324 )));
325 }
326 if hour > 23 {
327 return Err(ValidationError(format!(
328 "UTCDate hour must be 0..=23, got {hour} in {s:?}"
329 )));
330 }
331 if minute > 59 {
332 return Err(ValidationError(format!(
333 "UTCDate minute must be 0..=59, got {minute} in {s:?}"
334 )));
335 }
336 // No leap seconds in RFC 8620 §1.4 (it specifies seconds 0..=59).
337 if second > 59 {
338 return Err(ValidationError(format!(
339 "UTCDate second must be 0..=59, got {second} in {s:?}"
340 )));
341 }
342 Ok(())
343}
344
345/// Validate a [`State`] string: must be non-empty.
346///
347/// RFC 8620 §1.2 does not restrict the character set for State beyond
348/// requiring it to be non-empty.
349fn validate_state(s: &str) -> Result<(), ValidationError> {
350 if s.is_empty() {
351 return Err(ValidationError("State must not be empty".into()));
352 }
353 Ok(())
354}
355
356impl Id {
357 /// Construct an [`Id`] with RFC 8620 §1.2 syntax validation.
358 ///
359 /// RFC 8620 §1.2 restricts Ids to the URL-safe base64 alphabet defined
360 /// in RFC 4648 §5, excluding the pad character `=`. The permitted
361 /// characters are therefore the ASCII alphanumerics (`A-Z`, `a-z`,
362 /// `0-9`), hyphen (`-`), and underscore (`_`). The string must also
363 /// be non-empty and at most 255 bytes.
364 ///
365 /// # Errors
366 ///
367 /// Returns [`ValidationError`] when the input does not satisfy
368 /// RFC 8620 §1.2. The error description contains a category keyword
369 /// that callers can match on if they need finer-grained handling:
370 ///
371 /// - `"empty"` — the input was an empty string;
372 /// - `"exceeds 255 bytes"` — the input was longer than the spec
373 /// maximum;
374 /// - `"invalid character"` — the input contained at least one
375 /// character outside `A-Z`, `a-z`, `0-9`, `-`, `_`.
376 ///
377 /// Use [`Id::from`] when the value is known to be valid (e.g. a string
378 /// received from a JMAP server response).
379 pub fn new_validated(s: impl Into<String>) -> Result<Self, ValidationError> {
380 let s = s.into();
381 validate_id(&s)?;
382 Ok(Self(s))
383 }
384}
385
386impl UTCDate {
387 /// Construct a [`UTCDate`] with RFC 8620 §1.4 validation.
388 ///
389 /// Validation has two layers:
390 ///
391 /// 1. **Shape**: the `YYYY-MM-DDTHH:MM:SS` layout with ASCII
392 /// digits in every numeric position, an optional fractional
393 /// second (`.` and one or more digits, rejected when all zero
394 /// because RFC 8620 §1.4 requires a zero `time-secfrac` to be
395 /// omitted), then `Z`.
396 /// 2. **Values**: month `1..=12`; day `1..=days_in_month(year,
397 /// month)` with proleptic Gregorian leap-year rules so e.g.
398 /// `2024-02-29` is accepted but `2023-02-29` and `2024-02-30`
399 /// are rejected; hour `0..=23`; minute `0..=59`; second
400 /// `0..=59` (RFC 8620 §1.4 does not permit leap seconds even
401 /// though RFC 3339 §5.6 does).
402 ///
403 /// # Errors
404 ///
405 /// Returns [`ValidationError`] when the input does not satisfy
406 /// RFC 8620 §1.4. The error description contains a substring that
407 /// callers can match on if they need finer-grained handling:
408 ///
409 /// - `"at least 20 characters"` — too short;
410 /// - `"wrong structure"` — separators or `Z` suffix missing /
411 /// misplaced, or a fractional second that is empty, non-numeric
412 /// or zero;
413 /// - `"is not a digit"` — non-digit at a numeric position;
414 /// - `"month must be"` — month outside `1..=12`;
415 /// - `"day must be"` — day outside `1..=days_in_month(year,
416 /// month)` (catches both out-of-range day numbers like `32` and
417 /// non-existent dates like Feb 30 or Feb 29 in a non-leap year);
418 /// - `"hour must be"`, `"minute must be"`, `"second must be"` —
419 /// the corresponding time component is out of range.
420 ///
421 /// Use [`UTCDate::from`] when the value is known to be valid.
422 pub fn new_validated(s: impl Into<String>) -> Result<Self, ValidationError> {
423 let s = s.into();
424 validate_utcdate(&s)?;
425 Ok(Self(s))
426 }
427
428 /// Convert this [`UTCDate`] to seconds since the Unix epoch
429 /// (`1970-01-01T00:00:00Z`).
430 ///
431 /// Re-validates the structural RFC 8620 §1.4 format (the value may have
432 /// been constructed via [`UTCDate::from`] without validation) and also
433 /// validates semantic ranges: month `1..=12`, day `1..=days_in_month`,
434 /// hour `0..=23`, minute `0..=59`, second `0..=59` (no leap seconds).
435 /// Returns [`ValidationError`] on any validation failure.
436 ///
437 /// Negative values are returned for dates before `1970-01-01T00:00:00Z`.
438 /// A fractional second is truncated toward the earlier whole second.
439 ///
440 /// Uses the proleptic Gregorian calendar via Hinnant's `days_from_civil`
441 /// algorithm, which is exact-integer and handles leap years and century
442 /// rules correctly. No external dependencies.
443 ///
444 /// # Examples
445 ///
446 /// ```
447 /// use jmap_types::UTCDate;
448 /// let d = UTCDate::new_validated("1970-01-01T00:00:00Z").unwrap();
449 /// assert_eq!(d.to_epoch_seconds().unwrap(), 0);
450 /// let rfc = UTCDate::new_validated("2014-10-30T06:12:00Z").unwrap();
451 /// assert_eq!(rfc.to_epoch_seconds().unwrap(), 1_414_649_520);
452 /// ```
453 pub fn to_epoch_seconds(&self) -> Result<i64, ValidationError> {
454 utcdate_to_epoch_seconds(&self.0)
455 }
456
457 /// Compare the instants `self` and `other` denote.
458 ///
459 /// Whole seconds first, then the fractional seconds compared as
460 /// decimals, so `…:00.5Z` is later than `…:00Z` and `…:00.50Z` equals
461 /// `…:00.5Z`. Use this rather than string order (`"…00.5Z" <
462 /// "…00Z"`), [`to_epoch_seconds`](Self::to_epoch_seconds) (which
463 /// truncates fractions), or a conversion to a fixed precision (RFC 8620
464 /// §1.4 sets no limit on fractional digits).
465 ///
466 /// # Errors
467 ///
468 /// [`ValidationError`] when either value is not a valid RFC 8620 §1.4
469 /// `UTCDate` (one built with [`UTCDate::from`] is re-validated).
470 ///
471 /// # Examples
472 ///
473 /// ```
474 /// use std::cmp::Ordering;
475 /// use jmap_types::UTCDate;
476 /// let whole = UTCDate::new_validated("2025-01-01T00:00:00Z").unwrap();
477 /// let half = UTCDate::new_validated("2025-01-01T00:00:00.5Z").unwrap();
478 /// assert_eq!(half.cmp_instant(&whole).unwrap(), Ordering::Greater);
479 /// ```
480 pub fn cmp_instant(&self, other: &UTCDate) -> Result<std::cmp::Ordering, ValidationError> {
481 let seconds = self.to_epoch_seconds()?.cmp(&other.to_epoch_seconds()?);
482 Ok(seconds.then_with(|| cmp_fraction(fraction(&self.0), fraction(&other.0))))
483 }
484}
485
486/// The fractional-second digits of a validated `UTCDate` (after `.`), or
487/// `""`.
488fn fraction(s: &str) -> &str {
489 s.get(19..s.len().saturating_sub(1))
490 .and_then(|f| f.strip_prefix('.'))
491 .unwrap_or("")
492}
493
494/// Compare two strings of decimal digits as fractions (`"5"` = 0.5), the
495/// shorter padded with zeros.
496fn cmp_fraction(a: &str, b: &str) -> std::cmp::Ordering {
497 let (a, b) = (a.as_bytes(), b.as_bytes());
498 (0..a.len().max(b.len()))
499 .map(|i| {
500 let x = a.get(i).copied().unwrap_or(b'0');
501 let y = b.get(i).copied().unwrap_or(b'0');
502 x.cmp(&y)
503 })
504 .find(|o| o.is_ne())
505 .unwrap_or(std::cmp::Ordering::Equal)
506}
507
508/// Number of days in `month` of `year`, accounting for proleptic Gregorian
509/// leap-year rules (year divisible by 4, except centuries not divisible by 400).
510fn days_in_month(year: i64, month: u32) -> u32 {
511 match month {
512 1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
513 4 | 6 | 9 | 11 => 30,
514 2 => {
515 if (year % 4 == 0 && year % 100 != 0) || year % 400 == 0 {
516 29
517 } else {
518 28
519 }
520 }
521 _ => 0, // unreachable when month range is validated by caller
522 }
523}
524
525/// Hinnant's `days_from_civil` algorithm: number of days from
526/// `1970-01-01` (positive) or to `1970-01-01` (negative) for the proleptic
527/// Gregorian date `(y, m, d)`. Source: Howard Hinnant, "chrono-Compatible
528/// Low-Level Date Algorithms", §6.
529///
530/// Preconditions (caller-validated): `m` in `1..=12`, `d` in
531/// `1..=days_in_month(y, m)`. Years are unbounded `i64`.
532fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
533 let y = if m <= 2 { y - 1 } else { y };
534 let era = if y >= 0 { y } else { y - 399 } / 400;
535 let yoe = y - era * 400; // [0, 399]
536 let m = m as i64;
537 let d = d as i64;
538 let mp = if m > 2 { m - 3 } else { m + 9 }; // [0, 11]
539 let doy = (153 * mp + 2) / 5 + d - 1; // [0, 365]
540 let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy; // [0, 146096]
541 era * 146097 + doe - 719_468
542}
543
544/// Internal helper: convert a `YYYY-MM-DDTHH:MM:SS[.fff]Z` string to epoch
545/// seconds, truncating any fractional second.
546///
547/// `validate_utcdate` performs both shape and value-range validation;
548/// after it returns Ok, the per-position digit parses are infallible
549/// and the parsed values are within their RFC 8620 §1.4 ranges.
550fn utcdate_to_epoch_seconds(s: &str) -> Result<i64, ValidationError> {
551 validate_utcdate(s)?;
552 let parse = |start: usize, end: usize| -> i64 {
553 let mut n: i64 = 0;
554 for &b in &s.as_bytes()[start..end] {
555 n = n * 10 + (b - b'0') as i64;
556 }
557 n
558 };
559 let year = parse(0, 4);
560 let month = parse(5, 7) as u32;
561 let day = parse(8, 10) as u32;
562 let hour = parse(11, 13) as u32;
563 let minute = parse(14, 16) as u32;
564 let second = parse(17, 19) as u32;
565
566 let days = days_from_civil(year, month, day);
567 Ok(days * 86_400 + hour as i64 * 3_600 + minute as i64 * 60 + second as i64)
568}
569
570impl State {
571 /// Construct a [`State`] with RFC 8620 §1.2 validation.
572 ///
573 /// Rejects empty strings. RFC 8620 §1.2 requires State to be non-empty;
574 /// no character-set restriction is imposed.
575 ///
576 /// Use [`State::from`] when the value is known to be valid.
577 pub fn new_validated(s: impl Into<String>) -> Result<Self, ValidationError> {
578 let s = s.into();
579 validate_state(&s)?;
580 Ok(Self(s))
581 }
582}
583
584#[cfg(test)]
585mod tests {
586
587 /// RFC 8620 §1.4: `time-secfrac` is a decimal fraction of a second, so
588 /// instants compare by seconds and then by that fraction's value, not
589 /// by string order or a truncated precision (bd JMAP-tna1.3.1).
590 #[test]
591 fn cmp_instant_compares_fractions_as_decimals() {
592 use std::cmp::Ordering::{Equal, Greater, Less};
593 let d = |s: &str| UTCDate::new_validated(s).unwrap();
594 let whole = d("2025-01-01T00:00:00Z");
595 assert_eq!(
596 d("2025-01-01T00:00:00.5Z").cmp_instant(&whole).unwrap(),
597 Greater
598 );
599 assert_eq!(
600 d("2025-01-01T00:00:00.0000000001Z")
601 .cmp_instant(&whole)
602 .unwrap(),
603 Greater
604 );
605 assert_eq!(
606 d("2025-01-01T00:00:00.5Z")
607 .cmp_instant(&d("2025-01-01T00:00:00.50Z"))
608 .unwrap(),
609 Equal
610 );
611 assert_eq!(
612 d("2025-01-01T00:00:00.09Z")
613 .cmp_instant(&d("2025-01-01T00:00:00.1Z"))
614 .unwrap(),
615 Less
616 );
617 assert_eq!(
618 d("2024-12-31T23:59:59.999Z").cmp_instant(&whole).unwrap(),
619 Less
620 );
621 assert!(UTCDate::from("nope").cmp_instant(&whole).is_err());
622 }
623 use super::*;
624
625 // Oracle: RFC 8620 §1.2 — Id is a plain JSON string, not a wrapped object.
626 #[test]
627 fn id_serializes_as_plain_string() {
628 let id = Id("abc123".to_owned());
629 let json = serde_json::to_string(&id).expect("serialize Id");
630 assert_eq!(json, "\"abc123\"");
631 }
632
633 // Oracle: RFC 8620 §1.2 — Id round-trips through JSON.
634 #[test]
635 fn id_deserializes_from_plain_string() {
636 let id: Id = serde_json::from_str("\"abc123\"").expect("deserialize Id");
637 assert_eq!(id.as_ref(), "abc123");
638 }
639
640 // Oracle: RFC 8620 §1.2 — "MUST be at least 1 character in length and
641 // maximum 255 octets in size" and "MUST only contain characters from the
642 // 'URL and Filename Safe' base64 alphabet ... excluding the pad
643 // character (=)". Hand-written JSON strings outside that rule must fail
644 // to deserialize.
645 #[test]
646 fn id_deserialize_rejects_non_conforming_strings() {
647 let too_long = format!("\"{}\"", "a".repeat(256));
648 for json in [
649 "\"\"",
650 "\"has space\"",
651 "\"#creation\"",
652 "\"a=\"",
653 "\"a/b\"",
654 "\"a.b\"",
655 too_long.as_str(),
656 ] {
657 assert!(
658 serde_json::from_str::<Id>(json).is_err(),
659 "{json} must be rejected"
660 );
661 }
662 }
663
664 // Oracle: RFC 8620 §1.2 — the full alphabet and the 255-octet maximum
665 // are accepted.
666 #[test]
667 fn id_deserialize_accepts_conforming_strings() {
668 let max = format!("\"{}\"", "Z".repeat(255));
669 for json in ["\"AZaz09-_\"", max.as_str()] {
670 assert!(
671 serde_json::from_str::<Id>(json).is_ok(),
672 "{json} must be accepted"
673 );
674 }
675 }
676
677 // Oracle: RFC 8620 §1.2 — Ids used as JSON object keys (e.g. /set
678 // "update") are validated the same way.
679 #[test]
680 fn id_deserialize_validates_map_keys() {
681 use std::collections::HashMap;
682 let ok: HashMap<Id, u8> = serde_json::from_str(r#"{"m1":1}"#).expect("valid key");
683 assert_eq!(ok.get("m1"), Some(&1));
684 assert!(serde_json::from_str::<HashMap<Id, u8>>(r#"{"bad key":1}"#).is_err());
685 }
686
687 // Oracle: RFC 8620 §1.4 example — "2014-10-30T06:12:00Z".
688 #[test]
689 fn utcdate_serializes_as_plain_string() {
690 let d = UTCDate("2014-10-30T06:12:00Z".to_owned());
691 let json = serde_json::to_string(&d).expect("serialize UTCDate");
692 assert_eq!(json, "\"2014-10-30T06:12:00Z\"");
693 }
694
695 // Oracle: RFC 8620 §3.4.1 fixture — sessionState value is "75128aab4b1b".
696 #[test]
697 fn state_serializes_as_plain_string() {
698 let s = State("75128aab4b1b".to_owned());
699 let json = serde_json::to_string(&s).expect("serialize State");
700 assert_eq!(json, "\"75128aab4b1b\"");
701 }
702
703 // Oracle: From<&str> trait contract.
704 #[test]
705 fn id_from_str() {
706 let id = Id::from("hello");
707 assert_eq!(id.as_ref(), "hello");
708 }
709
710 // Oracle: Display delegates to inner String.
711 #[test]
712 fn id_display() {
713 let id = Id("display-test".to_owned());
714 assert_eq!(id.to_string(), "display-test");
715 }
716
717 // Oracle: AsRef<str> returns the inner string.
718 #[test]
719 fn id_as_ref_str() {
720 let id = Id("ref-test".to_owned());
721 assert_eq!(id.as_ref(), "ref-test");
722 }
723
724 // Oracle: RFC 8620 §3.4.1 — State in sessionState field round-trips correctly.
725 #[test]
726 fn state_round_trip() {
727 let s = State("75128aab4b1b".to_owned());
728 let json = serde_json::to_string(&s).expect("serialize");
729 let s2: State = serde_json::from_str(&json).expect("deserialize");
730 assert_eq!(s, s2);
731 }
732
733 // Oracle: RFC 8620 §1.4 example — Date allows non-UTC offsets, unlike UTCDate.
734 #[test]
735 fn date_accepts_non_utc_offset() {
736 let d = Date("2014-10-30T14:12:00+08:00".to_owned());
737 let json = serde_json::to_string(&d).expect("serialize Date");
738 assert_eq!(json, "\"2014-10-30T14:12:00+08:00\"");
739 let d2: Date = serde_json::from_str(&json).expect("deserialize Date");
740 assert_eq!(d, d2);
741 }
742
743 // -----------------------------------------------------------------------
744 // new_validated / ValidationError tests
745 // Oracle for all: RFC 8620 §1.2 (Id, State) and §1.4 (UTCDate).
746 // -----------------------------------------------------------------------
747
748 /// Oracle: RFC 8620 §1.2 — Id must not be empty.
749 #[test]
750 fn id_new_validated_empty_fails() {
751 let err = Id::new_validated("").unwrap_err();
752 assert!(err.0.contains("empty"), "error must mention 'empty': {err}");
753 }
754
755 /// Oracle: RFC 8620 §1.2 URL-safe base64 alphabet — space (0x20) is
756 /// not in `A-Za-z0-9-_`.
757 #[test]
758 fn id_new_validated_space_fails() {
759 let err = Id::new_validated("has space").unwrap_err();
760 assert!(err.0.contains("invalid character"), "{err}");
761 }
762
763 /// Oracle: RFC 8620 §1.2 URL-safe base64 alphabet — double-quote
764 /// (0x22) is not in `A-Za-z0-9-_`.
765 #[test]
766 fn id_new_validated_dquote_fails() {
767 let err = Id::new_validated("has\"quote").unwrap_err();
768 assert!(err.0.contains("invalid character"), "{err}");
769 }
770
771 /// Oracle: RFC 8620 §1.2 URL-safe base64 alphabet — a control
772 /// character (0x01) is not in `A-Za-z0-9-_`.
773 #[test]
774 fn id_new_validated_control_char_fails() {
775 let err = Id::new_validated("has\x01ctrl").unwrap_err();
776 assert!(err.0.contains("invalid character"), "{err}");
777 }
778
779 /// Oracle: RFC 8620 §1.2 URL-safe base64 alphabet (RFC 4648 §5) —
780 /// every visible-ASCII character outside `A-Za-z0-9-_` MUST be
781 /// rejected. These characters were accepted by the previous
782 /// (incorrect) `SAFE-CHAR` validator; this test pins the spec-
783 /// conforming rejection (bd:JMAP-6xs8.19).
784 #[test]
785 fn id_new_validated_rejects_non_url_safe_base64_chars() {
786 // Representative sample of characters that are visible ASCII
787 // (the old SAFE-CHAR set) but NOT in the RFC 4648 §5 URL-safe
788 // base64 alphabet. Each MUST be rejected with category
789 // "invalid character".
790 let rejected = [
791 '!', '#', '$', '%', '&', '\'', '(', ')', '*', '+', ',', '.', '/', ':', ';', '<', '=',
792 '>', '?', '@', '[', '\\', ']', '^', '`', '{', '|', '}', '~',
793 ];
794 for ch in rejected {
795 let input = format!("a{ch}z");
796 let err = Id::new_validated(&input).unwrap_err();
797 assert!(
798 err.0.contains("invalid character"),
799 "char {ch:?} (input {input:?}) must be rejected with \
800 'invalid character', got: {err}"
801 );
802 }
803 }
804
805 /// Oracle: RFC 8620 §1.2 — max length 255 bytes.
806 #[test]
807 fn id_new_validated_too_long_fails() {
808 let long = "a".repeat(256);
809 assert!(Id::new_validated(long).is_err());
810 }
811
812 /// Oracle: valid printable ASCII Id succeeds and is preserved verbatim.
813 #[test]
814 fn id_new_validated_valid_succeeds() {
815 let id = Id::new_validated("abc123-_ABC").expect("valid Id must succeed");
816 assert_eq!(id.as_ref(), "abc123-_ABC");
817 }
818
819 /// Oracle: exactly 255-byte Id succeeds.
820 #[test]
821 fn id_new_validated_max_length_succeeds() {
822 let id255 = "a".repeat(255);
823 Id::new_validated(id255).expect("255-byte Id must succeed");
824 }
825
826 /// Oracle: RFC 8620 §1.4 example "2014-10-30T06:12:00Z" must succeed.
827 #[test]
828 fn utcdate_new_validated_valid_succeeds() {
829 let d = UTCDate::new_validated("2014-10-30T06:12:00Z").expect("valid UTCDate must succeed");
830 assert_eq!(d.as_ref(), "2014-10-30T06:12:00Z");
831 }
832
833 /// Oracle: UTC date without Z suffix is not RFC 8620 §1.4 format.
834 #[test]
835 fn utcdate_new_validated_no_z_fails() {
836 assert!(UTCDate::new_validated("2014-10-30T06:12:00+00:00").is_err());
837 }
838
839 /// Oracle: empty UTCDate fails.
840 #[test]
841 fn utcdate_new_validated_empty_fails() {
842 assert!(UTCDate::new_validated("").is_err());
843 }
844
845 /// Oracle: UTCDate with wrong length fails.
846 #[test]
847 fn utcdate_new_validated_wrong_length_fails() {
848 assert!(UTCDate::new_validated("2014-10-30").is_err());
849 // fractional seconds are not permitted in RFC 8620 §1.4 format.
850 assert!(UTCDate::new_validated("2014-10-30T06:12:00.000Z").is_err());
851 }
852
853 /// Oracle: RFC 8620 §1.4 makes UTCDate an RFC 3339 "date-time"
854 /// (`time-secfrac = "." 1*DIGIT`) where "the "time-secfrac" MUST
855 /// always be omitted if zero" (rfc8620.txt:346-347). A non-zero
856 /// fraction is therefore valid.
857 #[test]
858 fn utcdate_new_validated_nonzero_secfrac_succeeds() {
859 for s in [
860 "2014-10-30T06:12:00.123Z",
861 "2014-10-30T06:12:00.1Z",
862 "2014-10-30T06:12:00.001Z",
863 "2014-10-30T06:12:00.000001Z",
864 ] {
865 assert!(UTCDate::new_validated(s).is_ok(), "{s} must be accepted");
866 }
867 }
868
869 /// Oracle: RFC 3339 `time-secfrac = "." 1*DIGIT` plus the RFC 8620
870 /// §1.4 omit-if-zero rule: an empty, zero, or non-digit fraction fails.
871 #[test]
872 fn utcdate_new_validated_bad_secfrac_fails() {
873 for s in [
874 "2014-10-30T06:12:00.Z",
875 "2014-10-30T06:12:00.0Z",
876 "2014-10-30T06:12:00.00000Z",
877 "2014-10-30T06:12:00.12aZ",
878 "2014-10-30T06:12:00.123",
879 "2014-10-30T06:12:00.123z",
880 "2014-10-30T06:12:00Z0",
881 ] {
882 let err = UTCDate::new_validated(s).unwrap_err();
883 assert!(err.to_string().contains("wrong structure"), "{s}: {err}");
884 }
885 }
886
887 /// Oracle: 2014-10-30T06:12:00Z is 1_414_649_520 (RFC 8620 §1.4
888 /// example, GNU `date -u -d 2014-10-30T06:12:00Z +%s`); a sub-second
889 /// fraction does not move it to the next second.
890 #[test]
891 fn utcdate_to_epoch_seconds_truncates_secfrac() {
892 let d = UTCDate::new_validated("2014-10-30T06:12:00.999Z").unwrap();
893 assert_eq!(d.to_epoch_seconds().unwrap(), 1_414_649_520);
894 }
895
896 /// Oracle: non-digit in year position fails.
897 #[test]
898 fn utcdate_new_validated_non_digit_fails() {
899 assert!(UTCDate::new_validated("XXXX-10-30T06:12:00Z").is_err());
900 }
901
902 /// Oracle: RFC 8620 §1.4 — month out of range MUST be rejected.
903 /// Pre-tightening, `validate_utcdate` was shape-only and would
904 /// accept this. bd:JMAP-6xs8.20 added semantic validation.
905 #[test]
906 fn utcdate_new_validated_rejects_month_out_of_range() {
907 let err = UTCDate::new_validated("2024-13-15T09:00:00Z").unwrap_err();
908 assert!(err.0.contains("month must be"), "{err}");
909 let err = UTCDate::new_validated("9999-99-99T09:00:00Z").unwrap_err();
910 assert!(err.0.contains("month must be"), "{err}");
911 }
912
913 /// Oracle: RFC 8620 §1.4 — day out of range MUST be rejected
914 /// including non-existent dates (Feb 30) and Feb 29 in non-leap
915 /// years. bd:JMAP-6xs8.20.
916 #[test]
917 fn utcdate_new_validated_rejects_day_out_of_range() {
918 // Day 32 in January
919 let err = UTCDate::new_validated("2024-01-32T09:00:00Z").unwrap_err();
920 assert!(err.0.contains("day must be"), "{err}");
921 // Feb 30 never exists
922 let err = UTCDate::new_validated("2024-02-30T09:00:00Z").unwrap_err();
923 assert!(err.0.contains("day must be"), "{err}");
924 // Feb 29 in non-leap year 2023 (not divisible by 4)
925 let err = UTCDate::new_validated("2023-02-29T09:00:00Z").unwrap_err();
926 assert!(err.0.contains("day must be"), "{err}");
927 // April 31 (April has 30 days)
928 let err = UTCDate::new_validated("2024-04-31T09:00:00Z").unwrap_err();
929 assert!(err.0.contains("day must be"), "{err}");
930 }
931
932 /// Oracle: RFC 8620 §1.4 — Feb 29 in a leap year MUST be accepted.
933 /// Pins the leap-year branch of the day-range check (2024 is
934 /// divisible by 4, not by 100, so leap). bd:JMAP-6xs8.20.
935 #[test]
936 fn utcdate_new_validated_accepts_feb_29_leap_year() {
937 UTCDate::new_validated("2024-02-29T00:00:00Z").expect("leap day must succeed");
938 }
939
940 /// Oracle: RFC 8620 §1.4 — time-component out of range MUST be
941 /// rejected. Includes hour 24, minute 60, second 60 (no leap
942 /// seconds per §1.4 even though RFC 3339 §5.6 permits them).
943 /// bd:JMAP-6xs8.20.
944 #[test]
945 fn utcdate_new_validated_rejects_time_out_of_range() {
946 let err = UTCDate::new_validated("2024-06-15T24:00:00Z").unwrap_err();
947 assert!(err.0.contains("hour must be"), "{err}");
948 let err = UTCDate::new_validated("2024-06-15T09:60:00Z").unwrap_err();
949 assert!(err.0.contains("minute must be"), "{err}");
950 let err = UTCDate::new_validated("2024-06-15T09:00:60Z").unwrap_err();
951 assert!(err.0.contains("second must be"), "{err}");
952 }
953
954 /// Oracle: the absurd case from the bd:JMAP-6xs8.20 bead body
955 /// (`9999-99-99T99:99:99Z`) MUST be rejected. Pinned here so a
956 /// future contributor can't accidentally regress to the old
957 /// shape-only validator.
958 #[test]
959 fn utcdate_new_validated_rejects_absurd_values() {
960 let err = UTCDate::new_validated("9999-99-99T99:99:99Z").unwrap_err();
961 assert!(
962 err.0.contains("month must be"),
963 "first rejected component (in left-to-right order) is the \
964 month; got: {err}"
965 );
966 }
967
968 /// Oracle: RFC 8620 §1.2 — State must be non-empty.
969 #[test]
970 fn state_new_validated_empty_fails() {
971 let err = State::new_validated("").unwrap_err();
972 assert!(err.0.contains("empty"), "{err}");
973 }
974
975 /// Oracle: non-empty State string succeeds.
976 #[test]
977 fn state_new_validated_valid_succeeds() {
978 let s = State::new_validated("75128aab4b1b").expect("valid State must succeed");
979 assert_eq!(s.as_ref(), "75128aab4b1b");
980 }
981
982 /// Oracle: ValidationError implements std::error::Error and Display.
983 #[test]
984 fn validation_error_implements_error() {
985 let e = Id::new_validated("").unwrap_err();
986 let _: &dyn std::error::Error = &e;
987 assert!(!e.to_string().is_empty(), "error message must not be empty");
988 assert_eq!(format!("{e}"), e.0, "Display must show the inner message");
989 }
990
991 // -----------------------------------------------------------------------
992 // UTCDate::to_epoch_seconds tests
993 //
994 // Oracle for all numeric vectors: Python 3 `datetime.datetime(...).
995 // replace(tzinfo=timezone.utc).timestamp()`, computed independently and
996 // hardcoded as integer literals per workspace AGENTS.md "Test vector
997 // discipline". The oracle is independent of the code under test — these
998 // are NOT round-trip self-tests.
999 // -----------------------------------------------------------------------
1000
1001 /// Oracle (Python): `1970-01-01T00:00:00Z` → 0.
1002 #[test]
1003 fn utcdate_to_epoch_seconds_unix_epoch() {
1004 let d = UTCDate::new_validated("1970-01-01T00:00:00Z").unwrap();
1005 assert_eq!(d.to_epoch_seconds().unwrap(), 0);
1006 }
1007
1008 /// Oracle (Python): RFC 8620 §1.4 example `2014-10-30T06:12:00Z` →
1009 /// 1_414_649_520.
1010 #[test]
1011 fn utcdate_to_epoch_seconds_rfc8620_example() {
1012 let d = UTCDate::new_validated("2014-10-30T06:12:00Z").unwrap();
1013 assert_eq!(d.to_epoch_seconds().unwrap(), 1_414_649_520);
1014 }
1015
1016 /// Oracle (Python): `2000-01-01T00:00:00Z` (Y2K, century-leap year) →
1017 /// 946_684_800.
1018 #[test]
1019 fn utcdate_to_epoch_seconds_y2k() {
1020 let d = UTCDate::new_validated("2000-01-01T00:00:00Z").unwrap();
1021 assert_eq!(d.to_epoch_seconds().unwrap(), 946_684_800);
1022 }
1023
1024 /// Oracle (Python): `1999-12-31T23:59:59Z` (one second before Y2K) →
1025 /// 946_684_799.
1026 #[test]
1027 fn utcdate_to_epoch_seconds_pre_y2k() {
1028 let d = UTCDate::new_validated("1999-12-31T23:59:59Z").unwrap();
1029 assert_eq!(d.to_epoch_seconds().unwrap(), 946_684_799);
1030 }
1031
1032 /// Oracle (Python): `2024-02-29T00:00:00Z` (leap year, leap day start) →
1033 /// 1_709_164_800.
1034 #[test]
1035 fn utcdate_to_epoch_seconds_leap_day_2024() {
1036 let d = UTCDate::new_validated("2024-02-29T00:00:00Z").unwrap();
1037 assert_eq!(d.to_epoch_seconds().unwrap(), 1_709_164_800);
1038 }
1039
1040 /// Oracle (Python): `2024-02-29T23:59:59Z` (leap day end) →
1041 /// 1_709_251_199.
1042 #[test]
1043 fn utcdate_to_epoch_seconds_leap_day_2024_end() {
1044 let d = UTCDate::new_validated("2024-02-29T23:59:59Z").unwrap();
1045 assert_eq!(d.to_epoch_seconds().unwrap(), 1_709_251_199);
1046 }
1047
1048 /// Oracle (Python): `2100-03-01T00:00:00Z` exercises the
1049 /// century-non-leap-year rule (2100 is not a leap year, divisible by 100
1050 /// but not 400).
1051 #[test]
1052 fn utcdate_to_epoch_seconds_2100_non_leap_century() {
1053 let d = UTCDate::new_validated("2100-03-01T00:00:00Z").unwrap();
1054 assert_eq!(d.to_epoch_seconds().unwrap(), 4_107_542_400);
1055 }
1056
1057 /// Oracle (Python): `1969-12-31T23:59:59Z` (one second before epoch) → -1.
1058 /// Verifies negative-epoch handling.
1059 #[test]
1060 fn utcdate_to_epoch_seconds_one_before_epoch() {
1061 let d = UTCDate::new_validated("1969-12-31T23:59:59Z").unwrap();
1062 assert_eq!(d.to_epoch_seconds().unwrap(), -1);
1063 }
1064
1065 /// Oracle (Python): `1900-01-01T00:00:00Z` → -2_208_988_800.
1066 /// 1900 is divisible by 100 but not 400, so NOT a leap year — exercises
1067 /// the same century rule as 2100 but well before the epoch.
1068 #[test]
1069 fn utcdate_to_epoch_seconds_1900() {
1070 let d = UTCDate::new_validated("1900-01-01T00:00:00Z").unwrap();
1071 assert_eq!(d.to_epoch_seconds().unwrap(), -2_208_988_800);
1072 }
1073
1074 /// Oracle (Python): `0001-01-01T00:00:00Z` → -62_135_596_800.
1075 /// Far-past boundary; verifies the proleptic Gregorian algorithm
1076 /// extrapolates correctly to year 1.
1077 #[test]
1078 fn utcdate_to_epoch_seconds_year_one() {
1079 let d = UTCDate::new_validated("0001-01-01T00:00:00Z").unwrap();
1080 assert_eq!(d.to_epoch_seconds().unwrap(), -62_135_596_800);
1081 }
1082
1083 /// Oracle (Python): `9999-12-31T23:59:59Z` (UTCDate max year) →
1084 /// 253_402_300_799.
1085 /// Far-future boundary within `i64` range.
1086 #[test]
1087 fn utcdate_to_epoch_seconds_year_9999() {
1088 let d = UTCDate::new_validated("9999-12-31T23:59:59Z").unwrap();
1089 assert_eq!(d.to_epoch_seconds().unwrap(), 253_402_300_799);
1090 }
1091
1092 /// Oracle (Python): `2038-01-19T03:14:07Z` = i32::MAX = 2_147_483_647
1093 /// (the "Year 2038 problem" boundary).
1094 #[test]
1095 fn utcdate_to_epoch_seconds_y2038_boundary() {
1096 let d = UTCDate::new_validated("2038-01-19T03:14:07Z").unwrap();
1097 assert_eq!(d.to_epoch_seconds().unwrap(), 2_147_483_647);
1098 }
1099
1100 /// Oracle (Python): `2038-01-19T03:14:08Z` = i32::MAX + 1.
1101 /// Verifies `i64` handles the i32 overflow point that 32-bit time_t
1102 /// implementations would wrap at.
1103 #[test]
1104 fn utcdate_to_epoch_seconds_post_y2038() {
1105 let d = UTCDate::new_validated("2038-01-19T03:14:08Z").unwrap();
1106 assert_eq!(d.to_epoch_seconds().unwrap(), 2_147_483_648);
1107 }
1108
1109 /// Oracle: `validate_utcdate` accepts month 13 structurally; semantic
1110 /// validation in `to_epoch_seconds` must reject it.
1111 #[test]
1112 fn utcdate_to_epoch_seconds_rejects_month_13() {
1113 let d = UTCDate::from("2024-13-01T00:00:00Z");
1114 let err = d.to_epoch_seconds().unwrap_err();
1115 assert!(err.0.contains("month"), "error must mention month: {err}");
1116 }
1117
1118 /// Oracle: `validate_utcdate` accepts day 32 structurally; semantic
1119 /// validation in `to_epoch_seconds` must reject it.
1120 #[test]
1121 fn utcdate_to_epoch_seconds_rejects_day_32() {
1122 let d = UTCDate::from("2024-01-32T00:00:00Z");
1123 let err = d.to_epoch_seconds().unwrap_err();
1124 assert!(err.0.contains("day"), "error must mention day: {err}");
1125 }
1126
1127 /// Oracle: 2023 is NOT a leap year; Feb 29 must be rejected as
1128 /// out-of-range for that month.
1129 #[test]
1130 fn utcdate_to_epoch_seconds_rejects_feb_29_non_leap() {
1131 let d = UTCDate::from("2023-02-29T00:00:00Z");
1132 let err = d.to_epoch_seconds().unwrap_err();
1133 assert!(err.0.contains("day"), "error must mention day: {err}");
1134 }
1135
1136 /// Oracle: hour 24 is out of range per RFC 8620 §1.4 (no end-of-day
1137 /// convention) — `to_epoch_seconds` must reject it.
1138 #[test]
1139 fn utcdate_to_epoch_seconds_rejects_hour_24() {
1140 let d = UTCDate::from("2024-01-01T24:00:00Z");
1141 let err = d.to_epoch_seconds().unwrap_err();
1142 assert!(err.0.contains("hour"), "error must mention hour: {err}");
1143 }
1144
1145 /// Oracle: minute 60 out of range.
1146 #[test]
1147 fn utcdate_to_epoch_seconds_rejects_minute_60() {
1148 let d = UTCDate::from("2024-01-01T00:60:00Z");
1149 let err = d.to_epoch_seconds().unwrap_err();
1150 assert!(err.0.contains("minute"), "error must mention minute: {err}");
1151 }
1152
1153 /// Oracle: second 60 (leap second) is not permitted by RFC 8620 §1.4 —
1154 /// `to_epoch_seconds` must reject it.
1155 #[test]
1156 fn utcdate_to_epoch_seconds_rejects_leap_second() {
1157 let d = UTCDate::from("2016-12-31T23:59:60Z");
1158 let err = d.to_epoch_seconds().unwrap_err();
1159 assert!(err.0.contains("second"), "error must mention second: {err}");
1160 }
1161
1162 /// Oracle: a value constructed via `UTCDate::from` with wrong structure
1163 /// must surface a structural ValidationError (re-validation in
1164 /// `to_epoch_seconds`).
1165 #[test]
1166 fn utcdate_to_epoch_seconds_rejects_invalid_structure() {
1167 let d = UTCDate::from("not-a-date");
1168 assert!(d.to_epoch_seconds().is_err());
1169 }
1170
1171 /// Oracle (Python): `2024-02-28T23:59:59Z` → `2024-02-29T00:00:00Z` is
1172 /// exactly one second forward. Verifies leap-day arithmetic is
1173 /// internally consistent.
1174 #[test]
1175 fn utcdate_to_epoch_seconds_leap_day_boundary_one_sec() {
1176 let a = UTCDate::new_validated("2024-02-28T23:59:59Z").unwrap();
1177 let b = UTCDate::new_validated("2024-02-29T00:00:00Z").unwrap();
1178 let diff = b.to_epoch_seconds().unwrap() - a.to_epoch_seconds().unwrap();
1179 assert_eq!(
1180 diff, 1,
1181 "Feb 28 23:59:59 → Feb 29 00:00:00 must be 1 second"
1182 );
1183 }
1184
1185 /// Oracle (Python): a 365-day duration `2023-01-01T00:00:00Z` to
1186 /// `2024-01-01T00:00:00Z` is exactly `365 * 86_400 = 31_536_000` seconds
1187 /// (2023 is not a leap year). Anchors the `CalendarsLimits::default()
1188 /// .max_expanded_query_duration_seconds` value (`31_536_000`).
1189 #[test]
1190 fn utcdate_to_epoch_seconds_365_day_year_duration() {
1191 let a = UTCDate::new_validated("2023-01-01T00:00:00Z").unwrap();
1192 let b = UTCDate::new_validated("2024-01-01T00:00:00Z").unwrap();
1193 let diff = b.to_epoch_seconds().unwrap() - a.to_epoch_seconds().unwrap();
1194 assert_eq!(diff, 31_536_000);
1195 }
1196
1197 /// Oracle (Python): a 366-day duration `2024-01-01T00:00:00Z` to
1198 /// `2025-01-01T00:00:00Z` is `366 * 86_400 = 31_622_400` seconds (2024 is
1199 /// a leap year).
1200 #[test]
1201 fn utcdate_to_epoch_seconds_366_day_leap_year_duration() {
1202 let a = UTCDate::new_validated("2024-01-01T00:00:00Z").unwrap();
1203 let b = UTCDate::new_validated("2025-01-01T00:00:00Z").unwrap();
1204 let diff = b.to_epoch_seconds().unwrap() - a.to_epoch_seconds().unwrap();
1205 assert_eq!(diff, 31_622_400);
1206 }
1207}