import { DRAIN_WAIT_MS, REPLY_WAIT_MS, SIGNAL_END_WAIT_MS } from "../model/deadlines.ts"; import type { ColorDepth, Host, HostEnd, HostSize, ProbeResult } from "./index.ts"; import { DISPLAY_QUERY, emptyProbe, PROBE_QUERY, ReplyFilter, withReply } from "./probe.ts"; /** * What `enter` turns on, in order, after raw mode: the alternate screen, the cursor hidden, focus * reports, bracketed paste, mouse 1002 with SGR 1006, and one kitty keyboard entry with flag 1. * LEAVE undoes exactly these in reverse; raw mode goes last. */ const ENTER = "\x1b[?1049h\x1b[?25l\x1b[?1004h\x1b[?2004h\x1b[?1002h\x1b[?1006h\x1b[>1u"; export const LEAVE = "\x1b[ void): void; /** hands what is already read (and not yet delivered) to the sink, at once */ readNow(): void; stopReading(): void; timer(ms: number, fire: () => void): () => void; /** the clock the timers run on, in ms */ now(): number; /** installs the hooks; returns their removal */ hook(hooks: HostHooks): () => void; exit(code: number): void; } /** EIO and EPIPE: the terminal is gone; EAGAIN reaches here only once the port gave up waiting for it. */ const isGone = (error: unknown) => { const code = (error as { code?: unknown } | null)?.code; return code === "EIO" || code === "EPIPE" || code === "EAGAIN"; }; /** * The one implementation of the `Host` rules over a port: every mode undone once, in reverse order, * on leave, exit and signal; the probe's replies kept inside; gone reported once. */ export function guardedHost(port: TerminalPort): Host { const encoder = new TextEncoder(); const inputs = new Set<(bytes: Uint8Array) => void>(); const resizes = new Set<(size: HostSize) => void>(); const ends = new Set<(end: HostEnd) => void | Promise>(); const colorDepth: ColorDepth = port.colorTerm === "truecolor" || port.colorTerm === "24bit" ? "truecolor" : "256"; let state: "idle" | "entered" | "left" = "idle"; let rawOn = false; let modesOn = false; let watchingDisplay = false; let gone = false; let ending = false; let entering = false; let deferred: HostSignal | null = null; let unhook: (() => void) | null = null; const filter = new ReplyFilter(); let phase: "none" | "probing" | "late" | "done" = "none"; let probeResult = emptyProbe(); let probePromise: Promise | null = null; let settleProbe: ((result: ProbeResult) => void) | null = null; let cancelProbeTimer: (() => void) | null = null; let cancelHoldTimer: (() => void) | null = null; let focusTail: Uint8Array = new Uint8Array(0); let drainState: { chunks: Uint8Array[]; cancel: () => void; resolve: (bytes: Uint8Array) => void } | null = null; let drainPromise: Promise | null = null; const reportGone = (why: "hangup" | "write-failed") => { if (gone) return []; gone = true; return [...ends].map((listener) => listener({ kind: "gone", why })); }; /** One write to the terminal; false when it is gone (reported here, once). */ const send = (bytes: Uint8Array): boolean => { if (gone) return false; try { port.write(bytes); return true; } catch (error) { if (!isGone(error)) throw error; reportGone("write-failed"); return false; } }; const finishProbe = (answered: boolean) => { if (phase !== "probing") return; cancelProbeTimer?.(); cancelProbeTimer = null; phase = answered ? "done" : "late"; settleProbe?.(probeResult); settleProbe = null; }; const finishDrain = () => { if (!drainState) return; const { chunks, cancel, resolve } = drainState; drainState = null; cancel(); const out = new Uint8Array(chunks.reduce((sum, chunk) => sum + chunk.length, 0)); let at = 0; for (const chunk of chunks) { out.set(chunk, at); at += chunk.length; } drainPromise = null; resolve(out); }; const modesAgain = () => { if (state === "entered" && !ending) send(encoder.encode(MODES_AGAIN)); }; const resized = () => { if (state !== "entered" || ending) return; modesAgain(); const size = port.size(); for (const listener of resizes) listener(size); }; /** A focus-in report anywhere in the input, one split across two reads included. */ const sawFocusIn = (input: Uint8Array): boolean => { const joined = Buffer.concat([focusTail, input]); const found = joined.includes(FOCUS_IN); focusTail = found ? new Uint8Array(0) : joined.subarray(-2).slice(); return found; }; /** Input bytes, in order: to a drain while one runs, else to the listeners (after a focus-in, the modes again). */ const deliver = (input: Uint8Array) => { if (drainState) { drainState.chunks.push(input); drainState.cancel(); drainState.cancel = port.timer(DRAIN_WAIT_MS, finishDrain); return; } if (input.length === 0) return; if (sawFocusIn(input)) modesAgain(); for (const listener of inputs) listener(input); }; /** One timer for the sequence the filter holds: when its wait ends, it goes out whole. */ const armHold = () => { cancelHoldTimer?.(); cancelHoldTimer = null; const due = filter.deadline(); if (due === undefined) return; cancelHoldTimer = port.timer(Math.max(0, due - port.now()), () => { cancelHoldTimer = null; if (state !== "entered") return; deliver(filter.expire(port.now())); armHold(); }); }; const take = (chunk: Uint8Array) => { if (state !== "entered") return; if (phase !== "probing" && phase !== "late") { deliver(chunk); return; } const taken = filter.feed(chunk, port.now(), phase === "late" && watchingDisplay); if (phase === "probing") for (const reply of taken.replies) probeResult = withReply(probeResult, reply); if (taken.rest) { if (phase === "probing") finishProbe(true); phase = "done"; deliver(Buffer.concat([taken.input, taken.rest])); } else deliver(taken.input); armHold(); }; const leave = () => { if (state !== "entered") return; state = "left"; port.stopReading(); cancelHoldTimer?.(); cancelHoldTimer = null; finishProbe(false); finishDrain(); // a write error that is not gone is thrown once the terminal is given back, never before let failed: { error: unknown } | null = null; if (modesOn) { try { send(encoder.encode(watchingDisplay ? `\x1b[?2031l${LEAVE}` : LEAVE)); } catch (error) { failed = { error }; } } modesOn = false; if (rawOn) { rawOn = false; try { port.setRaw(false); } catch { /* the terminal is gone: nothing left to restore */ } } // after a signal the hooks stay until the process ends, so a second signal finds the restore done if (!ending) { unhook?.(); unhook = null; } if (failed) throw failed.error; }; const onSignal = (name: HostSignal) => { if (entering) { deferred ??= name; return; } if (ending) return; ending = true; // the signal decides the end: a leave write that failed changes neither the restore nor the exit code try { leave(); } catch { /* given back all the same: leave throws only after the restore */ } const pending = name === "SIGHUP" ? reportGone("hangup") : [...ends].map((listener) => listener({ kind: "signal", signal: name })); gone = true; const code = 128 + SIGNAL_NUMBERS[name]; const waits = pending.filter((value): value is Promise => value instanceof Promise); if (waits.length === 0) { port.exit(code); return; } let exited = false; const exit = () => { if (!exited) { exited = true; cancel(); port.exit(code); } }; const cancel = port.timer(SIGNAL_END_WAIT_MS, exit); void Promise.allSettled(waits).then(exit); }; return { colorDepth, enter() { if (state === "entered") return true; if (state === "left" || !port.isTerminal) return false; entering = true; try { unhook = port.hook({ signal: onSignal, exit: leave, resize: resized }); state = "entered"; port.setRaw(true); rawOn = true; modesOn = true; send(encoder.encode(ENTER)); port.startReading(take); } catch (error) { entering = false; // the first error is the one enter reports; one the restore meets after it is not try { leave(); } catch { /* given back all the same: leave throws only after the restore */ } throw error; } entering = false; if (deferred) onSignal(deferred); return true; }, leave, size: () => port.size(), onInput(listener) { inputs.add(listener); return () => { inputs.delete(listener); }; }, onResize(listener) { resizes.add(listener); return () => { resizes.delete(listener); }; }, onEnd(listener) { ends.add(listener); return () => { ends.delete(listener); }; }, write(data) { if (state !== "entered") return false; return send(typeof data === "string" ? encoder.encode(data) : data); }, probe() { if (probePromise) return probePromise; if (state !== "entered" || gone) { probePromise = Promise.resolve(emptyProbe()); return probePromise; } probePromise = new Promise((resolve) => { settleProbe = resolve; }); phase = "probing"; let sent = false; try { sent = send(encoder.encode(PROBE_QUERY)); } finally { // a query that was not written, gone or thrown, ends the probe now: a later call gets that answer if (!sent) finishProbe(false); } if (phase === "probing") cancelProbeTimer = port.timer(REPLY_WAIT_MS, () => finishProbe(false)); return probePromise; }, watchDisplay() { if (state !== "entered" || watchingDisplay) return; watchingDisplay = true; send(encoder.encode("\x1b[?2031h")); }, refreshDisplay() { if (state === "entered") send(encoder.encode(DISPLAY_QUERY)); }, drain() { if (drainPromise) return drainPromise; if (state !== "entered") return Promise.resolve(new Uint8Array(0)); drainPromise = new Promise((resolve) => { drainState = { chunks: [], cancel: port.timer(DRAIN_WAIT_MS, finishDrain), resolve }; }); port.readNow(); return drainPromise; }, }; }