@xterm/xterm 5.4.0-beta.1

package/src/common/input/WriteBuffer.ts

@@ -0,0 +1,246 @@
+
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { EventEmitter } from 'common/EventEmitter';
+import { Disposable } from 'common/Lifecycle';
+
+declare const setTimeout: (handler: () => void, timeout?: number) => void;
+
+/**
+ * Safety watermark to avoid memory exhaustion and browser engine crash on fast data input.
+ * Enable flow control to avoid this limit and make sure that your backend correctly
+ * propagates this to the underlying pty. (see docs for further instructions)
+ * Since this limit is meant as a safety parachute to prevent browser crashs,
+ * it is set to a very high number. Typically xterm.js gets unresponsive with
+ * a 100 times lower number (>500 kB).
+ */
+const DISCARD_WATERMARK = 50000000; // ~50 MB
+
+/**
+ * The max number of ms to spend on writes before allowing the renderer to
+ * catch up with a 0ms setTimeout. A value of < 33 to keep us close to
+ * 30fps, and a value of < 16 to try to run at 60fps. Of course, the real FPS
+ * depends on the time it takes for the renderer to draw the frame.
+ */
+const WRITE_TIMEOUT_MS = 12;
+
+/**
+ * Threshold of max held chunks in the write buffer, that were already processed.
+ * This is a tradeoff between extensive write buffer shifts (bad runtime) and high
+ * memory consumption by data thats not used anymore.
+ */
+const WRITE_BUFFER_LENGTH_THRESHOLD = 50;
+
+export class WriteBuffer extends Disposable {
+  private _writeBuffer: (string | Uint8Array)[] = [];
+  private _callbacks: ((() => void) | undefined)[] = [];
+  private _pendingData = 0;
+  private _bufferOffset = 0;
+  private _isSyncWriting = false;
+  private _syncCalls = 0;
+  private _didUserInput = false;
+
+  private readonly _onWriteParsed = this.register(new EventEmitter<void>());
+  public readonly onWriteParsed = this._onWriteParsed.event;
+
+  constructor(private _action: (data: string | Uint8Array, promiseResult?: boolean) => void | Promise<boolean>) {
+    super();
+  }
+
+  public handleUserInput(): void {
+    this._didUserInput = true;
+  }
+
+  /**
+   * @deprecated Unreliable, to be removed soon.
+   */
+  public writeSync(data: string | Uint8Array, maxSubsequentCalls?: number): void {
+    // stop writeSync recursions with maxSubsequentCalls argument
+    // This is dangerous to use as it will lose the current data chunk
+    // and return immediately.
+    if (maxSubsequentCalls !== undefined && this._syncCalls > maxSubsequentCalls) {
+      // comment next line if a whole loop block should only contain x `writeSync` calls
+      // (total flat vs. deep nested limit)
+      this._syncCalls = 0;
+      return;
+    }
+    // append chunk to buffer
+    this._pendingData += data.length;
+    this._writeBuffer.push(data);
+    this._callbacks.push(undefined);
+
+    // increase recursion counter
+    this._syncCalls++;
+    // exit early if another writeSync loop is active
+    if (this._isSyncWriting) {
+      return;
+    }
+    this._isSyncWriting = true;
+
+    // force sync processing on pending data chunks to avoid in-band data scrambling
+    // does the same as innerWrite but without event loop
+    // we have to do it here as single loop steps to not corrupt loop subject
+    // by another writeSync call triggered from _action
+    let chunk: string | Uint8Array | undefined;
+    while (chunk = this._writeBuffer.shift()) {
+      this._action(chunk);
+      const cb = this._callbacks.shift();
+      if (cb) cb();
+    }
+    // reset to avoid reprocessing of chunks with scheduled innerWrite call
+    // stopping scheduled innerWrite by offset > length condition
+    this._pendingData = 0;
+    this._bufferOffset = 0x7FFFFFFF;
+
+    // allow another writeSync to loop
+    this._isSyncWriting = false;
+    this._syncCalls = 0;
+  }
+
+  public write(data: string | Uint8Array, callback?: () => void): void {
+    if (this._pendingData > DISCARD_WATERMARK) {
+      throw new Error('write data discarded, use flow control to avoid losing data');
+    }
+
+    // schedule chunk processing for next event loop run
+    if (!this._writeBuffer.length) {
+      this._bufferOffset = 0;
+
+      // If this is the first write call after the user has done some input,
+      // parse it immediately to minimize input latency,
+      // otherwise schedule for the next event
+      if (this._didUserInput) {
+        this._didUserInput = false;
+        this._pendingData += data.length;
+        this._writeBuffer.push(data);
+        this._callbacks.push(callback);
+        this._innerWrite();
+        return;
+      }
+
+      setTimeout(() => this._innerWrite());
+    }
+
+    this._pendingData += data.length;
+    this._writeBuffer.push(data);
+    this._callbacks.push(callback);
+  }
+
+  /**
+   * Inner write call, that enters the sliced chunk processing by timing.
+   *
+   * `lastTime` indicates, when the last _innerWrite call had started.
+   * It is used to aggregate async handler execution under a timeout constraint
+   * effectively lowering the redrawing needs, schematically:
+   *
+   *   macroTask _innerWrite:
+   *     if (Date.now() - (lastTime | 0) < WRITE_TIMEOUT_MS):
+   *        schedule microTask _innerWrite(lastTime)
+   *     else:
+   *        schedule macroTask _innerWrite(0)
+   *
+   *   overall execution order on task queues:
+   *
+   *   macrotasks:  [...]  -->  _innerWrite(0)  -->  [...]  -->  screenUpdate  -->  [...]
+   *         m  t:                    |
+   *         i  a:                  [...]
+   *         c  s:                    |
+   *         r  k:              while < timeout:
+   *         o  s:                _innerWrite(timeout)
+   *
+   * `promiseResult` depicts the promise resolve value of an async handler.
+   * This value gets carried forward through all saved stack states of the
+   * paused parser for proper continuation.
+   *
+   * Note, for pure sync code `lastTime` and `promiseResult` have no meaning.
+   */
+  protected _innerWrite(lastTime: number = 0, promiseResult: boolean = true): void {
+    const startTime = lastTime || Date.now();
+    while (this._writeBuffer.length > this._bufferOffset) {
+      const data = this._writeBuffer[this._bufferOffset];
+      const result = this._action(data, promiseResult);
+      if (result) {
+        /**
+         * If we get a promise as return value, we re-schedule the continuation
+         * as thenable on the promise and exit right away.
+         *
+         * The exit here means, that we block input processing at the current active chunk,
+         * the exact execution position within the chunk is preserved by the saved
+         * stack content in InputHandler and EscapeSequenceParser.
+         *
+         * Resuming happens automatically from that saved stack state.
+         * Also the resolved promise value is passed along the callstack to
+         * `EscapeSequenceParser.parse` to correctly resume the stopped handler loop.
+         *
+         * Exceptions on async handlers will be logged to console async, but do not interrupt
+         * the input processing (continues with next handler at the current input position).
+         */
+
+        /**
+         * If a promise takes long to resolve, we should schedule continuation behind setTimeout.
+         * This might already be too late, if our .then enters really late (executor + prev thens
+         * took very long). This cannot be solved here for the handler itself (it is the handlers
+         * responsibility to slice hard work), but we can at least schedule a screen update as we
+         * gain control.
+         */
+        const continuation: (r: boolean) => void = (r: boolean) => Date.now() - startTime >= WRITE_TIMEOUT_MS
+          ? setTimeout(() => this._innerWrite(0, r))
+          : this._innerWrite(startTime, r);
+
+        /**
+         * Optimization considerations:
+         * The continuation above favors FPS over throughput by eval'ing `startTime` on resolve.
+         * This might schedule too many screen updates with bad throughput drops (in case a slow
+         * resolving handler sliced its work properly behind setTimeout calls). We cannot spot
+         * this condition here, also the renderer has no way to spot nonsense updates either.
+         * FIXME: A proper fix for this would track the FPS at the renderer entry level separately.
+         *
+         * If favoring of FPS shows bad throughtput impact, use the following instead. It favors
+         * throughput by eval'ing `startTime` upfront pulling at least one more chunk into the
+         * current microtask queue (executed before setTimeout).
+         */
+        // const continuation: (r: boolean) => void = Date.now() - startTime >= WRITE_TIMEOUT_MS
+        //   ? r => setTimeout(() => this._innerWrite(0, r))
+        //   : r => this._innerWrite(startTime, r);
+
+        // Handle exceptions synchronously to current band position, idea:
+        // 1. spawn a single microtask which we allow to throw hard
+        // 2. spawn a promise immediately resolving to `true`
+        // (executed on the same queue, thus properly aligned before continuation happens)
+        result.catch(err => {
+          queueMicrotask(() => {throw err;});
+          return Promise.resolve(false);
+        }).then(continuation);
+        return;
+      }
+
+      const cb = this._callbacks[this._bufferOffset];
+      if (cb) cb();
+      this._bufferOffset++;
+      this._pendingData -= data.length;
+
+      if (Date.now() - startTime >= WRITE_TIMEOUT_MS) {
+        break;
+      }
+    }
+    if (this._writeBuffer.length > this._bufferOffset) {
+      // Allow renderer to catch up before processing the next batch
+      // trim already processed chunks if we are above threshold
+      if (this._bufferOffset > WRITE_BUFFER_LENGTH_THRESHOLD) {
+        this._writeBuffer = this._writeBuffer.slice(this._bufferOffset);
+        this._callbacks = this._callbacks.slice(this._bufferOffset);
+        this._bufferOffset = 0;
+      }
+      setTimeout(() => this._innerWrite());
+    } else {
+      this._writeBuffer.length = 0;
+      this._callbacks.length = 0;
+      this._pendingData = 0;
+      this._bufferOffset = 0;
+    }
+    this._onWriteParsed.fire();
+  }
+}

package/src/common/input/XParseColor.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) 2021 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+
+// 'rgb:' rule - matching: r/g/b | rr/gg/bb | rrr/ggg/bbb | rrrr/gggg/bbbb (hex digits)
+const RGB_REX = /^([\da-f])\/([\da-f])\/([\da-f])$|^([\da-f]{2})\/([\da-f]{2})\/([\da-f]{2})$|^([\da-f]{3})\/([\da-f]{3})\/([\da-f]{3})$|^([\da-f]{4})\/([\da-f]{4})\/([\da-f]{4})$/;
+// '#...' rule - matching any hex digits
+const HASH_REX = /^[\da-f]+$/;
+
+/**
+ * Parse color spec to RGB values (8 bit per channel).
+ * See `man xparsecolor` for details about certain format specifications.
+ *
+ * Supported formats:
+ * - rgb:<red>/<green>/<blue> with <red>, <green>, <blue> in h | hh | hhh | hhhh
+ * - #RGB, #RRGGBB, #RRRGGGBBB, #RRRRGGGGBBBB
+ *
+ * All other formats like rgbi: or device-independent string specifications
+ * with float numbering are not supported.
+ */
+export function parseColor(data: string): [number, number, number] | undefined {
+  if (!data) return;
+  // also handle uppercases
+  let low = data.toLowerCase();
+  if (low.indexOf('rgb:') === 0) {
+    // 'rgb:' specifier
+    low = low.slice(4);
+    const m = RGB_REX.exec(low);
+    if (m) {
+      const base = m[1] ? 15 : m[4] ? 255 : m[7] ? 4095 : 65535;
+      return [
+        Math.round(parseInt(m[1] || m[4] || m[7] || m[10], 16) / base * 255),
+        Math.round(parseInt(m[2] || m[5] || m[8] || m[11], 16) / base * 255),
+        Math.round(parseInt(m[3] || m[6] || m[9] || m[12], 16) / base * 255)
+      ];
+    }
+  } else if (low.indexOf('#') === 0) {
+    // '#' specifier
+    low = low.slice(1);
+    if (HASH_REX.exec(low) && [3, 6, 9, 12].includes(low.length)) {
+      const adv = low.length / 3;
+      const result: [number, number, number] = [0, 0, 0];
+      for (let i = 0; i < 3; ++i) {
+        const c = parseInt(low.slice(adv * i, adv * i + adv), 16);
+        result[i] = adv === 1 ? c << 4 : adv === 2 ? c : adv === 3 ? c >> 4 : c >> 8;
+      }
+      return result;
+    }
+  }
+
+  // Named colors are currently not supported due to the large addition to the xterm.js bundle size
+  // they would add. In order to support named colors, we would need some way of optionally loading
+  // additional payloads so startup/download time is not bloated (see #3530).
+}
+
+// pad hex output to requested bit width
+function pad(n: number, bits: number): string {
+  const s = n.toString(16);
+  const s2 = s.length < 2 ? '0' + s : s;
+  switch (bits) {
+    case 4:
+      return s[0];
+    case 8:
+      return s2;
+    case 12:
+      return (s2 + s2).slice(0, 3);
+    default:
+      return s2 + s2;
+  }
+}
+
+/**
+ * Convert a given color to rgb:../../.. string of `bits` depth.
+ */
+export function toRgbString(color: [number, number, number], bits: number = 16): string {
+  const [r, g, b] = color;
+  return `rgb:${pad(r, bits)}/${pad(g, bits)}/${pad(b, bits)}`;
+}

package/src/common/parser/Constants.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) 2017 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+/**
+ * Internal states of EscapeSequenceParser.
+ */
+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
+}
+
+/**
+ * Internal actions of EscapeSequenceParser.
+ */
+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
+}
+
+/**
+ * Internal states of OscParser.
+ */
+export const enum OscState {
+  START = 0,
+  ID = 1,
+  PAYLOAD = 2,
+  ABORT = 3
+}
+
+// payload limit for OSC and DCS
+export const PAYLOAD_LIMIT = 10000000;

package/src/common/parser/DcsParser.ts

@@ -0,0 +1,192 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IDisposable } from 'common/Types';
+import { IDcsHandler, IParams, IHandlerCollection, IDcsParser, DcsFallbackHandlerType, ISubParserStackState } from 'common/parser/Types';
+import { utf32ToString } from 'common/input/TextDecoder';
+import { Params } from 'common/parser/Params';
+import { PAYLOAD_LIMIT } from 'common/parser/Constants';
+
+const EMPTY_HANDLERS: IDcsHandler[] = [];
+
+export class DcsParser implements IDcsParser {
+  private _handlers: IHandlerCollection<IDcsHandler> = Object.create(null);
+  private _active: IDcsHandler[] = EMPTY_HANDLERS;
+  private _ident: number = 0;
+  private _handlerFb: DcsFallbackHandlerType = () => { };
+  private _stack: ISubParserStackState = {
+    paused: false,
+    loopPosition: 0,
+    fallThrough: false
+  };
+
+  public dispose(): void {
+    this._handlers = Object.create(null);
+    this._handlerFb = () => { };
+    this._active = EMPTY_HANDLERS;
+  }
+
+  public registerHandler(ident: number, handler: IDcsHandler): IDisposable {
+    if (this._handlers[ident] === undefined) {
+      this._handlers[ident] = [];
+    }
+    const handlerList = this._handlers[ident];
+    handlerList.push(handler);
+    return {
+      dispose: () => {
+        const handlerIndex = handlerList.indexOf(handler);
+        if (handlerIndex !== -1) {
+          handlerList.splice(handlerIndex, 1);
+        }
+      }
+    };
+  }
+
+  public clearHandler(ident: number): void {
+    if (this._handlers[ident]) delete this._handlers[ident];
+  }
+
+  public setHandlerFallback(handler: DcsFallbackHandlerType): void {
+    this._handlerFb = handler;
+  }
+
+  public reset(): void {
+    // force cleanup leftover handlers
+    if (this._active.length) {
+      for (let j = this._stack.paused ? this._stack.loopPosition - 1 : this._active.length - 1; j >= 0; --j) {
+        this._active[j].unhook(false);
+      }
+    }
+    this._stack.paused = false;
+    this._active = EMPTY_HANDLERS;
+    this._ident = 0;
+  }
+
+  public hook(ident: number, params: IParams): void {
+    // always reset leftover handlers
+    this.reset();
+    this._ident = ident;
+    this._active = this._handlers[ident] || EMPTY_HANDLERS;
+    if (!this._active.length) {
+      this._handlerFb(this._ident, 'HOOK', params);
+    } else {
+      for (let j = this._active.length - 1; j >= 0; j--) {
+        this._active[j].hook(params);
+      }
+    }
+  }
+
+  public put(data: Uint32Array, start: number, end: number): void {
+    if (!this._active.length) {
+      this._handlerFb(this._ident, 'PUT', utf32ToString(data, start, end));
+    } else {
+      for (let j = this._active.length - 1; j >= 0; j--) {
+        this._active[j].put(data, start, end);
+      }
+    }
+  }
+
+  public unhook(success: boolean, promiseResult: boolean = true): void | Promise<boolean> {
+    if (!this._active.length) {
+      this._handlerFb(this._ident, 'UNHOOK', success);
+    } else {
+      let handlerResult: boolean | Promise<boolean> = false;
+      let j = this._active.length - 1;
+      let fallThrough = false;
+      if (this._stack.paused) {
+        j = this._stack.loopPosition - 1;
+        handlerResult = promiseResult;
+        fallThrough = this._stack.fallThrough;
+        this._stack.paused = false;
+      }
+      if (!fallThrough && handlerResult === false) {
+        for (; j >= 0; j--) {
+          handlerResult = this._active[j].unhook(success);
+          if (handlerResult === true) {
+            break;
+          } else if (handlerResult instanceof Promise) {
+            this._stack.paused = true;
+            this._stack.loopPosition = j;
+            this._stack.fallThrough = false;
+            return handlerResult;
+          }
+        }
+        j--;
+      }
+      // cleanup left over handlers (fallThrough for async)
+      for (; j >= 0; j--) {
+        handlerResult = this._active[j].unhook(false);
+        if (handlerResult instanceof Promise) {
+          this._stack.paused = true;
+          this._stack.loopPosition = j;
+          this._stack.fallThrough = true;
+          return handlerResult;
+        }
+      }
+    }
+    this._active = EMPTY_HANDLERS;
+    this._ident = 0;
+  }
+}
+
+// predefine empty params as [0] (ZDM)
+const EMPTY_PARAMS = new Params();
+EMPTY_PARAMS.addParam(0);
+
+/**
+ * Convenient class to create a DCS handler from a single callback function.
+ * Note: The payload is currently limited to 50 MB (hardcoded).
+ */
+export class DcsHandler implements IDcsHandler {
+  private _data = '';
+  private _params: IParams = EMPTY_PARAMS;
+  private _hitLimit: boolean = false;
+
+  constructor(private _handler: (data: string, params: IParams) => boolean | Promise<boolean>) { }
+
+  public hook(params: IParams): void {
+    // since we need to preserve params until `unhook`, we have to clone it
+    // (only borrowed from parser and spans multiple parser states)
+    // perf optimization:
+    // clone only, if we have non empty params, otherwise stick with default
+    this._params = (params.length > 1 || params.params[0]) ? params.clone() : EMPTY_PARAMS;
+    this._data = '';
+    this._hitLimit = false;
+  }
+
+  public put(data: Uint32Array, start: number, end: number): void {
+    if (this._hitLimit) {
+      return;
+    }
+    this._data += utf32ToString(data, start, end);
+    if (this._data.length > PAYLOAD_LIMIT) {
+      this._data = '';
+      this._hitLimit = true;
+    }
+  }
+
+  public unhook(success: boolean): boolean | Promise<boolean> {
+    let ret: boolean | Promise<boolean> = false;
+    if (this._hitLimit) {
+      ret = false;
+    } else if (success) {
+      ret = this._handler(this._data, this._params);
+      if (ret instanceof Promise) {
+        // need to hold data and params until `ret` got resolved
+        // dont care for errors, data will be freed anyway on next start
+        return ret.then(res => {
+          this._params = EMPTY_PARAMS;
+          this._data = '';
+          this._hitLimit = false;
+          return res;
+        });
+      }
+    }
+    this._params = EMPTY_PARAMS;
+    this._data = '';
+    this._hitLimit = false;
+    return ret;
+  }
+}