It is the week before an investigation report is due. A forensic accountant is reconciling a ledger, two investigators are coding documents from a mailbox Donna is still processing, a lawyer is drafting the report, and the client is reading the findings. They all work in one Space. Each of them needs to see the others’ work as it happens, and none of them may see anything they are not entitled to.
This post describes how we built that. It covers the single realtime connection each person holds, how we decide what each event may carry and to whom, how access is taken away from a screen that is already open, and how several people and Donna edit one document without losing anyone’s work.
Where Separate Channels Broke
Our first realtime features each brought their own channel. Document processing had a socket of its own. Messages streamed from the API server over a separate connection. The inbox polled. Each was reasonable on its own day.
Together they caused three problems. Connections multiplied per tab. Features updated at different speeds, so the product felt uneven. The third problem was the one that mattered: every channel made its own decision about who should receive what, and every new feature was a new place to get that decision wrong.
One Connection per Person
Each signed-in browser now holds one realtime connection, and everything travels over it: document progress, messages, typing, notifications, profile changes, roster and file changes, review tables and dashboards. The browser reads each event’s type and routes it to the surface that cares.
The important part is who decides what the connection hears. The hub has three kinds of group: one per matter, one per firm and one private to each person. The browser never names a group. It asks the core API for a short-lived connection that carries no rights to join, leave or publish. Once connected, it asks the core API to join, and the server works out the person’s allowed groups from their memberships and places the connection in exactly those. A person in one firm is never a member of another firm’s matters, so they can never join another firm’s groups.
- 1 · NegotiateThe browser asks the core API for a short-lived connection. It names no channels and gets no rights to join or publish.
- 2 · JoinOn every connect, the core API places the connection in the groups the person is allowed: each matter, their firm, themselves.
- 3 · PublishThe core API and the processing pipeline publish events to those groups.
- 4 · RouteOne connection carries everything. The browser routes each event by its type.
- The server assigns the groups. The browser only listens.
The join runs on every connect and every reconnect. A reconnect reuses the same address, so if the matter groups were baked into it, a connection could come back into a matter its owner had since left. Asking the server each time means a reconnect only ever returns to what is allowed now. It also keeps the connection address small for people who sit in many matters.
What an Event May Carry
A single connection gives us one place to answer the question that actually matters: who should receive this event, and what can it safely say? We settled on two shapes.
- Content events go to an exact audience. A message carries the full message, so it appears without a fetch. That is only safe if the audience is exactly right, so a message in a private channel is sent to each of its members on their private group, never to the whole matter. Typing follows the same rule, because knowing someone is typing in a channel reveals that the channel exists.
- Signal events go to the matter and say almost nothing. Files, review tables and dashboards have audiences finer than the matter. A document can be restricted to named people. So their events carry a nudge, the kind of change and at most a rough size, and the screen then reloads through the same permission-checked reads it always uses.
The rule we apply is simple: the bus is never the authority. Events are published after the database write commits, and screens treat an event as a reason to ask again. When a role changes, the event says so, but the screen re-reads the person’s role from the API before it changes a menu.
Taking Access Away From an Open Screen
Removing someone from a matter is a single write. Making their open browser reflect it takes more. A browser that is already open keeps its page and its cached data until something tells it otherwise, and a document editor checks membership when it connects and not on every keystroke.
- 1 · Membership removedThe record changes. Every read and write is refused from here on. This is the boundary.
- 2 · Person toldOn their private channel only. The rest of the matter sees a plain “members changed”.
- 3 · Groups droppedThe server removes the open connection from the matter’s group, so its traffic stops.
- 4 · Editors closedTheir open documents in that matter are disconnected, and any cached admission is forgotten.
- 5 · Dropped againOnce more a little later, a backstop for a join that was already in flight.
Every join, on every connect
Read the allowed groups, add the connection, then read them again and remove anything no longer allowed.
Two races needed care. A join can start just before a removal commits and finish just after, putting the connection back into a group it has lost. So every join reads the allowed groups again after it has added the connection, and removes it from anything no longer allowed. If that second read fails, it yields fewer groups, so more are removed. A join that times out on our side might still land at the hub later, which is why the removal drops the groups a second time.
The steps after the first fail open, and we count them. The removal has already committed, and every read and write already refuses the person, so an unreachable editing service must not block it. Each failed disconnect is recorded as a countable event, because a live editing session that outlasts its owner’s access is exactly the thing we want to see across the fleet.
Presence as Live Identity
In a shared document, presence answers two questions: who is here, and where are they working. A draft shows a strip of the people on it, with whether each is editing, viewing or idle, and a caret for every co-author, whose name label fades a moment after they stop moving. A sheet draws a coloured box and a name on the cell each person has selected.
These have to read as one person. A colleague’s caret is drawn in the same colour as their avatar, and their tracked changes carry that colour too. When someone changes their name, colour or photo, one event reaches the matters they sit in, and a small store keyed by person repaints only that person’s avatars, wherever they appear.
Presence is published by each browser, which makes it a place a browser could lie. So the editing service rewrites every presence state it relays and stamps it with the authenticated person and whether their connection may write. A viewer cannot claim write rights it does not have, or take over another connection’s presence.
Co-Editing Without Lost Work
Draft reports and working sheets are edited together, by people and by Donna. Each open document is a room on a separate collaboration service, and its content is held as a conflict-free replicated data type, or CRDT. Every edit merges with every other, so two people typing in the same paragraph or the same row both keep their work.
The room is where permissions are enforced for editing. Before a connection is admitted, the collaboration service asks the core API, under its own service identity, whether this person is a member of the matter and may read this document. If the API cannot answer, it retries once and then refuses. A refusal caused by an outage is never cached, so the next attempt succeeds once the API is back. A connection whose rank does not allow editing is read-only at the socket. The server drops its edits, whatever its browser has been persuaded to do.
- Room guardsAdmit each connection after asking the core API, keep viewers read-only at the socket, stamp who each presence is, and put back changes to locked clauses.
- Shared documentEvery edit from every person merges here.
- SnapshotThe merged state is saved to storage in batches while people type.
- Matter recordOne elected editor writes it, so Donna and search read what everyone sees.
Merging is the easy part. Three details took most of the work.
- One writer for the record. The merged document is snapshotted to storage, but Donna and search read a copy in the matter’s database. When every editor wrote that copy, each change set every open tab racing the others to save it. Now the room elects one writer with no lock and no extra message: the lowest-numbered connected editor that may write, preferring a tab in the foreground, because browsers slow the timers of background tabs. Every client computes the same answer from presence it already has.
- Tracked changes that survive co-editing. Two people striking overlapping text at the same moment could end each other’s marks, so “accept all” kept text someone had deleted. Each tracked change is now written under a key of its own, so one change’s markers can never close another’s.
- Locked clauses held in the room. A fixed clause may only be reworded by the person who locked it or a draft admin. The editor refuses the keystrokes, but a connection speaking the protocol directly could still change the shared document. Refusing the update only closes the socket, and the client resends the change on every reconnect. So the room puts the approved words back as an ordinary edit, and every client converges on them. If the API cannot confirm who may change the clause, the words go back.
When someone applies an edit Donna proposed to a sheet while others are in it, the edit enters the shared document like any keystroke and reaches everyone through the same merge. The elected writer then credits that save to Donna, so the version history shows which changes Donna made and which a person made.
When a Connection Drops
Delivery on the bus is best effort. Events can be missed while a laptop sleeps or a train goes through a tunnel. We treat the database as the source of truth and the bus as a way to learn sooner. After every successful join, the browser tells its open surfaces they may have missed something, and each one reloads from the API. Messages are merged by identifier, so a message that arrives both by event and by reload appears once. If the realtime service is unavailable, the product falls back to polling the few things that need it.
For co-editing, the shared document lives in every connected browser as well as on the server. A browser that reconnects exchanges what each side is missing and converges. We test this by opening many clients on one document, typing at random positions, and asserting that every client ends with an identical state and that a new client receives the same state from the server. For sheets we also assert that every cell holds a value some client actually wrote to it, and that nothing written has gone missing.
What We Took Away
- One connection, groups chosen by the server. A browser that names its own channels is a browser that can name the wrong ones.
- Decide the shape of every event. Content only where every recipient may read it; otherwise a signal that says nothing and a reload through the normal permission checks.
- Revocation is a sequence. The record is the boundary. Re-check after joining, drop twice, and count the steps that fail.
- Enforce in the room. Read-only at the socket, presence stamped by the server, locked words put back. The browser’s own restraint is a courtesy.
Presence, live co-editing and realtime updates each exist in many products. An investigation needs them in one place, for people with different rights to the same matter, at the moment the work is busiest. That is what one Space per matter means in engineering terms: one connection, one set of rules about who hears what, and one shared record that everyone, including Donna, works on together.