VTX 1 · core · beta draft d03
VTX 1 Wire Specification: core
§6Session, state synchronization and resume
The server owns the scene; the client holds a numbered replica of it. A client that loses its connection resumes from the last state it applied, so a dropped link costs one catch-up, not a redraw.
Session. READY creates the session and gives it a 16-byte random ID. The session outlives connections: it ends when the application ends, or linger seconds after its last connection drops (no linger means 0). When the application ends, the server closes every connection with session_ended (Section 14), carrying the exit status or the signal when there is one; such a session cannot be resumed.
State numbers. Each scene UPDATE carries state, one higher than the previous update; the parts of a multi-frame update share one state (Section 7). READY reports the last state the server has produced: 0 for a new session, so its first UPDATE carries state 1.
Acknowledgement. The client sends ACK with the highest state it has applied. It SHOULD do so within 100 ms of applying an update and MAY cover several updates with one ACK.
Retention. The server keeps every update after the last acknowledged state, up to its retain limit in bytes. Beyond that it falls back to a snapshot.
Resume.
- The client sends HELLO with
resume: the session ID, the last state it applied and, when this device holds one, the resume token. - The server checks the token, when one is sent. Tokens are 32 random bytes and single-use. If WELCOME lists auth methods, the client signs in again, and the user MUST be the session's user; otherwise the resume fails. A resume without a token always requires sign-in.
- On success the server sends READY with
resumed: trueand a new token. It then either replays the updates after the client's state up to READY's state, in order, or sends one UPDATE withreset: trueand the state after READY's, holding the whole scene. - On failure the server starts a new session: READY carries
resumed: false, and the client discards its old scene.
Pending requests. After a resume, the server sends again every zone and clipboard request that is still pending, with its original ID. A client that had already answered one sends the same answer again.
Input delivery. INTENT, PASTE and the commit of COMPOSE carry seq, which starts at 1 in each session and rises by one with each such event.
- READY's
input_seqis the highestseqthe server has delivered to the application; 0 for a new session. - While connected, the server sends INPUT_ACK with that number at least once a second while any events are unacknowledged.
- The client keeps each such event until it is acknowledged. After a resume it sends again, in order, every one above READY's
input_seq. The server drops aseqit has already delivered. - Keys, pointer, wheel, gesture and gamepad events are never sent again: they belong to a moment that has passed, and the user sees the resumed screen before acting again.
Resuming from another device. A client without the token, such as a second device, sends HELLO with resume holding the session and state 0, and signs in as the session's user; the server then sends a reset snapshot, and the connection that held the session gets GOAWAY taken_over (below). After READY, a client may send SESSIONS to list the signed-in user's sessions; SESSION_LIST answers with each session's ID, application, title and whether a connection is attached.
GOAWAY. A client that follows a GOAWAY reconnect URI sends its resume token only when that URI names the same host; to any other host it resumes without the token and signs in again.
Token rotation. READY carries a fresh resume token, and the server sends TOKEN with another at least once an hour. The server keeps accepting the previous token until a resume has used the newer one, so a TOKEN lost with a dropped connection does not strand the client.
Detach. DETACH tells the server the client is leaving deliberately; its linger asks how long to keep the session. The server closes the connection at once with no_error and keeps the session for the requested time, capped at WELCOME's linger. WELCOME's linger is the server's maximum; READY's is the value in force.
One active connection in the core. A resume from a new connection takes the session over; the old connection receives GOAWAY with code taken_over. Several viewers with roles (owner, operate, interact, approve, watch) come with the Viewers 1 extension, which adds joining as a viewer alongside this resume.
Stale input. Every input event carries seen, the last state the client had applied when the event happened. Applications use it to recognise actions on UI that has since changed, such as a click on a removed button, and MAY ignore them.
Keep-alive. An endpoint sends PING after idle/3 seconds without sending anything. A connection that receives nothing for idle seconds is dead; the client then resumes. idle comes from WELCOME, defaults to 60 and MUST be at least 30.
Local prediction. Layer 2 fields echo typing locally (Section 9). A grid with echo: "predict" lets the client predict printable characters, as Mosh does. Predicted cells SHOULD be visually marked until an update confirms them.