@cplieger/web-terminal-engine 1.2.0

package/src/wire-binary.ts

@@ -0,0 +1,238 @@
+// Binary wire decoder. Mirrors wire_binary.go on the server.
+//
+// All multi-byte integers are little-endian. See the Go terminal package's
+// wire_binary.go for the exact frame layout.
+
+import type {
+  WireRun,
+  ScreenMessage,
+  ScrollMessage,
+  ResumeAckMessage,
+  ModesMessage,
+  TitleMessage,
+  ServerMessage,
+} from "./types.js";
+
+// Wire message type tags (mirrored from Go wire_binary.go constants).
+const MSG_SCREEN = 0;
+const MSG_SCROLL = 1;
+const MSG_RESUME_ACK = 2;
+const MSG_MODES = 3;
+const MSG_TITLE = 4;
+const MSG_PONG = 5;
+
+/**
+ * Wire protocol version. Sent by the client in the `resume` control message so
+ * the server can detect a client built against a different protocol revision
+ * (e.g. a stale cached bundle after a breaking change) and warn rather than
+ * silently mis-decode. Bump on any breaking change to the binary frame layout
+ * or control-message shape. Mirrors `wireProtocolVersion` in wire_binary.go.
+ */
+export const WIRE_PROTOCOL_VERSION = 2;
+const MODE_FLAG_BRACKETED_PASTE = 1;
+const MODE_FLAG_APP_CURSOR_KEYS = 2;
+const MODE_FLAG_MOUSE_SGR = 4;
+const MODE_FLAG_FOCUS_REPORTING = 8;
+const MODE_FLAG_APP_KEYPAD = 16;
+const MODE_FLAG_REVERSE_VIDEO = 32;
+
+class Cursor {
+  view: DataView;
+  bytes: Uint8Array;
+  off = 0;
+  constructor(buf: ArrayBuffer) {
+    this.view = new DataView(buf);
+    this.bytes = new Uint8Array(buf);
+  }
+  u8(): number {
+    const v = this.view.getUint8(this.off);
+    this.off += 1;
+    return v;
+  }
+  u16(): number {
+    const v = this.view.getUint16(this.off, true);
+    this.off += 2;
+    return v;
+  }
+  i32(): number {
+    const v = this.view.getInt32(this.off, true);
+    this.off += 4;
+    return v;
+  }
+  u64(): number {
+    // Number(v) is safe here: all values this protocol encodes in u64
+    // fields (bytesReceived, serverEpoch) fit within JavaScript's 53-bit
+    // integer precision. If the protocol ever needs true 64-bit values,
+    // this must return BigInt instead.
+    const v = this.view.getBigUint64(this.off, true);
+    this.off += 8;
+    return Number(v);
+  }
+  utf8(len: number): string {
+    const slice = this.bytes.subarray(this.off, this.off + len);
+    this.off += len;
+    return new TextDecoder().decode(slice);
+  }
+}
+
+function readRowRuns(c: Cursor): WireRun[] {
+  const numRuns = c.u16();
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- pre-allocated array filled immediately below
+  const runs: WireRun[] = new Array(numRuns);
+  for (let i = 0; i < numRuns; i++) {
+    const tlen = c.u16();
+    const t = c.utf8(tlen);
+    const f = c.i32();
+    const b = c.i32();
+    const a = c.u16();
+    const uc = c.i32();
+    const ulen = c.u16();
+    const u = ulen > 0 ? c.utf8(ulen) : undefined;
+    runs[i] = u ? { t, f, b, a, uc, u } : { t, f, b, a, uc };
+  }
+  return runs;
+}
+
+/**
+ * Decode a binary frame from the server's WebSocket into a `ServerMessage`.
+ * Returns `null` for frames smaller than the minimum header (9 bytes) or for
+ * truncated/invalid frames; the caller should drop such frames silently.
+ *
+ * Frame format mirrors the Go `vt` package's wire encoding:
+ *   - 1 byte type tag
+ *   - 8 bytes inputAck (u64 little-endian)
+ *   - type-specific body (rows of styled runs for screen/scroll, etc.)
+ *
+ * @param buf  Raw binary frame received over WebSocket.
+ * @returns    Decoded message, or `null` if the frame couldn't be parsed.
+ */
+export function decodeWireBinary(buf: ArrayBuffer): ServerMessage | null {
+  if (buf.byteLength < 9) {
+    return null;
+  }
+  try {
+    return decodeWireBinaryInner(buf);
+  } catch (err) {
+    // Graceful frame drop: a RangeError means the frame was truncated
+    // or malformed (e.g. network split mid-frame). Returning null lets
+    // the caller skip this frame rather than crashing the decode loop.
+    // The next flush will carry a complete snapshot anyway.
+    if (err instanceof RangeError) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+function decodeWireBinaryInner(buf: ArrayBuffer): ServerMessage | null {
+  const c = new Cursor(buf);
+  const msgType = c.u8();
+  const inputAck = c.u64();
+
+  if (msgType === MSG_RESUME_ACK) {
+    // Optional tails, length-gated for back-compat with older servers:
+    //   >= 17 bytes: + serverEpoch (restart detection)
+    //   >= 33 bytes: + committed + oldestIndex (resume gap detection)
+    let serverEpoch: number | undefined;
+    let committed: number | undefined;
+    let oldestIndex: number | undefined;
+    if (buf.byteLength >= 17) {
+      serverEpoch = c.u64();
+    }
+    if (buf.byteLength >= 33) {
+      committed = c.u64();
+      oldestIndex = c.u64();
+    }
+    const msg: ResumeAckMessage = { type: "resumeAck", received: inputAck };
+    if (serverEpoch !== undefined) {
+      msg.serverEpoch = serverEpoch;
+    }
+    if (committed !== undefined) {
+      msg.committed = committed;
+    }
+    if (oldestIndex !== undefined) {
+      msg.oldestIndex = oldestIndex;
+    }
+    return msg;
+  }
+  if (msgType === MSG_SCREEN) {
+    // Sparse row array: the frame carries only changed rows (indexed by
+    // row_idx). The client allocates a full screenHeight-sized array but
+    // only the indices listed in `changed` are populated. Absolute index
+    // of a changed row `y` is `base + y`.
+    const base = c.u64();
+    const cursorRow = c.u16();
+    const cursorCol = c.u16();
+    const screenHeight = c.u16();
+    const numChanged = c.u16();
+    const cursorStyle = c.u8();
+    const cursorFlags = c.u8();
+    const cursorHidden = (cursorFlags & 1) !== 0;
+    const bell = (cursorFlags & 2) !== 0;
+    const cursorBlink = (cursorFlags & 4) !== 0;
+    const altActive = (cursorFlags & 8) !== 0;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- pre-allocated array filled below
+    const rows: WireRun[][] = new Array(screenHeight);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- pre-allocated array filled below
+    const changed: number[] = new Array(numChanged);
+    for (let i = 0; i < numChanged; i++) {
+      const idx = c.u16();
+      changed[i] = idx;
+      rows[idx] = readRowRuns(c);
+    }
+    const msg: ScreenMessage = {
+      type: "screen",
+      rows,
+      base,
+      cursor: [cursorRow, cursorCol],
+      changed,
+      altActive,
+      cursorStyle,
+      cursorHidden,
+      cursorBlink,
+      bell,
+      inputAck,
+    };
+    return msg;
+  }
+  if (msgType === MSG_SCROLL) {
+    const firstIndex = c.u64();
+    const numLines = c.u16();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- pre-allocated array filled below
+    const lines: WireRun[][] = new Array(numLines);
+    for (let i = 0; i < numLines; i++) {
+      lines[i] = readRowRuns(c);
+    }
+    const msg: ScrollMessage = { type: "scroll", firstIndex, lines, inputAck };
+    return msg;
+  }
+  if (msgType === MSG_MODES) {
+    const flags = c.u8();
+    const mouseMode = c.u16();
+    const msg: ModesMessage = {
+      type: "modes",
+      bracketedPaste: (flags & MODE_FLAG_BRACKETED_PASTE) !== 0,
+      applicationCursor: (flags & MODE_FLAG_APP_CURSOR_KEYS) !== 0,
+      applicationKeypad: (flags & MODE_FLAG_APP_KEYPAD) !== 0,
+      mouseSGR: (flags & MODE_FLAG_MOUSE_SGR) !== 0,
+      focusReporting: (flags & MODE_FLAG_FOCUS_REPORTING) !== 0,
+      reverseVideo: (flags & MODE_FLAG_REVERSE_VIDEO) !== 0,
+      mouseMode,
+      inputAck,
+    };
+    return msg;
+  }
+  if (msgType === MSG_TITLE) {
+    const titleLen = c.u16();
+    const title = c.utf8(titleLen);
+    const msg: TitleMessage = { type: "title", title, inputAck };
+    return msg;
+  }
+  if (msgType === MSG_PONG) {
+    // Liveness pong: no payload to deliver. The message listener already
+    // refreshed the activity clock on arrival, so there is nothing to do
+    // here — returning null keeps it out of the onMessage path.
+    return null;
+  }
+  return null;
+}

package/src/wire.ts

@@ -0,0 +1,36 @@
+// Pure wire-format helpers for the client → server WebSocket protocol.
+//
+// Protocol: every WebSocket message the client sends to the server is a
+// binary frame whose first byte tags the message type:
+//
+//   0x00  control message (JSON-encoded {type, ...} payload)
+//   any   raw terminal input bytes
+//
+// The 0x00 prefix is the only framing convention; raw input flows
+// through the rest of the byte space, because terminal input never
+// starts a write with NUL. See the Go terminal package's frame parser
+// for the receiving end.
+//
+// Pulled into a dedicated module so unit tests can exercise the framing
+// without spinning up a WebSocket. Pure: no DOM, no WebSocket, no
+// module-level state.
+
+/** Type tag prefix for control messages. */
+export const CONTROL_FRAME_PREFIX = 0x00;
+
+/**
+ * controlFrame builds the 0x00-prefixed binary frame containing the
+ * JSON encoding of msg. The result is the exact bytes to pass to
+ * `WebSocket.send(...)`.
+ *
+ * Returns a Uint8Array backed by a fresh ArrayBuffer (not a
+ * SharedArrayBuffer slice) so it satisfies WebSocket.send's
+ * BufferSource parameter.
+ */
+export function controlFrame(msg: unknown): Uint8Array<ArrayBuffer> {
+  const body = new TextEncoder().encode(JSON.stringify(msg));
+  const frame = new Uint8Array(new ArrayBuffer(body.length + 1));
+  frame[0] = CONTROL_FRAME_PREFIX;
+  frame.set(body, 1);
+  return frame;
+}

package/src/wsurl.ts

@@ -0,0 +1,19 @@
+// Pure URL helper, no DOM / terminal / WebSocket dependencies.
+// Kept in a dedicated module so it can be property-tested without
+// touching `location`. The caller threads the live `location.*` through.
+
+/**
+ * Build the WebSocket URL for a terminal session from a page
+ * protocol/host pair and a path. `https:` selects `wss:`; any other
+ * page protocol selects `ws:`.
+ *
+ * @param pageProtocol `location.protocol` (e.g. `"https:"`).
+ * @param pageHost     `location.host` (host[:port]).
+ * @param path         WebSocket endpoint path; defaults to `"/ws"`.
+ * @returns            A parseable `ws://`/`wss://` URL.
+ */
+export function wsURL(pageProtocol: string, pageHost: string, path = "/ws"): string {
+  const wsProto = pageProtocol === "https:" ? "wss:" : "ws:";
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${wsProto}//${pageHost}${normalizedPath}`;
+}