Snapshot and restore

A snapshot is a saved copy of a whole namespace. Take one after setting up the state a test needs, and restore it before each test: the namespace goes back to exactly that state, so the requests that follow give the same responses every time.

#Interface

#Admin page

Open http://localhost:8787/__admin/ui#snapshots. The sidebar item is Snapshot & restore. On a narrow window the sidebar shows its icon; the label is on the tooltip. Jump (⌘K or Ctrl+K) finds the screen by "snapshot" or "restore".

The header Namespace select chooses which namespace the buttons act on.

Checkpoints also has a button named Restore. That one checks out a checkpoint. It does not restore a snapshot.

#Quick start

# Save the namespace under a name.
curl -X POST localhost:8787/__admin/snapshots -d '{"name": "baseline"}'

# ... run a test that changes things ...

# Put it back.
curl -X POST localhost:8787/__admin/snapshots/baseline/restore

{ "status": "ok", "id": "baseline", "namespace": "default" }

#What a snapshot holds

Everything the namespace is, so that restoring it replays what followed:

Not in a snapshot: the journal and metrics (what happened is not undone), other snapshots, and anything outside the namespace.

#Admin API

A snapshot belongs to the namespace it was taken in. Its id is unique within that namespace.

#POST /__admin/snapshots

Take a snapshot now.

curl -X POST localhost:8787/__admin/snapshots -d '{"name": "baseline"}'

{ "id": "baseline", "namespace": "default", "records": 0, "at": 1893456000000, "portable": true }

Status 201.

#GET /__admin/snapshots

The namespace's snapshots, oldest first.

curl localhost:8787/__admin/snapshots

{
  "snapshots": [
    { "id": "baseline", "namespace": "default", "records": 0, "at": 1893456000000, "portable": true }
  ]
}

#POST /__admin/snapshots/<id>/restore

Replace the namespace with the snapshot. No body. The snapshot stays, so it can be restored again.

curl -X POST localhost:8787/__admin/snapshots/baseline/restore

{ "status": "ok", "id": "baseline", "namespace": "default" }

#GET /__admin/snapshots/<id>

Export the snapshot as a JSON document. Commit it beside a test suite, import it into another namespace, or boot another process from it.

curl localhost:8787/__admin/snapshots/baseline

{
  "format": "mockingbird.snapshot/v1",
  "service": "stripe",
  "records": [],
  "sequences": [],
  "clock": { "now": 1893456000000, "frozen": true, "autoAdvanceMs": 0 },
  "seed": 0,
  "rng": { "state": 0, "faults": 0, "latency": 0 },
  "faults": { "rules": [], "nextId": 0 },
  "latency": { "delayMs": 0, "jitterMs": 0, "operations": {} },
  "virtualTime": false
}

#PUT /__admin/snapshots/<id>

Store a document as a snapshot under this id. Nothing in the namespace changes until it is restored.

curl -X PUT localhost:8787/__admin/snapshots/seeded -d '{
  "format": "mockingbird.snapshot/v1",
  "records": [
    { "collection": "customers", "id": "cus_1", "value": { "id": "cus_1", "email": "ada@example.com" } }
  ]
}'

{ "id": "seeded", "namespace": "default", "records": 1, "at": 1893456000000, "portable": true }

Status 200.

#DELETE /__admin/snapshots/<id>

Delete a snapshot. Answers {"status": "ok"}.

curl -X DELETE localhost:8787/__admin/snapshots/seeded

#The snapshot document

Only format and records are required, so a hand-written seed file is a valid snapshot.

Collection names and row shapes are the emulator's own; read them from GET /__admin/state.

A document restores what it holds and leaves the rest of the namespace as it is. A file with only records replaces the records and touches no clock, fault or latency.

#Request headers

# Create a customer and save the result as "one-customer".
curl -X POST localhost:8787/v1/customers -H 'x-mockingbird-snapshot: one-customer' \
  -H 'authorization: Bearer sk_test_mockingbird' -d email=ada@example.com

# Later: go back to it, then list.
curl localhost:8787/v1/customers -H 'x-mockingbird-restore: one-customer' \
  -H 'authorization: Bearer sk_test_mockingbird'

A snapshot asked for in a header is taken only when there is a response to carry its name: not when the connection is dropped.

#At boot

Start every namespace from a document instead of the emulator's own seed data:

curl localhost:8787/__admin/snapshots/baseline > baseline.json
npx mockingbird-stripe serve --snapshot baseline.json

import baseline from "./baseline.json"

const stripe = createRuntime({ adminControls: { snapshot: baseline } })

Reset then returns to that document. A control named beside snapshot (a clock, a seed) wins over the one the snapshot carries.

#In process

runtime.snapshots.create({ name: "baseline" })           // → { id, namespace, records, at, portable }
runtime.snapshots.create({ name: "s", namespace: "w" })
runtime.snapshots.list("w")                               // → [{ id, … }]
runtime.snapshots.restore("baseline")
const document = runtime.snapshots.export("baseline")    // → SnapshotDocument
runtime.snapshots.import(document, { name: "copy", namespace: "w" })
runtime.snapshots.delete("baseline")                      // → true

restore and export throw a RangeError for a snapshot that is not there.

#Rules

• Restoring adds to history. It does not rewrite checkpoints: the same write after a restore is the same response under a later checkpoint id.
• A reset discards snapshots. Export the ones you want to keep, or boot from them.
• Imported rules land in the namespace they are restored into, wherever the snapshot was taken.
• Snapshots stay in the process. They are gone when the emulator stops; an exported document is what persists.

#Errors

A request with x-mockingbird-restore naming a snapshot that is not there answers 404 and changes nothing.

#Related

• Reset returns to boot instead of to a snapshot.
• Checkpoints and branches are taken automatically after every write and are read with a header.
• Journal, metrics and state for the collection names a document's records use.