Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 42 ยท Projects

Project: Chat Rooms with Presence

Build chat rooms on Redis: pub/sub for live messages, streams for history, and sets plus expiring heartbeat keys for who is online, with live demos.

A chat room looks simple: people type, everyone else sees it. Underneath are three different problems. Live delivery: a new message should reach every connected person within milliseconds. History: someone who joins later must see what was said before. Presence: the room should know who is online right now, including people whose browser crashed and never said goodbye.

No single Redis structure solves all three, and that is what makes this project useful. Pub/sub is the fastest way to fan a message out, but it forgets everything. A stream remembers everything, but it does not push. A set plus keys with a time to live can answer "who is here?" and clean up after crashed clients automatically.

Real Redis cannot run on this page. The code runs against a plain JavaScript emulator: a command table with the real semantics of XADD, XREVRANGE, SADD, SET ... EX, PUBLISH and friends, plus a fake clock so every run prints the same times. The emulator has no network, so a "client" is a JavaScript object whose callback receives published messages, which is exactly the role a real SUBSCRIBE connection plays.

Three jobs, three tools

Pub/sub Push each message to everyone online.
Stream Keep recent history for late joiners.
Set plus TTL keys Know who is online.
1 / 2

The design

For a room called general we use these keys:

  • room:general is a pub/sub channel, not a key. Everything that happens in the room is published there as a small JSON event: a message, someone joining, someone leaving. Subscribers get it only if they are connected at that instant. Publishing returns the number of receivers, which is 0 for an empty room.
  • room:general:history is a stream. XADD ... MAXLEN ~ 50 appends each message and trims the log so it never grows without bound. Entry IDs are made of the millisecond time plus a sequence number, so they are unique and sorted, and the ID doubles as the message id the client can sort and de-duplicate by.
  • room:general:members is a set of users who joined the room.
  • hb:general:ana is a heartbeat key per user, written with SET ... EX 30. The client refreshes it every ten seconds or so. If the browser dies, nobody deletes the key, and Redis removes it 30 seconds after the last refresh.

Why both a set and heartbeat keys? A set lets you list the members cheaply; a TTL key lets Redis notice absence for you. Neither does both jobs alone: sets have no per-member expiry, and finding "all keys that look like hb:general:*" would need a SCAN, which is not something you want on every page view. So we list from the set and verify each member against its heartbeat key. A member without a heartbeat is a ghost; we remove it and tell the room.

Redis can also publish keyspace notifications when a key expires, so a listener could announce departures at the exact moment a heartbeat disappears. They are off by default, they are delivered at-most-once like all pub/sub, and Redis expires keys lazily or in the background rather than at the exact millisecond. A sweep when someone asks "who is online?" is simpler and good enough for a first version.

Live messages and history

post does two things: it appends to the stream (the permanent record) and publishes the same event (the live copy). history reads the newest entries with XREVRANGE and flips them into reading order.

The interesting part is connect, because a late joiner needs both live messages and history, and there is a trap between them. If a client loads history first and subscribes afterwards, any message posted in the gap between those two steps is in neither: it was not in the history it read and it was published before the client was listening. The safe order is the opposite: subscribe first, then read history, then remove duplicates by id. A message that arrives in the gap is received live and may also appear in the history; because both carry the same stream id, a Map keyed by id shows it once.

sequenceDiagram
  participant C as New client
  participant R as Redis
  C->>R: SUBSCRIBE room:general
  Note over R: bo posts a message now
  R-->>C: live message (id 4000-0)
  C->>R: XREVRANGE room:general:history + - COUNT 5
  R-->>C: entries 1000-0 ... 4000-0
  Note over C: de-duplicate by id

Subscribing before reading history means nothing can fall into the gap.

The TryIt below connects three clients. ana was there from the start. cy connects the safe way and a message arrives in the middle of connecting. dan connects the unsafe way, with the same interruption.

JS Live delivery, history and the connect race

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the three screens. ana and cy both show all five messages, including the one posted mid-connect, even though cy also reads it from the stream. dan is missing the last line, welcome, new people: it was posted after he had read the history but before he subscribed, so it reached neither. That is the gap bug in action. The last lines show MAXLEN at work: after 60 more posts the stream holds exactly 50 entries. (In real Redis, ~ means "approximately": trimming happens in whole internal blocks, so the stream may hold a bit more than 50. The emulator trims exactly.)

Presence with heartbeats

Now the second half. join writes the heartbeat key, adds the user to the member set and, only if the user was new, announces the join. SADD returns 1 for a new member and 0 for one that is already there, so a user who reconnects does not announce themselves twice. leave is the polite exit: delete the heartbeat, remove from the set, announce. whoIsOnline is the sweeper that handles the impolite exits.

In the next TryIt a watcher listens to the lobby while three people come and go. Notice who disappears, and when.

JS Heartbeats, ghosts and the sweeper

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Follow the timeline. When bo goes silent, nothing happens at first: his heartbeat key still has 5 seconds left, so he is correctly listed. Ten seconds later the key has expired by itself, and the next call to whoIsOnline finds the ghost in the set, removes it and publishes a leave event, which the watcher receives. The same sweep removes ana at the end because a full minute passed without a heartbeat.

The sweeper is idempotent. If two servers sweep at once, only one SREM returns 1, so only one announces the departure. That pattern, using the return value of a Redis command as a tiny lock, appears again in the job queue project.

Taking it further

  • Several rooms: nothing changes except the room name inside the keys. PSUBSCRIBE room:* lets an admin tool listen to every room, and in a cluster sharded pub/sub keeps a room's traffic on one shard.
  • Reliable delivery: pub/sub is at-most-once. A client that drops for two seconds misses messages but can ask history for everything after the last id it saw: XRANGE room:general:history (LASTID +. That one command is what makes the stream the source of truth and pub/sub only the shortcut.
  • Per-user unread counts: a hash unread:ana with HINCRBY per room, reset with HSET.
  • Typing indicators: a heartbeat key with a 3-second TTL is all it takes.
  • Moderation: ZADD muted <expiry> user and check the score, or a plain key muted:general:bo with an expiry that ends the mute.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does a client subscribe to the channel before it loads the history?

    Pub/sub does not store messages. Subscribing first closes the gap, and de-duplicating by stream id removes the overlap.
  2. 2. Why is a heartbeat key written with EX instead of being deleted by the client when it leaves?

    The client that needs removing is exactly the one that cannot clean up after itself. A TTL turns absence into an automatic event.
  3. 3. What does SADD return that the presence code relies on?

    Only a new member triggers a join announcement, so a reconnecting user does not spam the room.
  4. 4. What does MAXLEN ~ 50 do on XADD?

    It caps the length of the stream. The tilde allows Redis to trim in whole internal blocks, which is cheaper, so the stream can hold slightly more than 50.
  5. 5. Which statement about pub/sub delivery is true?

    Pub/sub is fire and forget. Anything that must survive a disconnect belongs in a stream or another stored structure.

Summary

  • Use pub/sub for instant fan-out, a stream for history, and a set plus TTL keys for presence: each tool forgets something on purpose.
  • Subscribe first, then read history, then de-duplicate by stream id, so no message falls into the gap.
  • XADD ... MAXLEN ~ N keeps history bounded; XREVRANGE ... COUNT n reads the newest entries.
  • Heartbeat keys with EX let Redis detect clients that vanished; a sweep removes the ghosts from the member set.
  • The return values of SADD and SREM make join and leave announcements safe even when several servers act at once.

Next project: A Reliable Job Queue.