lib: refactor transferable AbortSignal

Co-authored-by: James M Snell <[email protected]>
PR-URL: nodejs#44048
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Stephen Belanger <[email protected]>
Reviewed-By: Paolo Insogna <[email protected]>
Reviewed-By: Joyee Cheung <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>

Author: 2 people

doc/api/util.md

@@ -1593,6 +1593,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 });
   }
 
   /**
@@ -256,7 +259,7 @@ class AbortSignal extends EventTarget {
 }
 
 function ClonedAbortSignal() {
-  return createAbortSignal();
+  return createAbortSignal({ transferable: true });
 }
 ClonedAbortSignal.prototype[kDeserialize] = () => {};
 
@@ -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) {
@@ -314,6 +330,30 @@ class AbortController {
       signal: this.signal
     }, depth, options);
   }
+
+  static [kMakeTransferable]() {
+    const controller = new AbortController();
+    controller.#signal = transferableAbortSignal(controller.#signal);
+    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, {
@@ -334,4 +374,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

@@ -78,6 +78,13 @@ const {
   toUSVString,
 } = require('internal/util');
 
+let abortController;
+
+function lazyAbortController() {
+  abortController ??= require('internal/abort_controller');
+  return abortController;
+}
+
 let internalDeepEqual;
 
 /**
@@ -377,5 +384,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]);