Skip to content
CounterFire Docs

Realtime: reconnect and snapshots

The realtime layer is the part of CounterFire that must never lose or duplicate a ticket. This page describes the OrderHub Durable Object, the snapshot-on-connect behavior, and the reconnect-and-replay protocol that delivers events exactly once and in order.

OrderHub: the event spine

There is one OrderHub Durable Object per restaurant, bound as ORDER_HUB. It is the realtime coordinator:

  • It holds the live WebSocket and SSE connections for the KDS and for customer trackers.
  • It maintains the authoritative in-flight ticket set and the per-order seq.
  • It serves a snapshot to each consumer on connect.
  • It replays missed events on reconnect.

Crucially, OrderHub is a fan-out and cache, not the source of truth. The durable source of truth is D1 plus the append-only order_event log. OrderHub rehydrates its state from D1 on a cold start, and its state is always derivable from the log. That separation is deliberate: if OrderHub were treated as the source of truth, an eviction could lose tickets.

The two streams

Both streams are served via OrderHub and both follow the same snapshot-then- incremental shape.

  • KDS stream, GET /v1/kds/stream: a WebSocket or SSE upgrade for the whole restaurant. On connect it sends a snapshot of all open tickets, then ordered incremental order events.
  • Customer tracker stream, GET /v1/track/:trackerToken/stream: an SSE stream for a single order. On connect it sends a snapshot of that order’s current status, then incremental events.

Snapshot on connect

When a consumer connects, OrderHub first sends a snapshot: the current state the consumer needs, computed from the durable log.

  • For the KDS, the snapshot is the full set of open tickets for the restaurant, so the board is never blank or stale on load, reload, or reconnect.
  • For a customer tracker, the snapshot is the current status and timestamps for that one order.

After the snapshot, the consumer receives incremental events as they happen.

Reconnect and gap replay

The reconnect protocol guarantees ordered, exactly-once delivery:

  1. The client tracks its last applied seq. Every event carries a per-order monotonic sequence number (see order event schema). The client remembers the highest seq it has applied.
  2. The client acknowledges its last seq on reconnect. When the connection drops and comes back, the client tells OrderHub where it left off.
  3. OrderHub replays only the gap. It sends the events after the acknowledged seq, not the entire history, so reconnect is fast and complete.
  4. The client merges idempotently, keyed by (order_id, seq). An event whose (order_id, seq) was already applied is ignored.

The result: after a tablet network drop, the KDS sees exactly the tickets it missed, in order, with no duplicates. The customer tracker deduplicates by seq the same way.

Why exactly-once holds

The guarantee is the product of three properties working together:

  • Append-only log with per-order seq gives a total order and a stable key.
  • Snapshot-on-connect means a consumer never starts from an unknown state.
  • Idempotent merge by (order_id, seq) absorbs any duplicate delivery.

Because the durable log is authoritative and OrderHub only fans out from it, a realtime restart or eviction degrades to a reconnect, which the protocol above already handles. No additional recovery path is needed.

Testing the guarantee

This behavior is verified at two levels. The OrderHub event sequencing, snapshot, and reconnect-replay logic is tested against a real Workers, D1, and Durable Object runtime with a 100 percent coverage gate on the business-logic source. End to end, a Playwright test simulates a KDS network drop and asserts no dropped or duplicated tickets and ordered delivery.