Skip to main content

Connection

The event stream is one long-lived HTTP response of server-sent events. Open it with the browser's built-in EventSource; you need no library.

Endpoint​

Method and pathGET /api/stream
Query parameterorg (optional) — the id of the organization your page shows; see Switching organization
Response typetext/event-stream
Reconnect delayretry: 1000 — one second, sent first on every connection
Keepalivean event named keepalive with data: {}, after 15 seconds with nothing else sent
Event nameskeepalive only; every change arrives as a plain message

Each change is one data: line holding a JSON object, the envelope. The stream sends only events you are allowed to see; the event catalog says who receives each entity.

Keepalives​

The keepalive is a named event:

event: keepalive
data: {}

It keeps proxies and load balancers from closing a quiet connection. Because it has a name, EventSource never passes it to your message handler, and its data names nothing. To notice a connection the network dropped without closing it, listen with addEventListener('keepalive', …): if neither a keepalive nor a change arrives for well over 15 seconds, close the stream and open a new one. A client that reads the raw response must skip it.

Reconnecting​

When the connection drops, EventSource reconnects by itself after the one-second retry delay, the standard behaviour of any EventSource.

That holds only while the server keeps answering with the stream. When it refuses a reconnect instead — after you sign out, or, on a stream opened with ?org=, after you switch organization in another tab — EventSource stops for good: its readyState becomes CLOSED and it never retries. Check readyState in your error handler, and open a new stream yourself once the cause is cleared.

The stream does not replay what you missed. Events carry no id: line, and a reconnect that sends Last-Event-ID gets no backlog. Anything that changed while you were disconnected is not resent, so refetch the state you show after every reconnect — the open event fires each time the connection is made, and is the place to do it.

The server closes the stream itself when your session ends — you sign out, it times out, your password changes, or you switch organization — and when you are removed from the organization. A switch closes it at once. The others are noticed only on the first change anywhere in Jaah, even one not sent to you, that comes more than a minute after the last check, so a quiet stream can stay open, sending keepalives, until something changes. In an organization with HIPAA turned on, an idle timeout is noticed at the next keepalive. Changes to what you may see do not close it: they apply to the events that follow, within about a minute.

In an organization with HIPAA turned on, the stream also closes itself at the first keepalive more than 15 minutes after the session it opened with was last refreshed. If the console was in use, the reconnect succeeds and the stream goes on. If nobody used the console for 15 minutes, the reconnect is refused and the stream stays closed until the user signs in again.

In an organization with an IP allowlist, the stream also closes once the list no longer includes the address it opened from: at the next keepalive, or within about a minute while events are flowing. Its reconnect is then refused with 403 until an org admin adds that address (see Errors).

The stream can also drop an event, with no error, when your client falls behind a burst of changes. If you must not miss a change, refetch on a timer as well as on open.

Switching organization​

Add ?org=<organization id> to the stream's address to tie it to the organization your page shows. Whenever org is not the organization your session has active, the request is refused with 409 Conflict (detail org_switched, plus active_org), on the first connect as on a reconnect. So if you switch organization in another tab, the next reconnect is refused and the stream stays closed, and the page can reload into the organization now active instead of mixing two. A stream opened without org reconnects as usual and follows the organization now active.

Example — subscribe and filter by entity​

Paste this into the browser console on a page of the Jaah console, then edit a task in another tab. Each change to a task prints one line.

const stream = new EventSource('/api/stream')
const wanted = new Set(['task']) // the entities to act on; see the event catalog

stream.addEventListener('open', () => {
// Connected or reconnected: nothing is replayed, so refetch what you display here.
console.log('event stream open')
})

stream.addEventListener('message', (message) => {
const event = JSON.parse(message.data) // { entity, id, action }
if (!wanted.has(event.entity)) return
console.log(`${event.entity} ${event.id}: ${event.action}`)
// Refetch that item here, for example the task with this id.
})

stream.addEventListener('error', () => {
if (stream.readyState === EventSource.CLOSED) {
// The server refused the reconnect: EventSource will not retry. Open a new stream when ready.
console.log('event stream closed')
return
}
// A dropped connection. EventSource retries on its own after one second.
console.log('event stream interrupted, reconnecting')
})

// Stop listening: stream.close()

Editing a task's title prints a line such as task 4916: updated.