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

package/dist/terminalwire/codec.d.ts

@@ -0,0 +1,176 @@
+/** The protocol version this codec speaks. */
+export declare const VERSION = 1;
+/** The WebSocket subprotocol a view negotiates. */
+export declare const SUBPROTOCOL = "tera.terminalwire.v1";
+export declare const HEADER_SIZE = 4;
+/** The bound on a DATA or INPUT payload: the runner link's stream frame. */
+export declare const MAX_DATA_PAYLOAD: number;
+/** The bound on a CBOR control body. */
+export declare const MAX_CONTROL_PAYLOAD: number;
+/** The bound on any frame's payload, a type this version does not know included. */
+export declare const MAX_PAYLOAD: number;
+/** The largest frame, and so the largest message, on the wire. */
+export declare const MAX_FRAME_BYTES: number;
+/**
+ * The bound on an output offset, 2^53-1: every offset the wire admits is a
+ * number held exactly. An encoder refuses one above it and a decoder reads a
+ * body carrying one as malformed, as the Go codec does.
+ */
+export declare const MAX_OFFSET: number;
+/**
+ * The frame types of version 1. Zero is no frame; a value is never reassigned.
+ * SIGNAL carries one keystroke's character outside the input window; its
+ * contract is sdk/terminalwire's `TypeSignal` (`encodeSignal`).
+ */
+export declare const FrameType: {
+    readonly Welcome: 1;
+    readonly Data: 2;
+    readonly Resync: 3;
+    readonly ReplayEnd: 4;
+    readonly InputAck: 5;
+    readonly Status: 6;
+    readonly Close: 7;
+    readonly Input: 8;
+    readonly Ack: 9;
+    readonly Resize: 10;
+    readonly Control: 11;
+    readonly Signal: 12;
+};
+export type FrameType = (typeof FrameType)[keyof typeof FrameType];
+/** Whether this version knows frame type `t`. A receiver ignores a frame it does not. */
+export declare function isKnownFrameType(t: number): t is FrameType;
+/** The wire name of a frame type: `WELCOME`, `DATA`, …; `FrameType(42)` for one this version does not know. */
+export declare function frameTypeName(t: number): string;
+/** Why a frame was refused, by the corpus's classes, beside the encoder's own. */
+export type TerminalwireErrorKind = "truncated" | "too_large" | "malformed" | "wrong_type" | "not_in_vocabulary";
+export declare class TerminalwireError extends Error {
+    readonly kind: TerminalwireErrorKind;
+    constructor(kind: TerminalwireErrorKind, message: string);
+}
+/** One frame. `payload` is a view of the buffer the frame was read from. */
+export interface Frame {
+    readonly type: number;
+    readonly payload: Uint8Array;
+}
+/** A terminal's size in cells. */
+export interface Size {
+    cols: number;
+    rows: number;
+}
+/** A view's part in its session (ADR-180 D7). */
+export declare const Role: {
+    readonly Controller: "controller";
+    readonly Viewer: "viewer";
+};
+export type Role = (typeof Role)[keyof typeof Role];
+/** Why a view ended, from a closed set (ADR-180 D4). */
+export declare const CloseReason: {
+    readonly Detached: "detached";
+    readonly Exited: "exited";
+    readonly Handover: "handover";
+    readonly Reauthenticate: "reauthenticate";
+    readonly NotAttendee: "not-attendee";
+    readonly Superseded: "superseded";
+    readonly RunnerUnreachable: "runner-unreachable";
+    readonly FlowControl: "flow-control";
+    readonly Expired: "expired";
+};
+export type CloseReason = (typeof CloseReason)[keyof typeof CloseReason];
+/** What a CONTROL frame asks (ADR-180 D7). */
+export declare const ControlAction: {
+    readonly Take: "take";
+    readonly Release: "release";
+};
+export type ControlAction = (typeof ControlAction)[keyof typeof ControlAction];
+/** Opens a view, minder → client. */
+export interface Welcome {
+    /** The minder's protocol version; a client sends nothing it lacks. */
+    version: number;
+    /** The view's id, the client's, kept across reconnects. */
+    viewId: string;
+    role: Role;
+    /** Whether this view's RESIZE sizes the pty. */
+    setsSize: boolean;
+    /** The pty's size. */
+    size: Size;
+    /** The output offset the following DATA starts at, at most MAX_OFFSET. */
+    offset: number;
+    /** Whether the DATA that follows is history, ended by REPLAY_END. */
+    replay: boolean;
+    /** How many views the session has, this one included. */
+    views: number;
+}
+/** Moves a view's base offset after its cursor fell out of the ring. */
+export interface Resync {
+    offset: number;
+    replay: boolean;
+}
+/** The session's state, minder → client. */
+export interface Status {
+    /** The receiving view's part. */
+    role: Role;
+    views: number;
+    /** The pty's size, which a view that does not set the size renders at. */
+    size: Size;
+    /** The controlling view's id; empty when none controls. */
+    controller: string;
+    /** The id of the view whose RESIZE sizes the pty. */
+    sizeSetter: string;
+    /** A handover is waiting for the session to go quiet. */
+    handoverPending: boolean;
+    /** The process exited, with its status and, when a signal ended it, the signal's name. */
+    exited: boolean;
+    exitStatus: number;
+    exitSignal: string;
+}
+/** Ends a view, either way. */
+export interface Close {
+    reason: CloseReason;
+    /** Reconnect at once with the view id. */
+    reconnect: boolean;
+}
+/** Takes or releases control, client → minder. */
+export interface Control {
+    action: ControlAction;
+}
+/** Reads a header: the frame type and the payload length. */
+export declare function parseHeader(msg: ArrayBuffer | Uint8Array): {
+    type: number;
+    length: number;
+};
+/** Reads a message holding exactly one frame. The payload aliases the message. */
+export declare function decodeFrame(msg: ArrayBuffer | Uint8Array): Frame;
+/** A DATA or INPUT frame of `bytes`. */
+export declare function encodeBytes(type: typeof FrameType.Data | typeof FrameType.Input, bytes: Uint8Array): Uint8Array;
+export declare function encodeReplayEnd(): Uint8Array;
+/** An ACK or INPUT_ACK frame of `count` bytes. */
+export declare function encodeCount(type: typeof FrameType.Ack | typeof FrameType.InputAck, count: number): Uint8Array;
+/** An ACK or INPUT_ACK frame's count. Bytes past the first four are a later version's. */
+export declare function decodeCount(f: Frame): number;
+/**
+ * A SIGNAL frame of one keystroke's character, `char` the byte the key
+ * produces (0x03 for Ctrl-C). It rides outside the input window, so it is how
+ * an interrupt reaches a session whose window is full (PRD-031 SC6). The
+ * minder signals the foreground process group when the byte is the pty's
+ * interrupt, quit or suspend character and ISIG is set, and drops it
+ * otherwise; it never queues it and never grants it back. A client sends a
+ * keystroke as INPUT while its credit holds it, and a one-byte keystroke the
+ * credit cannot hold as one SIGNAL instead of holding it for credit, once per
+ * keystroke (sdk/terminalwire `TypeSignal` states the whole contract).
+ */
+export declare function encodeSignal(char: number): Uint8Array;
+/** A SIGNAL frame's character. Bytes past the first are a later version's. */
+export declare function decodeSignal(f: Frame): number;
+export declare function encodeResize(size: Size): Uint8Array;
+/** A RESIZE frame's size. Bytes past the first four are a later version's. */
+export declare function decodeResize(f: Frame): Size;
+export declare function encodeWelcome(w: Welcome): Uint8Array;
+export declare function decodeWelcome(f: Frame): Welcome;
+export declare function encodeResync(s: Resync): Uint8Array;
+export declare function decodeResync(f: Frame): Resync;
+export declare function encodeStatus(s: Status): Uint8Array;
+export declare function decodeStatus(f: Frame): Status;
+export declare function encodeClose(c: Close): Uint8Array;
+export declare function decodeClose(f: Frame): Close;
+export declare function encodeControl(c: Control): Uint8Array;
+export declare function decodeControl(f: Frame): Control;