`EventTarget.captureFallbackContext` API

[nicolo-ribaudo]

Extracted from AsyncContext & events: alternative proposal

Ref #100

---

The proposed web integration runs event listener in the "dispatch context", and use the "empty context" as a fallback when there is no dispatch context available.

This clashes with one of the goals: having "isolated" parts of the applications, and being able to trace from which part of the application a given error came from. The trivial approach is to store the "island ID" in an AsyncContext variable, and reading it when errors happen.

The solution that we have been discussing is to provide an EventTarget.captureFallbackContext API that lets people say "take a snapshot now, and use that as the fallback context for all the event listeners registered inside it". For example:

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() {
  // ...
}

This imposes less memory constraints than the approach of having event listeners always capture the registration-time context, because the expectation is that you'd define "fallbacks" much less frequently than how often you .run AsyncContext.Variables, and thus event listeners will end up capturing all the same (or a few) snapshot.

This "fallback context" is not a safe way to completely hide the root empty context: for example, a simple dynamic import is enough to get access to it. It's meant to reduce the cases where you don't want to see the root context, which most commonly happens in EventTarget and its subclasses.

---

There are a couple of open questions:

Explicitly pass the snapshot?

Instead of EventTarget.captureFallbackContext(fn), we might want to have EventTarget.withFallbackContext(snapshot, fn). This would make it more obvious that there is a snapshot being taken.

Support a way to get the fallback context?

#100 (comment) by @Jamesernator made me think: what if I want to just add one variable to the "fallback", rather than capturing whatever I have?

If there was a way to query the current fallback context (e.g. EventTarget.runFallbackContext()), then you'd be able to get the current context, update a variable, and set the new snapshot as the new fallback context:

const updatedFallback = EventTarget.runFallbackContext(() =>
  myVar.run("hello", () => new AsyncContext.Snapshot)
);

EventTarget.withFallbackContext(updatedFallback, ()=> {
  document.addEventListener("click", () => { ... });
});

Or maybe we could have more an API like EventTarget.updateFallbackContext(myVar, value, calback), although I'd prefer to only have the "primitive" that this can be built on top. Ideally, this should only happen if/after we get a way to update a Snapshot without running it.

[dead-claudia]

This imposes less memory constraints than the approach of having event listeners always capture the registration-time context, because the expectation is that you'd define "fallbacks" much less frequently than how often you .run AsyncContext.Variables, and thus event listeners will end up capturing all the same (or a few) snapshot.

You can structure snapshots such that they're cheap to capture and cheap to enter. You just have to move the iteration work to asyncVar.get(). I don't see the issue in encouraging that, especially since the iteration itself can often be avoided.

Here's a (currently untested) implementation of how one might do it:

interface ContextNode {
    parent: undefined | ContextNode
    key: object
    current: any
}

let snapshot: undefined | ContextNode
let head: undefined | ContextNode

const Hole = Symbol()
type Hole = typeof Hole

export class Variable<T> {
    #initial: T
    // both of these should be weakly held
    #snapshot: Hole | undefined | ContextNode = Hole
    #current: any

    constructor(initial: T) {
        this.#initial = initial
    }

    get(): T {
        // Likely branch in hot code, only fails on snapshot change
        // This also is taken when a variable is only used in the same snapshot's scope and that snapshot is just saved and restored
        if (snapshot === this.#snapshot) return this.#current

        this.#snapshot = snapshot

        let value = this.#initial
        let node = snapshot

        while (node) {
            if (node.key === this) {
                value = node.current
                break
            }
            node = node.parent
        }

        this.#current = value
        return value
    }

    with<R>(value: T, f: () => R): R {
        const prevSnapshot = this.#snapshot
        const prevValue = this.#current
        const prevHead = head
        head = {
            parent: prevHead,
            key: this,
            current: value,
        }
        // Ensures a guaranteed cache hit in `.get()`
        this.#current = value
        this.#snapshot = snapshot
        try {
            return f()
        } finally {
            this.#current = prevValue
            this.#snapshot = prevSnapshot
            head = prevHead
        }
    }
}

export class Snapshot {
    #state: undefined | ContextNode = head

    run<R>(f: () => R) {
        const prevSnapshot = snapshot
        const prevHead = head
        head = this.#state
        snapshot = this.#state
        try {
            return f(...args)
        } finally {
            head = prevHead
            snapshot = prevSnapshot
        }
    }
}

I'm obviously excluding the Async part of the implementation here, but async is just an extension of this.

---

Edit: worth mentioning that high-performance frameworks have a need for fast snapshot save/restore as well. It's not just the DOM who would stand to benefit.