lib: add AbortSignal.timeout

Refs: whatwg/dom#1032
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: #40899
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Author: jasnell

doc/api/globals.md

@@ -98,6 +98,17 @@ changes:
 
 Returns a new already aborted `AbortSignal`.
 
+#### Static method: `AbortSignal.timeout(delay)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`delay` {number} The number of milliseconds to wait before triggering
+ the AbortSignal.
+
+Returns a new `AbortSignal` which will be aborted in `delay` milliseconds.
+
 #### Event: `'abort'`
 
 <!-- YAML

lib/internal/abort_controller.js

@@ -8,15 +8,20 @@ const {
  ObjectDefineProperties,
  ObjectSetPrototypeOf,
  ObjectDefineProperty,
+ SafeFinalizationRegistry,
+ SafeSet,
  Symbol,
  SymbolToStringTag,
+ WeakRef,
 }=primordials;
 
 const{
  defineEventHandler,
  EventTarget,
  Event,
- kTrustEvent
+ kTrustEvent,
+ kNewListener,
+ kRemoveListener,
 }=require('internal/event_target');
 const{
  customInspectSymbol,
@@ -29,8 +34,26 @@ const {
 }
 }=require('internal/errors');
 
+const{
+ validateUint32,
+}=require('internal/validators');
+
+const{
+ DOMException,
+}=internalBinding('messaging');
+
+const{
+ clearTimeout,
+ setTimeout,
+}=require('timers');
+
 constkAborted=Symbol('kAborted');
 constkReason=Symbol('kReason');
+constkTimeout=Symbol('kTimeout');
+
+consttimeOutSignals=newSafeSet();
+
+constclearTimeoutRegistry=newSafeFinalizationRegistry(clearTimeout);
 
 functioncustomInspect(self,obj,depth,options){
 if(depth<0)
@@ -48,6 +71,30 @@ function validateAbortSignal(obj) {
 thrownewERR_INVALID_THIS('AbortSignal');
 }
 
+// Because the AbortSignal timeout cannot be canceled, we don't want the
+// presence of the timer alone to keep the AbortSignal from being garbage
+// collected if it otherwise no longer accessible. We also don't want the
+// timer to keep the Node.js process open on it's own. Therefore, we wrap
+// the AbortSignal in a WeakRef and have the setTimeout callback close
+// over the WeakRef rather than directly over the AbortSignal, and we unref
+// the created timer object. Separately, we add the signal to a
+// FinalizerRegistry that will clear the timeout when the signal is gc'd.
+functionsetWeakAbortSignalTimeout(weakRef,delay){
+consttimeout=setTimeout(()=>{
+constsignal=weakRef.deref();
+if(signal!==undefined){
+timeOutSignals.delete(signal);
+abortSignal(
+signal,
+newDOMException(
+'The operation was aborted due to timeout',
+'TimeoutError'));
+}
+},delay);
+timeout.unref();
+returntimeout;
+}
+
 classAbortSignalextendsEventTarget{
 constructor(){
 thrownewERR_ILLEGAL_CONSTRUCTOR();
@@ -82,6 +129,42 @@ class AbortSignal extends EventTarget {
 staticabort(reason){
 returncreateAbortSignal(true,reason);
 }
+
+/**
+ * @param {number} delay
+ * @returns {AbortSignal}
+ */
+statictimeout(delay){
+validateUint32(delay,'delay',true);
+constsignal=createAbortSignal();
+signal[kTimeout]=true;
+clearTimeoutRegistry.register(
+signal,
+setWeakAbortSignalTimeout(newWeakRef(signal),delay));
+returnsignal;
+}
+
+[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){
+// 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
+// strong ref that is held for as long as the listener is registered.
+timeOutSignals.add(this);
+}
+}
+
+[kRemoveListener](size,type,listener,capture){
+super[kRemoveListener](size,type,listener,capture);
+if(this[kTimeout]&&type==='abort'&&size===0){
+timeOutSignals.delete(this);
+}
+}
 }
 
 ObjectDefineProperties(AbortSignal.prototype,{

test/parallel/test-abortcontroller.js

@@ -1,10 +1,21 @@
-// Flags: --no-warnings
+// Flags: --no-warnings --expose-gc --expose-internals
 'use strict';
 
 constcommon=require('../common');
 const{ inspect }=require('util');
 
-const{ ok, strictEqual, throws }=require('assert');
+const{
+ ok,
+ notStrictEqual,
+ strictEqual,
+ throws,
+}=require('assert');
+
+const{
+ kWeakHandler,
+}=require('internal/event_target');
+
+const{setTimeout: sleep}=require('timers/promises');
 
 {
 // Tests that abort is fired with the correct event type on AbortControllers
@@ -153,3 +164,69 @@ const { ok, strictEqual, throws } = require('assert');
 constsignal=AbortSignal.abort('reason');
 strictEqual(signal.reason,'reason');
 }
+
+{
+// Test AbortSignal timeout
+constsignal=AbortSignal.timeout(10);
+ok(!signal.aborted);
+setTimeout(common.mustCall(()=>{
+ok(signal.aborted);
+strictEqual(signal.reason.name,'TimeoutError');
+strictEqual(signal.reason.code,23);
+}),20);
+}
+
+{
+(async()=>{
+// Test AbortSignal timeout doesn't prevent the signal
+// from being garbage collected.
+letref;
+{
+ref=newglobalThis.WeakRef(AbortSignal.timeout(1_200_000));
+}
+
+awaitsleep(10);
+globalThis.gc();
+strictEqual(ref.deref(),undefined);
+})().then(common.mustCall());
+
+(async()=>{
+// Test that an AbortSignal with a timeout is not gc'd while
+// there is an active listener on it.
+letref;
+functionhandler(){}
+{
+ref=newglobalThis.WeakRef(AbortSignal.timeout(1_200_000));
+ref.deref().addEventListener('abort',handler);
+}
+
+awaitsleep(10);
+globalThis.gc();
+notStrictEqual(ref.deref(),undefined);
+ok(ref.deref()instanceofAbortSignal);
+
+ref.deref().removeEventListener('abort',handler);
+
+awaitsleep(10);
+globalThis.gc();
+strictEqual(ref.deref(),undefined);
+})().then(common.mustCall());
+
+(async()=>{
+// If the event listener is weak, however, it should not prevent gc
+letref;
+functionhandler(){}
+{
+ref=newglobalThis.WeakRef(AbortSignal.timeout(1_200_000));
+ref.deref().addEventListener('abort',handler,{[kWeakHandler]: {}});
+}
+
+awaitsleep(10);
+globalThis.gc();
+strictEqual(ref.deref(),undefined);
+})().then(common.mustCall());
+
+// Setting a long timeout (20 minutes here) should not
+// keep the Node.js process open (the timer is unref'd)
+AbortSignal.timeout(1_200_000);
+}