@slopus/ghostty-web 0.1.0

package/dist/RemoteTerminalProtocolClient.js

@@ -0,0 +1,350 @@
+import { applyGridPatch } from "./applyGridPatch.js";
+import { encodeWirePacket } from "./encodeWirePacket.js";
+import { decodeJsonPayload, encodeJsonPayload } from "./jsonPayload.js";
+import { WirePacketDecoder } from "./WirePacketDecoder.js";
+import { WirePacketType } from "./WirePacket.js";
+export class RemoteTerminalProtocolClient {
+    appliedOutputOffset;
+    epoch;
+    grid;
+    inputLease;
+    mode;
+    ready;
+    #decoder = new WirePacketDecoder();
+    #inputSequence;
+    #lastInputAck = 0;
+    #options;
+    #operation = Promise.resolve();
+    #pendingInputs = new Map();
+    #pendingResizes = new Map();
+    #pendingScrollback = new Map();
+    #readySettled = false;
+    #rejectReady;
+    #resizeSequence = 0;
+    #resolveReady;
+    #scrollbackSequence = 0;
+    #stream;
+    constructor(options) {
+        validateClientOptions(options);
+        this.#options = options;
+        this.#stream = options.stream;
+        this.epoch = options.epoch;
+        this.inputLease = options.inputLease;
+        this.appliedOutputOffset = options.resumeOutputOffset ?? 0;
+        this.#inputSequence = options.resumeInputSequence ?? 0;
+        for (const pending of options.pendingInputs ?? []) {
+            if (!Number.isSafeInteger(pending.sequence) ||
+                pending.sequence < 1 ||
+                pending.sequence > this.#inputSequence)
+                throw new Error("Invalid pending input sequence.");
+            this.#pendingInputs.set(pending.sequence, Buffer.from(pending.data));
+        }
+        this.ready = new Promise((resolve, reject) => {
+            this.#resolveReady = resolve;
+            this.#rejectReady = reject;
+        });
+        options.stream.on("data", (data) => {
+            try {
+                const packets = this.#decoder.push(data);
+                if (packets.length > 0)
+                    options.stream.pause();
+                for (const packet of packets)
+                    this.#operation = this.#operation.then(() => this.#receive(packet));
+                void this.#operation
+                    .then(() => {
+                    if (!options.stream.destroyed)
+                        options.stream.resume();
+                })
+                    .catch((error) => options.stream.destroy(error));
+            }
+            catch (error) {
+                options.stream.destroy(error);
+            }
+        });
+        options.stream.once("error", (error) => this.#settleClosed(error));
+        options.stream.once("close", () => this.#settleClosed(new Error("Remote terminal connection closed.")));
+        this.#send({
+            payload: encodeJsonPayload({
+                capabilities: options.capabilities ?? { grid: true, vt: true },
+                clientId: options.clientId,
+                creditBytes: options.creditBytes ?? 256 * 1024,
+                ...(options.epoch === undefined ? {} : { epoch: options.epoch }),
+                ...(options.inputLease === undefined ? {} : { inputLease: options.inputLease }),
+                resumeOutputOffset: this.appliedOutputOffset,
+                parserFingerprint: options.parserFingerprint ?? "libghostty-vt/0.2/defaults",
+            }),
+            sequence: this.appliedOutputOffset,
+            type: WirePacketType.ClientHello,
+        });
+    }
+    close() {
+        this.#stream.destroy();
+    }
+    reconnectState() {
+        return {
+            epoch: this.epoch,
+            inputLease: this.inputLease,
+            pendingInputs: [...this.#pendingInputs].map(([sequence, data]) => ({
+                data: Buffer.from(data),
+                sequence,
+            })),
+            resumeInputSequence: this.#inputSequence,
+            resumeOutputOffset: this.appliedOutputOffset,
+        };
+    }
+    requestScrollback(start, count, basis) {
+        if (!Number.isSafeInteger(start) ||
+            start < 0 ||
+            !Number.isSafeInteger(count) ||
+            count < 1 ||
+            count > 1_000 ||
+            this.#pendingScrollback.size >= 128) {
+            return Promise.reject(new Error("Invalid scrollback request."));
+        }
+        const sequence = ++this.#scrollbackSequence;
+        return new Promise((resolve, reject) => {
+            this.#pendingScrollback.set(sequence, { reject, resolve });
+            this.#send({
+                payload: encodeJsonPayload({
+                    ...(basis === undefined ? {} : { basis }),
+                    count,
+                    start,
+                }),
+                sequence,
+                type: WirePacketType.ScrollbackRequest,
+            });
+        });
+    }
+    resize(cols, rows) {
+        validateDimensions(cols, rows);
+        if (this.#pendingResizes.size >= 32)
+            return Promise.reject(new Error("Too many pending terminal resizes."));
+        const sequence = ++this.#resizeSequence;
+        return new Promise((resolve, reject) => {
+            this.#pendingResizes.set(sequence, { reject, resolve });
+            this.#send({
+                payload: encodeJsonPayload({ cols, rows }),
+                sequence,
+                type: WirePacketType.Resize,
+            });
+        });
+    }
+    writeInput(data) {
+        const bytes = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);
+        if (bytes.length > 64 * 1024)
+            throw new Error("Terminal input is too large.");
+        if (this.#pendingInputs.size >= 1_024)
+            throw new Error("Too many unacknowledged terminal inputs.");
+        this.#inputSequence += 1;
+        this.#pendingInputs.set(this.#inputSequence, bytes);
+        this.#send({ payload: bytes, sequence: this.#inputSequence, type: WirePacketType.Input });
+        return this.#inputSequence;
+    }
+    #send(packet) {
+        if (this.#stream.destroyed)
+            throw new Error("Remote terminal connection is closed.");
+        this.#stream.write(encodeWirePacket(packet).data);
+    }
+    async #receive(packet) {
+        if (packet.type === WirePacketType.Error) {
+            const value = decodeJsonPayload(packet.payload);
+            throw new Error(value.error);
+        }
+        if (packet.type === WirePacketType.Welcome) {
+            if (this.#readySettled)
+                throw new Error("Duplicate server welcome.");
+            const welcome = decodeJsonPayload(packet.payload);
+            validateWelcome(welcome);
+            if (this.epoch !== undefined && this.epoch !== welcome.epoch)
+                this.appliedOutputOffset = 0;
+            this.epoch = welcome.epoch;
+            this.inputLease = welcome.inputLease;
+            this.mode = welcome.mode;
+            this.#options.onMode?.(welcome.mode);
+            await this.#options.replica.resize(welcome.cols, welcome.rows);
+            this.#send({
+                payload: Buffer.alloc(0),
+                sequence: welcome.resizeRevision,
+                type: WirePacketType.ResizeApplied,
+            });
+            for (const [sequence, data] of this.#pendingInputs) {
+                if (sequence > welcome.inputSequence)
+                    this.#send({ payload: data, sequence, type: WirePacketType.Input });
+                else
+                    this.#pendingInputs.delete(sequence);
+            }
+            this.#lastInputAck = welcome.inputSequence;
+            this.#readySettled = true;
+            this.#resolveReady();
+            return;
+        }
+        if (!this.#readySettled)
+            throw new Error("Server welcome is required.");
+        if (packet.type === WirePacketType.Output) {
+            if (this.mode !== "vt")
+                throw new Error("VT output received outside VT mode.");
+            const start = packet.sequence - packet.payload.length;
+            if (packet.sequence <= this.appliedOutputOffset)
+                return;
+            if (start !== this.appliedOutputOffset) {
+                this.#send({ payload: Buffer.alloc(0), sequence: 0, type: WirePacketType.Resync });
+                return;
+            }
+            await this.#options.replica.applyVt(packet.payload);
+            this.appliedOutputOffset = packet.sequence;
+            this.#send({
+                payload: Buffer.alloc(0),
+                sequence: this.appliedOutputOffset,
+                type: WirePacketType.OutputAck,
+            });
+            return;
+        }
+        if (packet.type === WirePacketType.Mode) {
+            const value = decodeJsonPayload(packet.payload);
+            if (value.mode !== "grid")
+                throw new Error("Invalid terminal mode transition.");
+            this.mode = value.mode;
+            this.#options.onMode?.(value.mode);
+            return;
+        }
+        if (packet.type === WirePacketType.GridKeyframe) {
+            const grid = decodeJsonPayload(packet.payload);
+            validateGrid(grid);
+            this.grid = grid;
+            this.mode = "grid";
+            await this.#options.replica.applyGrid(grid);
+            this.#send({
+                payload: Buffer.alloc(0),
+                sequence: grid.revision,
+                type: WirePacketType.GridAck,
+            });
+            return;
+        }
+        if (packet.type === WirePacketType.GridPatch) {
+            const patch = decodeJsonPayload(packet.payload);
+            if (this.grid === undefined || this.grid.revision !== patch.baseRevision) {
+                this.#send({ payload: Buffer.alloc(0), sequence: 0, type: WirePacketType.Resync });
+                return;
+            }
+            this.grid = applyGridPatch(this.grid, patch);
+            validateGrid(this.grid);
+            await this.#options.replica.applyGrid(this.grid);
+            this.#send({
+                payload: Buffer.alloc(0),
+                sequence: this.grid.revision,
+                type: WirePacketType.GridAck,
+            });
+            return;
+        }
+        if (packet.type === WirePacketType.InputAck) {
+            if (packet.payload.length !== 0 ||
+                packet.sequence < this.#lastInputAck ||
+                packet.sequence > this.#inputSequence)
+                throw new Error("Invalid input acknowledgement.");
+            this.#lastInputAck = packet.sequence;
+            for (const sequence of this.#pendingInputs.keys())
+                if (sequence <= packet.sequence)
+                    this.#pendingInputs.delete(sequence);
+            return;
+        }
+        if (packet.type === WirePacketType.ResizeAck) {
+            const value = decodeJsonPayload(packet.payload);
+            validateDimensions(value.cols, value.rows);
+            if (!Number.isSafeInteger(value.barrier) ||
+                value.barrier < 0 ||
+                (this.mode === "vt" && this.appliedOutputOffset !== value.barrier))
+                throw new Error("Resize output barrier mismatch.");
+            await this.#options.replica.resize(value.cols, value.rows);
+            this.#send({
+                payload: Buffer.alloc(0),
+                sequence: value.resizeRevision,
+                type: WirePacketType.ResizeApplied,
+            });
+            if (value.requestSequence > 0) {
+                const pending = this.#pendingResizes.get(value.requestSequence);
+                if (pending === undefined)
+                    throw new Error("Unknown resize acknowledgement.");
+                this.#pendingResizes.delete(value.requestSequence);
+                pending.resolve();
+            }
+            return;
+        }
+        if (packet.type === WirePacketType.ScrollbackPage) {
+            const pending = this.#pendingScrollback.get(packet.sequence);
+            if (pending === undefined)
+                throw new Error("Unknown scrollback response.");
+            this.#pendingScrollback.delete(packet.sequence);
+            pending.resolve(decodeJsonPayload(packet.payload));
+            return;
+        }
+        if (packet.type === WirePacketType.Exit) {
+            const value = decodeJsonPayload(packet.payload);
+            if (this.mode === "vt" && this.appliedOutputOffset !== value.outputOffset)
+                throw new Error("Exit output barrier mismatch.");
+            if (this.mode === "grid" && (this.grid?.coversOutputOffset ?? -1) < value.outputOffset)
+                throw new Error("Exit grid barrier mismatch.");
+            this.#options.onExit?.(value.exitCode);
+            return;
+        }
+        throw new Error("Packet is invalid in the current client state.");
+    }
+    #settleClosed(error) {
+        if (!this.#readySettled) {
+            this.#readySettled = true;
+            this.#rejectReady(error);
+        }
+        for (const pending of this.#pendingResizes.values())
+            pending.reject(error);
+        for (const pending of this.#pendingScrollback.values())
+            pending.reject(error);
+        this.#pendingResizes.clear();
+        this.#pendingScrollback.clear();
+    }
+}
+function validateClientOptions(options) {
+    if (typeof options.clientId !== "string" ||
+        options.clientId.length < 1 ||
+        options.clientId.length > 128)
+        throw new Error("Invalid client identifier.");
+    const credit = options.creditBytes ?? 256 * 1024;
+    if (!Number.isSafeInteger(credit) || credit < 1 || credit > 64 * 1024 * 1024)
+        throw new Error("Invalid client credit.");
+}
+function validateDimensions(cols, rows) {
+    if (!Number.isSafeInteger(cols) ||
+        cols < 1 ||
+        cols > 1_000 ||
+        !Number.isSafeInteger(rows) ||
+        rows < 1 ||
+        rows > 1_000)
+        throw new Error("Invalid terminal dimensions.");
+}
+function validateWelcome(value) {
+    validateDimensions(value.cols, value.rows);
+    if (typeof value.epoch !== "string" ||
+        value.epoch.length < 1 ||
+        value.epoch.length > 128 ||
+        typeof value.inputLease !== "string" ||
+        value.inputLease.length < 1 ||
+        value.inputLease.length > 128 ||
+        !Number.isSafeInteger(value.inputSequence) ||
+        value.inputSequence < 0 ||
+        !Number.isSafeInteger(value.resizeRevision) ||
+        value.resizeRevision < 0 ||
+        (value.mode !== "vt" && value.mode !== "grid"))
+        throw new Error("Invalid server welcome.");
+}
+function validateGrid(grid) {
+    if (!Number.isSafeInteger(grid.revision) ||
+        grid.revision < 1 ||
+        !Number.isSafeInteger(grid.coversOutputOffset) ||
+        grid.coversOutputOffset < 0 ||
+        !Number.isSafeInteger(grid.cols) ||
+        grid.cols < 1 ||
+        grid.cols > 1_000 ||
+        !Array.isArray(grid.rows) ||
+        grid.rows.length > 1_000 ||
+        !Array.isArray(grid.styles) ||
+        grid.styles.length > 4_096)
+        throw new Error("Invalid terminal grid.");
+}

package/dist/RemoteTerminalProtocolServer.d.ts

@@ -0,0 +1,75 @@
+import type { Duplex } from "node:stream";
+import type { RemoteTerminalGridState, RemoteTerminalProtocolMetrics, RemoteTerminalServerOptions } from "./types.js";
+import { type WirePacket } from "./WirePacket.js";
+interface EncodedPacket {
+    data: Buffer;
+}
+interface OutputChunk {
+    data: Buffer;
+    encoded: EncodedPacket;
+    end: number;
+    start: number;
+}
+interface ExitState {
+    exitCode: number | null;
+    outputOffset: number;
+}
+export declare class RemoteTerminalProtocolServer {
+    #private;
+    readonly epoch: string;
+    readonly metrics: RemoteTerminalProtocolMetrics;
+    constructor(options: RemoteTerminalServerOptions);
+    attach(stream: Duplex): () => void;
+    publishExit(exitCode: number | null): void;
+    publishGrid(state: Omit<RemoteTerminalGridState, "revision">): void;
+    publishOutput(data: Uint8Array): void;
+    /** Parse output into the canonical emulator first, then publish bytes and its matching grid atomically. */
+    publishUpdate(data: Uint8Array, state: Omit<RemoteTerminalGridState, "coversOutputOffset" | "revision">): void;
+    claimInputLease(requested: string | undefined, connection: ServerConnection): {
+        outputOffset: number;
+        resizeRevision: number;
+        sequence: number;
+        token: string;
+    };
+    releaseInputLease(connection: ServerConnection): void;
+    receiveInput(token: string, sequence: number, data: Uint8Array): Promise<void>;
+    acknowledgeOutput(token: string, outputOffset: number): void;
+    acknowledgeResize(token: string, revision: number): void;
+    requestResize(requester: ServerConnection | undefined, requestSequence: number, cols: number, rows: number): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    scrollback(start: number, count: number, basis?: {
+        historyEpoch: string;
+        historyRevision: number;
+    }): import("./types.js").RemoteTerminalScrollbackPage | Promise<import("./types.js").RemoteTerminalScrollbackPage>;
+    setFlowPaused(connection: ServerConnection, paused: boolean): void;
+    encode(packet: WirePacket): EncodedPacket;
+    gridPacket(grid: RemoteTerminalGridState): EncodedPacket;
+    dimensions(): {
+        cols: number;
+        rows: number;
+    };
+    maxBufferedBytes(): number;
+    exitState(): ExitState | undefined;
+    grid(): RemoteTerminalGridState | undefined;
+    lastResizeBarrier(): number;
+    maxUnacknowledgedBytes(): number;
+    parserFingerprint(): string;
+    oldestOutputOffset(): number;
+    outputOffset(): number;
+    resizeRevision(): number;
+    replayAfter(offset: number): readonly OutputChunk[];
+    wireChunkBytes(): number;
+    fail(error: unknown): void;
+}
+declare class ServerConnection {
+    #private;
+    constructor(server: RemoteTerminalProtocolServer, stream: Duplex, maxFrameBytes?: number);
+    close(): void;
+    fail(error: unknown): void;
+    publishGrid(previous: RemoteTerminalGridState | undefined, next: RemoteTerminalGridState): void;
+    publishOutput(chunk: OutputChunk): void;
+    sendResize(cols: number, rows: number, barrier: number, resizeRevision: number, requestSequence: number): void;
+    maybeSendExit(): void;
+}
+export {};
+//# sourceMappingURL=RemoteTerminalProtocolServer.d.ts.map

package/dist/RemoteTerminalProtocolServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteTerminalProtocolServer.d.ts","sourceRoot":"","sources":["../sources/RemoteTerminalProtocolServer.ts"],"names":[],"mappings":"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"}