Skip to content

App Event Stream

An app's page learns of the mutations the runtime writes to its instance through GET /api/v2/event, a server-sent events stream served on the app's own origin. Each event names one mutation by its object key and its mutation id, with the db it went to and the replica that wrote it; the row itself never rides. The page decides from the key whether the change concerns what it shows, and rereads through its own request route when it does. An app that lists PresenceStatus among its objects also receives the online status of the account's colleagues on the same stream (Presence).

The request

GET /api/v2/event
Accept: text/event-stream

The URL is relative to the app's entry point, like /api/v2/object. The response is 200 OK, Content-Type: text/event-stream, Cache-Control: no-cache, of unknown length. It stays open until the page navigates away, closes, or drops its EventSource. Any other method is answered 405 Method not allowed. A page may hold more than one stream, and several pages of one instance each hold their own; every open stream of the instance receives every event.

The stream is the page's own. A page receives the events of the instance it belongs to and no other's: a request that names another instance, or one made from a frame that is not an app page, is answered 403 Forbidden.

A reconnecting EventSource sends the id of the last event it received as Last-Event-ID. The stream then opens with every applied mutation written since that one to the db the id names, in id order, before anything new. A mutation received from a peer but not yet applied is announced once it is applied. A Last-Event-ID that is not an event id of this stream is answered 400 Bad request.

Delivery is at least once. A mutation written while a stream is opening can arrive twice, once live and once in the catch-up, and a reconnect repeats whatever the browser had not acknowledged. A listener treats an event as a prompt to reread, never as a count.

The events

The stream opens with a comment line and a retry field:

: ok
retry: 2000

Every mutation then arrives as one event:

event: {https://sobamail.com/module/counter/v1}AddCounter
id: 4712
data: {"db":"main","replica":"{6a1d0e57-2c9b-4f3e-8d71-b04c5e9a2f68}"}
Field Value
event The mutation's object key, as its namespace and name spell it. A row deleted with soba.data.delete() is announced as {https://sobamail.com/module/base/v1}DeleteRow, whichever table it left, and a column updated with soba.data.update() as {https://sobamail.com/module/base/v1}UpdateRow, whichever table holds the row.
id The mutation id in the instance's db. For a db other than main the id is prefixed with the db name and a colon: id: extra:4712.
data A JSON object on one line, with the keys below.
Key Value
db The name of the db the mutation was written to.
replica The uuid of the mailbox replica that wrote the mutation, in braced hexadecimal uuid format, as soba.app.replicaUuid() returns it.

Every mutation written to the instance is announced, whatever produced it: a request from this page, a request from another page of the same instance, or a peer's mutation arriving over replication. replica tells the last apart from the others: a mutation written on the replica the page runs on carries that replica's uuid, whichever of its pages made the request, and one that arrived over replication carries the uuid of the replica that wrote it. A batch the runtime wrote at once is announced as consecutive events, one per mutation, in id order. A replay of an earlier batch is announced like any other write. Besides presence and the answers to the page's cross requests, only mutations ride the stream; a non-replicated request and its response leave no event.

Presence

An app receives the online status of the colleagues of the account its instance belongs to by listing PresenceStatus among its objects. The object has no class to import; the app lists it by its key:

export default class Application {
    static objects = new Map([
        // ...
        [ "{https://sobamail.com/module/base/v1}PresenceStatus", false ],
    ]);
}

The stream of every instance of such an app then carries one event per address; the streams of other apps carry none:

event: {https://sobamail.com/module/base/v1}PresenceStatus
data: {"content":{"address":"jane@example.com","state":2},"name":"PresenceStatus","namespace":"https://sobamail.com/module/base/v1"}

The event has no id, so Last-Event-ID and the reconnect catch-up stay the mutations'. data is the PresenceStatus object as JSON, its content the keys below.

Key Value
address The colleague's address, lowercased.
state 2 online, 1 offline, 0 unknown: the client no longer knows the address's status, after it lost its connection to the server, for one.

The stream opens with the status of every address the client knows, after the handshake and any catch-up, and every change follows as it happens. A reconnect opens with the statuses known then. Delivery is at least once, and the last event for an address is its current status. An address the client has never learned about gets no event.

The client learns the status of the colleagues it shows. The contacts app (contacts.app.sobamail.com) asks for every colleague who is online by posting {https://sobamail.com/module/contacts/v1}GetOnlineUsers to its /api/v2/object; the request is answered 202 Accepted with no body, and the statuses arrive on the stream. Any other app's post is answered 401 Unauthorized.

Subscribing from a page

EventSource dispatches each event under its event field, so a page listens by object key and never sees the keys it did not ask for:

const events = new EventSource("/api/v2/event");

events.addEventListener(
    "{https://sobamail.com/module/counter/v1}AddCounter",
    (ev) => {
        // ev.lastEventId is the mutation id
        const { db, replica } = JSON.parse(ev.data);
        if (replica !== ownReplicaUuid) {
            // written on another replica
        }
        reloadCounters();
    });

ownReplicaUuid stands for the value of soba.app.replicaUuid(), which the page gets from its backend through a request of its own.

Presence is subscribed to the same way:

const presence = new Map();

events.addEventListener(
    "{https://sobamail.com/module/base/v1}PresenceStatus",
    (ev) => {
        const { address, state } = JSON.parse(ev.data).content;
        presence.set(address, state);
        redrawDots();
    });

The browser reconnects by itself after a dropped stream and sends the last id it saw, so the listeners above also receive whatever was written while the stream was down.