@kottera/tera-web 0.1.0-rc.6 → 0.1.0-rc.7

package/dist/terminal/view.js

@@ -0,0 +1,540 @@
+/**
+ * The terminal view: one view of an attended session's terminal (ADR-181
+ * D11 item 2), speaking `terminalwire` (ADR-180 D4) over a
+ * {@link StreamConnection} to the kit's terminal route. It holds ADR-180's
+ * client duties itself, so a page hands it a renderer and keystrokes and
+ * keeps none of them.
+ *
+ * # Output: two offsets
+ *
+ * - **The resume offset is bytes handed to the renderer.** It counts from the
+ *   last `WELCOME` or `RESYNC`, as the minder does, and a reconnect names it,
+ *   so the minder never sends twice what the renderer already has queued
+ *   (ADR-180 D2 item 1). A replay cut off before its `REPLAY_END` names none
+ *   and is replayed whole: a resume could not mark the rest of it as history.
+ * - **An `ACK` counts bytes the renderer's `parsed` callback reported**, never
+ *   bytes received (ADR-180 D6 item 1), coalesced to one per
+ *   {@link ACK_EVERY} or when the renderer has parsed all it was handed,
+ *   whichever is first. A callback for bytes handed over an earlier socket
+ *   acknowledges nothing: the minder's window is per connection.
+ *
+ * A `DATA` payload reaches the renderer as a `Uint8Array` over the message's
+ * own buffer (ADR-181 D11 item 5): nothing on the receive path copies a byte.
+ *
+ * # Input: the window, and what rides outside it
+ *
+ * - **At most {@link INPUT_WINDOW} of `INPUT` beyond what `INPUT_ACK` has
+ *   granted back** (ADR-180 D6 item 2). A paste is queued in the view and
+ *   sent in frames of at most `MAX_DATA_PAYLOAD` as the grants return; the
+ *   queue holds at most {@link MAX_QUEUED_INPUT}. Each new socket starts with
+ *   the whole window, since the minder counts it per connection.
+ * - **A one-byte keystroke the window cannot hold is sent as `SIGNAL`**
+ *   (P-R2, W4-X1; `terminalwire.encodeSignal`), once, ahead of whatever is
+ *   queued: with the window full and the process not reading, it is how
+ *   Ctrl-C still reaches the session. The minder signals the foreground
+ *   process group for the pty's interrupt, quit or suspend character and
+ *   drops any other byte. At most {@link MAX_SIGNALS_PER_GRANT} are sent
+ *   between two grants, half of ADR-180 D6 item 3's 8 KiB control allowance;
+ *   past that a keystroke is dropped. The view's other frames outside the
+ *   window (`ACK`, `RESIZE`, `CONTROL`) are each sent on an event — a parsed
+ *   chunk, a debounced resize, a role change — and never per keystroke, and
+ *   none of them waits behind input.
+ * - **A grant outstanding {@link INPUT_GRANT_TIMEOUT_MS}** closes the socket
+ *   and reconnects ({@link INPUT_GRANT_TIMEOUT}): a page cannot send a ping,
+ *   so this is how it finds a dead connection while the person types.
+ * - **History is not answered** (ADR-180 D2 item 4): from a `WELCOME` or
+ *   `RESYNC` marked replay until the renderer has parsed past `REPLAY_END`,
+ *   `input` is dropped and `status.restoring` is true, so the renderer's own
+ *   replies to queries in the history never reach the process. A replay
+ *   discards input still queued: it was typed at a screen being redrawn.
+ * - **Control first** (ADR-180 D7 item 2): a viewer's first `INPUT` or
+ *   `SIGNAL` is preceded by `CONTROL {take}`.
+ *
+ * # Size
+ *
+ * `resize` is sent, debounced {@link RESIZE_DEBOUNCE_MS}, only while this
+ * view sets the size (ADR-180 D7 item 3), which control does not change. A
+ * view that does not set it renders at `status.size`, the pty's size; the
+ * page resizes its renderer to it. A view that becomes the size-setter sends
+ * its own size if the minder does not already have it.
+ *
+ * # Ending
+ *
+ * A `CLOSE` frame says what the normal closure after it does (ADR-181 D9
+ * item 2): `handover` and `reauthenticate` reconnect at once,
+ * `runner-unreachable` after backoff, and every other reason ends the view.
+ * `detach` is the page's own end: a `CLOSE {detached}`, then the socket's.
+ */
+import { routePath } from "../routes.js";
+import { StreamConnection, } from "../stream/connection.js";
+import { CloseReason, ControlAction, FrameType, MAX_DATA_PAYLOAD, Role, SUBPROTOCOL, decodeClose, decodeCount, decodeFrame, decodeResync, decodeStatus, decodeWelcome, encodeBytes, encodeClose, encodeControl, encodeCount, encodeResize, encodeSignal, } from "../terminalwire/codec.js";
+/** The `INPUT` a view sends beyond what the minder has granted back (ADR-180 D6 item 2). */
+export const INPUT_WINDOW = 64 << 10;
+/** The parsed bytes that make one `ACK`; a renderer with nothing left to parse acknowledges sooner. */
+export const ACK_EVERY = 16 << 10;
+/** How long a grant may stay outstanding before the view treats its socket as dead. */
+export const INPUT_GRANT_TIMEOUT_MS = 5_000;
+/** The close reason the view gives up on a socket with after {@link INPUT_GRANT_TIMEOUT_MS}. */
+export const INPUT_GRANT_TIMEOUT = "input_grant_timeout";
+/** How long `resize` waits for the next before the size is sent. */
+export const RESIZE_DEBOUNCE_MS = 100;
+/** The most input the view queues for credit; a paste past it is dropped. */
+export const MAX_QUEUED_INPUT = 4 << 20;
+/**
+ * The `SIGNAL`s sent between two grants: half of the 8 KiB control allowance
+ * outside the input window (ADR-180 D6 item 3), at five bytes a frame.
+ */
+export const MAX_SIGNALS_PER_GRANT = Math.floor((8 << 10) / 2 / 5);
+const realClock = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    random: () => Math.random(),
+};
+const encoder = new TextEncoder();
+const MAX_U16 = 0xffff;
+function checkSize(cols, rows) {
+    for (const v of [cols, rows]) {
+        if (!Number.isInteger(v) || v < 1 || v > MAX_U16)
+            throw new RangeError(`TerminalView: a size of ${v} cells is not from 1 to 65535`);
+    }
+    return { cols, rows };
+}
+/** A canonical lower-case UUIDv7 (RFC 9562) at `ms`, which the kit's terminal route requires of a view id. */
+export function newViewId(ms) {
+    const b = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(b);
+    let t = Math.max(0, Math.floor(ms));
+    for (let i = 5; i >= 0; i--) {
+        b[i] = t % 256;
+        t = Math.floor(t / 256);
+    }
+    b[6] = 0x70 | (b[6] & 0x0f);
+    b[8] = 0x80 | (b[8] & 0x3f);
+    const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+/** What the normal closure after a `CLOSE` frame of `reason` does (ADR-181 D11 item 2). */
+export function nextAfterClose(reason) {
+    switch (reason) {
+        case CloseReason.Handover:
+        case CloseReason.Reauthenticate:
+            return "reconnect";
+        case CloseReason.RunnerUnreachable:
+            return "backoff";
+        default:
+            return "end";
+    }
+}
+export class TerminalView {
+    viewId;
+    renderer;
+    clock;
+    onStatus;
+    conn;
+    want;
+    local;
+    // The size the minder has from this view: the connect's query or the last RESIZE.
+    sent;
+    // Every socket is one generation; a parsed callback for bytes handed over
+    // an older one acknowledges nothing.
+    gen = 0;
+    connection = { phase: "connecting", attempt: 0 };
+    welcomed = false;
+    ended = false;
+    role = Role.Viewer;
+    setsSize = false;
+    views = 0;
+    size = { cols: 0, rows: 0 };
+    controller = "";
+    sizeSetter = "";
+    handoverPending = false;
+    exit = null;
+    closeReason = null;
+    dropped = 0;
+    takeSent = false;
+    // Output: the base from the last WELCOME or RESYNC, and bytes handed since.
+    hasOffset = false;
+    base = 0;
+    handed = 0;
+    // Bytes parsed on this socket and not yet acknowledged, and writes not yet parsed.
+    unacked = 0;
+    pending = 0;
+    // Restoring: every write is numbered; history ends at the write REPLAY_END followed.
+    restoring = false;
+    writeSeq = 0;
+    parsedSeq = 0;
+    replayEndSeq = null;
+    // Input: queued chunks, the offset into the first, and the bytes queued.
+    queue = [];
+    queueHead = 0;
+    queued = 0;
+    inFlight = 0;
+    signalsSinceGrant = 0;
+    grantTimer = null;
+    resizeTimer = null;
+    /** Opens the view's socket at once. */
+    constructor(options) {
+        if (options.want !== "control" && options.want !== "view")
+            throw new TypeError(`TerminalView: want is "control" or "view"`);
+        this.local = checkSize(options.cols, options.rows);
+        this.sent = this.local;
+        this.want = options.want;
+        this.renderer = options.renderer;
+        this.clock = options.clock ?? realClock;
+        this.onStatus = options.onStatus;
+        this.viewId = newViewId(this.clock.now());
+        this.conn = new StreamConnection({
+            path: routePath("workorders", options.workOrder, "terminal"),
+            subprotocol: SUBPROTOCOL,
+            query: () => this.query(),
+            onMessage: (data) => this.message(data),
+            onState: (state) => this.connectionState(state),
+            base: options.base,
+            socket: options.socket,
+            fetch: options.fetch,
+            reSignIn: options.reSignIn,
+            clock: this.clock,
+            signals: options.signals,
+        });
+    }
+    get status() {
+        return {
+            viewId: this.viewId,
+            connection: this.connection,
+            welcomed: this.welcomed,
+            role: this.role,
+            setsSize: this.setsSize,
+            views: this.views,
+            size: { ...this.size },
+            controller: this.controller,
+            sizeSetter: this.sizeSetter,
+            handoverPending: this.handoverPending,
+            exit: this.exit,
+            restoring: this.restoring,
+            closeReason: this.closeReason,
+            dropped: this.dropped,
+        };
+    }
+    /**
+     * Sends what the person typed: what xterm.js's `onData` hands the page, a
+     * string sent as its UTF-8 bytes. A `Uint8Array` is copied, so the caller
+     * may reuse it.
+     */
+    input(data) {
+        const bytes = typeof data === "string" ? encoder.encode(data) : data.slice();
+        if (bytes.length === 0)
+            return;
+        if (this.ended || this.restoring) {
+            this.drop(bytes.length);
+            return;
+        }
+        if (bytes.length === 1 && this.ready && (this.queued > 0 || this.inFlight >= INPUT_WINDOW)) {
+            this.signal(bytes[0]);
+            return;
+        }
+        if (this.queued + bytes.length > MAX_QUEUED_INPUT) {
+            this.drop(bytes.length);
+            return;
+        }
+        this.queue.push(bytes);
+        this.queued += bytes.length;
+        this.pump();
+    }
+    /** The view's own size changed. It reaches the pty only while this view sets the size. */
+    resize(cols, rows) {
+        this.local = checkSize(cols, rows);
+        if (this.setsSize)
+            this.scheduleResize();
+    }
+    /** Asks for control now, rather than at the next keystroke. */
+    takeControl() {
+        this.want = "control";
+        this.takeSent = false;
+        if (this.ready && this.role !== Role.Controller)
+            this.sendTake();
+    }
+    /** The page's own end: tells the minder the view detached, and closes the socket. */
+    detach() {
+        if (this.ended)
+            return;
+        if (this.ready)
+            this.conn.send(encodeClose({ reason: CloseReason.Detached, reconnect: false }));
+        this.conn.close();
+    }
+    get ready() {
+        return this.welcomed && this.connection.phase === "open";
+    }
+    emit() {
+        this.onStatus?.(this.status);
+    }
+    query() {
+        const q = new URLSearchParams();
+        q.set("view", this.viewId);
+        q.set("want", this.want);
+        // A replay cut off before REPLAY_END is replayed whole, so its history
+        // is still marked as history.
+        const replayCut = this.restoring && this.replayEndSeq === null;
+        if (this.hasOffset && !replayCut)
+            q.set("resume", String(this.base + this.handed));
+        q.set("cols", String(this.local.cols));
+        q.set("rows", String(this.local.rows));
+        this.sent = this.local;
+        return q;
+    }
+    connectionState(state) {
+        this.connection = state;
+        this.gen += 1;
+        this.welcomed = false;
+        this.unacked = 0;
+        this.pending = 0;
+        this.inFlight = 0;
+        this.signalsSinceGrant = 0;
+        this.takeSent = false;
+        this.clearGrantTimer();
+        if (state.phase === "ended") {
+            this.ended = true;
+            this.clearResizeTimer();
+            this.discardQueue();
+        }
+        this.emit();
+    }
+    message(data) {
+        let f;
+        try {
+            f = decodeFrame(new Uint8Array(data));
+        }
+        catch {
+            return; // a frame the codec refuses carries nothing the view can act on
+        }
+        try {
+            this.apply(f);
+        }
+        catch {
+            // A body this version cannot read is ignored, as an unknown type is.
+        }
+    }
+    apply(f) {
+        switch (f.type) {
+            case FrameType.Welcome:
+                this.welcome(f);
+                return;
+            case FrameType.Data:
+                if (this.welcomed)
+                    this.data(f.payload);
+                return;
+            case FrameType.Resync: {
+                if (!this.welcomed)
+                    return;
+                const r = decodeResync(f);
+                this.base = r.offset;
+                this.handed = 0;
+                if (r.replay)
+                    this.startRestoring();
+                return;
+            }
+            case FrameType.ReplayEnd:
+                if (this.welcomed && this.restoring) {
+                    this.replayEndSeq = this.writeSeq;
+                    this.restored();
+                }
+                return;
+            case FrameType.InputAck:
+                if (this.welcomed)
+                    this.granted(decodeCount(f));
+                return;
+            case FrameType.Status:
+                if (this.welcomed)
+                    this.statusFrame(f);
+                return;
+            case FrameType.Close: {
+                const c = decodeClose(f);
+                this.closeReason = c.reason;
+                this.conn.onNormalClose(nextAfterClose(c.reason));
+                this.emit();
+                return;
+            }
+        }
+        // A frame type this version does not know, or one a client never receives, is ignored.
+    }
+    welcome(f) {
+        const w = decodeWelcome(f);
+        this.welcomed = true;
+        this.hasOffset = true;
+        this.base = w.offset;
+        this.handed = 0;
+        this.role = w.role;
+        this.setsSize = w.setsSize;
+        this.size = w.size;
+        this.views = w.views;
+        this.closeReason = null;
+        this.takeSent = false;
+        this.want = w.role === Role.Controller ? "control" : this.want;
+        if (w.replay)
+            this.startRestoring();
+        this.emit();
+        if (this.want === "control" && this.role !== Role.Controller)
+            this.sendTake();
+        if (this.setsSize)
+            this.scheduleResize();
+        this.pump();
+    }
+    statusFrame(f) {
+        const s = decodeStatus(f);
+        const wasController = this.role === Role.Controller;
+        this.role = s.role;
+        this.views = s.views;
+        this.size = s.size;
+        this.controller = s.controller;
+        this.sizeSetter = s.sizeSetter;
+        this.setsSize = s.sizeSetter === this.viewId;
+        this.handoverPending = s.handoverPending;
+        if (s.exited)
+            this.exit = { status: s.exitStatus, signal: s.exitSignal };
+        if (s.role === Role.Controller)
+            this.want = "control";
+        else {
+            // Control moved to another device: a reconnect does not take it back,
+            // and the next keystroke here takes it again.
+            if (wasController)
+                this.want = "view";
+            this.takeSent = false;
+        }
+        this.emit();
+        if (this.setsSize)
+            this.scheduleResize();
+    }
+    data(payload) {
+        if (payload.length === 0)
+            return;
+        const gen = this.gen;
+        const n = payload.length;
+        const seq = ++this.writeSeq;
+        this.handed += n;
+        this.pending += 1;
+        let done = false;
+        this.renderer.write(payload, () => {
+            if (done)
+                return;
+            done = true;
+            this.parsed(gen, n, seq);
+        });
+    }
+    parsed(gen, n, seq) {
+        this.parsedSeq = seq;
+        if (this.restoring)
+            this.restored();
+        if (gen !== this.gen)
+            return;
+        this.pending -= 1;
+        this.unacked += n;
+        if (this.unacked >= ACK_EVERY || this.pending === 0) {
+            const count = this.unacked;
+            this.unacked = 0;
+            this.conn.send(encodeCount(FrameType.Ack, count));
+        }
+    }
+    startRestoring() {
+        this.restoring = true;
+        this.replayEndSeq = null;
+        this.discardQueue();
+        this.emit();
+    }
+    /** Ends the restoring once the renderer has parsed every write before REPLAY_END. */
+    restored() {
+        if (this.replayEndSeq === null || this.parsedSeq < this.replayEndSeq)
+            return;
+        this.restoring = false;
+        this.replayEndSeq = null;
+        this.emit();
+    }
+    granted(n) {
+        this.inFlight = Math.max(0, this.inFlight - n);
+        if (n > 0) {
+            this.signalsSinceGrant = 0;
+            this.clearGrantTimer();
+        }
+        this.pump();
+        this.armGrantTimer();
+    }
+    /** Sends queued input as far as the window allows. */
+    pump() {
+        while (this.ready && this.queued > 0 && this.inFlight < INPUT_WINDOW) {
+            if (this.role !== Role.Controller && !this.takeSent)
+                this.sendTake();
+            const head = this.queue[0];
+            const n = Math.min(head.length - this.queueHead, MAX_DATA_PAYLOAD, INPUT_WINDOW - this.inFlight);
+            if (!this.conn.send(encodeBytes(FrameType.Input, head.subarray(this.queueHead, this.queueHead + n))))
+                return;
+            this.inFlight += n;
+            this.queued -= n;
+            this.queueHead += n;
+            if (this.queueHead === head.length) {
+                this.queue.shift();
+                this.queueHead = 0;
+            }
+        }
+        this.armGrantTimer();
+    }
+    signal(char) {
+        if (this.signalsSinceGrant >= MAX_SIGNALS_PER_GRANT) {
+            this.drop(1);
+            return;
+        }
+        if (this.role !== Role.Controller && !this.takeSent)
+            this.sendTake();
+        if (this.conn.send(encodeSignal(char)))
+            this.signalsSinceGrant += 1;
+    }
+    sendTake() {
+        this.want = "control";
+        if (this.conn.send(encodeControl({ action: ControlAction.Take })))
+            this.takeSent = true;
+    }
+    drop(n) {
+        this.dropped += n;
+        this.emit();
+    }
+    discardQueue() {
+        if (this.queued === 0)
+            return;
+        this.dropped += this.queued;
+        this.queue.length = 0;
+        this.queueHead = 0;
+        this.queued = 0;
+    }
+    armGrantTimer() {
+        if (this.inFlight === 0) {
+            this.clearGrantTimer();
+            return;
+        }
+        if (this.grantTimer !== null)
+            return;
+        this.grantTimer = this.clock.setTimeout(() => {
+            this.grantTimer = null;
+            this.conn.reconnect(INPUT_GRANT_TIMEOUT);
+        }, INPUT_GRANT_TIMEOUT_MS);
+    }
+    clearGrantTimer() {
+        if (this.grantTimer !== null)
+            this.clock.clearTimeout(this.grantTimer);
+        this.grantTimer = null;
+    }
+    scheduleResize() {
+        this.clearResizeTimer();
+        this.resizeTimer = this.clock.setTimeout(() => {
+            this.resizeTimer = null;
+            if (!this.ready || !this.setsSize)
+                return;
+            if (this.local.cols === this.sent.cols && this.local.rows === this.sent.rows)
+                return;
+            if (this.conn.send(encodeResize(this.local)))
+                this.sent = this.local;
+        }, RESIZE_DEBOUNCE_MS);
+    }
+    clearResizeTimer() {
+        if (this.resizeTimer !== null)
+            this.clock.clearTimeout(this.resizeTimer);
+        this.resizeTimer = null;
+    }
+}