Socket events (realtime chat)

​

What the realtime layer is for

• REST (send-message, list-messages, mark-read, etc.) — request-response, works everywhere, the canonical history-of-record.
• WebSocket (this page) — Socket.IO bi-directional events for low-latency send, live receipt of new messages, typing indicators, and read receipts.

​

Connection lifecycle

​

Step 1 — fetch a ticket

​

Step 2 — connect

import { io, type Socket } from 'socket.io-client';

const socket: Socket = io('wss://api.swappr.co.uk', {
  auth: { ticket },              // single-use, server-side GETDEL
  transports: ['websocket'],     // skip long-polling; mobile networks tolerate WS fine
  reconnection: true,
  reconnectionAttempts: Infinity,
  reconnectionDelay: 500,
  reconnectionDelayMax: 5_000,
});

socket.on('connect', () => {
  // safe to emit chat:open here
});

socket.on('connect_error', (err) => {
  // err.message === 'UNAUTHENTICATED' on ticket failure
});

​

Step 3 — open conversations

​

Room model

​

Event catalog

​

chat:open (client → server)

• Calls chatEvents.isParticipant(conversationId, userId).
• On true: socket.join('conversation:<conversationId>').
• On false or thrown error: silently ignored (no ack, no error event). Probing for valid conversation ids via chat:open is therefore not a useful side channel.

socket.emit('chat:open', { conversationId: '66400a8f1c2b4d5e6f7a9000' });

​

chat:message:send (client → server, with ack)

• On ok: true AND deduped: false: server emits chat:message:new to conversation:<id> (every socket joined to that room, including the sender’s own socket — so a single client with multiple open tabs/devices sees the message land everywhere).
• On ok: true AND deduped: true: NO broadcast (the receivers already got the original).
• On ok: false: NO broadcast.

socket.emit(
  'chat:message:send',
  {
    conversationId: '66400a8f1c2b4d5e6f7a9000',
    clientMessageId: 'cm_01HZQ7K3M4N5P6Q7R8S9T0V1W2',
    text: 'Hi! Loved your kitchen.',
  },
  (ack: { ok: boolean; messageId?: string; sentAt?: string; deduped?: boolean; reason?: string }) => {
    if (!ack.ok) {
      // surface ack.reason to the UI
      return;
    }
    if (ack.deduped) {
      // already in optimistic UI — nothing more to do
      return;
    }
    // reconcile the optimistic row with messageId / sentAt
  },
);

​

chat:message:new (server → room broadcast)

socket.on('chat:message:new', (event: { conversationId: string; message: MessageRow }) => {
  // append to the local message list, scroll to bottom if user is at bottom
});

​

chat:read (client → server, with ack)

socket.emit(
  'chat:read',
  { conversationId, upToMessageId },
  (ack: { ok: boolean; newlyReceiptedCount?: number; reason?: string }) => { /* ... */ },
);

​

chat:message:read (server → room broadcast)

​

chat:typing:start / chat:typing:stop (client → server)

• Emit chat:typing:start when the user starts typing (e.g. first keystroke).
• Emit chat:typing:stop after 3s of inactivity, when the user sends, OR when the screen loses focus.
• Do not spam chat:typing:start on every keystroke — the server forwards each one and the recipient’s UI will flicker.

socket.emit('chat:typing:start', { conversationId });
// ...3s later if still idle...
socket.emit('chat:typing:stop', { conversationId });

​

chat:typing (server → room broadcast)

socket.on('chat:typing', (event: { conversationId: string; userId: string; phase: 'start' | 'stop'; at: string }) => {
  // update typing indicator
});

​

At-least-once delivery and dedup

• A (senderId, clientMessageId) unique index on messages makes the second insert E11000.
• The service’s findByClientId fast-path returns the existing row without a re-insert.
• The race-recovery catch on E11000 re-reads after a duplicate-key error.
• The ack reports deduped: true so the client knows this was a retry, not a fresh send.
• No chat:message:new is broadcast on the dedup path — the original send already broadcast it, and replaying would cause UIs to render the same message twice.

​

Dedup race diagram

​

Client requirements

1. Generate clientMessageId BEFORE the first attempt (ULID or UUID recommended).
2. Reuse the SAME clientMessageId on every retry of the same logical message.
3. Treat ack.deduped === true as success — the message landed (on the first attempt) and the broadcast already fired (other recipients have it).
4. NOT increment the optimistic row twice: when the ack arrives with deduped: true, the local optimistic UI is already in the correct state.

​

Full send-flow sequence

​

REST and WS parity

• A client can send via REST and receive the broadcast via WebSocket — works.
• A client can send via WebSocket and read history via REST — works.
• Error codes are the same: a REST 403 CONVERSATION_BLOCKED corresponds to a WS ack with reason: 'CONVERSATION_BLOCKED'.
• Mobile clients with intermittent connectivity should send via REST (which queues nicely at the OS layer) and use WebSocket purely for receiving live broadcasts. Mobile clients with a stable connection can send via either.

​

Ack error reasons

​

Payload validation (server-side guard rejection — no service call)

​

Service-level rejection (passed through from AppError.code)

​

Reconnect strategy

1. Treat the ticket as exhausted on every reconnect. Tickets are single-use; the original was consumed at first connect. The reconnect path MUST fetch a fresh ticket via POST /api/v1/auth/socket-ticket before re-emitting io({ auth: { ticket } }). Trying to reconnect with the old ticket fails with connect_error('UNAUTHENTICATED').
2. Re-emit chat:open for every conversation it had open before the disconnect. Rooms are NOT remembered across socket lifecycles — a fresh socket starts in only user:<userId>. The client should keep a local list of “currently open conversation ids” and emit chat:open for each one after connect.
3. Re-fetch history via REST. During the disconnect window, messages may have been sent that the client never saw via chat:message:new. After reconnect, the client should call list-messages for each open conversation to catch up. The REST endpoint is the canonical history-of-record; the socket is the live channel.

socket.on('reconnect_attempt', async () => {
  const fresh = await fetchSocketTicket();   // POST /auth/socket-ticket
  socket.auth = { ticket: fresh.ticket };
});

socket.on('connect', async () => {
  for (const conversationId of openConversationIds) {
    socket.emit('chat:open', { conversationId });
  }
  for (const conversationId of openConversationIds) {
    const fresh = await fetch(`/api/v1/chat/conversations/${conversationId}/messages?limit=50`);
    // merge with local cache
  }
});

​

Out-of-scope (intentionally)

• Per-conversation rate limiting on the socket transport. The REST send is documented to be subject to 60/min/user; the socket transport piggybacks on the same messageService but the realtime layer does not yet wrap it in a rate limiter. Coming in Phase 5.
• Delivered receipts (chat:message:delivered). The data model has a deliveredTo[] field but Phase 4 does not yet populate it — the field is always []. Receipts are emitted in Phase 5 once the push pipeline is wired (an APNs/FCM “delivered” callback flips it).
• Edit / delete events (chat:message:edited, chat:message:deleted). The data model has editedAt and deletedAt but no API exposes them yet.
• Presence (user:online / user:offline). Socket.IO knows when a socket connects/disconnects but no broadcast fires today. Phase 5 may add this for the inbox UI.
• Multiple namespaces. The MVP is single-tenant and uses the root namespace exclusively.

​

See also

• Send message — the REST mirror of chat:message:send.
• Mark conversation read — the REST mirror of chat:read.
• List messages — catch-up history; use after reconnect.
• Match → Conversation handshake — how a conversation:<id> room gets created in the first place.
• Socket ticket endpoint — how to get the ticket used in the auth handshake.
• Errors — full code catalog; socket reason strings map 1:1 to REST code strings.