Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(watch-link): a viewer joining a running session starts its filter mid-stream

reviewbc4b73f91ee2
diff --git a/src/core/watch-link/__fixtures__/xterm-vt500.ts b/src/core/watch-link/__fixtures__/xterm-vt500.ts
new file mode 100644
index 000000000..fb77d47a7
--- /dev/null
+++ b/src/core/watch-link/__fixtures__/xterm-vt500.ts
@@ -0,0 +1,268 @@
+// xterm.js 5.5.0's VT500 parser table, for the stream filter's differential test (test-only).
+//
+// The six blocks between the BEGIN/END markers are copied VERBATIM from the installed package:
+// node_modules/@xterm/xterm/src/common/parser/Constants.ts ParserState, ParserAction
+// node_modules/@xterm/xterm/src/common/parser/EscapeSequenceParser.ts TableAccess, TransitionTable,
+// NON_ASCII_PRINTABLE,
+// VT500_TRANSITION_TABLE
+// `stream-filter.xterm.test.ts` compares each block with that source, so an xterm upgrade that
+// changes the table fails there instead of silently testing the filter against an old model.
+// Only the code after the END marker is ours.
+//
+// The copied blocks: Copyright (c) 2017-2018 The xterm.js authors. MIT license.
+
+// ---- BEGIN verbatim xterm 5.5.0 ----
+export const enum ParserState {
+ GROUND = 0,
+ ESCAPE = 1,
+ ESCAPE_INTERMEDIATE = 2,
+ CSI_ENTRY = 3,
+ CSI_PARAM = 4,
+ CSI_INTERMEDIATE = 5,
+ CSI_IGNORE = 6,
+ SOS_PM_APC_STRING = 7,
+ OSC_STRING = 8,
+ DCS_ENTRY = 9,
+ DCS_PARAM = 10,
+ DCS_IGNORE = 11,
+ DCS_INTERMEDIATE = 12,
+ DCS_PASSTHROUGH = 13
+}
+
+export const enum ParserAction {
+ IGNORE = 0,
+ ERROR = 1,
+ PRINT = 2,
+ EXECUTE = 3,
+ OSC_START = 4,
+ OSC_PUT = 5,
+ OSC_END = 6,
+ CSI_DISPATCH = 7,
+ PARAM = 8,
+ COLLECT = 9,
+ ESC_DISPATCH = 10,
+ CLEAR = 11,
+ DCS_HOOK = 12,
+ DCS_PUT = 13,
+ DCS_UNHOOK = 14
+}
+
+const enum TableAccess {
+ TRANSITION_ACTION_SHIFT = 4,
+ TRANSITION_STATE_MASK = 15,
+ INDEX_STATE_SHIFT = 8
+}
+
+export class TransitionTable {
+ public table: Uint8Array;
+
+ constructor(length: number) {
+ this.table = new Uint8Array(length);
+ }
+
+ /**
+ * Set default transition.
+ * @param action default action
+ * @param next default next state
+ */
+ public setDefault(action: ParserAction, next: ParserState): void {
+ this.table.fill(action << TableAccess.TRANSITION_ACTION_SHIFT | next);
+ }
+
+ /**
+ * Add a transition to the transition table.
+ * @param code input character code
+ * @param state current parser state
+ * @param action parser action to be done
+ * @param next next parser state
+ */
+ public add(code: number, state: ParserState, action: ParserAction, next: ParserState): void {
+ this.table[state << TableAccess.INDEX_STATE_SHIFT | code] = action << TableAccess.TRANSITION_ACTION_SHIFT | next;
+ }
+
+ /**
+ * Add transitions for multiple input character codes.
+ * @param codes input character code array
+ * @param state current parser state
+ * @param action parser action to be done
+ * @param next next parser state
+ */
+ public addMany(codes: number[], state: ParserState, action: ParserAction, next: ParserState): void {
+ for (let i = 0; i < codes.length; i++) {
+ this.table[state << TableAccess.INDEX_STATE_SHIFT | codes[i]] = action << TableAccess.TRANSITION_ACTION_SHIFT | next;
+ }
+ }
+}
+
+const NON_ASCII_PRINTABLE = 0xA0;
+
+export const VT500_TRANSITION_TABLE = (function (): TransitionTable {
+ const table: TransitionTable = new TransitionTable(4095);
+
+ // range macro for byte
+ const BYTE_VALUES = 256;
+ const blueprint = Array.apply(null, Array(BYTE_VALUES)).map((unused: any, i: number) => i);
+ const r = (start: number, end: number): number[] => blueprint.slice(start, end);
+
+ // Default definitions.
+ const PRINTABLES = r(0x20, 0x7f); // 0x20 (SP) included, 0x7F (DEL) excluded
+ const EXECUTABLES = r(0x00, 0x18);
+ EXECUTABLES.push(0x19);
+ EXECUTABLES.push.apply(EXECUTABLES, r(0x1c, 0x20));
+
+ const states: number[] = r(ParserState.GROUND, ParserState.DCS_PASSTHROUGH + 1);
+ let state: any;
+
+ // set default transition
+ table.setDefault(ParserAction.ERROR, ParserState.GROUND);
+ // printables
+ table.addMany(PRINTABLES, ParserState.GROUND, ParserAction.PRINT, ParserState.GROUND);
+ // global anywhere rules
+ for (state in states) {
+ table.addMany([0x18, 0x1a, 0x99, 0x9a], state, ParserAction.EXECUTE, ParserState.GROUND);
+ table.addMany(r(0x80, 0x90), state, ParserAction.EXECUTE, ParserState.GROUND);
+ table.addMany(r(0x90, 0x98), state, ParserAction.EXECUTE, ParserState.GROUND);
+ table.add(0x9c, state, ParserAction.IGNORE, ParserState.GROUND); // ST as terminator
+ table.add(0x1b, state, ParserAction.CLEAR, ParserState.ESCAPE); // ESC
+ table.add(0x9d, state, ParserAction.OSC_START, ParserState.OSC_STRING); // OSC
+ table.addMany([0x98, 0x9e, 0x9f], state, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);
+ table.add(0x9b, state, ParserAction.CLEAR, ParserState.CSI_ENTRY); // CSI
+ table.add(0x90, state, ParserAction.CLEAR, ParserState.DCS_ENTRY); // DCS
+ }
+ // rules for executables and 7f
+ table.addMany(EXECUTABLES, ParserState.GROUND, ParserAction.EXECUTE, ParserState.GROUND);
+ table.addMany(EXECUTABLES, ParserState.ESCAPE, ParserAction.EXECUTE, ParserState.ESCAPE);
+ table.add(0x7f, ParserState.ESCAPE, ParserAction.IGNORE, ParserState.ESCAPE);
+ table.addMany(EXECUTABLES, ParserState.OSC_STRING, ParserAction.IGNORE, ParserState.OSC_STRING);
+ table.addMany(EXECUTABLES, ParserState.CSI_ENTRY, ParserAction.EXECUTE, ParserState.CSI_ENTRY);
+ table.add(0x7f, ParserState.CSI_ENTRY, ParserAction.IGNORE, ParserState.CSI_ENTRY);
+ table.addMany(EXECUTABLES, ParserState.CSI_PARAM, ParserAction.EXECUTE, ParserState.CSI_PARAM);
+ table.add(0x7f, ParserState.CSI_PARAM, ParserAction.IGNORE, ParserState.CSI_PARAM);
+ table.addMany(EXECUTABLES, ParserState.CSI_IGNORE, ParserAction.EXECUTE, ParserState.CSI_IGNORE);
+ table.addMany(EXECUTABLES, ParserState.CSI_INTERMEDIATE, ParserAction.EXECUTE, ParserState.CSI_INTERMEDIATE);
+ table.add(0x7f, ParserState.CSI_INTERMEDIATE, ParserAction.IGNORE, ParserState.CSI_INTERMEDIATE);
+ table.addMany(EXECUTABLES, ParserState.ESCAPE_INTERMEDIATE, ParserAction.EXECUTE, ParserState.ESCAPE_INTERMEDIATE);
+ table.add(0x7f, ParserState.ESCAPE_INTERMEDIATE, ParserAction.IGNORE, ParserState.ESCAPE_INTERMEDIATE);
+ // osc
+ table.add(0x5d, ParserState.ESCAPE, ParserAction.OSC_START, ParserState.OSC_STRING);
+ table.addMany(PRINTABLES, ParserState.OSC_STRING, ParserAction.OSC_PUT, ParserState.OSC_STRING);
+ table.add(0x7f, ParserState.OSC_STRING, ParserAction.OSC_PUT, ParserState.OSC_STRING);
+ table.addMany([0x9c, 0x1b, 0x18, 0x1a, 0x07], ParserState.OSC_STRING, ParserAction.OSC_END, ParserState.GROUND);
+ table.addMany(r(0x1c, 0x20), ParserState.OSC_STRING, ParserAction.IGNORE, ParserState.OSC_STRING);
+ // sos/pm/apc does nothing
+ table.addMany([0x58, 0x5e, 0x5f], ParserState.ESCAPE, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);
+ table.addMany(PRINTABLES, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);
+ table.addMany(EXECUTABLES, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);
+ table.add(0x9c, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.GROUND);
+ table.add(0x7f, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);
+ // csi entries
+ table.add(0x5b, ParserState.ESCAPE, ParserAction.CLEAR, ParserState.CSI_ENTRY);
+ table.addMany(r(0x40, 0x7f), ParserState.CSI_ENTRY, ParserAction.CSI_DISPATCH, ParserState.GROUND);
+ table.addMany(r(0x30, 0x3c), ParserState.CSI_ENTRY, ParserAction.PARAM, ParserState.CSI_PARAM);
+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.CSI_ENTRY, ParserAction.COLLECT, ParserState.CSI_PARAM);
+ table.addMany(r(0x30, 0x3c), ParserState.CSI_PARAM, ParserAction.PARAM, ParserState.CSI_PARAM);
+ table.addMany(r(0x40, 0x7f), ParserState.CSI_PARAM, ParserAction.CSI_DISPATCH, ParserState.GROUND);
+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.CSI_PARAM, ParserAction.IGNORE, ParserState.CSI_IGNORE);
+ table.addMany(r(0x20, 0x40), ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.CSI_IGNORE);
+ table.add(0x7f, ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.CSI_IGNORE);
+ table.addMany(r(0x40, 0x7f), ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.GROUND);
+ table.addMany(r(0x20, 0x30), ParserState.CSI_ENTRY, ParserAction.COLLECT, ParserState.CSI_INTERMEDIATE);
+ table.addMany(r(0x20, 0x30), ParserState.CSI_INTERMEDIATE, ParserAction.COLLECT, ParserState.CSI_INTERMEDIATE);
+ table.addMany(r(0x30, 0x40), ParserState.CSI_INTERMEDIATE, ParserAction.IGNORE, ParserState.CSI_IGNORE);
+ table.addMany(r(0x40, 0x7f), ParserState.CSI_INTERMEDIATE, ParserAction.CSI_DISPATCH, ParserState.GROUND);
+ table.addMany(r(0x20, 0x30), ParserState.CSI_PARAM, ParserAction.COLLECT, ParserState.CSI_INTERMEDIATE);
+ // esc_intermediate
+ table.addMany(r(0x20, 0x30), ParserState.ESCAPE, ParserAction.COLLECT, ParserState.ESCAPE_INTERMEDIATE);
+ table.addMany(r(0x20, 0x30), ParserState.ESCAPE_INTERMEDIATE, ParserAction.COLLECT, ParserState.ESCAPE_INTERMEDIATE);
+ table.addMany(r(0x30, 0x7f), ParserState.ESCAPE_INTERMEDIATE, ParserAction.ESC_DISPATCH, ParserState.GROUND);
+ table.addMany(r(0x30, 0x50), ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);
+ table.addMany(r(0x51, 0x58), ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);
+ table.addMany([0x59, 0x5a, 0x5c], ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);
+ table.addMany(r(0x60, 0x7f), ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);
+ // dcs entry
+ table.add(0x50, ParserState.ESCAPE, ParserAction.CLEAR, ParserState.DCS_ENTRY);
+ table.addMany(EXECUTABLES, ParserState.DCS_ENTRY, ParserAction.IGNORE, ParserState.DCS_ENTRY);
+ table.add(0x7f, ParserState.DCS_ENTRY, ParserAction.IGNORE, ParserState.DCS_ENTRY);
+ table.addMany(r(0x1c, 0x20), ParserState.DCS_ENTRY, ParserAction.IGNORE, ParserState.DCS_ENTRY);
+ table.addMany(r(0x20, 0x30), ParserState.DCS_ENTRY, ParserAction.COLLECT, ParserState.DCS_INTERMEDIATE);
+ table.addMany(r(0x30, 0x3c), ParserState.DCS_ENTRY, ParserAction.PARAM, ParserState.DCS_PARAM);
+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.DCS_ENTRY, ParserAction.COLLECT, ParserState.DCS_PARAM);
+ table.addMany(EXECUTABLES, ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);
+ table.addMany(r(0x20, 0x80), ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);
+ table.addMany(r(0x1c, 0x20), ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);
+ table.addMany(EXECUTABLES, ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_PARAM);
+ table.add(0x7f, ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_PARAM);
+ table.addMany(r(0x1c, 0x20), ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_PARAM);
+ table.addMany(r(0x30, 0x3c), ParserState.DCS_PARAM, ParserAction.PARAM, ParserState.DCS_PARAM);
+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_IGNORE);
+ table.addMany(r(0x20, 0x30), ParserState.DCS_PARAM, ParserAction.COLLECT, ParserState.DCS_INTERMEDIATE);
+ table.addMany(EXECUTABLES, ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_INTERMEDIATE);
+ table.add(0x7f, ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_INTERMEDIATE);
+ table.addMany(r(0x1c, 0x20), ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_INTERMEDIATE);
+ table.addMany(r(0x20, 0x30), ParserState.DCS_INTERMEDIATE, ParserAction.COLLECT, ParserState.DCS_INTERMEDIATE);
+ table.addMany(r(0x30, 0x40), ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_IGNORE);
+ table.addMany(r(0x40, 0x7f), ParserState.DCS_INTERMEDIATE, ParserAction.DCS_HOOK, ParserState.DCS_PASSTHROUGH);
+ table.addMany(r(0x40, 0x7f), ParserState.DCS_PARAM, ParserAction.DCS_HOOK, ParserState.DCS_PASSTHROUGH);
+ table.addMany(r(0x40, 0x7f), ParserState.DCS_ENTRY, ParserAction.DCS_HOOK, ParserState.DCS_PASSTHROUGH);
+ table.addMany(EXECUTABLES, ParserState.DCS_PASSTHROUGH, ParserAction.DCS_PUT, ParserState.DCS_PASSTHROUGH);
+ table.addMany(PRINTABLES, ParserState.DCS_PASSTHROUGH, ParserAction.DCS_PUT, ParserState.DCS_PASSTHROUGH);
+ table.add(0x7f, ParserState.DCS_PASSTHROUGH, ParserAction.IGNORE, ParserState.DCS_PASSTHROUGH);
+ table.addMany([0x1b, 0x9c, 0x18, 0x1a], ParserState.DCS_PASSTHROUGH, ParserAction.DCS_UNHOOK, ParserState.GROUND);
+ // special handling of unicode chars
+ table.add(NON_ASCII_PRINTABLE, ParserState.GROUND, ParserAction.PRINT, ParserState.GROUND);
+ table.add(NON_ASCII_PRINTABLE, ParserState.OSC_STRING, ParserAction.OSC_PUT, ParserState.OSC_STRING);
+ table.add(NON_ASCII_PRINTABLE, ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.CSI_IGNORE);
+ table.add(NON_ASCII_PRINTABLE, ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);
+ table.add(NON_ASCII_PRINTABLE, ParserState.DCS_PASSTHROUGH, ParserAction.DCS_PUT, ParserState.DCS_PASSTHROUGH);
+ return table;
+})();
+// ---- END verbatim xterm 5.5.0 ----
+
+const STRING_STATES = new Set<number>([
+ ParserState.SOS_PM_APC_STRING,
+ ParserState.OSC_STRING,
+ ParserState.DCS_ENTRY,
+ ParserState.DCS_PARAM,
+ ParserState.DCS_IGNORE,
+ ParserState.DCS_INTERMEDIATE,
+ ParserState.DCS_PASSTHROUGH
+])
+
+// One code through `EscapeSequenceParser.parse()`'s state walk, without its handlers. Two facts
+// about `parse()` make a one-code-at-a-time walk of the table exact: its read-ahead loops (PRINT,
+// PARAM, OSC_PUT, DCS_PUT) only take codes whose table entry keeps the state they are in, and an
+// OSC or DCS ended by ESC goes to ESCAPE although the table says GROUND
+// (`transition |= ParserState.ESCAPE`). An ERROR (a non-ASCII code in SOS/PM/APC or a DCS header)
+// goes to GROUND with the default error handler, as the table says.
+function step(state: number, code: number): number {
+ let transition = VT500_TRANSITION_TABLE.table[state << TableAccess.INDEX_STATE_SHIFT | (code < 0xa0 ? code : NON_ASCII_PRINTABLE)]
+ const action = transition >> TableAccess.TRANSITION_ACTION_SHIFT
+ if ((action === ParserAction.OSC_END || action === ParserAction.DCS_UNHOOK) && code === 0x1b) {
+ transition |= ParserState.ESCAPE
+ }
+ return transition & TableAccess.TRANSITION_STATE_MASK
+}
+
+/**
+ * For each code point of a stream read from GROUND, whether xterm consumes it INSIDE a string
+ * sequence (OSC, DCS, SOS, PM, APC): in a string state before it and still in one after it.
+ */
+export function xtermStringPayload(codePoints: readonly number[]): boolean[] {
+ let state: number = ParserState.GROUND
+ return codePoints.map((code) => {
+ const next = step(state, code)
+ const inside = STRING_STATES.has(state) && STRING_STATES.has(next)
+ state = next
+ return inside
+ })
+}
+
+/** Whether xterm, reading these code points from GROUND, ever enters a string sequence. */
+export function xtermEntersString(codePoints: readonly number[]): boolean {
+ let state: number = ParserState.GROUND
+ for (const code of codePoints) {
+ state = step(state, code)
+ if (STRING_STATES.has(state)) return true
+ }
+ return false
+}
diff --git a/src/core/watch-link/stream-filter.test.ts b/src/core/watch-link/stream-filter.test.ts
index 5f2d1eecc..1b7178508 100644
--- a/src/core/watch-link/stream-filter.test.ts
+++ b/src/core/watch-link/stream-filter.test.ts
@@ -10,8 +10,9 @@ const run = (chunks: string[], max?: number): string => {
// The filter's rules, one UTF-16 unit at a time and without a fast path: the oracle the fuzz test
// holds the production parser to.
-function oneCharAtATime(input: string, max: number): string {
- let mode: 'text' | 'esc' | 'string' | 'stringEsc' = 'text'
+function oneCharAtATime(input: string, max: number, midStream: boolean): string {
+ // midStream: as if an 8-bit DCS introducer had just been read.
+ let mode: 'text' | 'esc' | 'string' | 'stringEsc' = midStream ? 'string' : 'text'
let osc = false
let len = 0
let out = ''
@@ -170,7 +171,7 @@ describe('createStreamFilter', () => {
expect(f.push(']visible')).toBe(']visible')
})
- it('output never carries a string introducer, whatever the input and however it is chunked', () => {
+ it('output never carries a string introducer, whatever the input, start and chunking', () => {
// Why this is enough: in xterm.js a string state (OSC/DCS/SOS/PM/APC) is entered only from
// ESCAPE on ] P X ^ _, or anywhere on an 8-bit introducer; ESCAPE is entered only by ESC and is
// left by any char except C0 executables, DEL and ESC. So if no push emits an 8-bit introducer
@@ -200,16 +201,17 @@ describe('createStreamFilter', () => {
let input = ''
for (let i = rand(60); i > 0; i--) input += ALPHABET[rand(ALPHABET.length)]
const cap = [2, 5, 1_048_576][rand(3)]
+ const midStream = rand(2) === 1
// Cut anywhere, a surrogate pair included: the cap counts UTF-16 units, so nothing depends on it.
const cuts = [0, input.length]
for (let k = rand(5); k > 0; k--) cuts.push(rand(input.length + 1))
cuts.sort((x, y) => x - y)
const chunks = cuts.slice(1).map((end, i) => input.slice(cuts[i], end))
- const f = createStreamFilter(cap)
+ const f = createStreamFilter(cap, { midStream })
const outs = chunks.map((c) => f.push(c))
for (const out of outs) {
- const ctx = JSON.stringify({ input, chunks, cap, out })
+ const ctx = JSON.stringify({ input, chunks, cap, midStream, out })
expect(INTRO_8.test(out), ctx).toBe(false)
expect(out.endsWith(ESC), ctx).toBe(false)
for (let i = out.indexOf(ESC); i !== -1; i = out.indexOf(ESC, i + 1)) {
@@ -218,7 +220,82 @@ describe('createStreamFilter', () => {
}
// However it is chunked, the result is the char-by-char statement of the same rules: the
// parser's slicing and fast path neither drop, reorder nor add a char.
- expect(outs.join(''), JSON.stringify({ chunks, cap })).toBe(oneCharAtATime(input, cap))
+ expect(outs.join(''), JSON.stringify({ chunks, cap, midStream })).toBe(oneCharAtATime(input, cap, midStream))
}
})
})
+
+describe('createStreamFilter, joined mid-stream', () => {
+ // A watcher co-attaches to a RUNNING session, so its first byte can land anywhere: inside an OSC 52,
+ // or right after an ESC that the previous read ended on. A filter that starts in text would print
+ // the rest of that string, or read `]52;…` as text.
+ const mid = (chunks: string[], max?: number): string => {
+ const f = createStreamFilter(max, { midStream: true })
+ return chunks.map((c) => f.push(c)).join('')
+ }
+
+ it('a join at any offset never prints a byte of a string, and resyncs at the next escape', () => {
+ // Text is lowercase, spaces and `ESC [ m`; every string's payload is from a disjoint alphabet
+ // (uppercase, digits, `=;]\`), so any payload byte in the output is visible as such.
+ const STREAM = [
+ 'pre ', `${ESC}[m`, 'one ',
+ `${ESC}]52;C;U0VDUkVUQQ==${BEL}`, 'mid ',
+ `${ESC}]52;C;U0VDUkVUQg==${ESC}\\`, 'two ',
+ `${ESC}PQDATA${BEL}MORE${ESC}\\`, 'three ',
+ `${ESC}_GAPC${BEL}HIDDEN${ESC}\\`, 'four ',
+ `\x9d52;C;U0VDUkVUQw==\x9c`, 'five ',
+ `\x90QDATA${BEL}MORE\x9c`,
+ `${ESC}[m`, 'tail'
+ ].join('')
+ const resync = STREAM.lastIndexOf(ESC)
+ for (let k = 0; k <= STREAM.length; k++) {
+ const rest = STREAM.slice(k)
+ for (const out of [mid([rest]), mid([rest.slice(0, 3), rest.slice(3)])]) {
+ expect(out, `join at ${k}`).toMatch(/^[a-z \x1b[]*$/)
+ if (k <= resync) expect(out.endsWith(`${ESC}[mtail`), `join at ${k}: ${JSON.stringify(out)}`).toBe(true)
+ }
+ }
+ })
+
+ it('a join right after a lone trailing ESC does not print the OSC 52 that ESC started', () => {
+ const rest = `]52;c;c2VjcmV0${BEL}rest${ESC}[mtail`
+ expect(mid([rest])).toBe(`${ESC}[mtail`)
+ // What a filter starting in text would have sent: the whole clipboard.
+ expect(run([rest])).toContain('c2VjcmV0')
+ })
+
+ it('a join into plain text loses only the text up to the first ESC', () => {
+ expect(mid(['hello world', ` ${ESC}[1mbold${ESC}[m after`])).toBe(`${ESC}[1mbold${ESC}[m after`)
+ })
+
+ it('starts as an unknown string: ST, ESC-ST and 8-bit introducers end it, BEL does not', () => {
+ expect(mid([`DATA${ESC}\\after`])).toBe('after')
+ expect(mid([`DATA${ESC}`, `\\after`])).toBe('after')
+ expect(mid(['DATA\x9cafter'])).toBe('after')
+ // It may be a DCS or APC, where BEL is data.
+ expect(mid([`DATA${BEL}more${ESC}[mafter`])).toBe(`${ESC}[mafter`)
+ // An 8-bit introducer starts a string of ITS kind: this one is an OSC, which BEL ends.
+ expect(mid([`DATA\x9d52;c;x${BEL}after`])).toBe('after')
+ })
+
+ it('the cap counts from the join, on creation and on reset', () => {
+ const f = createStreamFilter(5, { midStream: true })
+ expect(f.push('12345')).toBe('')
+ expect(f.push('6789')).toBe('789')
+
+ const g = createStreamFilter(10)
+ expect(g.push(`a${ESC}]12345678`)).toBe('a')
+ g.reset({ midStream: true })
+ expect(g.push('1234567890')).toBe('')
+ expect(g.push('Xab')).toBe('ab')
+ })
+
+ it('reset({ midStream }) drops what was being read and starts as a join', () => {
+ const f = createStreamFilter()
+ expect(f.push('a')).toBe('a')
+ f.reset({ midStream: true })
+ expect(f.push(`b${ESC}[mc`)).toBe(`${ESC}[mc`)
+ f.reset()
+ expect(f.push('d')).toBe('d')
+ })
+})
diff --git a/src/core/watch-link/stream-filter.ts b/src/core/watch-link/stream-filter.ts
index 76d7da280..c208746d9 100644
--- a/src/core/watch-link/stream-filter.ts
+++ b/src/core/watch-link/stream-filter.ts
@@ -19,8 +19,16 @@
// ESC, and takes an 8-bit introducer as a string start: `ESC \n ]52;…` is still an OSC 52.
// - An 8-bit introducer inside a string starts a new string of ITS kind (an OSC turned DCS no longer
// ends at BEL), with a fresh count toward the cap.
-// Where xterm ENDS a string on something this parser does not (CAN, SUB, other C1 controls), the
-// viewer misses a little text until the next terminator; it never sees more than the owner.
+// Where xterm ENDS a string on something this parser does not (CAN, SUB, other C1 controls, and a
+// non-ASCII char, U+00A0 and up, inside SOS/PM/APC or a DCS before its final byte: ERROR → GROUND),
+// the viewer misses a little text until the next terminator; it never sees more than the owner.
+//
+// A viewer that joins a RUNNING session (`midStream`) cannot know where in the stream its first byte
+// falls: inside an OSC 52, or right after an ESC the previous read ended on (`]52;c;…` would then
+// read as text, the whole clipboard). So it starts as if an unknown string had just begun: nothing
+// is shown until the next ESC, ST or 8-bit introducer, where xterm's state is known again whatever
+// it was (ESCAPE, GROUND, a new string). The cost is the text between the join and the first
+// escape: the viewer misses it until those cells are painted again.
//
// The output guarantee the caller relies on: no push emits an 8-bit introducer or ends on ESC, and
// every ESC it emits is followed by a char that leaves ESCAPE without starting a string. So the
@@ -49,12 +57,25 @@ function isC0Executable(c: number): boolean {
return c <= 0x17 || c === 0x19 || (c >= 0x1c && c <= 0x1f)
}
+export interface StreamFilterOptions {
+ /**
+ * The first byte may fall anywhere in the stream. Every viewer that co-attaches to a running
+ * session must set it, and so must every `reset()` onto a session that is already running;
+ * without it a join inside a string, or right after an ESC, sends the string's payload as text.
+ * Starts exactly as if an 8-bit DCS introducer had just been read: nothing is shown until the
+ * next ESC (an `ESC \` ST is dropped), ST or 8-bit introducer; BEL does not end it (the unknown
+ * string may be a DCS or APC, where BEL is data); the cap counts from the join.
+ */
+ midStream?: boolean
+}
+
export interface StreamFilter {
push(chunk: string): string
- reset(): void
+ /** Forget the current sequence, for a new pty session; `midStream` as for `createStreamFilter`. */
+ reset(opts?: StreamFilterOptions): void
}
-export function createStreamFilter(maxStringChars = 1_048_576): StreamFilter {
+export function createStreamFilter(maxStringChars = 1_048_576, opts?: StreamFilterOptions): StreamFilter {
// 'esc' is ESCAPE after a plain ESC; 'stringEsc' is ESCAPE after the ESC that ended a string,
// where `ESC \` is that string's ST and is dropped with it.
let mode: 'text' | 'esc' | 'string' | 'stringEsc' = 'text'
@@ -65,11 +86,18 @@ export function createStreamFilter(maxStringChars = 1_048_576): StreamFilter {
osc = introducer === 0x5d || introducer === 0x9d
len = 0
}
- return {
- reset() {
+ const start = (o: StreamFilterOptions | undefined): void => {
+ if (o?.midStream) enterString(0x90)
+ else {
mode = 'text'
osc = false
len = 0
+ }
+ }
+ start(opts)
+ return {
+ reset(o) {
+ start(o)
},
push(chunk) {
if (mode === 'text' && !TEXT_SPECIAL.test(chunk)) return chunk
diff --git a/src/core/watch-link/stream-filter.xterm.test.ts b/src/core/watch-link/stream-filter.xterm.test.ts
new file mode 100644
index 000000000..46fea3a9b
--- /dev/null
+++ b/src/core/watch-link/stream-filter.xterm.test.ts
@@ -0,0 +1,144 @@
+// The stream filter held to xterm.js itself, through xterm 5.5's own VT500 table (copied verbatim in
+// __fixtures__/xterm-vt500.ts). Two ways a viewer could get what is not on the owner's screen, one
+// check each, on random streams:
+// - payload: every letter xterm consumes INSIDE a string sequence is changed; if the filter's
+// output changes with it, a byte of string payload reached the viewer;
+// - synthesis: xterm reading the filter's OUTPUT must never enter a string sequence (a lone ESC
+// glued to the text after a removed string would be one, without any payload byte leaking).
+// This is what the hand-written cases cannot do: it asks xterm, not the filter's own reading of
+// xterm, where each string starts and ends.
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createStreamFilter } from './stream-filter'
+import { xtermEntersString, xtermStringPayload } from './__fixtures__/xterm-vt500'
+
+const ESC = '\x1b'
+const BEL = '\x07'
+const XTERM_PARSER = join(__dirname, '..', '..', '..', 'node_modules', '@xterm', 'xterm', 'src', 'common', 'parser')
+
+const read = (file: string): string => readFileSync(file, 'utf8').replace(/\r\n/g, '\n')
+function block(src: string, start: string, end: string): string {
+ const i = src.indexOf(start)
+ if (i === -1) return `<missing: ${start}>`
+ return src.slice(i, src.indexOf(end, i) + end.length)
+}
+
+// mulberry32, seeded: reproducible.
+function rng(seed: number): (n: number) => number {
+ return (n) => {
+ seed = (seed + 0x6d2b79f5) >>> 0
+ let z = seed
+ z = Math.imul(z ^ (z >>> 15), z | 1)
+ z ^= z + Math.imul(z ^ (z >>> 7), z | 61)
+ return ((z ^ (z >>> 14)) >>> 0) % n
+ }
+}
+
+const LETTERS = 'abcdefghijklmnopqrstuvwxyz'
+const IS_LETTER = new Set(LETTERS)
+// Changing one lowercase letter to another moves neither parser: both take them as the same class
+// in every state (printable, OSC/DCS data, an ESC or DCS final byte).
+const flipLetter = (c: string): string => LETTERS[(LETTERS.indexOf(c) + 1) % LETTERS.length]
+
+// Text, C0 (BEL, CAN, SUB and others), DEL, ESC, the 7-bit introducer letters, 8-bit introducers and
+// other C1, and non-ASCII (U+00A0 is where xterm's NON_ASCII_PRINTABLE starts).
+const SINGLES = [
+ '\x00', '\t', '\n', '\r', BEL, '\x18', '\x1a', '\x19', '\x1c', '\x7f', ESC, ']', 'P', 'X', '^', '_', '[',
+ '\\', ';', '0', '9', ' ', '(', 'é', ' ', '🙂', '\x85', '\x99', '\x9b', '\x9c', '\x9d', '\x90', '\x98',
+ '\x9e', '\x9f'
+]
+const SNIPPETS = [
+ [ESC, ']'], [ESC, 'P'], [ESC, 'X'], [ESC, '^'], [ESC, '_'], [ESC, '\\'], [ESC, '['], [ESC, ESC], [ESC, '\n'],
+ [ESC, '\x7f'], [ESC, '('], [ESC, '\x9d'], ['\x9d'], ['\x90'], ['\x9c'], [BEL],
+ [ESC, ']', '5', '2', ';', 'c', ';'], [ESC, ']', '8', ';', ';'], [ESC, 'P', 'q'], [ESC, 'P', '1', ';', '2', '$', 'q'],
+ ['\x90', 'q'], [ESC, '_', 'G']
+]
+
+/** A random stream as code points, so a join lands between code points like a decoded pty read. */
+function randomStream(rand: (n: number) => number): string[] {
+ const cps: string[] = []
+ for (let parts = 1 + rand(40); parts > 0; parts--) {
+ const kind = rand(10)
+ if (kind < 4) for (let i = 1 + rand(6); i > 0; i--) cps.push(LETTERS[rand(LETTERS.length)])
+ else if (kind < 8) cps.push(...SNIPPETS[rand(SNIPPETS.length)])
+ else cps.push(SINGLES[rand(SINGLES.length)])
+ }
+ return cps
+}
+
+function filterInChunks(text: string, cuts: number[], midStream: boolean): string[] {
+ const f = createStreamFilter(undefined, { midStream })
+ const outs: string[] = []
+ let from = 0
+ for (const to of [...cuts, text.length]) {
+ outs.push(f.push(text.slice(from, to)))
+ from = to
+ }
+ return outs
+}
+
+const codePoints = (s: string): number[] => Array.from(s, (c) => c.codePointAt(0) ?? 0)
+
+/**
+ * Feeds the stream from code point `join` on (xterm itself read it from the start), once as it is
+ * and once with every string-payload letter after the join changed, cut into the same random
+ * chunks; the two outputs must be equal, and xterm must not enter a string reading the output, as a
+ * whole or any one push of it (the caller may drop pushes). Returns how many letters were changed.
+ */
+function checkNothingHiddenReachesOutput(cps: string[], join: number, midStream: boolean, rand: (n: number) => number): number {
+ const payload = xtermStringPayload(cps.map((c) => c.codePointAt(0) ?? 0))
+ let flips = 0
+ const changed = cps.map((c, i) => {
+ if (i < join || !payload[i] || !IS_LETTER.has(c)) return c
+ flips++
+ return flipLetter(c)
+ })
+ const text = cps.slice(join).join('')
+ const cuts: number[] = []
+ for (let k = rand(4); k > 0; k--) cuts.push(rand(text.length + 1))
+ cuts.sort((a, b) => a - b)
+ const outs = filterInChunks(text, cuts, midStream)
+ const out = outs.join('')
+ const ctx = JSON.stringify({ stream: cps.join(''), join, midStream, cuts, out })
+ expect(filterInChunks(changed.slice(join).join(''), cuts, midStream).join(''), ctx).toBe(out)
+ for (const piece of [out, ...outs]) expect(xtermEntersString(codePoints(piece)), ctx).toBe(false)
+ return flips
+}
+
+describe('createStreamFilter against xterm 5.5', () => {
+ it('the model is the installed xterm parser table, verbatim', () => {
+ const fixture = read(join(__dirname, '__fixtures__', 'xterm-vt500.ts'))
+ const constants = read(join(XTERM_PARSER, 'Constants.ts'))
+ const parser = read(join(XTERM_PARSER, 'EscapeSequenceParser.ts'))
+ const blocks: [string, string, string][] = [
+ [constants, 'export const enum ParserState {', '\n}'],
+ [constants, 'export const enum ParserAction {', '\n}'],
+ [parser, 'const enum TableAccess {', '\n}'],
+ [parser, 'export class TransitionTable {', '\n}'],
+ [parser, 'const NON_ASCII_PRINTABLE = 0xA0;', ';'],
+ [parser, 'export const VT500_TRANSITION_TABLE = (function (): TransitionTable {', '\n})();']
+ ]
+ for (const [src, start, end] of blocks) {
+ expect(block(fixture, start, end), `re-copy ${start} from the installed xterm`).toBe(block(src, start, end))
+ }
+ })
+
+ it('nothing xterm hides reaches the output, from the start of a stream', () => {
+ const rand = rng(0xc0ffee)
+ let flips = 0
+ for (let n = 0; n < 3000; n++) flips += checkNothingHiddenReachesOutput(randomStream(rand), 0, false, rand)
+ // Not vacuous: the seeded run changes ~51k payload letters here, ~28k in the midStream run.
+ expect(flips).toBeGreaterThan(20_000)
+ })
+
+ it('nothing xterm hides reaches the output, joined at a random offset (midStream)', () => {
+ const rand = rng(0x10ad)
+ let flips = 0
+ for (let n = 0; n < 3000; n++) {
+ const cps = randomStream(rand)
+ flips += checkNothingHiddenReachesOutput(cps, rand(cps.length + 1), true, rand)
+ }
+ expect(flips).toBeGreaterThan(10_000)
+ })
+})