Enum ClientMessage 

pub enum ClientMessage {
    Ping,
    Subscribe {
        what: Subject,
        answering: bool,
        review: bool,
    },
    Unsubscribe {
        what: Subject,
    },
    Showing {
        seat: Option<SessionSlot>,
    },
    Command {
        command: Box<Command>,
        reply_to: Option<u64>,
    },
    More {
        conversation: SessionSlot,
        before: Option<String>,
        turns: u32,
    },
    SeatRange {
        slot: SessionSlot,
        epoch: Option<SessionId>,
        from: u64,
        to: u64,
    },
    CommitDiff {
        session: SessionSlot,
        sha: String,
    },
    BrowserView {
        seat: SessionSlot,
        tab: Option<u16>,
        reply_to: Option<u64>,
    },
    BrowserViewPage {
        seat: SessionSlot,
        target: String,
        reply_to: Option<u64>,
    },
    BrowserFileAnswer {
        id: u64,
        files: Vec<BrowserFileWire>,
    },
    BrowserDetach,
    TerminalView {
        seat: SessionSlot,
        id: Option<u16>,
        cols: Option<u16>,
        rows: Option<u16>,
        reply_to: Option<u64>,
    },
    TerminalDetach,
    TerminalResize {
        seat: SessionSlot,
        id: u16,
        cols: u16,
        rows: u16,
    },
    TerminalPause {
        paused: bool,
    },
    TerminalControl {
        seat: SessionSlot,
        id: u16,
        take: bool,
    },
    TerminalClose {
        seat: SessionSlot,
        id: u16,
    },
    BrowserInput {
        seq: u64,
        event: BrowserInputEvent,
    },
    BrowserControl {
        take: bool,
    },
    BrowserNav {
        back: bool,
    },
    BrowserResize {
        width: u32,
        height: u32,
        scale: f64,
    },
    BrowserTabs {
        seat: SessionSlot,
        reply_to: Option<u64>,
    },
    DocumentRead {
        session: SessionSlot,
        path: String,
        reviewable: bool,
    },
    FileContent {
        session: SessionSlot,
        path: String,
        sha: Option<String>,
    },
    ClientPerf {
        records: Vec<Value>,
    },
    SettingsEdit {
        fingerprint: String,
        edits: Vec<SettingsEditRequest>,
        id: u64,
    },
}

What a client sends.

Variants

Ping

A liveness probe, sent by a transport after a quiet spell and by the page on a return from the background.

Application-level rather than a WebSocket control frame: a browser page cannot send a Ping, so control frames would leave the web build with no probe at all. Any inbound frame answers one; this exists so a quiet peer is always asked something.

Subscribe

Fields

what: Subject

answering: bool

Whether this client can answer the prompts it is shown.

Off unless the client says otherwise, because the core parks a turn on the reply of whoever registered as answering: a client counted as able to answer a prompt it has no surface to draw hangs the turn rather than failing it. A client with a dock to answer from says so here; the connection registers with the core accordingly before it forwards anything.

It is the CONNECTION’s role, not the subject’s. The core keeps one role per connection and it only ever rises, so a client that can answer states it on the first subscribe it makes - usually the home - and not only while a seat it could draw is showing.

What it guards is an install with no answerer anywhere. Every update is delivered to every subscriber regardless of role; the role decides only what the core may PARK on. A forge with an answering client attached already has an answerer, so a second client that says nothing is a guest beside one that can. Where nobody can answer, an ask is cancelled at birth rather than held for a reply that could not come. Declaring this means that case never arises while this client is attached.

review: bool

The review page’s own read: refresh the branch diff’s base before the record is encoded, and pin the stats and content reads to the sha that refresh resolved.

Off for every other read. The ordinary record read is the one behind every seat page and must not wait on the network; a page that draws a diff asks again with this set when it opens, so the state beside that diff belongs to the moment it was read.

Unsubscribe

Fields

what: Subject

Showing

Which seat this connection has on screen, None when it shows none.

A state assertion, not an event: the last one wins and repeating it is a no-op. A showing spends a seat’s diamond, its failure mark and its death trace - once the seat is also subscribed, so a client that keeps every visited seat subscribed spends nothing until the reader opens one. Nothing answers it.

Fields

seat: Option<SessionSlot>

Command

reply_to is set only when the client wants an answer - which is the eight commands whose reply rides a oneshot, and nothing else.

Boxed because a command is 360 bytes and every other variant here is a fraction of that (clippy::large_enum_variant). Serde writes a box as the value inside it, so the wire form is unchanged.

Fields

command: Box<Command>

reply_to: Option<u64>

More

Fields

conversation: SessionSlot

before: Option<String>

turns: u32

SeatRange

The frames a seat’s stream emitted between two numbers, for a client that read a gap in them.

The numbers are the seat’s own, minted as each frame crossed, so a repair folds into the client’s stream exactly where the frames fell rather than reading as a second conversation. epoch is the occupant those numbers belong to: a seat whose occupant has changed has started counting again, and a repair across the two is refused rather than answered.

Fields

slot: SessionSlot

epoch: Option<SessionId>

from: u64

to: u64

CommitDiff

One commit’s own diff, for the review canvas’ commit scopes.

Asked on demand rather than carried on the record: a branch can hold dozens of commits, and every reader of a record would pay their content on every read for a scope only one page draws.

Fields

session: SessionSlot

sha: String

BrowserView

Attach this connection to one of a seat’s browser tabs, as a viewer.

tab is the tab to drive; None is the asking seat’s current tab, else its profile’s first. The answer is a browser_view naming the profile’s wire id and the tab, then a browser_nav_state, then frames as they paint. Attaching again replaces what this connection was viewing.

Fields

seat: SessionSlot

tab: Option<u16>

reply_to: Option<u64>

Answers the attach: {"ok": true, "profile": <the one attached>, "tab": <the tab>}, or {"ok": false, "why": ...} with the server’s own words. A raise that cannot be answered is a dark surface, so a client that can wait sends one; the profile and tab are what the page’s Done lowers.

BrowserViewPage

Open the page a parked hand-off named: the same attach, addressed by the page’s CDP target instead of a tab number.

A number is not an identity across a host restart. The successor host’s first tab takes number 1 again, so an ask parked through the replacement must name its page; a page that is gone is refused with the tabs that are open now.

Fields

seat: SessionSlot

target: String

reply_to: Option<u64>

The same answer BrowserView gives: the profile and tab attached, or the server’s refusal.

BrowserFileAnswer

The files a person chose for a page’s dialog, or none for a dismiss.

The bytes cross base64 because the wire is JSON; the server writes them to its own temp directory and hands the host the paths, because the host reads a file’s content at the moment it is answered.

Fields

id: u64

files: Vec<BrowserFileWire>

BrowserDetach

Stop viewing the attached profile. Lowering the takeover is a detach: the idle clock counts an attached viewer as a use, and a connection that switched profiles must not leave a phantom viewer on the old one.

TerminalView

Attach this connection to one of a seat’s terminals, as a viewer. The answer is a terminal_view carrying the screen as a VT stream, then output frames as the shell writes them.

Fields

seat: SessionSlot

id: Option<u16>

The terminal id, or None to open the seat’s terminal - creating it when the seat has none - and attach to it. The person’s door on a seat every agent has left alone.

cols: Option<u16>

The grid the client will draw on, sent with the attach so the repaint is laid out for it: a client that attached first and resized after had to draw nothing until a second repaint arrived, which read as the screen flushing.

rows: Option<u16>

reply_to: Option<u64>

Answers the attach: {"ok": true, "id": <the one attached>} or {"ok": false, "why": ...}. A raise that cannot be answered is a dark surface, so a client that can wait sends one.

TerminalDetach

Stop viewing the attached terminal: the idle clock and the resize arbitration both read the truth from it.

TerminalResize

The attached surface changed size: the PTY and the model resize.

Fields

seat: SessionSlot

id: u16

cols: u16

rows: u16

TerminalPause

Client-driven flow control, so a phone that backgrounded stops being written to rather than being dropped. A resume is answered with a fresh terminal_view, because the frames it missed are not replayed.

Fields

paused: bool

TerminalControl

Take the person’s control of an attached terminal, or give it back. One controller at a time, like the browser’s role: a take always lands, and the previous holder hears it lost the role.

Fields

seat: SessionSlot

id: u16

take: bool

TerminalClose

The person’s close door: end the terminal’s process group.

Fields

seat: SessionSlot

id: u16

BrowserInput

One input event from the controlling viewer.

seq is the viewer’s own ordering: the server drops an event at or below the last one the role carried, so a superseded gesture never lands late. The event is the gesture, not CDP - the server maps it.

Fields

seq: u64

event: BrowserInputEvent

BrowserControl

Take the controller role, or give it back.

Fields

take: bool

BrowserNav

Move through the page’s history: the takeover bar’s arrows.

Fields

back: bool

BrowserResize

The controller’s surface changed size: the page is laid out to it.

width and height are the surface’s DEVICE pixels - the client multiplies its CSS box by the ratio it draws at - and scale is that ratio, which the host gives CEF.

Fields

width: u32

height: u32

scale: f64

BrowserTabs

The tabs of this seat’s profile, for a client’s strip. Answered through reply_to with {"ok": true, "tabs": { "profile", "id", "up", "connected", "closing_at_ms", "rows" }}, and then pushed as a browser_tabs whenever they change.

Fields

seat: SessionSlot

reply_to: Option<u64>

DocumentRead

One document, read out of a seat’s own tree for a viewer’s route.

path resolves against the seat’s working directory, and reviewable is what the hand-off asked for - the hand-off’s own fact, refused on a PDF because that kind can never carry a review. Whether the DOCUMENT is reviewable is the read’s own answer, not this flag’s echo. The answer is a document_read message or an error naming it; those are its only two.

Fields

session: SessionSlot

path: String

reviewable: bool

FileContent

One file’s whole content at a revision, for the review page’s between-hunk expansion.

The record’s diff carries bounded hunks, so the lines BETWEEN them are exactly what it does not carry - and only a page whose reader opened a gap needs them, which is why this is asked for on demand rather than carried on every record. sha names the scope’s own revision: a commit’s tree for a commit scope, and None for the seat’s branch tip, which is the new side of the all-changes diff. The answer is a file_content message; a read that could not run answers as itself rather than as an error.

Fields

session: SessionSlot

path: String

sha: Option<String>

ClientPerf

One page’s own perf records, for a client with no shell to write them.

The records stay JSON, unparsed here: they are the page’s instrument (client/src/perf.ts), and the server’s part is the file - written beside forge.log so a web client produces diagnostics like the shells do. Nothing answers it; a batch that could not be written is a debug record, not the client’s failure.

Fields

records: Vec<Value>

SettingsEdit

A batched save of the effective config. A save that writes is answered with ServerMessage::SettingsSaved; one that does not is answered with ServerMessage::SettingsRefused. A refused save writes nothing, so no push follows it.

Fields

fingerprint: String

The fingerprint of the raw file text the page loaded.

edits: Vec<SettingsEditRequest>

id: u64

The page’s own number for this save, echoed by ServerMessage::SettingsSaved and ServerMessage::SettingsRefused so a reply is matched to the request that made it. Required: a client that forgets it is refused rather than silently answered as id 0.

Trait Implementations

impl Debug for ClientMessage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ClientMessage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ClientMessage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.