Introduce AbortSignal.timeout()

[domenic]

Closes #951.

Mini-explainer for TAG review/blink-dev purposes:

This introduces a new static method, AbortSignal.timeout(milliseconds), which returns a newly-created AbortSignal that, after milliseconds milliseconds, becomes automatically aborted. The AbortSignal's reason property will be a "TimeoutError" DOMException.

The main motivating use case for this is helping web developers easily time out async operations, such as fetch(). For example, now you can write:

fetch(url, { signal: AbortSignal.timeout(10_000) });

to ensure your fetch operation has a 10-second timeout. A more full example would be:

try {
  const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
  const result = await res.text();
  // ...
} catch (e) {
  if (e.name === "TimeoutError") {
    // It took more than 10 seconds to get the result!
  } else if (e.name === "AbortError") {
    // The fetch was explicitly aborted, e.g. by the user pressing the stop button!
  } else {
    // Something horrible went wrong, like a network error!
  }
}

This has come up in the context of several specs; see discussions on fetch at whatwg/fetch#951 and streams at WICG/serial#122 (comment). It is generally helpful for any operation that takes an AbortSignal, including web-developer-defined operations.

Interesting points of discussion are:

• It is specifically important that the reason be a "TimeoutError" DOMException, instead of the default-for-AbortSignal "AbortError" DOMException. This is because developers almost always want to discriminate between those two: a timeout is a proper failure which they might show to users, whereas an abort usually more of a "third state" (alongside success and failure) which usually they don't want to tell users about. (E.g., because the user is the one that caused the abort in the first place.)

• We treat the milliseconds argument the same as scheduler.postTask(), and almost the same as setTimeout(). (The difference is, we don't have the nested-clamping-to-4-ms behavior that setTimeout() does.) In particular this means that the timer does not advance while the document is in bfcache, or the worker is suspended. See Introduce AbortSignal.timeout() #1032 (comment) for the reasoning there.

Future work: this feature would benefit greatly from a solution for combining AbortSignals, so that people could have an operation that aborts on either a timeout or an explicit abort. For example, something like this:

// NOT REAL CODE, YET:
const controller = new AbortController();
fetch(url, { signal: AbortSignal.all([AbortSignal.timeout(10_000), controller.signal]) });

abortButton.onclick = () => controller.abort();

Unfortunately there are a lot of possible shapes for such an API and so we still need to do a bit more work and research to find the best one. That's tracked in #920. Until then, people can combine such signals manually, as discussed in that issue thread.

• At least two implementers are interested (and none opposed):
  • Chromium
  • Gecko
• Tests are written and can be reviewed and commented upon at:
  • Implement AbortSignal.timeout web-platform-tests/wpt#32622
• Implementation bugs are filed:
  • Chrome: https://bugs.chromium.org/p/chromium/issues/detail?id=1181925
  • Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1753309
  • Safari: https://bugs.webkit.org/show_bug.cgi?id=236039

(See WHATWG Working Mode: Changes for more details.)

---

Now-obsolete discussion of "Subtle things to deal with"

• Need to export "timer task source" from HTML
• What portions of the delay logic from setTimeout and postTask should we port over here?
  • I so far ported: wait milliseconds; ensure ordering within a global; and allow implementation-defined extra waiting (e.g. to align on CPU wakeups or allow throttling while in the background).
  • I'm on the fence as to whether we should port suspending the timer while the document is in bfcache or the worker is suspended. For e.g. fetch timeouts, it doesn't seem to matter much whether you were in bfcache/suspended; if the server took 30 wall-clock seconds to respond, you probably want to give up. On the other hand, it might be strange (or hard to implement) for this timer mechanism to behave differently from others on the platform.
  • Should these timers impact idle callback deadline computation? postTask timers do not, but that may be an oversight. @shaseley @noamr
  • I think that, like postTask, we should not port the nesting and clamping messiness from setTimeout. The implementation-defined extra time is enough.
• Probably it's time to centralize this delay logic so that this spec, HTML, and postTask can reuse it. But we'd need to decide on the above questions first.

---

Preview | Diff

---

Preview | Diff

[shaseley]

• Should these timers impact idle callback deadline computation? postTask timers do not, but that may be an oversight. @shaseley @noamr

Ah, yeah it's an oversight if postTask timers don't affect the idle deadline computation, and they do in our implementation. Looks like we'll need to insert an entry into that map, but it looks like that might also require moving handle outside of setTimeout spec?

[domenic]

Yeah, in that case I will work on a HTML spec PR pulling out the common infrastructure. For now it will behave exactly like the shared parts of postTask/setTimeout. If we decide AbortSignal.timeout() should behave the same as those with regard to bfcache/suspended workers then this PR can just use that; otherwise we can add a flag.

[domenic]

I did the centralization work at whatwg/html#7349, and sent WICG/scheduling-apis#54 plus updated this PR to match.

Now this PR does pause the timeout while in bfcache/while the worker is suspended. We should discuss whether that's a good idea or not; it's certainly the path of least resistance.

[annevk]

I like it! And yeah, Mozilla can be considered supportive.

[domenic]

I was going to write a big comment with the pros/cons of suspending while in bfcache/in a worker. But in the end it mostly ended up with pros for suspended. So I am currently advocating we keep the setTimeout() behavior here, i.e. if you do AbortSignal.timeout(10_000), you need to spend 10 seconds active before the signal aborts, not 10 seconds wall time.

Here's was my thought process on the pros/cons of suspending:

• (+) Matches setTimeout() so might be more expected for developers
• (+) Easier to spec and probably easier to implement
• (+/-) Avoids "timer storms" upon reactivation
• (-? but not really) Seemingly doesn't match the primary use case that well, of erroring an operation if it took too long. E.g. if you use fetch(..., { signal: AbortSignal.timeout(30_000) }), and the server still hasn't responded after 30 seconds, you don't care whether some of those 30 seconds were spent in bfcache: the server is probably not going to respond.
  • This is why the "timer storms" argument is both a pro and a con: having a bunch of stuff get aborted upon bfcache restore, because it took too long, actually seems OK! It's very different than running a bunch of code upon bfcache restore, which is what you would expect with setTimeout().
  • On the other hand, I believe this scenario isn't realistic: if you go into bfcache, I'm pretty sure all ongoing fetches will be aborted immediately anyway. (Or maybe we just won't let you go into bfcache with ongoing fetches; not sure.)
  • Finally, what really swung this for me was remembering that we use fetch()'s signal for more than just the network operation: we use it for, e.g., JSON decoding or other consume-body operations. So consider the scenario where the server responds, and perhaps even all of the body is read into memory. But then we go into bfcache, before the promise returned from json() can fulfill. If we spend a minute in bfcache and then go back, we don't really want the promise to reject; we want it to do that last tiny bit of work, and fulfill! I think this is probably a specific case of a more general scenario, possibly involving non-browser APIs that use AbortSignal and care about timeouts.

@shaseley, does this reasoning seem reasonable to you? I'd like to have your blessing on our decision here, as the person who has thought most about these sorts of timing and scheduling things in Chromium :)

[shaseley]

Yep, this sounds reasonable; suspending in bfcache LGTM. These roughly match what I've been thinking, and great point about how fetch's signal is used for more than just the network operation. A few more thoughts inline below:

Here's was my thought process on the pros/cons of suspending:

• (+) Matches setTimeout() so might be more expected for developers

Note: this is unfortunately broken in in Chromium, but I do like the consistency.

• (+) Easier to spec and probably easier to implement

• (+/-) Avoids "timer storms" upon reactivation

• (-? but not really) Seemingly doesn't match the primary use case that well, of erroring an operation if it took too long. E.g. if you use fetch(..., { signal: AbortSignal.timeout(30_000) }), and the server still hasn't responded after 30 seconds, you don't care whether some of those 30 seconds were spent in bfcache: the server is probably not going to respond.

  • This is why the "timer storms" argument is both a pro and a con: having a bunch of stuff get aborted upon bfcache restore, because it took too long, actually seems OK! It's very different than running a bunch of code upon bfcache restore, which is what you would expect with setTimeout().

Yeah aborting stuff on restore would be good in this scenario, although timer storms could still result if these signals have abort event listeners that do a bunch of work in response to the error.

• On the other hand, I believe this scenario isn't realistic: if you go into bfcache, I'm pretty sure all ongoing fetches will be aborted immediately anyway. (Or maybe we just won't let you go into bfcache with ongoing fetches; not sure.)

We're recommending that devs close connections in pagehide, and that article is leading me to believe pages with ongoing fetches aren't eligible for bfcache in Chromium. I'm not sure about other browsers.

Combining a timeout signal with one that gets aborted on pagehide seems like maybe a good option? If we can make it more ergonomic to combine signals that would be even better. (Although, you might get into scenarios where you have the data but end up aborting the processing like you're describing below.)

• Finally, what really swung this for me was remembering that we use fetch()'s signal for more than just the network operation: we use it for, e.g., JSON decoding or other consume-body operations. So consider the scenario where the server responds, and perhaps even all of the body is read into memory. But then we go into bfcache, before the promise returned from json() can fulfill. If we spend a minute in bfcache and then go back, we don't really want the promise to reject; we want it to do that last tiny bit of work, and fulfill! I think this is probably a specific case of a more general scenario, possibly involving non-browser APIs that use AbortSignal and care about timeouts.

[annevk]

The main thing I'm worried about for Firefox is that I think @farre or @smaug---- at some point mentioned to me that the clamping logic sits pretty deep in our timeout code. And beyond that, I worry that if we don't enforce clamping for these new timer mechanisms we'll eventually end up back there due to misbehaving websites. But perhaps if no browser budges it's feasible to hold the door.

[jasnell]

You can add Node.js and Cloudflare Workers to the list of runtime implementations in support of this. I have PRs pending to land in both environments implementing the setTimeout() compatible behavior.

[domenic]

The main thing I'm worried about for Firefox is that I think @farre or @smaug---- at some point mentioned to me that the clamping logic sits pretty deep in our timeout code. And beyond that, I worry that if we don't enforce clamping for these new timer mechanisms we'll eventually end up back there due to misbehaving websites. But perhaps if no browser budges it's feasible to hold the door.

I feel like we (Mozilla and Chromium) discussed this in the context of postTask() and our conclusion was that the allowance for implementation-defined waiting was enough, at least to start with.

[annevk]

Thanks, that makes sense.

[domenic]

Alright, I've updated this with a mini-explainer. All that remains are someone to write some web platform tests, probably as part of an implementation :)

[smaug----]

So the signal on the fetch (in the example) would be aborted even if the fetch() succeeds, abort would just happen when the timeout happens to run? Isn't that error prone, getting abort event, even though the fetch() itself has succeeded?

[domenic]

I'm not sure I understand the concern. Nobody else is listening for the abort event in the example... and if they were, then the contract is that the AbortSignal should signal abort to both the fetch (which ignores it) and that other thing (which doesn't), so it seems like it's working as intended.

[smaug----]

The concern, which may not be that major, is just that one gets now always an aborted signal eventually, so the event listener on the signal is called, even though fetch() or other APIs using signal succeed.
One could think of some way to cancel the timeout.

[jasnell]

I think the issue is more that the timer can continue well after the set of operations completed successfully. Take a pathological case where I create an AbortSignal with a timeout of 20 minutes and I attach a handler to it with a closure.

const signal = AbortSignal.timeout(1_200_000);
signal.addEventListener('abort', () => {
  throw signal.reason;
});

The complete set of operations that I pass the signal to complete successfully, but the internal timer for the signal keeps right on going, holding the AbortSignal and the closure (along with whatever memory it's closing over) for the whole 20 minutes. Then, it unconditionally throws a synchronous error.

Ideally there would be a way of canceling the timeout. Obviously that doesn't help with the closure holding on to things but it ensures that the underlying timer it at least no holding the reference for way longer than it needs to.

const signal = AbortSignal.timeout(1_200_000);
await fetch('http://example.org', { signal });
signal.clearTimeout();

This case is similar to why we allowed adding an AbortSignal to addEventListener() itself. We can even follow a similar pattern here if necessary:

const cancelAbort = AbortController();
const signal = AbortSignal.timeout(1_200_000, { signal: cancelAbort.signal });
signal.addEventListener('abort', () => {
  throw signal.reason;
}, { signal: cancelAbort.signal });
await fetch('http://example.org', { signal });
cancelAbort.abort();

Granted, this doesn't prevent the pathological case but it provides a Right Way To Do It alternative.

[domenic]

I'm still having trouble understanding the concern. Could someone produce a semi-realistic example of what someone might do with the current proposal, and how they think that the code would give unexpected results?

[jasnell]

Is this example not realistic?

const signal = AbortSignal.timeout(1_200_000);
signal.addEventListener('abort', () => { throw signal.reason; });
await fetch('http://example.org', { signal });

[domenic]

Well, I'm not sure what the consumer on the second line is trying to do. What about that example is not working as expected? I.e. what are the expected results, vs. the actual results in this proposal?

[domenic]

Tests have landed! Merging, and will file browser bugs and edit the OP with them momentarily.