Change notification

The generator emits an event per entity — country_event and its siblings — and the services publish them on {component}.v1.{resource}_events.{action}, for example refdata.v1.events.countries.updated. They are not something the interface invents.

The browser never reaches NATS, so the BFF carries the news. One long-lived stream per session, not one per screen: a screen opening and closing must not churn connections, and a person with six lists open wants one stream.

GET /api/events           text/event-stream

The envelope already exists in the protocol package. connected, party-changed, session-expired and account-changed are already declared, and the last three are this channel's business, because they are the same question asked by different parts of the interface. The consumer needs one more kind, which is specified here and not yet declared:

{ event: 'entity-changed', data: { component, entity, at } }

This is the decision that matters most, and it is the one that keeps a bulk import from becoming a denial of service on the interface.

A change notification says "this collection changed at time T". For a list, it does not say which records. A person cannot act on a list of a thousand identifiers, and the interface cannot do anything with them that it cannot do better itself. A record page is different, and the section 4.4 says how. What it actually needs to know is one thing: is what I am showing older than what exists? A time answers that. A list does not.

So the payload carries the time of the change. The server's clock and the browser's differ, so the client does not compare that time with its own. It compares the moment the news arrived with the moment the load that produced its data began, both on the browser's clock. The server's time is kept for the tooltip only.

news arrived 12:00:03  >  load began 11:59:58   →  stale
news arrived 11:59:41  >  load began 11:59:58   →  not stale, and nothing to do

News that arrives while a load is in flight counts, because that load may have read before the change. The cost is one refresh that finds nothing new.

Coalescing falls out of that for free. A thousand events from one import all carry a time after the client's load, so the first makes the screen stale and the remaining nine hundred and ninety-nine change nothing. They are not deduplicated by a special case; they are idempotent by construction. There is no ceiling to choose and no set to bound, because no set exists.

The rows that changed are worked out after the reload, not before it. The Qt client marks the rows whose recorded_at is newer than its last reload, which compares the server's clock with its own. The web compares each row with the same page read before: a row that was not there, or whose content is not what it was, is marked. It uses no clock, and the first read of a page marks nothing. The events name a collection, so the records are identified from the data rather than from the notification.

A list shows many records and goes stale for any change to its entity. A record page shows one, and a pulse for another person's record teaches the reader to ignore the pulse. Found in the live test: Diane changed her job title, and Hazel's own page pulsed.

Every event already carries the key of its record in the payload. The BFF now passes it on:

{ event: 'entity-changed', data: { component, entity, at, keys?: [{ username: 'diane.kay' }] } }

• The BFF joins the events of one entity that arrive within 150 ms into one message for each session that may hear them, so a bulk import is one message and not a thousand. The window is fixed from the first event and is not extended, so a very long burst is a series of messages, one for each 150 ms, and not one.
• A message names up to 20 records. With more, or when any event had an empty key, it names none. keys is then left out, and a reader treats every record as changed.
• A list is stale once, for any change, as before. It also uses keys to say where the change fell; see the section 4.5.
• A record page names its record in its watch, by the entity's declared key, such as { username }. It goes stale when the message names its record or names none.
• The tenant and party filter is unchanged. The keys of a message are only those of events the session may hear.

A watch that cannot state its record's key before it has read it, such as a contact record that is keyed by its email, leaves record out and stays stale for any change.

A list goes stale for any change to its entity, because a record that is not on the page can still move a row onto it or off it, through the sort, the search or the total. A stale Refresh does not tell the reader where to look, so the list uses the keys to place the change. It keeps the keys of the changes heard since its load, and compares them with the rows on the page, which it identifies by the source's recordKey:

The strip says that something changed which the page cannot show. When the changes name rows on the page and a record off it, both show. A list keeps at most 100 records by name, and past that it only knows that something changed. The Refresh button stays gold in every case, and the list never reloads by itself.

One subscription per screen would be wrong twice over: a deployment with a hundred people watching accounts would open a hundred NATS subscriptions to the same subject, and every one of them would carry the same message.

So a subscription is shared, keyed by the tenant and the entity, and the BFF keeps a map from that key to the sessions watching it:

(tenant, component.entity)
      │
      ├── session A   ← has a list of countries open
      ├── session B   ← has a list of countries open
      └── session C   ← has a country open

Filtered by tenant, and that is not decoration. Tenancy is the boundary the whole system is built on: a change in one tenant's accounts is not news in another's, and telling a session about it would leak the fact that it happened. The subject is the same for every tenant, so every event arrives at the registry and each carries its tenant in the envelope. A session is told only of its own tenant and the system tenant, whose rows are shared, and a member only of the parties they work in. An administrator hears every party of the tenant.

Reference counted, and torn down when the last watcher goes. The map entry exists while at least one session watches and is removed when the last one stops, so a subscription is not held open for an entity nobody is looking at. A person who navigates away stops watching that entity and keeps watching nothing else until they navigate somewhere that watches something.

A session watches what is on screen. A list of countries watches country. A country's detail screen watches that record's entity, because the record it is showing is in it. A screen that watches nothing is not subscribed to anything, and that is the normal state of most of the interface.

Only the entity itself. A change to a country is news to the country list. It is also news to a book that references one, and to anything showing a country's name by lookup — and none of those are told, because the event names the entity that changed and not the entities that depend on it. This is the right thing to leave for later: the dependency graph is real, it is not derivable from the notification, and getting it wrong means a screen that refreshes constantly for reasons nobody can see.

It follows that a screen can be quietly out of date about something it shows by reference. A book list showing a country's name will keep showing the old name until something else makes it reload. That is a known limitation rather than a bug, and it is recorded here so it is not mistaken for one later.

// The browser holds one stream. A screen names what it shows, and the hook says
// whether that is older than a change that has been heard.
const load = useLoadState([['account', username], ['timeline', 'person', username]]);
const { stale, changedAt } = useEntityChanges(
    [{ component: 'iam', entity: 'accounts' }],
    load,
);

The entity is the events collection as the services name it, such as accounts. stale is true once news has arrived after the load began, and stays true until the screen loads again. changedAt is the server's time of the newest change, for the tooltip. A screen outside the provider hears nothing. The names a refdata list watches come from the registry (events on each resource).