Short answer: keep bidding commands, event delivery, and presence evidence behind separate API boundaries, then measure sequence gaps and freshness instead of guessing that a connected socket means a present bidder.
| Boundary | Pick this when | Observe first |
|---|---|---|
| Command API | A user changes auction state | Idempotency key, authorization result, commit latency |
| Event stream | Many dashboards need the same committed change | Sequence, cursor, delivery age |
| Presence service | The UI must show who can bid now | Lease age, heartbeat skew, last-seen confidence |
| Replay endpoint | A client reconnects or detects a gap | Requested range, replay result, snapshot age |
That table is the field guide. The least complex design that preserves an honest presence indicator is a small command endpoint plus an append-only event log and a lease-based presence record. Add a replay path before adding more transports. A shiny stream without replay just turns a brief network pause into a wrong auction board.
Measure the truth.
How should realtime event observability shape API boundaries in a live auction dashboard?
Start with the state transition, not the WebSocket. In a live auction, bid.accepted is a fact only after the server validates the lot, bidder scope, and current price. The command boundary owns that decision. It returns a stable event identifier and a monotonic streamSeq; it does not promise that every browser has painted the update.
The event boundary distributes committed facts. A browser can consume Server-Sent Events, WebSocket frames, or a polling cursor because the contract is about ordering and replay, not a particular connection. I use one envelope everywhere:
type AuctionEvent = {
id: string;
stream: string;
streamSeq: number;
type: "bid.accepted" | "lot.closed";
occurredAt: string;
payload: Record<string, unknown>;
};
The presence boundary answers a narrower question: “has this participant renewed a scoped lease recently?” That is different from “did the browser receive event 812?” Mixing those answers creates false confidence. A tab can receive events while its microphone, identity token, or bidding permission has expired. Conversely, a participant can be present while a dashboard is catching up from a replay cursor.
Keep the identifiers explicit. auctionId, lotId, and participantId belong in the authorization context and in logs. Do not infer scope from a topic string supplied by the browser. A useful trace links the command request, committed event, delivery attempt, and presence renewal with the same traceId.
What does a trustworthy signal look like?
Presence is a measurement with uncertainty. Store a lease expiry and the server timestamp of the last renewal. Render “present” only while the lease is valid; render “stale” during a short grace interval; render “unknown” after that. The exact interval is a product decision, so publish it as configuration and alert on drift. During a school-hosted auction, for example, a student may switch tabs just as a heartbeat is delayed by browser scheduling; the dashboard should show the confidence transition instead of silently extending the old state. Record the reason for every transition so support can explain what the bidder saw without reconstructing it from packet captures.
For event delivery, record four clocks: occurredAt, publishedAt, receivedAt, and renderedAt. Their differences expose different failures. A high publish delay points at the broker or producer. A high receive delay points at the network or subscriber. A high render delay points at the browser main thread. One end-to-end number hides this distinction.
Sequence gaps are more actionable than raw disconnect counts. If a client has streamSeq=810 and receives 812, it should pause rendering, request 811..811, and resume only after continuity is restored. The server must make replay bounded and authorization-aware. Never let a cursor from one auction read another auction's history.
Here is a compact client loop. It uses generic HTTP so the same contract works in any language.
type CursorResponse = { events: AuctionEvent[]; nextSeq: number };
async function readFrom(auctionId: string, after: number, signal: AbortSignal) {
const url = `/auctions/${encodeURIComponent(auctionId)}/events?after=${after}`;
const response = await fetch(url, { headers: { accept: "application/json" }, signal });
if (!response.ok) throw new Error(`event replay failed: ${response.status}`);
return response.json() as Promise<CursorResponse>;
}
function applyInOrder(state: Map<string, unknown>, events: AuctionEvent[], expected: number) {
let next = expected;
for (const event of events) {
if (event.streamSeq !== next + 1) return { next, gap: true };
state.set(event.id, event.payload);
next = event.streamSeq;
}
return { next, gap: false };
}
The important behavior is the gap check, not the transport. Emit a metric when gap: true, with auction and participant dimensions kept low-cardinality. Put the full identifiers in a structured log or trace instead. This is where teams often burn time: a dashboard says “connected,” while the last accepted bid is 20 seconds behind.
A practical observability contract
Define a small vocabulary before wiring alerts. Counters should include commands_total, events_published_total, replay_requests_total, and presence_expired_total. Histograms should cover command commit latency, event delivery age, replay duration, and render delay. Gauges can show active leases, but a gauge alone cannot explain why it changed.
Every event log entry needs a reason for rejection when a command fails: lot_closed, price_too_low, or scope_denied. These are business outcomes, not server errors. Keep transport failures separate, and include the HTTP status and retry classification. A 409 conflict may be expected during a fast bidding round; a burst of 5xx responses needs a different page and a different owner.
Alert on user-visible truth. For example, page when the p95 age of bid.accepted on the dashboard exceeds 2 seconds for five minutes, or when the replay-gap rate crosses a threshold agreed with product. Do not page on every reconnect. Mobile networks reconnect constantly; a reconnect is a clue, not a verdict.
I keep a before-and-after trace in the runbook. Before the boundary split, one request log showed a 200 response and nothing about delivery. Afterward, a single traceId reads like a diagram in words: command accepted, event committed at sequence 812, subscriber received it 140 ms later, browser rendered it 38 ms after that, presence lease renewed 4 seconds ago. If the next frame reports sequence 814, the same trace records the gap, the bounded replay request, the authorization check for that range, and the point where rendering resumed; it also records whether the presence lease crossed its expiry while the repair was running. That narrative lets an on-call engineer choose the right layer in minutes, gives a product manager a defensible freshness number, and leaves a test case the client team can replay locally.
Pick the transport that fits the boundary
WebSocket is useful when the dashboard needs bidirectional control messages, but it increases lifecycle states to observe. Server-Sent Events are a simpler fit for server-to-browser event delivery and make HTTP infrastructure visible in the path. A cursor-based polling endpoint is slower and often easier to operate, which can be perfectly adequate for an internal auction console.
The catch is that none of these transports supplies ordering, authorization, or presence semantics by itself. Add those to the application contract. The W3C WebRTC specification is relevant when a separate video or voice room exists, yet its connection state should not be reused as auction presence; media connectivity and bidding authority are different signals.
Choose a transport per boundary when necessary. A command can remain ordinary HTTPS while events use SSE and replay uses the same HTTPS API. That split costs a little more documentation, but it keeps failure domains legible.
Limits and decision rules
This approach is not suitable when the product requires a total global order across unrelated auctions; use a domain model that defines that order first. It is also a poor fit for clients that cannot persist a cursor or tolerate a brief “unknown” presence state. Stick with a simpler polling view when stale data is acceptable and the team cannot yet operate an event log.
Presence accuracy still depends on clock discipline, lease renewal policy, and clear UI wording. Your mileage may vary with background-tab throttling and long mobile suspensions. Test those cases deliberately: advance a fake clock, drop events 811 and 812, revoke a token, and reconnect after a snapshot expires. The acceptance rule is concrete: no dashboard may show a bidder as present when its authorized lease is expired, and no committed bid may be rendered out of sequence.
Top comments (0)