Skip to main content

now_utc_string_checked

jmap_server

Function now_utc_string_checked 

Source 
pub fn now_utc_string_checked() -> Option<UTCDate>
Expand description

Return the current UTC instant as an UTCDate (RFC 3339, millisecond precision, format YYYY-MM-DDTHH:MM:SS.mmmZ), or None if the system clock cannot be expressed as an RFC 3339 timestamp.

Added in bd:JMAP-jfia.30 to replace the previous sentinel-string failure mode of now_utc_string with a typed Option shape. Callers that want to react to a clock fault (audit-log timestamps, last-seen markers, retention sweeps) SHOULD use this variant; callers for whom a panic at the first sign of clock corruption is acceptable MAY use now_utc_string directly.

Returns None when:

  • SystemTime::now().duration_since(UNIX_EPOCH).as_secs() exceeds i64::MAX (only reachable on a corrupted clock — approx ±292 billion years from epoch).
  • The negation of a pre-epoch duration overflows i64 (unreachable on a try_from-validated input but checked defensively).
  • civil_from_days reports a year outside i32 (bd:JMAP-jfia.2 — between the i32-year boundary and the i64::MAX-secs cap).

§Why Option<UTCDate> and not Result<UTCDate, ClockError> (bd:JMAP-jfia.38)

The three failure modes are all “corrupted clock” — each one is physically unreachable on a sane host (years 5.7M-to-292B, try_from-impossible negation, i32-overflowing year). A caller that wants to branch on which physical mechanism fired would be branching on states that don’t happen. The shapes the workspace uses elsewhere for typed-variant-per-mode (SetError, BackendChangesError, BackendSetError, MergePatchError) all carry failure modes that DO occur in normal operation — notFound, tooManyChanges, invalidPatch, depthExceeded. The clock-corruption modes are different in kind. Erasing the discriminator here trades a hypothetical observability win for a cleaner contract: “the clock is unusable for RFC 3339, abandon timestamping.” A future need for per-mode telemetry can be added non-breakingly as a parallel helper (e.g. now_utc_string_diagnose -> Result<UTCDate, ClockError>) without disturbing this shape.