Expand description
The one clock the standard library reads, with an override for
nitr test (nitr.test.clock).
Every wall-clock or elapsed-time read whose answer a script can observe
goes through here: nitr.time.now/monotonic, session and JWT expiry,
the after/before validation rules, cache TTLs, and the rate
limiter’s window. A test can then age a session or expire a cache entry
by saying so, instead of sleeping.
What deliberately does not read this clock: the runtime’s execution
deadline, every tokio::time timeout, and the body-stall timers. They
measure real time by design — routed through the override,
t.clock.advance(3600) would trip the budget of the very test that
called it.
The override is process-global, because several readers (the rate
limiter, the cache) have no Lua state to find a per-state value in.
That is sound only because nothing sets it but the nitr test runner,
which runs files and tests strictly one after another and resets the
override after every test and every file. A production process never
calls set or advance, and then every read costs one relaxed
atomic load on top of the real clock. The standard library’s own unit
tests exercise a private Clock instance, never the global one.
Functions§
- advance
- Moves wall and monotonic time forward together by
secs— what a TTL or a rate-limit window needs to see. Fornitr testonly. - now_
instant - The monotonic clock, moved forward by
advance. - now_
system - The wall clock.
- now_
unix - The wall clock as whole unix seconds (
0before the epoch). - now_
unix_ f64 - The wall clock as fractional unix seconds (
0.0before the epoch). - reset
- Removes any override: every reader sees the real clock again.
- set
- Freezes the wall clock at
tsunix seconds. Monotonic time keeps flowing: anInstantcannot be moved backwards. Fornitr testonly. - take_
touched - Whether the clock was set or advanced since the last call — even if it has been reset since. Anything that stored an instant meanwhile (a cache entry’s expiry) carries the overridden time: the runner clears such state when this says so.