Skip to main content

now_utc_string

Function now_utc_string 

Source
pub fn now_utc_string() -> UTCDate
Expand description

Return the current UTC instant as an UTCDate (RFC 3339, millisecond precision, format YYYY-MM-DDTHH:MM:SS.mmmZ, or YYYY-MM-DDTHH:MM:SSZ when the milliseconds are zero because RFC 8620 §1.4 says the “time-secfrac” “MUST always be omitted if zero”). For years 0000..=9999 the value passes UTCDate::new_validated.

Uses std::time::SystemTime so no external dependency is needed.

Returns a typed UTCDate rather than a String (bd:JMAP-wlip.20) so callers do not need to wrap the result in UTCDate::from(now_utc_string().as_str()). The function name is retained for back-compat across the workspace’s many call sites.

Pre-epoch handling: SystemTime::now().duration_since(UNIX_EPOCH) fails on clocks drifted before the epoch. The function uses Err::duration() to recover the magnitude and negates the seconds before formatting; the result is a correct RFC 3339 timestamp anywhere from the BCE proleptic Gregorian range up to 1970-01-01T00:00:00Z. The rem_euclid / div_euclid math at the format step handles arbitrarily-large negative offsets, not only sub-day drifts. Pre-epoch correctness is best-effort — SystemTime is non-monotonic and the JMAP spec does not require pre-epoch timestamps. (bd:JMAP-wlip.11 corrected the previous docstring’s incorrect “1969-12-31T… through 1970-01-01T00:00:00Z” range claim.)

Clock-overflow handling: on a corrupted clock (system clock reporting a Duration whose as_secs() exceeds i64::MAX, civil_from_days reporting a year outside i32, or any other SystemTime failure mode), this function panics. The previous sentinel-string behaviour (UTCDate::from("clock-out-of-range")) was an idiom-grade defect (bd:JMAP-jfia.30): the sentinel was not a valid wire-format timestamp, had no in-band signal to distinguish it from a real value, and could silently propagate into JSON responses, audit logs, and database rows.

Callers that need to handle clock failure without panicking MUST use now_utc_string_checked, which returns Option<UTCDate>. Long-running daemons, schedulers, and persistence layers SHOULD prefer the checked variant; one-shot tools and request handlers MAY accept the panic since clock corruption is unrecoverable and the dispatcher’s task::spawn isolation already converts the panic into a serverFail invocation rather than crashing the process.

§Panics

Panics if SystemTime::now() cannot be expressed as an RFC 3339 timestamp — the same conditions under which now_utc_string_checked returns None.