Realtime

How a screen changes without a page reload, and what it is listening to.

Who this is for. Somebody building a client, or working out why a screen
stopped updating.

Before you start. Realtime is an accelerator here, never the source of
truth. Every screen below also has a read that returns the same state. A dropped
socket costs freshness, not correctness.

The connection

The single-page app connects with socket.io-client to the page's own origin,
in a namespace named after the site.

io(`${window.location.origin}/${window.site_name}`, { withCredentials: true });

Whatever serves the app also proxies /socket.io to the websocket service, so
no second host is involved. This mirrors Frappe's own
socketio_client.get_host().

Reconnection never gives up. reconnectionAttempts is infinity. Five
attempts was about thirty seconds of trouble before the client stopped trying
for the life of the page, and a laptop asleep through its lease woke to a frozen
countdown and never received its expiry event.

The six events

The last two have no listener in the app. They are published, and a client may
use them. Do not assume a screen reacts to either one.

bench_deploy_log and lab_build_log

Both carry one line of a running log. The two differ only in what a run is of,
so the payload shape is shared.

A step boundary adds five more keys. They are additive, so a client written
before the stepper existed keeps working.

Both events are published with after_commit=False, and each line is committed
to the log row as it is written. A deploy runs for minutes inside one background
job, so its transaction would otherwise hold every line until the run ended.
Somebody opening the log mid-run, or reloading after a dropped socket, has to
see what has happened so far.

The line is also written into the log row. The socket is the fast path, and the
row is the record.

benchpress:lease_expired and benchpress:lease_renewed

Both carry full state, never a delta, and never the bench document.

Never bench.as_dict(). The Bench Instance DocType holds three passwords.
The payload is built field by field for that reason.

revision exists because two events can arrive out of order. A tab that
receives both keeps the later stamp.

server_now_ms is what a countdown corrects against. The
server_time endpoint answers the same question
for a client that has not received an event yet.

Both are published with after_commit=True. A client must never learn of an
expiry the database has not committed.

Scoping

Every event except mariadb_health_failure is published with a user, so
Frappe sends it to that user's sessions only.

A deploy log is the bench owner's, and nobody else's socket has any business
receiving it. This matters more than usual here, because a deploy log names the
site, the container and the apps.

mariadb_health_failure is a broadcast about shared infrastructure and names
only the server.

Verify

Watch a deploy log arrive, from the browser console with the app open:

const socket = io(`${window.location.origin}/${window.site_name}`, { withCredentials: true });
socket.on("bench_deploy_log", (data) => console.log(data.step_index, data.log));

Then deploy a bench. See
Deploy from a template.

Troubleshooting

Reference

Related

• Deploy pipeline — the marker behind the step payload.
• API — the read that returns the same state.
• Logs and monitoring — the same events, as a screen.
• Data model — the row every line is written to.