Module connection 

One connection: the upgrade, what the server says first, and the loop that answers what a client asks for.

Re-exports

use std::path::Path; 🔒

use std::sync::Arc; 🔒

use std::sync::atomic::AtomicBool; 🔒

use std::sync::atomic::Ordering; 🔒

use std::time::Duration; 🔒

use std::time::Instant; 🔒

use axum::extract::ws::Message; 🔒

use axum::extract::ws::WebSocketUpgrade; 🔒

use axum::extract::ConnectInfo; 🔒

use axum::extract::State; 🔒

use axum::http::HeaderMap; 🔒

use axum::http::StatusCode; 🔒

use axum::http::header; 🔒

use axum::response::IntoResponse as _; 🔒

use axum::response::Response; 🔒

use futures_util::SinkExt as _; 🔒

use futures_util::StreamExt; 🔒

use tokio::sync::mpsc; 🔒

use tokio::sync::oneshot; 🔒

use base64::Engine as _; 🔒

use forge_primitives::SessionSlot; 🔒

use forge_primitives::browser::BrowserFrame; 🔒

use forge_primitives::browser::BrowserInputEvent; 🔒

use forge_primitives::browser::BrowserTabList; 🔒

use forge_primitives::browser::BrowserViewState; 🔒

use forge_primitives::browser::MouseAction; 🔒

use forge_primitives::document::DocumentRead; 🔒

use forge_primitives::wire::COMPRESSED_JSON_TAG; 🔒

use forge_workspace::browser::BrowserAttachment; 🔒

use serde_json::json; 🔒

use super::batch; 🔒

use super::batch::Batch; 🔒

use super::envelope::ClientMessage; 🔒

use super::envelope::ClientSettings; 🔒

use super::envelope::SeatFrameWire; 🔒

use super::envelope::ServerMessage; 🔒

use super::envelope::SettingsRefusal; 🔒

use super::envelope::Subject; 🔒

use super::frame::FrameTransport as _; 🔒

use super::origin as origin_gate; 🔒

use super::wire::FileContentWire; 🔒

use super::wire::OpenTimings; 🔒

use super::wire::ReviewedThreadWire; 🔒

use super::wire::cap_message_record; 🔒

use super::wire::cap_tool_records; 🔒

use super::wire::conversation_for; 🔒

use super::wire::encode_subject; 🔒

use super::wire::encode_subject_timed; 🔒

use super::wire::floor_cursor; 🔒

use super::wire::page_within; 🔒

use super::wire::placement_wire; 🔒

use super::PROTOCOL_VERSION; 🔒

use super::TransportState; 🔒

use super::WRITE_BOUND; 🔒

use super::WriteStalled; 🔒

use super::write_within; 🔒

use crate::live::Live; 🔒

use crate::surface::DictateOutcome; 🔒

use crate::surface::ViewSurface; 🔒

use crate::Command; 🔒

use crate::DispatchError; 🔒

use crate::SeatUpdate; 🔒

use crate::SessionUpdate; 🔒

Structs

AbortOnDrop 🔒

A task that is aborted when its handle drops, so a read nobody will answer does not outlive the subscription or the socket that asked for it.

AnswerLanes 🔒

The connection’s own loop, so that every way out of it runs the detach above rather than only the clean one. The connection’s answer lanes, bundled so the loop’s signature carries them as one piece of state rather than two.

Arrival 🔒

A message on its way through the loop: who sent it, and when it reached this connection. The instant is the arrival’s rather than the handling’s, so an ask that queued behind an earlier read pays that wait in its open.

AttachedClient 🔒

Counts this connection among the attached clients for as long as it lives, so a document hand-off can tell a viewer exists to open on. A guard, for the same reason Holds is one: the count must come back down however the connection ends, a dropped socket included.

BrowserViewing 🔒

This connection’s browser half: the tab it draws and the strip it follows.

Caller 🔒

This connection as the log names it: the number its takes are told apart by, and the address it is attached from.

Claim 🔒

One seat’s claim: the seat, and the generation of the take that holds it.

ClientSocket 🔒

This connection’s socket, with the one fact the write path needs from the upgrade: whether the client declared it can inflate a compressed frame.

ConnectionLife 🔒

What a connection leaves behind when it ends.

FrameWrite 🔒

One frame’s write, measured: its size, the time the socket took it, and whether the write yielded at least once before it was done.

Holds 🔒

The seats this connection is holding, each given back when this drops.

Keepalive 🔒

One connection’s keepalive: the ping it has out, if any.

OpenReport 🔒

One subscribe’s open, as its write and its log state it.

PeerVanished 🔒

The peer stopped answering the keepalive’s ping, so the connection was ended from inside its own loop.

Progress 🔒

The connection’s own clock: one stamp per completed socket write, and the seat it last said it was showing.

ReadAnswer 🔒

One subscribe read finished off the loop.

ReadAnswerGuard 🔒

Answers the loop if the read task ends without doing so. A panic in the encode must not leave the connection waiting on a record nobody owes: no answer leaves the read in flight for the connection’s life, and every later subscribe queues behind it in silence.

Reading 🔒

The subscribe read this connection is waiting on, and what arrived for it while it ran.

Reads 🔒

The connection’s subscribe reads: the one served off the loop, the asks that queued behind it, and the channel its task answers on.

SentWords 🔒

The words a review write sends, the seat they were the reader’s in, and what the write’s own reply says when it landed.

SettingsPush 🔒

The settings push this connection follows: the watch it hears and the frame its greeting already wrote.

Streaming 🔒

What this connection is streaming: the seats it has claimed takes for - a start’s seat is claimed as soon as its dispatch answers, so a refused one keeps its entry, and a frame that follows a start always finds the seat - and whether it is recording the read-aloud set. A dictation frame carries no seat of its own - and the recording carries none at all - so these are what address one.

SystemClock 🔒

The shipping clock: the process’s own monotonic one.

TerminalViewing 🔒

The terminal this connection is viewing.

TerminalViewingState 🔒

This connection’s terminal half.

Viewers 🔒

The viewer halves one connection carries: the browser tab it draws and the terminal it is attached to. One value rather than four arguments, because the read loop already carries the connection’s whole mutable state and the pair would push every handler past the arity a reader can hold.

Viewing 🔒

One tab this connection is viewing: its profile, its id, its frames and its state.

Watching 🔒

What this connection is watching, and which of it is on screen.

WedgeStalled 🔒

A connection task that stopped making progress.

Enums

Answer 🔒

What a task off this loop asks it to send.

Ask 🔒

What a more asks for, out of the cursor it was sent.

Beat 🔒

What one beat should do.

BelowFloor 🔒

What a paging read below the held window’s floor resolves to.

FrameRoute 🔒

Where one binary message went, decided without touching a take.

Queued 🔒

An ask waiting behind the connection’s read.

TerminalEvent 🔒

What the terminal has for the loop.

ViewEvent 🔒

What a viewer has to say to the loop.

Constants

BOUNDARY_TRIES 🔒

How many of a window’s rows a below-floor page tries to start from.

COMPRESSED_MIN_BYTES 🔒

The JSON bytes at which a frame crosses compressed, for a connection that declared the capability.

HEARTBEAT_DEAD 🔒

How long a ping may go unanswered before the connection is reaped. Four missed beats: long enough that a busy peer is never cut, short enough that a role is not held by a corpse for the minutes a TCP retransmission timeout takes. Chosen, not measured: the one number it changes for a person is how fast a call on a paused host fails (a tool call’s own bound is longer).

HEARTBEAT_EVERY 🔒

How often a connection is asked to prove it is still there.

MAX_CLIENT_MESSAGE_BYTES 🔒

The largest message a client may send.

MAX_HELD_READ_FRAMES 🔒

Frames held for a seat whose record is being read. The record is encoded after them, so everything below its seq is discarded by the client and the newest are the ones worth keeping; a read that never ends stays bounded.

WEDGE_DEAD 🔒

How long a connection may write nothing before a watchdog outside its future ends it.

Traits

WriteClock 🔒

The clock a measured write reads.

Functions

answer_ask 🔒

Answer one strip ask: through the reply it carried, or as the error frame when it carried none.

answered 🔒

Dispatch one of those, and answer the client that asked.

answers_through_a_reply 🔒

Whether a command reports its outcome through the reply rather than through an update on the subscription.

attach_terminal 🔒

Attach this connection to a seat’s terminal as a viewer.

attach_view 🔒

One viewer’s attach: the same body for a tab number and for a hand-off’s page, because everything after the resolution is identical.

below_the_floor 🔒

Two cursor forms, one walk. The window’s newest page hands back the frame index its front sits at; every page below the floor hands back a row cursor (r:<byte>[:<id>]) minted from the row it reached. A frame cursor cannot be resolved to a row, because the frames the CLI streams and never writes sit between the window’s rows, so no arithmetic lines the two numberings up. It is answered from the window’s oldest row the file resolves instead: overlap at worst, never a gap, and a walk from any cursor converges on the same descending chain.

boundary_candidates 🔒

The rows a walk below the window may start from, the walk’s own stop first and the rest of the window behind it.

call_output 🔒

A call’s own output, read from the transport’s held copy of its seat.

carries_a_result 🔒

Whether a frame is a user row carrying a tool result - the frame a stop may not land on, because the call it answers sits just beneath it.

cron_names_off_loop 🔒

The cron pairings a page’s rows need, read off the connection loop.

discrete_gesture 🔒

Whether one gesture is worth its own record: a pointer move and a wheel are streams, so their refusal is the click’s that follows and logging every one would bury the answer in it.

dispatch_answering 🔒

Dispatch one reply-carrying command and hand its answer to the connection.

dispatch_refusal 🔒

One refused dispatch, as the frame the asking client reads: the operation the refusal names, the core’s own words, and the dispatch id the press that made it minted - echoed so a press can attribute this refusal to itself rather than to whatever was pressed last.

dispatched 🔒

Which hand sent what (issue #2372: a parked hand-off’s answer arrived over the socket and could not be attributed - no dispatch named its connection). Logged where a command is actually dispatched: a refusal never was.

document_answer 🔒

One document read’s outcome, as the asking client reads it: the answer with the document’s bytes base64, or the refusal under the seat that asked - the seat is what lets a client holding several seats drain only its own.

drive 🔒

Read what a client sends, and hear what its subscriptions asked for.

ending 🔒

Why a connection ended, for the teardown records that run after it: a wedge and a clean close leave the same marks to release, and a reader looking at one of them has to know which it was.

finish 🔒

Everything a connection leaves behind, undone on every way out of it: a clean close, a failed read, and a connection the watchdog dropped.

finish_read 🔒

Answer a subscribe read that ran off the loop: its record, its refusal, or nothing when the client let the seat go while it ran.

for_a_client 🔒

The update as it crosses to a client.

forward_queued 🔒

The frames a subscribe read out of the stream it replaced: filtered for this connection, and bounded like every other path to a client (#2374).

forwards 🔒

Whether this connection forwards one update.

frame_bytes 🔒

The bytes a frame carries, which is what the write’s own record reports.

frame_for 🔒

One message as the frame this connection sends: text as it always was, or a gzipped body behind COMPRESSED_JSON_TAG when the client declared the capability and the body is over the threshold.

frame_for_flag 🔒

frame_route 🔒

Decide one binary message’s destination.

gesture_kind 🔒

The gesture’s kind, for a record that names what was refused without carrying it. A typed text is never logged, only how long it was.

greet 🔒

Greet, then serve the client until it goes.

greeting_for 🔒

The frame that tells a client it is speaking to a forge and carries the [client] sets it draws with. Built when the connection opens, so a reload applies to the next connection.

gzipped 🔒

handle_client 🔒

Answer one client message.

handle_message 🔒

handle_client with the message already read, so a subscribe that queued behind a read off the loop takes the same path the socket’s own did.

is_take_news 🔒

Whether this update is one of a take’s own.

log_open 🔒

The open’s two records: the snapshot’s write, and the session’s slices.

mint_connection_id 🔒

The next number for a connection, unique for the process’s life.

next_tab_change 🔒

The next tab list this connection asked to follow, or a future that never resolves while it follows none - the same shape next_view_event uses, so a connection with no strip parks rather than ending the loop.

next_terminal_event 🔒

The next thing this connection’s terminal has for the loop.

next_update 🔒

The stream’s next update, or a future that never resolves while there is none - which is what keeps the branch out of the way until the client has subscribed and the role is known.

next_view_event 🔒

The next thing this connection’s viewer has for the loop.

open_stream 🔒

This connection’s stream from the core, opened when the client first subscribes and registered with the role that subscribe declares.

ours_to_hear 🔒

Whether this connection is one of an update’s readers.

page_of_span 🔒

The page a span of transcript rows answers with, cursors and all.

refusal_tag 🔒

The operation a dispatch refusal names, which a client routes by.

refuse_attach 🔒

Answer a refused attach: through the client’s reply when it sent one, and as the protocol’s error frame otherwise.

released_subscribe 🔒

The answer a subscribe owes when the subject it named was released before any read for it could land.

row_cursor 🔒

The row a page below the floor is asked for, out of a cursor this server minted: the byte the walk reached next, and the id that row carries where it has one.

row_cursor_of 🔒

A row as the cursor a page below the floor hands back.

row_id 🔒

The id a transcript row names a frame by, for the frames that carry one.

rows_below_floor 🔒

Answer a page below the held window’s floor from the session’s transcript.

run_connection 🔒

send 🔒

send_frame 🔒

send, answering how many bytes the frame carried.

send_frame_timed 🔒

send_frame, timing the socket’s share of the write.

send_terminal_view 🔒

Send the attached terminal’s screen as a VT stream, and where the stream continues from.

send_text 🔒

Write an already-encoded frame. The settings document is encoded once per reload and shared, so a connection writes its bytes rather than building the frame again.

set_showing 🔒

Move this connection’s shown seat, spending exactly what that showing earns.

spawn_read 🔒

Spawn a subscribe read off the connection’s loop, with its answer guard armed INSIDE the task: an encode that panics must still answer the loop, or its read stays in flight for the connection’s life and every later subscribe queues behind it in silence.

spend_showing 🔒

Spend what showing slot earns: its diamond, its failure mark and its death trace, and the home refresh a spent mark owes.

stamp 🔒

This connection’s own stamp on the commands that carry one.

submit_landed 🔒

Whether a submit’s reply carries a sealed round, which null does not.

supervise 🔒

Run one connection under the wedge watchdog.

take_frame 🔒

Push one dictation frame into this connection’s takes or its read-aloud recording, recording anything else.

text_chars 🔒

How many characters a refused text carried, and nothing of what they were.

transcript_frames 🔒

The frames a range ask is answered with once the seat’s own window has shed them: the conversation’s own rows, numbered to END at the range’s end.

upgrade

Take the upgrade and give the connection its own task.

upsert_landed 🔒

Whether an upsert’s reply says the store took the write.

words_sent 🔒

write_snapshot 🔒

Write a subscribe’s snapshot, register the subject, log the open and spend the showing marks the snapshot completes.