The current web integration draft for AsyncContext proposes that event handlers run using the context that was active when .addEventListener was called (the "registration context").
This is because it is significantly easier to specify and to implement: the change is limited to the EventTarget interface, that is responsible for capturing the async context snapshot and then restoring it when running the callback.
Unfortunately for that proposal, many AsyncContext use cases require access to the context that was active when the event was dispatched (or when the action that caused the event to be dispatched was started): the proposal thus leaves the door open to expose that as a property on the event. This approach however:
I propose that instead we run event handlers using the context that was active when the event was dispatched, instead of the one when the handler was registered. Events that have no dispatch-time context would fallback to the top-level root context.
This document goes through how it can be done.
To better understand the problem space, we need to divide events in three cathegories:
A single (target, event type) pair can fall under multiple cathegories, however every specific fired event will be only in one.
Example: events dispatched through eventTarget.dispatchEvent(), element.click(), or abortController.abort().
For events that fall in this cathegory, propagating the dispatch context is trivial: there is nothing to do. The "dispatch context" is the one stored in the surrounding agent, which will be the same surrounding agent used to run the callback, and (unless some spec algorithm explicitly changes it) the async context remains the same.
Propagating the registration context on the other hand requires more work: you need to store a snapshot of the context when .addEventListener was called, which will be kept alive for as long as the event handler is registered and thus cannot be garbage-collected.
Example: user clicking on the document, localStorage changes from a different tab, messages from a different worker.
For these events there is no JavaScript dispatch context, so we need to choose a fallback between the root empty context and the registration context. The coherent answer is to fallback to the root context (Why "root context" is the coherent fallback for "dispatch context").
Falling back to the empty context shuold be simple implementation-wise, and compared to using the registration context has the benefit of not keeping the registration context alive (as for sync events dispatched from JS).
Example: xhr.send() -> load, indexedDB.commit() -> complete, animation.play() -> finish
This where most of the complexity of propagating the dispatch context comes from. The rule of thumb for what the dispatch context should be is "if the async part was internally implemented using async/await that synchronously dispatches events during its process, what would the context be?".
A trivial approach to propagating the dispatch context inside specifications is to capture a snapshot when the function that starts the process is called (e.g. when calling xhr.send()), manually passing it around up to where the event is dispatched, and activate that snapshot before dispatching the event. However, this method has a significant problem: it adds noise to the specification, that makes it harder both to read and to write it.
This problem would also happen if we default to the registration context and expose the dispatch context as e.dispatchContext.
To solve this problem, we can instead impilicitly pass the context around through specification. This implicit propagation would be for specification what AsyncContext is for JavaScript. You can read more details about this approach at "Web integration for AsyncContext: in-spec context tracking".
While this implicit approach works well in many cases (especially for completion callbacks, where the callback is a direct consequence of the API that has been called), it doesn't work for all events. They will all need to be manually reviewed.
Due to its need of extensive review, testing, and potential implementation complexity, properly propagating the dispatch context for asynchronous events triggered by JS will require significant time and effort.
Propagation of the context for those async events can be verified and exposed over time. Those handlers can initially run in the root context, similarly to events caused by outside triggers, and over time start exposing a better context when feasible. This is observable, but being a change from "exposing less info" to "exposing more info" it's likely going to be web-compatible.
The way this incremental approach can be implemented in specifications is by adding an optional "propagate asynchronous context" flag to the fire an event algorithm, that defaults to false. If there is no JavaScript code on the stack and the flag is not set to true, it will restore the root context before dispatching the event.
There are some asynchronous events that will need to properly propagate the context from the beginning:
postMessage -> onmessage in the same agent, because it's often used as an alternative to queueMicrotask (same window would probably be enough, if same agent is too complex to implement?)postMessage -> onmessage on a MessageChannel whose ports have not been transferred yetunhandledrejection and errorXMLHttpRequest (tc39/proposal-async-context#22)While we do not have to follow precedent when designing language features, it can at least be a good indication of what the expectation might be.
There are two types of precedent we can look at: how do features with similar properties to AsyncContext behave on the web, and the equivalent of AsyncContext behaves in other platforms.
There are no user-exposed API that behave similarly to AsyncContext in the standard/cross-browser web plaftorm. However, there are different WICG and Chrome-specific APIs that do: Prioritized Task Scheduling, Task Attribution and Chrome's Async Stack Tagging API.
Rather than having 3-4 features that similarly propagate some data through asynchronous steps, we should try to unify them under a single model.
The Prioritized Task Scheduling proposal (MDN) allows defining some tasks that shuold run with a given priority, and it allows yielding back to the event loop while executing the task:
scheduler.postTask(async () => {
await doSomething();
await scheduler.yield();
await doSomethingElse();
await scheduler.yield();
await doSomethingAgain();
}, { priority: "user-blocking" })
In this example, the scheduler.yield() call will yield with the priority "user-blocking", which is tracked across awaits.
When it comes to events, priority is preserved from the dispatch context for synchronous events, and it's lost for asynchronous events and for events with non-JS causes, falling back to the default global priority.
The Soft Navigations proposal allows developers to attribute timing properties to "soft navigations", i.e. same-page navigations that happen through the Navigation API as a consequence of user gesture.
The proposal provides, through Task Attribution, a way to track the logic relative to a navigation even accross asynchronous steps: through timers, through queued tasks and through promises.
When it comes to event handlers:
postMessage which propagates the task to the message event handlersChrome's Async Stack Tagging API exposes Chrome's async stack traces tracking ability to user code, so that user-defined schedulers can integrate with it.
For example, this code:
function schedule(cb) {
const task = console.createTask("schedule");
return () => task.run(cb);
}
function main() {
setTimeout(async function afterTime() {
const run = schedule(function logger() {
console.trace("Hi!")
});
await something;
run();
}, 10)
}
will log a stack trace that contains:
logger
schedule
afterTime
setTimeout
main
even though the actual stack of the console.trace call does not contain neither schedule nor main.
These traces are propagated through async/await, through timers and other schedulers.
When it comes to events, it behaves exactly like the Task Attribution API above.
However, this API special cases load and error, regardless of their target:, the handlers run with the trace that was active the first time the given callback was registered with .addEventListener on the given target.
You can read more about it at "AsyncContext: console.createTask API".
Node.js already implements an API that is very similar to AsyncContext, called AsyncLocalStorage (it's "async-local storage", and not "async LocalStorage"). You can read more about it in their documentation. It is frequently used in Node.js-based web servers to associate data with a given request, and to collect telemetry data.
When it comes to events, Node.js behaves as proposed in this document: it uses the dispatch context when available, and it falls back to the root context when not.
C# and Dart both have concepts similar to AsyncContext: respectively, AsyncLocal and Zones. Both languages run event handlers in the context where the event was dispatched, falling back to the root context.
You can read more about them, with examples ready to be run, at "AsyncContext: other languages".
While this approach works perfectly for many of the AsyncContext use cases, it fails when trying to use it to detect which part of code is responsible for some action.
Consider this scenario: your web app has two parts developed by two separate teams, and whenever there is an unhandled promise rejection you want to associate it to the corresponding team.
You might try to do something like the following, which initially seems to work well:
function teamOne() {
// do something
setTimeout(() => {
Promise.reject(); // :(
})
}
function teamTwo() {
// ...
}
const currentTeam = new AsyncContext.Variable();
addEventListener("unhandledrejection", () => {
console.log("Rejection from team " + currentTeam.get());
});
currentTeam.run("one", teamOne);
currentTeam.run("two", teamTwo);
However, as soon as you introduce user interaction events it breaks apart. If Team One rewrites their code as follows, the currentTeam variable will have no value when running the unhandledrejection callback, because click used the root context:
function teamOne() {
button.addEventListener("click", () => {
Promise.reject(); // :(
});
}
A solution to this problem is to allow re-defining a new "root context", which is captured at registration time and that is used in cases where there is no JS dispatch context:
const currentTeam = new AsyncContext.Variable();
addEventListener("unhandledrejection", () => {
console.log("Rejection from team " + currentTeam.get());
});
currentTeam.run("one", () =>
EventTarget.captureFallbackContext(teamOne)
);
currentTeam.run("two", () =>
EventTarget.captureFallbackContext(teamTwo)
);
function teamOne() {
button.addEventListener("click", () => {
// this listener will never run in the root context:
// if possible it will propagate the contex that
// dispatched it (e.g. by a .click() call), but if
// not it will fallback to the context that was active
// when EventTarget.captureFallbackContext was called
Promise.reject();
});
}
function teamTwo() {
// ...
}
The idea is that EventTarget.captureFallbackContext would only be called a small number of times compared to how much .addEventListener is used, mostly to define "code regions" while the application is being bootstrapped. Thus, it captures significantly fewer async context snapshots than if we did it every time an event handler is registered, and it's always explicit rather than implicit.
If browser internals were written in JavaScript, an implementation would look as follows:
EventTargetclass EventTarget {
static #fallbackContext = new AsyncContext.Variable({
defaultValue: new AsyncContext.Snapshot(),
});
#callbacks = [];
addEventListener(callback) {
this.#callbacks.push({
callback,
fallbackContext: EventTarget.#fallbackContext.get(),
});
}
dispatchEvent(event) {
this.__browser_internal__dispatchEventInCurrentContext(event);
}
__browser_internal__dispatchEventInCurrentContext(event) {
// Assert: there is some JS code code on the stack,
// or if not there is some AsyncContext that was propagated
// from the async call that caused this event
for (const { callback } of this.#callbacks) {
callback(event);
}
}
__browser_internal__dispatchEventInEmptyContext(event) {
// Assert: there is no JS code code on the stack, because
// sync events always easily propagate their dispatch context
for (const { callback, fallbackContext } of this.#callbacks) {
fallbackContext.run(() => callback(event));
}
}
static captureFallbackContext(run) {
EventTarget.#fallbackContext.run(new AsyncContext.Snapshot(), run);
}
}
-
Any changes
Be notified of any changes
-
Mention me
Be notified of mention me
-
Unsubscribe
Subscribe