lib: refactor transferable AbortSignal

Co-authored-by: James M Snell <jasnell@gmail.com> PR-URL: #44048 Backport-PR-URL: #44941 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: 2 people

doc/api/util.md

@@ -1597,6 +1597,37 @@ Returns the `string` after replacing any surrogate code points
 (or equivalently, any unpaired surrogate code units) with the
 Unicode "replacement character" U+FFFD.
 
+## `util.transferableAbortController()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Creates and returns an {AbortController} instance whose {AbortSignal} is marked
+as transferable and can be used with `structuredClone()` or `postMessage()`.
+
+## `util.transferableAbortSignal(signal)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `signal` {AbortSignal}
+* Returns: {AbortSignal}
+
+Marks the given {AbortSignal} as transferable so that it can be used with
+`structuredClone()` and `postMessage()`.
+
+```js
+const signal = transferableAbortSignal(AbortSignal.timeout(100));
+const channel = new MessageChannel();
+channel.port2.postMessage(signal, [signal]);
+```
+
 ## `util.types`
 
 <!-- YAML

lib/internal/abort_controller.js

@@ -26,11 +26,13 @@ const {
 const {
  customInspectSymbol,
  kEnumerableProperty,
+ kEmptyObject,
 } = require('internal/util');
 const { inspect } = require('internal/util/inspect');
 const {
  codes: {
  ERR_ILLEGAL_CONSTRUCTOR,
+ ERR_INVALID_ARG_TYPE,
  ERR_INVALID_THIS,
  }
 } = require('internal/errors');
@@ -79,6 +81,7 @@ const kAborted = Symbol('kAborted');
 const kReason = Symbol('kReason');
 const kCloneData = Symbol('kCloneData');
 const kTimeout = Symbol('kTimeout');
+const kMakeTransferable = Symbol('kMakeTransferable');
 
 function customInspect(self, obj, depth, options) {
  if (depth < 0)
@@ -159,7 +162,7 @@ class AbortSignal extends EventTarget {
  */
  static abort(
  reason = new DOMException('This operation was aborted', 'AbortError')) {
- return createAbortSignal(true, reason);
+ return createAbortSignal({ aborted: true, reason });
  }
 
  /**
@@ -179,10 +182,10 @@ class AbortSignal extends EventTarget {
  [kNewListener](size, type, listener, once, capture, passive, weak) {
  super[kNewListener](size, type, listener, once, capture, passive, weak);
  if (this[kTimeout] &&
-  type === 'abort' &&
-  !this.aborted &&
-  !weak &&
-  size === 1) {
+ type === 'abort' &&
+ !this.aborted &&
+ !weak &&
+ size === 1) {
  // If this is a timeout signal, and we're adding a non-weak abort
  // listener, then we don't want it to be gc'd while the listener
  // is attached and the timer still hasn't fired. So, we retain a
@@ -256,9 +259,9 @@ class AbortSignal extends EventTarget {
 }
 
 function ClonedAbortSignal() {
- return createAbortSignal();
+ return createAbortSignal({ transferable: true });
 }
-ClonedAbortSignal.prototype[kDeserialize] = () => {};
+ClonedAbortSignal.prototype[kDeserialize] = () => { };
 
 ObjectDefineProperties(AbortSignal.prototype, {
  aborted: kEnumerableProperty,
@@ -274,12 +277,25 @@ ObjectDefineProperty(AbortSignal.prototype, SymbolToStringTag, {
 
 defineEventHandler(AbortSignal.prototype, 'abort');
 
-function createAbortSignal(aborted = false, reason = undefined) {
+/**
+ * @param {{
+ * aborted? : boolean,
+ * reason? : any,
+ * transferable? : boolean
+ * }} [init]
+ * @returns {AbortSignal}
+ */
+function createAbortSignal(init = kEmptyObject) {
+ const {
+ aborted = false,
+ reason = undefined,
+ transferable = false,
+ } = init;
  const signal = new EventTarget();
  ObjectSetPrototypeOf(signal, AbortSignal.prototype);
  signal[kAborted] = aborted;
  signal[kReason] = reason;
- return lazyMakeTransferable(signal);
+ return transferable ? lazyMakeTransferable(signal) : signal;
 }
 
 function abortSignal(signal, reason) {
@@ -327,6 +343,30 @@ class AbortController {
  signal: this.signal
  }, depth, options);
  }
+
+ static [kMakeTransferable]() {
+ const controller = new AbortController();
+ controller[kSignal] = transferableAbortSignal(controller[kSignal]);
+ return controller;
+ }
+}
+
+/**
+ * Enables the AbortSignal to be transferable using structuredClone/postMessage.
+ * @param {AbortSignal} signal
+ * @returns {AbortSignal}
+ */
+function transferableAbortSignal(signal) {
+ if (signal?.[kAborted] === undefined)
+ throw new ERR_INVALID_ARG_TYPE('signal', 'AbortSignal', signal);
+ return lazyMakeTransferable(signal);
+}
+
+/**
+ * Creates an AbortController with a transferable AbortSignal
+ */
+function transferableAbortController() {
+ return AbortController[kMakeTransferable]();
 }
 
 ObjectDefineProperties(AbortController.prototype, {
@@ -347,4 +387,6 @@ module.exports = {
  AbortController,
  AbortSignal,
  ClonedAbortSignal,
+ transferableAbortSignal,
+ transferableAbortController,
 };

lib/internal/worker/js_transferable.js

@@ -40,6 +40,8 @@ function setup() {
 }
 
 function makeTransferable(obj) {
+ // If the object is already transferable, skip all this.
+ if (obj instanceof JSTransferable) return obj;
  const inst = ReflectConstruct(JSTransferable, [], obj.constructor);
  const properties = ObjectGetOwnPropertyDescriptors(obj);
  const propertiesValues = ObjectValues(properties);

lib/util.js

@@ -79,6 +79,13 @@ const {
  toUSVString,
 } = require('internal/util');
 
+let abortController;
+
+function lazyAbortController() {
+ abortController ??= require('internal/abort_controller');
+ return abortController;
+}
+
 let internalDeepEqual;
 
 /**
@@ -384,5 +391,11 @@ module.exports = {
  toUSVString,
  TextDecoder,
  TextEncoder,
+ get transferableAbortSignal() {
+ return lazyAbortController().transferableAbortSignal;
+ },
+ get transferableAbortController() {
+ return lazyAbortController().transferableAbortController;
+ },
  types
 };

test/parallel/test-abortsignal-cloneable.js

@@ -3,6 +3,11 @@
 const common = require('../common');
 const { ok, strictEqual } = require('assert');
 const { setImmediate: pause } = require('timers/promises');
+const {
+ transferableAbortSignal,
+ transferableAbortController,
+} = require('util');
+
 
 function deferred() {
  let res;
@@ -11,7 +16,7 @@ function deferred() {
 }
 
 (async () => {
- const ac = new AbortController();
+ const ac = transferableAbortController();
  const mc = new MessageChannel();
 
  const deferred1 = deferred();
@@ -54,7 +59,7 @@ function deferred() {
 })().then(common.mustCall());
 
 {
- const signal = AbortSignal.abort('boom');
+ const signal = transferableAbortSignal(AbortSignal.abort('boom'));
  ok(signal.aborted);
  strictEqual(signal.reason, 'boom');
  const mc = new MessageChannel();
@@ -70,7 +75,7 @@ function deferred() {
 {
  // The cloned AbortSignal does not keep the event loop open
  // waiting for the abort to be triggered.
- const ac = new AbortController();
+ const ac = transferableAbortController();
  const mc = new MessageChannel();
  mc.port1.onmessage = common.mustCall();
  mc.port2.postMessage(ac.signal, [ac.signal]);