Two-week programme · Day 10 of 14
Now the edit is a message
Part 1Basics
Now take everything you know and build chat. A message is just an offline write: save it locally, put it in the outbox, send it later. You've already done most of the work.
One thing is different. People are waiting for a reply right now, so a background job that runs eventually isn't good enough. We add a fast path, and keep the old path as the safety net.
Words you need today
- WebSocket
- A connection that stays open, so the server can send to the phone instantly.
- client_msg_id
- The message's op_id: made on the phone, it stops double sends.
- Per-conversation sequence
- A number giving each message its place within one chat.
- Fan-out
- Delivering one message to everyone in the conversation.
- FCM and APNs
- Google's and Apple's services for delivering push notifications to phones.
- Receipts
- The sent, delivered and read states shown beside a message.
The story
A customer in a lift types running late to a plumber and taps Send. You already know this part: a local insert, an outbox row, and a client-made ID. The message shows one tick straight away, with no signal at all.
When the signal returns, the ID stops a double send, just like op 7f3a. The new part is that the plumber shouldn't wait for a sync job. So messages travel over a live socket while the app is open, and a push wakes the phone when it is closed. If the socket dies, nothing is lost, because history still syncs by cursor, as on Day 4.
Part 2Today's question
What changes when the same design must also feel live?
By the end of this lesson, you should be able to:
- Reuse the outbox for messages
- Explain why sockets aren't the guarantee
- Design ordering per conversation
Part 3In detail
Step by step
- Save locally. The message goes into the local table and the outbox, and shows one tick immediately.
- Send over the socket. If the app is open and connected, it goes now. Otherwise the outbox waits, as Priya's edit did.
- The server gives it a place. It checks client_msg_id, assigns the next sequence number in this chat, and saves it.
- Deliver to the others. Online members get it over their socket. Offline members get a push.
- Catch up on reconnect. Any device asks for messages after its last sequence number, which fills any gap.
Live is an optimisation; the cursor is the guarantee
Sockets drop all the time. Treat them as the fast path, and treat sync by cursor as the correct path. On reconnect the client asks for everything after its last sequence number and fills any gaps.
Order per conversation, not globally
Day 6 used one sequence per tenant. Chat needs one per conversation, owned by one service instance at a time. That gives correct order without a global lock.
Push is a hint, again
As on Day 6, push only prompts the app to fetch. Silent pushes get throttled, and payloads can leak onto lock screens, so sensitive content should be fetched on the device.
The outbox row, renamed
1{2 "client_msg_id": "0192e0c5-1b7e",3 "conversation_id": "c-77",4 "text": "running late",5 "state": "pending"6}7 8// Server reply: same ID, now with a place in the order.9{10 "client_msg_id": "0192e0c5-1b7e",11 "seq": 4182,12 "state": "sent"13}Compare with Day 2: client_msg_id is op_id, and seq is the change log's sequence.
The code, explained
This is the real code, and our tests run it. Read each block, then the notes under it.
One conversation's order
A resent message must keep its place. This is the server's op_id check, applied to chat.
1/** Owns one conversation's order. The client's ID makes a resend harmless. */2class ConversationLog {3 private val byClientId = HashMap<String, Long>()4 private var nextSeq = 0L5 6 @Synchronized7 fun receive(clientMsgId: String): Long =8 byClientId.getOrPut(clientMsgId) { nextSeq += 1; nextSeq }9}byClientId.getOrPut(...)- The first arrival takes the next number. A resend returns the same one.
@Synchronized- One owner per conversation. Consistent hashing routes each chat to one instance, so no global lock is needed.
Compiled and tested by npm run test:mobile.
The phone's copy of a chat
Socket, push and catch-up all feed one method, so ordering logic lives in one place.
1/** The phone's copy of one chat. Socket, push and catch-up all end up in [onServerMessage]. */2class ChatThread {3 private val bySeq = sortedMapOf<Long, Msg>()4 private val pending = LinkedHashMap<String, Msg>()5 var highestRead = 0L6 private set7 8 fun sendLocal(id: String, text: String) { pending[id] = Msg(id, text) }9 10 /** Our own message came back with its place in the order. */11 fun onServerMessage(m: Msg) {12 val seq = checkNotNull(m.seq)13 pending.remove(m.clientMsgId)14 bySeq[seq] = m.copy(state = MsgState.SENT)15 }16 17 /** Confirmed messages in order, then the ones still waiting. */18 fun visible(): List<Msg> = bySeq.values + pending.values19 20 /** Holes to ask the server for after a reconnect. */21 fun missingSeqs(): List<Long> {22 val last = bySeq.keys.lastOrNull() ?: return emptyList()23 return (1..last).filter { it !in bySeq }24 }25 26 /** One number stands for many messages, and two devices merge by taking the larger. */27 fun markRead(seq: Long) { highestRead = maxOf(highestRead, seq) }28}sendLocal- Shows the message straight away, with no signal needed.
sortedMapOf<Long, Msg>()- Keyed by sequence, so arrival order stops mattering.
missingSeqs()- A gap in the numbers means a message was missed. After a reconnect, the client asks for these.
maxOf(highestRead, seq)- One number covers many messages, and two devices merge by taking the larger.
Compiled and tested by npm run test:mobile.
What can go wrong
- The socket drops mid-send
- Resend with the same client_msg_id. The server recognises it, so no duplicate appears.
- Messages arrive out of order
- Sort by sequence number. A gap means fetch what's missing.
- A push is dropped or delayed
- The app syncs on next open anyway, so the message still arrives.
- Message text appears on a lock screen
- For sensitive content, send only an ID in the push, and fetch the text on the device.
Decisions to defend
- Same from Week 1: Local first, outbox, client ID, cursor catch-up. A message is just another offline write.
- New for chat: Socket while open, push while closed, not polling, or push alone. People expect to see replies within a second, and only a live connection does that cheaply.
Part 4Questions and answers
Answer out loud first, then open each one.
Two devices of one user both show a message as read. How?
A group of 50 gets a message. Who stores what?
Part 5Going further
The three questions, for today
- Where does it live?
- In a local message row plus its outbox entry.
- Who runs the next step?
- A socket while the app is open, a push and a sync job while it is closed.
- What if it runs twice?
- client_msg_id stops a double send.
Practise
- Mock45 minReal-time chat with offline delivery
Before you begin, list what you can reuse from Week 1. Spend your time on what is new: sockets, fan-out and receipts.
Optional reference pages
You don’t need these for the lesson. They hold more detail if you want it later.
Tomorrow a duplicate stops being a nuisance and starts costing someone money.