h2lean 0.0.0-stage → 0.1.1

package/lib/fast-timer.js

@@ -0,0 +1,436 @@
+'use strict';
+
+// Copied from 'undici'
+//
+// This file is deliberately a byte-for-byte copy of that source, with no local
+// changes, so that it can be lifted out into a standalone npm package and have
+// h2lean require it instead. Any deviation here would make that extraction a
+// merge rather than a move, and would break the upstream tests that come with it.
+//
+// What h2lean uses it for: one shared 499 ms clock for all idle/keep-alive
+// timeouts, instead of one libuv timer handle per connection. See
+// Http2Session.setTimeout() in lib/session.js.
+
+/**
+ * This module offers an optimized timer implementation designed for scenarios
+ * where high precision is not critical.
+ *
+ * The timer achieves faster performance by using a low-resolution approach,
+ * with an accuracy target of within 500ms. This makes it particularly useful
+ * for timers with delays of 1 second or more, where exact timing is less
+ * crucial.
+ *
+ * It's important to note that Node.js timers are inherently imprecise, as
+ * delays can occur due to the event loop being blocked by other operations.
+ * Consequently, timers may trigger later than their scheduled time.
+ */
+
+/**
+ * The fastNow variable contains the internal fast timer clock value.
+ *
+ * @type {number}
+ */
+let fastNow = 0;
+
+/**
+ * RESOLUTION_MS represents the target resolution time in milliseconds.
+ *
+ * @type {number}
+ * @default 1000
+ */
+const RESOLUTION_MS = 1e3;
+
+/**
+ * TICK_MS defines the desired interval in milliseconds between each tick.
+ * The target value is set to half the resolution time, minus 1 ms, to account
+ * for potential event loop overhead.
+ *
+ * @type {number}
+ * @default 499
+ */
+const TICK_MS = (RESOLUTION_MS >> 1) - 1;
+
+/**
+ * fastNowTimeout is a Node.js timer used to manage and process
+ * the FastTimers stored in the `fastTimers` array.
+ *
+ * @type {NodeJS.Timeout}
+ */
+let fastNowTimeout;
+
+/**
+ * The kFastTimer symbol is used to identify FastTimer instances.
+ *
+ * @type {Symbol}
+ */
+const kFastTimer = Symbol('kFastTimer');
+
+/**
+ * The fastTimers array contains all active FastTimers.
+ *
+ * @type {FastTimer[]}
+ */
+const fastTimers = [];
+
+/**
+ * These constants represent the various states of a FastTimer.
+ */
+
+/**
+ * The `NOT_IN_LIST` constant indicates that the FastTimer is not included
+ * in the `fastTimers` array. Timers with this status will not be processed
+ * during the next tick by the `onTick` function.
+ *
+ * A FastTimer can be re-added to the `fastTimers` array by invoking the
+ * `refresh` method on the FastTimer instance.
+ *
+ * @type {-2}
+ */
+const NOT_IN_LIST = -2;
+
+/**
+ * The `TO_BE_CLEARED` constant indicates that the FastTimer is scheduled
+ * for removal from the `fastTimers` array. A FastTimer in this state will
+ * be removed in the next tick by the `onTick` function and will no longer
+ * be processed.
+ *
+ * This status is also set when the `clear` method is called on the FastTimer instance.
+ *
+ * @type {-1}
+ */
+const TO_BE_CLEARED = -1;
+
+/**
+ * The `PENDING` constant signifies that the FastTimer is awaiting processing
+ * in the next tick by the `onTick` function. Timers with this status will have
+ * their `_idleStart` value set and their status updated to `ACTIVE` in the next tick.
+ *
+ * @type {0}
+ */
+const PENDING = 0;
+
+/**
+ * The `ACTIVE` constant indicates that the FastTimer is active and waiting
+ * for its timer to expire. During the next tick, the `onTick` function will
+ * check if the timer has expired, and if so, it will execute the associated callback.
+ *
+ * @type {1}
+ */
+const ACTIVE = 1;
+
+/**
+ * The onTick function processes the fastTimers array.
+ *
+ * @returns {void}
+ */
+function onTick() {
+  /**
+   * Increment the fastNow value by the TICK_MS value, despite the actual time
+   * that has passed since the last tick. This approach ensures independence
+   * from the system clock and delays caused by a blocked event loop.
+   *
+   * @type {number}
+   */
+  fastNow += TICK_MS;
+
+  /**
+   * The `idx` variable is used to iterate over the `fastTimers` array.
+   * Expired timers are removed by replacing them with the last element in the array.
+   * Consequently, `idx` is only incremented when the current element is not removed.
+   *
+   * @type {number}
+   */
+  let idx = 0;
+
+  /**
+   * The len variable will contain the length of the fastTimers array
+   * and will be decremented when a FastTimer should be removed from the
+   * fastTimers array.
+   *
+   * @type {number}
+   */
+  let len = fastTimers.length;
+
+  while (idx < len) {
+    /**
+     * @type {FastTimer}
+     */
+    const timer = fastTimers[idx];
+
+    // If the timer is in the ACTIVE state and the timer has expired, it will
+    // be processed in the next tick.
+    if (timer._state === PENDING) {
+      // Set the _idleStart value to the fastNow value minus the TICK_MS value
+      // to account for the time the timer was in the PENDING state.
+      timer._idleStart = fastNow - TICK_MS;
+      timer._state = ACTIVE;
+    } else if (
+      timer._state === ACTIVE &&
+      fastNow >= timer._idleStart + timer._idleTimeout
+    ) {
+      timer._state = TO_BE_CLEARED;
+      timer._idleStart = -1;
+      timer._onTimeout(timer._timerArg);
+    }
+
+    if (timer._state === TO_BE_CLEARED) {
+      timer._state = NOT_IN_LIST;
+
+      // Move the last element to the current index and decrement len if it is
+      // not the only element in the array.
+      if (--len !== 0) {
+        fastTimers[idx] = fastTimers[len];
+      }
+    } else {
+      ++idx;
+    }
+  }
+
+  // Set the length of the fastTimers array to the new length and thus
+  // removing the excess FastTimers elements from the array.
+  fastTimers.length = len;
+
+  // If there are still active FastTimers in the array, refresh the Timer.
+  // If there are no active FastTimers, the timer will be refreshed again
+  // when a new FastTimer is instantiated.
+  if (fastTimers.length !== 0) {
+    refreshTimeout();
+  }
+}
+
+function refreshTimeout() {
+  // If the fastNowTimeout is already set and the Timer has the refresh()-
+  // method available, call it to refresh the timer.
+  // Some timer objects returned by setTimeout may not have a .refresh()
+  // method (e.g. mocked timers in tests).
+  if (fastNowTimeout?.refresh) {
+    fastNowTimeout.refresh();
+    // fastNowTimeout is not instantiated yet or refresh is not availabe,
+    // create a new Timer.
+  } else {
+    clearTimeout(fastNowTimeout);
+    fastNowTimeout = setTimeout(onTick, TICK_MS);
+    // If the Timer has an unref method, call it to allow the process to exit,
+    // if there are no other active handles. When using fake timers or mocked
+    // environments (like Jest), .unref() may not be defined,
+    fastNowTimeout?.unref();
+  }
+}
+
+/**
+ * The `FastTimer` class is a data structure designed to store and manage
+ * timer information.
+ */
+class FastTimer {
+  [kFastTimer] = true;
+
+  /**
+   * The state of the timer, which can be one of the following:
+   * - NOT_IN_LIST (-2)
+   * - TO_BE_CLEARED (-1)
+   * - PENDING (0)
+   * - ACTIVE (1)
+   *
+   * @type {-2|-1|0|1}
+   * @private
+   */
+  _state = NOT_IN_LIST;
+
+  /**
+   * The number of milliseconds to wait before calling the callback.
+   *
+   * @type {number}
+   * @private
+   */
+  _idleTimeout = -1;
+
+  /**
+   * The time in milliseconds when the timer was started. This value is used to
+   * calculate when the timer should expire.
+   *
+   * @type {number}
+   * @default -1
+   * @private
+   */
+  _idleStart = -1;
+
+  /**
+   * The function to be executed when the timer expires.
+   * @type {Function}
+   * @private
+   */
+  _onTimeout;
+
+  /**
+   * The argument to be passed to the callback when the timer expires.
+   *
+   * @type {*}
+   * @private
+   */
+  _timerArg;
+
+  /**
+   * @constructor
+   * @param {Function} callback A function to be executed after the timer
+   * expires.
+   * @param {number} delay The time, in milliseconds that the timer should wait
+   * before the specified function or code is executed.
+   * @param {*} arg
+   */
+  constructor(callback, delay, arg) {
+    this._onTimeout = callback;
+    this._idleTimeout = delay;
+    this._timerArg = arg;
+
+    this.refresh();
+  }
+
+  /**
+   * Sets the timer's start time to the current time, and reschedules the timer
+   * to call its callback at the previously specified duration adjusted to the
+   * current time.
+   * Using this on a timer that has already called its callback will reactivate
+   * the timer.
+   *
+   * @returns {void}
+   */
+  refresh() {
+    // In the special case that the timer is not in the list of active timers,
+    // add it back to the array to be processed in the next tick by the onTick
+    // function.
+    if (this._state === NOT_IN_LIST) {
+      fastTimers.push(this);
+    }
+
+    // If the timer is the only active timer, refresh the fastNowTimeout for
+    // better resolution.
+    if (!fastNowTimeout || fastTimers.length === 1) {
+      refreshTimeout();
+    }
+
+    // Setting the state to PENDING will cause the timer to be reset in the
+    // next tick by the onTick function.
+    this._state = PENDING;
+  }
+
+  /**
+   * The `clear` method cancels the timer, preventing it from executing.
+   *
+   * @returns {void}
+   * @private
+   */
+  clear() {
+    // Set the state to TO_BE_CLEARED to mark the timer for removal in the next
+    // tick by the onTick function.
+    this._state = TO_BE_CLEARED;
+
+    // Reset the _idleStart value to -1 to indicate that the timer is no longer
+    // active.
+    this._idleStart = -1;
+  }
+}
+
+/**
+ * This module exports a setTimeout and clearTimeout function that can be
+ * used as a drop-in replacement for the native functions.
+ */
+module.exports = {
+  /**
+   * The setTimeout() method sets a timer which executes a function once the
+   * timer expires.
+   * @param {Function} callback A function to be executed after the timer
+   * expires.
+   * @param {number} delay The time, in milliseconds that the timer should
+   * wait before the specified function or code is executed.
+   * @param {*} [arg] An optional argument to be passed to the callback function
+   * when the timer expires.
+   * @returns {NodeJS.Timeout|FastTimer}
+   */
+  setTimeout(callback, delay, arg) {
+    // If the delay is less than or equal to the RESOLUTION_MS value return a
+    // native Node.js Timer instance.
+    return delay <= RESOLUTION_MS
+      ? setTimeout(callback, delay, arg)
+      : new FastTimer(callback, delay, arg);
+  },
+  /**
+   * The clearTimeout method cancels an instantiated Timer previously created
+   * by calling setTimeout.
+   *
+   * @param {NodeJS.Timeout|FastTimer} timeout
+   */
+  clearTimeout(timeout) {
+    // If the timeout is a FastTimer, call its own clear method.
+    if (timeout[kFastTimer]) {
+      /**
+       * @type {FastTimer}
+       */
+      timeout.clear();
+      // Otherwise it is an instance of a native NodeJS.Timeout, so call the
+      // Node.js native clearTimeout function.
+    } else {
+      clearTimeout(timeout);
+    }
+  },
+  /**
+   * The setFastTimeout() method sets a fastTimer which executes a function once
+   * the timer expires.
+   * @param {Function} callback A function to be executed after the timer
+   * expires.
+   * @param {number} delay The time, in milliseconds that the timer should
+   * wait before the specified function or code is executed.
+   * @param {*} [arg] An optional argument to be passed to the callback function
+   * when the timer expires.
+   * @returns {FastTimer}
+   */
+  setFastTimeout(callback, delay, arg) {
+    return new FastTimer(callback, delay, arg);
+  },
+  /**
+   * The clearTimeout method cancels an instantiated FastTimer previously
+   * created by calling setFastTimeout.
+   *
+   * @param {FastTimer} timeout
+   */
+  clearFastTimeout(timeout) {
+    timeout.clear();
+  },
+  /**
+   * The now method returns the value of the internal fast timer clock.
+   *
+   * @returns {number}
+   */
+  now() {
+    return fastNow;
+  },
+  /**
+   * Trigger the onTick function to process the fastTimers array.
+   * Exported for testing purposes only.
+   * Marking as deprecated to discourage any use outside of testing.
+   * @deprecated
+   * @param {number} [delay=0] The delay in milliseconds to add to the now value.
+   */
+  tick(delay = 0) {
+    fastNow += delay - RESOLUTION_MS + 1;
+    onTick();
+    onTick();
+  },
+  /**
+   * Reset FastTimers.
+   * Exported for testing purposes only.
+   * Marking as deprecated to discourage any use outside of testing.
+   * @deprecated
+   */
+  reset() {
+    fastNow = 0;
+    fastTimers.length = 0;
+    clearTimeout(fastNowTimeout);
+    fastNowTimeout = null;
+  },
+  /**
+   * Exporting for testing purposes only.
+   * Marking as deprecated to discourage any use outside of testing.
+   * @deprecated
+   */
+  kFastTimer
+};

package/lib/frames.js

@@ -0,0 +1,127 @@
+// Frame layer: constants and in-place header read/write. Deliberately tiny --
+// a frame is (offset, length) into a caller-provided Buffer, never an object.
+'use strict';
+
+const PREFACE = Buffer.from('PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n');
+const PREFACE_LEN = PREFACE.length;
+const HEADER_LEN = 9;
+
+// Frame types, RFC 9113 §6 and the IANA HTTP/2 frame registry. The numbers are the
+// wire format, not an internal enumeration: a peer sends 9 when it splits a header
+// block, and 10 is ALTSVC (RFC 7807, and RFC 9113 §5.5 says a frame of unknown or
+// unsupported type MUST be discarded). Getting one of these wrong is invisible to our own
+// tests -- both ends would use the same wrong number -- and looks to every other
+// implementation like a connection error, so each value here was checked against a
+// live node:http2 endpoint rather than recalled.
+const DATA = 0, HEADERS = 1, PRIORITY = 2, RST_STREAM = 3, SETTINGS = 4;
+const PUSH_PROMISE = 5, PING = 6, GOAWAY = 7, WINDOW_UPDATE = 8, CONTINUATION = 9;
+
+const F_END_STREAM = 0x1;
+const F_ACK = 0x1;
+const F_END_HEADERS = 0x4;
+const F_PADDED = 0x8;
+const F_PRIORITY = 0x20;
+
+// Wire error codes, RFC 9113 §7. Values verified against http2.constants
+// (NGHTTP2_*), because rstCode/goawayCode are part of the observable API.
+const NO_ERROR = 0, PROTOCOL_ERROR = 1, INTERNAL_ERROR = 2, FLOW_CONTROL_ERROR = 3;
+const SETTINGS_TIMEOUT = 4, STREAM_CLOSED = 5, FRAME_SIZE_ERROR = 6;
+const REFUSED_STREAM = 7, CANCEL = 8, COMPRESSION_ERROR = 9, CONNECT_ERROR = 10;
+const ENHANCE_YOUR_CALM = 11, INADEQUATE_SECURITY = 12, HTTP_1_1_REQUIRED = 13;
+
+// Stream state numbers as node reports them in stream.state.state.
+const ST_IDLE = 1, ST_OPEN = 2, ST_RESERVED_LOCAL = 3, ST_RESERVED_REMOTE = 4;
+const ST_HALF_CLOSED_LOCAL = 5, ST_HALF_CLOSED_REMOTE = 6, ST_CLOSED = 7;
+
+// Results of readHeader land in these module-level slots instead of in a
+// returned object: one allocation avoided per frame.
+let FH_LEN = 0, FH_TYPE = 0, FH_FLAGS = 0, FH_SID = 0;
+
+function readHeader(buf, off) {
+  FH_LEN = (buf[off] << 16) | (buf[off + 1] << 8) | buf[off + 2];
+  FH_TYPE = buf[off + 3];
+  FH_FLAGS = buf[off + 4];
+  FH_SID = buf.readUInt32BE(off + 5) & 0x7fffffff;
+}
+
+function writeHeader(dst, off, len, type, flags, streamId) {
+  dst[off] = len >> 16;
+  dst[off + 1] = len >> 8;
+  dst[off + 2] = len;
+  dst[off + 3] = type;
+  dst[off + 4] = flags;
+  dst.writeUInt32BE(streamId >>> 0, off + 5); // reserved bit stays 0
+}
+
+// RFC 9113 6.1: a padded DATA frame's payload is one octet of pad length, then
+// the data, then that many octets of padding. The views a payload arrived in are
+// therefore not the payload: the pad length has to come off the front and the
+// padding off the back. The pad length is the payload's first octet, so it is
+// known as soon as the payload starts -- there is nothing to wait for.
+//
+// The views are edited in place: the pad length octet is dropped from the first
+// one, the padding from the last one, and the pieces that are left empty are
+// dropped. A frame that arrived in pieces is handed to the application in
+// pieces, and a copy made to trim it would undo that.
+//
+// Returns the number of data octets, or -1 when the frame is malformed: a padded
+// frame with an empty payload has no pad length to read at all, and padding that
+// does not fit in the payload is what RFC 9113 6.1 calls a connection error of
+// type PROTOCOL_ERROR. Node answers both with GOAWAY(PROTOCOL_ERROR) (measured
+// against a live node server, tools/probe-pad-bad.js).
+function trimPadding(pieces) {
+  let first = 0;
+  while (first < pieces.length && pieces[first].length === 0) {
+    first++;
+  }
+  if (first === pieces.length) {
+    return -1;
+  } // no pad length octet
+  const pad = pieces[first][0];
+  pieces[first] = pieces[first].subarray(1); // the pad length is not data
+  let left = pad;
+  for (let i = pieces.length - 1; i >= 0 && left > 0; i--) {
+    const p = pieces[i];
+    if (left >= p.length) {
+      left -= p.length; pieces[i] = null;
+    } else {
+      pieces[i] = p.subarray(0, p.length - left); left = 0;
+    }
+  }
+  if (left > 0) {
+    return -1;
+  } // the padding does not fit
+  let total = 0;
+  for (let i = 0; i < pieces.length; i++) {
+    if (pieces[i] === null || pieces[i].length === 0) {
+      pieces[i] = null; continue;
+    }
+    total += pieces[i].length;
+  }
+  return total;
+}
+
+module.exports = {
+  PREFACE, PREFACE_LEN, HEADER_LEN,
+  DATA, HEADERS, PRIORITY, RST_STREAM, SETTINGS, PUSH_PROMISE, PING, GOAWAY,
+  WINDOW_UPDATE, CONTINUATION,
+  F_END_STREAM, F_ACK, F_END_HEADERS, F_PADDED, F_PRIORITY,
+  NO_ERROR, PROTOCOL_ERROR, INTERNAL_ERROR, FLOW_CONTROL_ERROR, SETTINGS_TIMEOUT,
+  STREAM_CLOSED, FRAME_SIZE_ERROR, REFUSED_STREAM, CANCEL, COMPRESSION_ERROR,
+  CONNECT_ERROR, ENHANCE_YOUR_CALM, INADEQUATE_SECURITY, HTTP_1_1_REQUIRED,
+  ST_IDLE, ST_OPEN, ST_RESERVED_LOCAL, ST_RESERVED_REMOTE,
+  ST_HALF_CLOSED_LOCAL, ST_HALF_CLOSED_REMOTE, ST_CLOSED,
+  readHeader, writeHeader, trimPadding,
+  get FH_LEN() {
+    return FH_LEN;
+  },
+  get FH_TYPE() {
+    return FH_TYPE;
+  },
+  get FH_FLAGS() {
+    return FH_FLAGS;
+  },
+  get FH_SID() {
+    return FH_SID;
+  }
+};