Writing / Build stories

Building SkipChat: a state machine for live stranger video

An engineering deep dive into SkipChat: scheduled liquidity, Durable Object coordination, one-use admission, WebRTC signaling, media-level pre-reveal privacy, and continuous rematching.

SkipChat looks simple from the outside: join a live window, meet someone over video, skip when it isn't working.

Underneath it's a distributed state machine. The product has to coordinate queue admission, live sockets, matchmaking, WebRTC signaling, timers, reveal choices, disconnects, reports, and rematching. The browser is a client of that system, not its source of truth.

The architecture is Cloudflare-first: Workers for the application and HTTP API, Durable Objects for live coordination, Durable Object SQLite for live state, D1 for durable product records, Turnstile for abuse resistance, Analytics Engine for lifecycle telemetry, and WebRTC for media.

Product constraints shape the system

The first decision was to not build a generic 24/7 random-video product. A stranger-video service has a liquidity problem before it has a media problem: if users trickle in a few at a time, the system can be fully available and still feel empty.

SkipChat uses scheduled live windows to concentrate demand. Admission is scheduled, but once you're in you can keep going through multiple matches after the window closes.

Product constraint

System consequence

No account required

Use anonymous sessions and short-lived admission records.

Scheduled entry

Validate eligibility before opening a queue socket.

Continuous session

Skip and partner leave return the user to matching.

Talk before reveal

Send a blurred media track before mutual consent.

Mutual reveal

Resolve both choices at one authoritative coordinator.

Abuse reporting

Persist reports after live state is gone.

The product loop is:

flowchart LR
  Visitor["Visitor"] --> Window["Availability window"]
  Window --> Gate["Age gate + Turnstile"]
  Gate --> Session["Anonymous session"]
  Session --> Admission["One-use admission"]
  Admission --> Lobby["Queue socket"]
  Lobby --> Pre["Pre-reveal match"]
  Pre --> Reveal["Mutual reveal"]
  Reveal --> Clear["Clear video"]
  Pre --> Rematch["Skip / partner leaves"]
  Clear --> Rematch
  Rematch --> Lobby

One match needs one owner

Matchmaking and the match lifecycle need serialized decisions. In a stateless design, every socket message would rebuild queue membership, match state, reveal choices, signal routing, and disconnect behavior from shared storage and client assumptions.

That's possible. It also smears one lifecycle across rows, locks, cache keys, and optimistic updates.

SkipChat uses a Coordinator Durable Object for the live environment. It owns queue membership, participant rows, match transitions, timers, reveal decisions, signaling relay, partner notifications, and socket cleanup.

flowchart LR
  Browser["Browser"] --> Worker["Worker app and API"]
  Worker --> Admission["Admission endpoint"]
  Admission --> D1["D1 durable records"]
  Worker --> Socket["Queue WebSocket"]
  Socket --> Coordinator["Coordinator Durable Object"]
  Coordinator --> SQLite["DO SQLite live state"]
  Coordinator --> Events["Lifecycle telemetry"]
  Browser --> Media["Peer-to-peer WebRTC"]
  Coordinator --> Signal["Validated signaling relay"]
  Signal --> Browser

The Coordinator isn't a media server. It owns the control plane; WebRTC carries the media plane peer-to-peer.

Admission happens before the socket

A WebSocket opening successfully shouldn't be enough to enter the queue. The browser first creates an anonymous session and requests admission. That request checks availability, country or window rules, session validity, and Turnstile verification.

If the user is eligible, the server creates a short-lived, one-use admission record:

type QueueAdmission = {
  id: string;
  sessionId: string;
  countryCode: string;
  timeZone: string;
  createdAt: string;
  expiresAt: string;
  consumedAt: string | null;
};

The Coordinator consumes the record when the socket sends queue.join, and rejects expired, already-consumed, and session-mismatched admissions.

sequenceDiagram
  participant B as Browser
  participant W as Worker
  participant T as Turnstile
  participant D as D1
  participant C as Coordinator

  B->>W: create anonymous session
  B->>T: complete challenge
  B->>W: request admission
  W->>D: evaluate availability rule
  W->>C: create short-lived admission
  C-->>W: admission id + expiry
  B->>C: open WebSocket
  B->>C: queue.join(admission)
  C->>C: consume admission once
  C-->>B: joined or matched

This keeps policy on the HTTP path and reserves the socket protocol for live lifecycle messages.

Matching should be boring

The initial matcher finds a waiting participant who isn't the user's previous partner, creates a match id and round id, persists the relationship, and sends queue.matched to both sockets.

It's deliberately not a recommendation engine. The hard problems here are lifecycle correctness, privacy, signaling, and rematching. A simple matcher keeps those problems testable.

type RoundState =
  | { type: "waiting"; admissionId: string }
  | {
      type: "pre_reveal";
      matchId: string;
      roundId: string;
      partnerId: string;
      reveal: "choosing" | "waiting";
      endsAt: string;
    }
  | {
      type: "post_reveal";
      matchId: string;
      roundId: string;
      partnerId: string;
      endsAt: string | null;
    }
  | { type: "rematching"; previousMatchId: string; reason: string };

On the client, the reducer accepts only valid transitions. On the server, the Coordinator validates commands against participant and match state. They aren't authority peers — the Coordinator is authoritative, and the client reflects accepted events.

Signaling is not match authority

WebRTC needs offers, answers, and ICE candidates. Those pass through the Coordinator, but they don't decide who's allowed to talk to whom.

For every signal, the Coordinator verifies:

  • the socket belongs to an active participant
  • the match exists
  • the sender belongs to the match
  • the target is the sender's actual partner
  • the target still has an attached socket

Only then does it relay the message. A client can submit an offer; it can't pick an arbitrary recipient.

type ClientSignal =
  | { type: "webrtc.offer"; matchId: string; targetParticipantId: string; description: unknown }
  | { type: "webrtc.answer"; matchId: string; targetParticipantId: string; description: unknown }
  | { type: "webrtc.ice"; matchId: string; targetParticipantId: string; candidate: unknown };

The routing check is part of the match protocol, not a convenience in the UI.

Privacy has to live in the media graph

The core privacy invariant is simple:

Before mutual reveal, the remote peer must not receive raw camera video.

A CSS blur isn't enough. The browser would still receive the clear track and just paint it differently — a client bug, DOM access, or debugging tool could expose the raw stream before consent.

SkipChat uses a browser-side CallAdapter. It grabs the camera and microphone, renders the camera into a blurred canvas, sends the canvas-derived video track to WebRTC, and replaces that outbound track only after the Coordinator emits reveal.mutual.

flowchart LR
  Camera["Raw camera track"] --> Canvas["Canvas renderer"]
  Canvas --> Blur["Blurred video track"]
  Mic["Microphone track"] --> Peer["WebRTC connection"]
  Blur --> Peer
  Reveal["reveal.mutual"] --> Replace["replaceTrack(raw camera)"]
  Camera --> Replace
  Replace --> Peer

The UI can show blurred frames, a timer, and reveal controls. The guarantee lives below the UI, in the track that's actually sent to the peer.

Reveal resolution is atomic

Reveal choices stay private until the Coordinator resolves them. If one participant chooses reveal, they get reveal.waiting. If both choose reveal, both get reveal.mutual. If either chooses skip, the match ends and both are released for rematching.

The property that matters: neither participant can observe or force the other's choice through client state. The Coordinator records both choices and emits one authoritative result.

stateDiagram-v2
  [*] --> Waiting
  Waiting --> PreReveal: queue.matched
  PreReveal --> PreReveal: one participant chooses reveal
  PreReveal --> Clear: both choose reveal
  PreReveal --> Rematching: skip / timeout / partner leaves
  Clear --> Rematching: skip / partner leaves
  Rematching --> PreReveal: queue.matched

Rematching is a normal transition

Skip shouldn't be modeled as an error page. A user enters one queue session and may pass through many rounds. When a partner leaves, a user skips, or the reveal window expires, the Coordinator cleans up the match, notifies the other participant, releases both queue states, and starts another match when it can.

Centralized cleanup is what keeps that safe. If participant rows, socket attachments, and partner notifications were owned by different effects, a disconnect could leave ghost queue members or a match that no longer has two live sockets.

Live state and durable records are different

Not everything belongs in the Coordinator. Live queue membership, socket attachments, and current match state belong near the live loop. Product history and configuration belong in D1.

D1 stores records like anonymous sessions, reports, bans, and availability-window rules. The Coordinator owns ephemeral live state and lifecycle transitions. That boundary lets the live object be replaced without losing moderation history or editable configuration. Availability rules are a good example — the landing page and the admission endpoint read the same source, so the product never advertises a live window that admission will reject.

Observability is part of availability

An HTTP dashboard can be green while the product is functionally down. Nobody's getting matched. Reveal never resolves. Camera permissions are failing. Rematching is too slow.

The useful events are lifecycle events:

  • admission accepted or rejected
  • socket joined or disconnected
  • match created or expired
  • reveal offered, resolved, or failed
  • WebRTC negotiation failed
  • report submitted
  • rematch latency

The Coordinator emits control-plane events; the client adapter emits media events. Together they tell me whether the product loop is actually healthy.

The cross-layer contract

SkipChat isn't interesting because it uses WebRTC or a Durable Object in isolation. It's interesting because one product promise crosses layers. “Reveal only after mutual choice” depends on a client reducer, a Durable Object decision, a persisted match state, a WebSocket message, a peer connection, and a video-track replacement.

Real-time products are state machines with feelings attached. The feelings matter, but the state machine has to be correct first.

Bhavin Kamani

A small command line for a curious visitor.