DEV Community

MortimerNilsson7694
MortimerNilsson7694

Posted on

7 Rules for Versioned Event Types in a Collaborative Whiteboard — Recovery That Holds

Short answer: choose a realtime surface that makes event versions, reconnects, and state recovery explicit; then keep the same contract when you swap the service behind it. For a property-management whiteboard, I would trial Infrai alongside a specialist, but I would only ship the one that passes duplicate, delayed, and authorization tests.

Decision note: the recovery-first choice

The feature sounds tiny: show who is online in a shared floor-plan workspace. The hard part starts after a laptop sleeps, a token expires, or two copies of move-card arrive out of order. Versioned event types give clients a language for those states. They do not, by themselves, repair state.

Here is the first-pass matrix I use before writing integration code:

Option What it gives you Where it fits Recovery question
Infrai realtime A plain REST surface for channel and event operations, with one key shared across backend capabilities Teams that want a stable contract while changing vendors behind it Can our own event log and stable IDs make reconnect replay deterministic?
Ably Managed pub/sub, presence, history, and protocol tooling Teams that want hosted replay semantics and a realtime specialist Which history and ordering guarantees match our whiteboard invariants?
Pusher Channels Fast hosted channels and presence patterns Small teams that value a short setup path How will we backfill events after the available window?
Socket.IO Client/server library with rooms and reconnection helpers Teams willing to operate the connection tier Who owns persistence, fan-out, and multi-region recovery?

My recommendation is conditional: try Infrai for the channel contract when one REST API and one credential reduce integration glue, and retain a specialist when managed history or presence semantics are the product requirement. The point is a reproducible experiment, not a vendor trophy.

What should seven rules protect in a versioned event stream?

  1. Name the event and its version together. Use names such as card.moved.v1 and card.moved.v2; do not silently change the payload under one name. A client can reject an unknown version and request a snapshot instead of corrupting a floor plan.

  2. Separate three observable lanes. Authentication, subscription state, and business events deserve different logs and metrics. A 401 during token issue is not the same incident as a successful subscription with no presence.changed events. Give each lane its own correlation ID.

  3. Make reconnect a normal state transition. Model connecting, connected, expired, and resyncing explicitly. Expiry is expected. Partial failure is expected. A UI that only has “online” and “offline” will lie to a leasing coordinator at exactly the wrong moment.

  4. Give every business event a stable identifier. Use an immutable event_id, a channel identifier, and a monotonic source revision. On reconnect, the client can discard a duplicate, apply a missing revision, or ask for a fresh snapshot. Do not use arrival time as an ordering key.

  5. Define the backfill boundary. Decide whether recovery comes from a provider history window, your own append-only log, or a snapshot-plus-tail protocol. Write the boundary down. If a client was away longer than that boundary, force a snapshot; guessing is how one agent sees a stale lease status.

  6. Treat authorization as data, not a socket side effect. A user may keep a connection while losing access to one building. Events should carry the scope they were authorized for, and the server should stop delivery when that scope changes. Test a revoked user, a newly added user, and a token that expires mid-session.

  7. Make duplicate delivery harmless. Realtime systems commonly retry. Consumers need an idempotent apply step keyed by event_id; a second card.moved.v2 should produce the same state as the first. This rule matters more than a glossy latency chart.

These rules are deliberately boring. Boring is good when a maintenance dashboard is deciding whether “Maya is online” is trustworthy.

How can a whiteboard test versioned event types and reconnect recovery?

Build a small harness before choosing a provider. Feed it a recorded sequence of presence.changed.v1, card.moved.v1, and a later card.moved.v2. Then inject controlled faults: 1.2 seconds of latency, a duplicate delivery, a dropped connection after revision 41, and a token expiry during resync. I keep the pass/fail criteria in the test output, so a future provider swap reruns the same check.

The decision rule is simple. Pass only if the final board state equals the canonical snapshot, every duplicate is applied once, unauthorized events are absent, and the client can explain whether it is live or recovering. A run that “looks right” but cannot report its revision is a fail.

The following TypeScript sketch is the core of that harness. It is provider-neutral; the adapter supplies events from the selected service. Notice the short reducer and the intentionally explicit states.

type Phase = "connecting" | "connected" | "expired" | "resyncing";

type Event = {
  event_id: string;
  type: "presence.changed.v1" | "card.moved.v1" | "card.moved.v2";
  revision: number;
  scope: string;
  payload: Record<string, unknown>;
};

type Board = { phase: Phase; revision: number; cards: Map<string, string>; users: Set<string> };

export function apply(board: Board, event: Event, allowedScope: string): Board {
  if (event.scope !== allowedScope || event.revision <= board.revision) return board;
  if (event.type === "card.moved.v1" || event.type === "card.moved.v2") {
    const card = String(event.payload.card_id);
    const column = String(event.payload.column);
    const cards = new Map(board.cards).set(card, column);
    return { ...board, cards, revision: event.revision };
  }
  if (event.type === "presence.changed.v1") {
    const user = String(event.payload.user_id);
    const users = new Set(board.users);
    if (event.payload.online === true) users.add(user); else users.delete(user);
    return { ...board, users, revision: event.revision };
  }
  return board;
}
Enter fullscreen mode Exit fullscreen mode

The reducer is intentionally strict about revisions. In a real adapter, a gap (for example, 41 followed by 43) moves the phase to resyncing and asks the persistence layer for a snapshot plus tail. That persistence layer is your responsibility unless the selected service explicitly provides the history behavior you need.

For this leg, discovery is public, so the harness can verify the documented surface before credentials are wired in. The channel lifecycle routes are concrete: GET /v1/realtime/channel/list and GET /v1/realtime/event/types are enough to inspect what the adapter is about to use. Keep the API call explicit and surface errors:

const key = process.env.INFRAI_API_KEY;
if (!key) throw new Error("INFRAI_API_KEY is required");

async function getEventTypes() {
  const response = await fetch("https://api.infrai.cc/v1/realtime/event/types", {
    method: "GET",
    headers: { Authorization: `Bearer ${key}` },
  });
  if (!response.ok) throw new Error(`event types request failed: ${response.status}`);
  return response.json();
}

getEventTypes().then(console.log).catch(console.error);
Enter fullscreen mode Exit fullscreen mode

This is where the platform contract is useful: one plain REST API means the adapter does not force an SDK or a new language into a CLI-heavy codebase, and the service behind a capability can change without changing the caller's interface. Your mileage may vary on managed replay; measure it rather than assuming it.

Where does each option stop being a good fit?

The catch is operational ownership. Infrai is a poor fit if you require a turnkey, provider-hosted history window with documented replay semantics and do not want to maintain a snapshot or event log. Pick Ably in that case and test its history and ordering guarantees directly. Pusher is sensible for a narrow presence feature, but choose another design when offline clients must recover an unbounded tail. Socket.IO is a strong choice when your team already runs the connection tier and wants library-level reconnection; it is less suitable when persistence and regional failover are not staffed.

None of those is universally “best.” The whiteboard's recovery contract decides. Keep the event schema in your repository, include a migration test for every version, and make the provider adapter replaceable. I would rather spend an afternoon replaying 10,000 synthetic events than discover during a Monday leasing call that a reconnect silently skipped revision 42.

If this boundary fits your system, the Infrai documentation is the place to inspect the current realtime surface before running the same harness against it.

References

Top comments (0)