@thevinci/web 1.0.0

package/server/lib/terminal/index.js

@@ -0,0 +1,31 @@
+export {
+  TERMINAL_WS_PATH,
+  TERMINAL_WS_CONTROL_TAG_JSON,
+  TERMINAL_WS_MAX_PAYLOAD_BYTES,
+  isTerminalWsPathname,
+  parseRequestPathname,
+  normalizeTerminalWsMessageToBuffer,
+  normalizeTerminalWsMessageToText,
+  readTerminalWsControlFrame,
+  createTerminalWsControlFrame,
+  pruneRebindTimestamps,
+  isRebindRateLimited,
+} from './terminal-ws-protocol.js';
+
+export {
+  TERMINAL_WS_PATH as TERMINAL_INPUT_WS_PATH,
+  TERMINAL_WS_CONTROL_TAG_JSON as TERMINAL_INPUT_WS_CONTROL_TAG_JSON,
+  TERMINAL_WS_MAX_PAYLOAD_BYTES as TERMINAL_INPUT_WS_MAX_PAYLOAD_BYTES,
+  normalizeTerminalWsMessageToBuffer as normalizeTerminalInputWsMessageToBuffer,
+  normalizeTerminalWsMessageToText as normalizeTerminalInputWsMessageToText,
+  readTerminalWsControlFrame as readTerminalInputWsControlFrame,
+  createTerminalWsControlFrame as createTerminalInputWsControlFrame,
+} from './terminal-ws-protocol.js';
+
+export {
+  TERMINAL_OUTPUT_REPLAY_MAX_BYTES,
+  createTerminalOutputReplayBuffer,
+  appendTerminalOutputReplayChunk,
+  listTerminalOutputReplayChunksSince,
+  getLatestTerminalOutputReplayChunkId,
+} from './output-replay-buffer.js';

package/server/lib/terminal/output-replay-buffer.js

@@ -0,0 +1,78 @@
+export const TERMINAL_OUTPUT_REPLAY_MAX_BYTES = 64 * 1024;
+
+const trimTerminalOutputChunkToMaxBytes = (data, maxBytes) => {
+  if (typeof data !== 'string' || data.length === 0) {
+    return '';
+  }
+
+  const bytes = Buffer.byteLength(data, 'utf8');
+  if (bytes <= maxBytes) {
+    return data;
+  }
+
+  const kept = [];
+  let trimmedBytes = 0;
+  const characters = Array.from(data);
+  for (let index = characters.length - 1; index >= 0; index -= 1) {
+    const character = characters[index];
+    const characterBytes = Buffer.byteLength(character, 'utf8');
+    if (trimmedBytes + characterBytes > maxBytes) {
+      break;
+    }
+    kept.push(character);
+    trimmedBytes += characterBytes;
+  }
+
+  return kept.reverse().join('');
+};
+
+export const createTerminalOutputReplayBuffer = () => ({
+  chunks: [],
+  totalBytes: 0,
+  nextId: 1,
+});
+
+export const appendTerminalOutputReplayChunk = (bufferState, data, maxBytes = TERMINAL_OUTPUT_REPLAY_MAX_BYTES) => {
+  if (!bufferState || typeof bufferState !== 'object') {
+    return null;
+  }
+
+  const normalizedData = trimTerminalOutputChunkToMaxBytes(data, maxBytes);
+  if (!normalizedData) {
+    return null;
+  }
+
+  const bytes = Buffer.byteLength(normalizedData, 'utf8');
+  const chunk = {
+    id: bufferState.nextId,
+    data: normalizedData,
+    bytes,
+  };
+
+  bufferState.nextId += 1;
+  bufferState.chunks.push(chunk);
+  bufferState.totalBytes += bytes;
+
+  while (bufferState.totalBytes > maxBytes && bufferState.chunks.length > 1) {
+    const removedChunk = bufferState.chunks.shift();
+    bufferState.totalBytes -= removedChunk?.bytes ?? 0;
+  }
+
+  return chunk;
+};
+
+export const listTerminalOutputReplayChunksSince = (bufferState, lastSeenId = 0) => {
+  if (!bufferState || typeof bufferState !== 'object' || !Array.isArray(bufferState.chunks)) {
+    return [];
+  }
+
+  return bufferState.chunks.filter((chunk) => chunk.id > lastSeenId);
+};
+
+export const getLatestTerminalOutputReplayChunkId = (bufferState) => {
+  if (!bufferState || typeof bufferState !== 'object' || !Array.isArray(bufferState.chunks) || bufferState.chunks.length === 0) {
+    return 0;
+  }
+
+  return bufferState.chunks[bufferState.chunks.length - 1]?.id ?? 0;
+};

package/server/lib/terminal/output-replay-buffer.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  TERMINAL_OUTPUT_REPLAY_MAX_BYTES,
+  appendTerminalOutputReplayChunk,
+  createTerminalOutputReplayBuffer,
+  getLatestTerminalOutputReplayChunkId,
+  listTerminalOutputReplayChunksSince,
+} from './output-replay-buffer.js';
+
+describe('terminal output replay buffer', () => {
+  it('starts empty', () => {
+    const bufferState = createTerminalOutputReplayBuffer();
+    expect(bufferState).toEqual({ chunks: [], totalBytes: 0, nextId: 1 });
+    expect(getLatestTerminalOutputReplayChunkId(bufferState)).toBe(0);
+  });
+
+  it('appends chunks with incrementing ids', () => {
+    const bufferState = createTerminalOutputReplayBuffer();
+    const first = appendTerminalOutputReplayChunk(bufferState, 'prompt> ');
+    const second = appendTerminalOutputReplayChunk(bufferState, 'ls\r\n');
+
+    expect(first).toEqual({ id: 1, data: 'prompt> ', bytes: 8 });
+    expect(second).toEqual({ id: 2, data: 'ls\r\n', bytes: 4 });
+    expect(getLatestTerminalOutputReplayChunkId(bufferState)).toBe(2);
+  });
+
+  it('lists chunks after a replay cursor', () => {
+    const bufferState = createTerminalOutputReplayBuffer();
+    appendTerminalOutputReplayChunk(bufferState, 'prompt> ');
+    appendTerminalOutputReplayChunk(bufferState, 'ls\r\n');
+    appendTerminalOutputReplayChunk(bufferState, 'file.txt\r\n');
+
+    expect(listTerminalOutputReplayChunksSince(bufferState, 1).map((chunk) => chunk.data)).toEqual([
+      'ls\r\n',
+      'file.txt\r\n',
+    ]);
+  });
+
+  it('trims old chunks beyond max bytes', () => {
+    const bufferState = createTerminalOutputReplayBuffer();
+    appendTerminalOutputReplayChunk(bufferState, '1234', 8);
+    appendTerminalOutputReplayChunk(bufferState, '5678', 8);
+    appendTerminalOutputReplayChunk(bufferState, '90', 8);
+
+    expect(bufferState.chunks.map((chunk) => chunk.data)).toEqual(['5678', '90']);
+    expect(bufferState.totalBytes).toBe(6);
+  });
+
+  it('trims oversized single chunks to the configured max bytes', () => {
+    const bufferState = createTerminalOutputReplayBuffer();
+    const chunk = appendTerminalOutputReplayChunk(bufferState, 'abcdefghij', 4);
+
+    expect(chunk?.data).toBe('ghij');
+    expect(chunk?.bytes).toBe(4);
+    expect(bufferState.totalBytes).toBe(4);
+  });
+
+  it('does not split multibyte characters when trimming oversized chunks', () => {
+    const bufferState = createTerminalOutputReplayBuffer();
+    const chunk = appendTerminalOutputReplayChunk(bufferState, '🙂x', 2);
+
+    expect(chunk?.data).toBe('x');
+    expect(chunk?.bytes).toBe(1);
+    expect(bufferState.totalBytes).toBe(1);
+  });
+
+  it('uses the default max bytes when not provided', () => {
+    const bufferState = createTerminalOutputReplayBuffer();
+    const chunk = appendTerminalOutputReplayChunk(bufferState, 'ok');
+
+    expect(chunk?.bytes).toBe(2);
+    expect(TERMINAL_OUTPUT_REPLAY_MAX_BYTES).toBe(64 * 1024);
+  });
+});