Clock

Every timestamp an emulator writes reads from its clock. Set it, freeze it or move it, and expiries, retry windows and renewals arrive in milliseconds instead of being waited for.

#Interface

An instant is epoch milliseconds or ISO-8601. A duration is milliseconds or a string: "250ms", "2s", "15m", "1h", "3d".

#Admin page

Open http://localhost:8787/__admin/ui#clock.

#Admin API

#GET /__admin/clock

curl localhost:8787/__admin/clock

{
  "now": 1893456000000,
  "iso": "2030-01-01T00:00:00.000Z",
  "frozen": true,
  "offsetMs": 0,
  "autoAdvanceMs": 0
}

#POST /__admin/clock

Move the namespace's clock. Every field is optional, and they apply in the order listed.

set and freeze are accepted as older spellings of now and frozen. Answers the same body as GET.

curl -X POST localhost:8787/__admin/clock -d '{"now": "2030-06-01T00:00:00Z", "frozen": true}'
curl -X POST localhost:8787/__admin/clock -d '{"advance": "15m"}'

{
  "now": 1906503300000,
  "iso": "2030-06-01T00:15:00.000Z",
  "frozen": true,
  "offsetMs": 0,
  "autoAdvanceMs": 0
}

#Request headers

Both persist, like the admin call they stand for. Sending the same x-mockingbird-time on every request of a test pins every one of them to that instant.

curl -X POST localhost:8787/v1/customers -H 'x-mockingbird-time: 2030-01-01T00:00:00Z' \
  -H 'authorization: Bearer sk_test_mockingbird' -d email=ada@example.com

#At boot

{ "clock": { "now": "2030-01-01T00:00:00Z", "frozen": true, "autoAdvance": "1s" } }

npx mockingbird-stripe serve --clock 2030-01-01T00:00:00Z --freeze --auto-advance 1s

#In process

const clock = runtime.namespaceClock("worker-3") // omit the key for "default"
clock.now()            // epoch ms
clock.set(Date.parse("2030-01-01T00:00:00Z"))
clock.advance(15 * 60_000)
clock.freeze()
clock.unfreeze()
clock.reset()          // follow the base clock again
clock.state()          // { now, frozen, offsetMs }

runtime.clock          // the base clock every namespace follows

#How the clocks relate

• Every namespace has its own clock, default included. Moving one never moves another.
• Each follows the base clock with an offset and a freeze of its own. The boot clock sets the base clock; in process it is runtime.clock. Moving the base moves every namespace that has not frozen its own clock.
• A frozen clock moves only when told to. That is what makes timestamps reproducible.
• autoAdvance keeps frozen timestamps distinct: each vendor request steps the clock first, so two records never share an instant. Admin calls do not step it.
• With virtual time, injected waits move the clock too.
• Reset returns the namespace's clock to boot. A snapshot restores the instant it was taken at.

An emulator that keeps a schedule (subscription renewals, session expiry) runs it as soon as the namespace's clock is moved, so what came due is visible on the next read.

#Errors

#Related

• Checkpoints and branches: travel through the namespace's state instead of its clock.
• Latency and timeouts: spend waits on this clock with virtual time.
• Faults: from and until open and close a fault on this clock.