Repository navigation
Add await_js() to Rust IoContext and use it for waitUntil() - #8337
Conversation
c712938 to
0cb41cc
Compare
0cb41cc to
ca0676e
Compare
d601540 to
2d952d5
Compare
ca0676e to
3bd5534
Compare
1c1f4e0 to
b07c07d
Compare
b07c07d to
72b0cb3
Compare
1284e6a to
3e71f49
Compare
ad7d9cb to
d32c0bf
Compare
3e71f49 to
6c51bb1
Compare
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #8337 +/- ##
==========================================
+ Coverage 66.77% 66.98% +0.20%
==========================================
Files 797 797
Lines 204128 206009 +1881
Branches 31719 32023 +304
==========================================
+ Hits 136312 137990 +1678
- Misses 49215 49238 +23
- Partials 18601 18781 +180 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
d32c0bf to
61eb99e
Compare
6c51bb1 to
9f9cc83
Compare
c79fa61 to
a967eaa
Compare
There was a problem hiding this comment.
Superseded by the review of
4ce4fc12.
This review, of 00abb6a1
✅ Approved — No correctness, security, performance or documentation issues found. The new await_js() path mirrors C++ awaitJs(), and the comparison tests cover it.
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
✅ All checks passed
🔒 Security: ✅ LGTM
No exploitable issues found. The unsafe impl Send blocks state their invariants, and the code upholds them. Rejection logging matches C++ behaviour. The C++ JSG allowlist gets smaller.
📖 AGENTS.md: ✅ LGTM
No issues found.
📋 Code Quality: ✅ LGTM
No issues found. I checked the destruction order of the abort state against ownedObjects, the MEMORY_LIMIT_MESSAGE constant, the UncaughtExceptionSource stringification, the locking discipline in AwaitJsShared, and the error paths in await_js().
⚡ Performance: ✅ LGTM
Each wait costs little: one abort watcher, an optional tracing resource, and one weak-reference lock taken on drop. Only tests use these APIs today.
📝 Documentation: ✅ LGTM
The doc comments describe the new await_js() and add_wait_until() behaviour accurately.
Reviewed commit: 00abb6a1
There was a problem hiding this comment.
Superseded by the review of
2704cff9.
This review, of 4ce4fc12
✅ Approved — No correctness, security, performance or documentation issues found. The changes since the last review are a test-size setting and test-only lint and destruction-order fixes.
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
✅ All checks passed
🔒 Security: ✅ LGTM
No exploitable issues found.
- A reaction that runs in another request fails rather than settling the wait, because it takes the sender through
IoOwned::take. - The drop path does not enter V8.
- Rejection logging matches what C++ does.
- The C++ JSG allowlist gets smaller.
📖 AGENTS.md: ✅ LGTM
No issues found.
📋 Code Quality: ✅ LGTM
No issues found.
ownedObjectsis still declared after the abort state, so it is destroyed first.- The heap-limit check without the lock enters no V8.
- The JSG allowlist matches what
ffi.c++actually uses. size = "large"onio-context-testis passed throughkj_testto both test variants.
⚡ Performance: ✅ LGTM
No issues found. The inspector and weak-reference paths run only on abnormal events, and only tests call these APIs today.
📝 Documentation: ✅ LGTM
No issues found.
Reviewed commit: 4ce4fc12
guybedford
left a comment
There was a problem hiding this comment.
LGTM. The comparison tests against C++ awaitJs() make this easy to trust, and the sender's lifetime and thread confinement hold up. Just nits, none blocking.
The branch could also do with a rebase before landing: it has two merges of main, a trailing lint/timeout fix commit, and still carries the #8406 commit.
IoContext::await_js() waits for a JavaScript promise from Rust, as C++ IoContext::awaitJs() does, without wrapping it. The promise's reactions hold the half of the wait that settles it through an IoOwned, which gives it the lifetime C++ gives AwaitJsFulfiller through IoOwn: it is taken only in the request that started the wait, and is dropped at once, through the request's delete queue, or with the request. Dropped before it settled the wait, as when GC collects an unsettled promise, it settles it as never completing. The returned AwaitJs future is Send and polled without the isolate lock; dropping it cancels the wait, and the conversion then does not run. The message of the never-settled error is IoContext::NEVER_SETTLED_MESSAGE, which Rust reads through the shim, so there is one copy. A rejection, and what JavaScript throws in the conversion, is tunneled with jsg::Lock::exception_to_kj(), as C++ tunnels it with jsg::createTunneledException(). If tunneling runs JavaScript that throws, such as a getter of the rejection's `stack`, the reaction rejects with that exception, and the wait ends as never settled, as in C++. Not yet covered: logging a rejection as an uncaught exception, joining the wait with the request's abort, async tracing, and the memory-limit error.
When the promise C++ IoContext::awaitJs() waits for rejects, or its func throws, AwaitJsFulfiller::rejectWithJsException() logs the value as an uncaught exception from INTERNAL_ASYNC before tunneling it, while its stack is still there to log. Rust await_js() now does the same, through a new IoContext::log_uncaught_exception(), which does what C++ Worker::Lock::logUncaughtException() does for a JavaScript value: - If the isolate has an inspector, it reports the value as thrown, with the source's text and a message V8 creates for the value, as jsg::sendExceptionToInspector() does without a v8::Message. The new io_context_send_exception_to_inspector() shim calls V8 and the inspector directly, and converts its strings as jsg::toInspectorStringView() does. - If KJ logs at INFO level (workerd --verbose), it logs `uncaught exception` with the source and the value's `stack`, or the value itself if it has none, as C++ describes them. Rust reads `stack` only then, as C++ does. C++ also adds uncaught exceptions to the request's tail-worker trace, but none from INTERNAL or INTERNAL_ASYNC, so log_uncaught_exception() adds none, and its UncaughtExceptionSource offers only those two. As in C++, what reading `stack` throws stays pending: the reaction rejects with it, unhandled, and the wait ends as never settled. An error that `map` returns now goes the way C++ sends a KJ exception from func: jsg::Lock::tryCatch() converts it to JavaScript, and it is then logged and tunneled like a thrown one, so the wait fails with the serialized value and metadata too, rather than with only `jsg.<name>: <message>`. An internal error is redacted and logged as jsg::Lock::throw_internal_error() does. The tests cover a rejection with and without a stack, what map throws and returns, an internal error, a fulfilled wait, the order of logging and tunneling, an inspector session, and that `stack` is read only at INFO level. request-ops-test runs a rejected wait through C++ awaitJs() and Rust await_js() and compares what they log.
When the reactions to the promise C++ IoContext::awaitJs() waits for are destroyed without settling it, ~AwaitJsFulfiller() rejects the wait. If the isolate has excessively exceeded its heap limit then, as its IsolateLimitEnforcer says through a weak reference to the isolate taken when the wait started, it rejects with an OVERLOADED `jsg.Error: Worker has exceeded memory limit.` carrying MEMORY_LIMIT_DETAIL_ID, which RequestObserver reports as an out-of-memory outcome. Otherwise, or if the isolate is gone, it rejects with `Promise will never complete.`. Rust await_js() now does the same. The sender half of a Rust wait holds a weak reference to the isolate, from Worker::Isolate::getWeakRef(), through a new shim. It is Send, since AtomicWeakRef is atomically refcounted and guards its pointer with a mutex. When the sender is dropped unsettled, it reads hasExcessivelyExceededHeapLimit() then, as C++ does in its destructor, and the future builds the error when it is polled. The check enters no V8 and needs no isolate lock, so it is safe in a GC finalizer, and limit-enforcer.h now says implementations must keep it so. The exception is defined once: the new IoContext::memoryLimitException() builds it for rejectNeverSettled(), and Rust receives the same kj::Exception from a shim that throws it, with its type, description, location and details, through the bridge. Its location is now io-context.c++, where the function is, rather than io-context.h. The tests cover GC collecting the unsettled promise past the heap limit, checking the type, description, location and detail. They also check that the error is chosen when the reactions are collected, neither when the wait starts nor when its future is polled, and they cover destroying the IoContext with the wait unsettled, past the limit and not. One test waits through C++ awaitJs() and Rust await_js() in the same scenario and compares the exceptions.
C++ IoContext::awaitJs() records each wait for async tracing: when the wait starts, IoContext::makeAwaitJsResource() creates a JS_TO_KJ resource named "awaitJs" if the context is traced, and AwaitJsFulfiller settles it when the JavaScript promise settles. It settles it OK once the promise is fulfilled and func succeeds, or once the promise is fulfilled after the KJ side stopped waiting, and ERROR once the promise rejects or func throws. A promise that never settles leaves it unsettled, and destroying it then reports a destroy event. Rust await_js() now does the same. The sender half of a Rust wait holds the resource, created through a new shim over makeAwaitJsResource(), which is now public so that the resource and its name are defined once. The shim returns none for an inert resource, so an untraced wait allocates nothing. The reactions settle it where AwaitJsFulfiller does, after settling the wait, and dropping the sender unsettled reports the destroy. The resource is bridged as an opaque AsyncResource and is Send: it holds an atomically refcounted AsyncTracker, whose methods do nothing on a thread other than its own, and the last reference can be released elsewhere only once the IoContext has closed the tracker. Two differences remain, both because a reaction takes the sender and drops it when it ends, while C++ keeps its AwaitJsFulfiller until both reactions are collected: - A settled resource is released from the tracker at the end of the reaction rather than when the reactions are collected, or never, if the tracker has closed by then. A release reports nothing but onRelease. - If the reaction fails before settling, because logging the rejection throws or execution terminates, the destroy is reported then rather than when the reactions are collected. Keeping the resource in the reactions' data instead would report the destroy of an unsettled wait at GC time, and lose it once the IoContext has closed the tracker, where C++ reports it when the IoContext frees its objects. No other event differs. The tests run each scenario through C++ awaitJs() and Rust await_js() in a traced request and compare the events: fulfilled, rejected, a conversion that fails or throws, cancelled then fulfilled, rejected or collected, and a promise GC collects. They check that the resource is settled or destroyed in the turn the promise settles or is collected in, and that a cancelled wait's conversion does not run. Another test checks that an untraced request creates no resource and its waits still settle.
C++ IoContext::awaitJs() joins its wait with onAbort(), so a wait fails with the exception its request is aborted with. Rust await_js() now does the same. An AbortWatcher holds IoContext::onAbort() eagerly evaluated, and calls back into Rust, which fails the wait with the abort exception, keeping its type, description, location and details. The half of the wait that settles it holds the watcher, so the watcher is dropped with it: in the settling reaction, when GC collects the promise, or with the IoContext. This relies on C++ onAbort() for now; a Rust IoContext will need its own abort signal. The watcher is a plain kj::Own rather than an IoOwn. The IoContext may drop the sender while OwnedObjectList::unlink() is unlinking the sender, and dropping an IoOwn there would reentrantly unlink a neighbouring node, which corrupts the heap. To match C++ event ordering, an abort after the wait started wins over a promise that settles later in the same turn (the conversion still runs, as in C++), and over the sender being dropped unsettled. In a request that was already aborted, a promise that settles in the same turn still wins, as C++'s breadth-first broken onAbort() promise lets it. Once the abort has failed the wait, a fulfillment runs no conversion, a rejection is still logged, and the trace reports how the promise settled. Unlike C++, a cancelled wait keeps its watcher until its sender is dropped. An abort then settles nothing. Tests run each abort scenario through both C++ awaitJs() and Rust await_js() and require the same outcome, conversion runs, trace events, logged rejections and exception. This adds no API surface visible to Workers.
C++ IoContext::awaitJs() fails with the very kj::Exception the request was aborted with, and with IoContext::memoryLimitException() itself, stack trace included. Rust's await_js() failed with a cxx::KjError, which C++ handed over by throwing it and which keeps only the type, description, location and details, so a C++ caller of the Rust wait received an exception without the trace. The future now fails with a cxx::KjException, the kj::Exception C++ fails with. C++ passes the abort exception, the pending abort and the memory-limit exception to Rust by value, rather than by throwing them, so they are never converted; a rejection is tunneled as before and becomes a KjException there. A KjException that reaches C++ through the bridge is that exception unchanged. The exception the tests abort a request with now has a stack trace, and the tests check that the exception a wait fails with starts its trace where the expected one does. KJ appends an address for each promise an exception passes through, and those differ between C++ and Rust, so only the start is compared.
4ce4fc1 to
2704cff
Compare
|
Thanks for the review! I've addressed all four nits and rebased onto main. The branch is now 7 linear commits: no merges, no #8406 commit, and the lint/timeout fix folded into the abort commit. "Bound Rust await_js() by HoldsNoGcReferences" was only an adaptation to main's #8401 and b0c45c3, so on top of current main it's folded into the first commit. Every commit builds with |
There was a problem hiding this comment.
Superseded by the review of
25ed36e0.
This review, of 2704cff9
💬 Approved with comments — No correctness, security or performance issues. One INFO note asks to narrow the abort wording in the await_js() doc comment.
Findings: 1 info (1 is an inline comment on the diff)
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
📝 Documentation: 💬 1 info
The abort bullet in the await_js() contract is slightly too broad.
Recommendation: 💬 Optional Nits
- [INFO] The abort bullet in the await_js() contract does not cover a request that was already aborted when the wait started. (
src/workerd/io/io-context/lib.rs:268)
View full review
- The abort bullet in the
await_js()doc comment (lib.rs:268-269) says the future fails with the abort exception whenever the context is aborted before the wait settles. That is not true for a request that was already aborted when the wait started: there, a promise that settles before the abort watcher runs wins.
✅ All other checks passed
🔒 Security: ✅ LGTM
No exploitable issues found.
- Two paths reach
ThreadBoundAbortWatcher, and both are on theIoContext's thread:IoOwned::takein the reaction, and the drop paths. Itsunsafe impl Sendis therefore sound. - A reaction that runs in another request settles nothing.
- When V8 cannot describe the exception message, the raw-V8
sendExceptionToInspectoroverload returns false instead of throwing. Thejsg::Lockoverload turns that false intoJsExceptionThrown.
📖 AGENTS.md: ✅ LGTM
No issues found.
📋 Code Quality: ✅ LGTM
No issues found.
- The
neverSettledException()andmemoryLimitException()helpers build the same exceptions on both implementations. - The JSG allowlist now permits only the one
JsExceptionThrownthatffi.c++still uses. io_context_send_exception_to_inspectorchecks for a pending exception before it calls any V8 API that takes a context.ownedObjectsis still destroyed before the abort state that the wait's sender reads.AwaitJssettles only while its state isWaiting, so a cancelled wait is never overwritten. Wakers are dropped outside the mutex.AwaitJsSender::dropenters no V8.
⚡ Performance: ✅ LGTM
No issues found. The inspector and heap-limit paths run only on abnormal events, and today only tests call these APIs.
Reviewed commit: 2704cff9
C++ ctx.waitUntil() has IoContext::addWaitUntil() wait for IoContext::awaitJs() of the promise. Rust's IoContext::add_wait_until() called that same C++ code through a shim that used C++ JSG, a reviewed exception to rule 3 of Rust JSG's safety rules. It now has addWaitUntil() wait for its own await_js() of the promise, whose value it discards, as C++ PromiseWrapper does for a kj::Promise<void>. The shim and its C++ JSG are gone, so io-context's ffi.c++ uses C++ JSG only to throw JsExceptionThrown in io_context_await_io_and_run(), and the allowlist and the README say so. A promise that never settles fails with IoContext::neverSettledException(), which C++ now defines for itself and for Rust, as it does memoryLimitException(). request-ops-test compares the two implementations of ctx.waitUntil() as before. It now compares stack traces only by whether an exception has one: each KJ promise an exception passes through adds its address, and the two implementations' promises differ. io-context-test checks that the trace starts where the exception's did. One difference is accepted. When the reaction to a promise runs in another request, both fail with "Cannot perform I/O on behalf of a different request", but C++ IoOwn appends " (I/O type: ...)" with the mangled name of the type it holds, AwaitJsFulfiller, which means nothing to the Worker; Rust names no type. The test compares the message without that suffix.
2704cff to
25ed36e
Compare
There was a problem hiding this comment.
✅ Approved — No findings. The one earlier documentation note about the abort wording in the await_js() contract is fixed in lib.rs.
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
✅ All checks passed
🔒 Security: ✅ LGTM
No exploitable issues found.
ThreadBoundAbortWatcher: itsunsafe impl Sendis sound. Both paths that reach it,IoOwned::takein the reaction and the drop paths, run on theIoContext's thread.- Reactions in another request: a reaction that runs in another request settles nothing.
- Raw-V8
sendExceptionToInspector: it returns false instead of throwing. Thejsg::Lockoverload turns that false intoJsExceptionThrown.
📖 AGENTS.md: ✅ LGTM
No issues found.
📋 Code Quality: ✅ LGTM
No issues found.
IoContext::neverSettledException()andmemoryLimitException()are defined once. C++AwaitJsFulfillerand the Rust bridge both call them.ownedObjectsis still destroyed before the abort state that the wait's sender reads.AbortWatchersetsabortedAtStartbefore theonAbort()promise starts.io_context_send_exception_to_inspectorchecksexceptionPending()before it calls any V8 API that takes a context.- The C++ JSG allowlist now permits only the one
JsExceptionThrownthatffi.c++still uses.
⚡ Performance: ✅ LGTM
No issues found.
- Cost per wait: each wait does a few allocations, comparable to C++
awaitJs(). - Locking: the mutex is never held across calls into V8.
- Cleanup: it is bounded. The sender is dropped when the reaction runs, when the reactions are collected, or when the request is destroyed.
📝 Documentation: ✅ LGTM
No issues found. The await_js() doc comment's abort bullet (lib.rs:268-270) now covers a request that was already aborted when the wait started.
Reviewed commit: 25ed36e0
Rust code that waits for a JavaScript promise as part of a request,
such as a Rust ctx.waitUntil(), needs what C++ IoContext::awaitJs()
does. Add IoContext::await_js() to the Rust io-context crate: it
returns a Send future for the outcome of a promise, which C++ or Rust
can wait for without the isolate lock.
It matches awaitJs(): a conversion maps the fulfilled value under the
lock, rejections are logged and sent to the inspector, and a wait that
never settles fails with "Promise will never complete." or, past the
heap limit, the memory-limit error. The wait is joined with the
request's abort and recorded for async tracing as the same awaitJs
resource. The future fails with a cxx::KjException, so C++ receives
the very exceptions it would have, including the abort's. The join
relies on C++ IoContext::onAbort(); a Rust IoContext will need its own
abort signal.
IoContext::add_wait_until() now uses await_js() instead of calling
C++ awaitJs() through a shim that used C++ JSG. jsg gains a
lock-free sendExceptionToInspector() that both implementations use.
io-context-test runs each behavior on both implementations and
compares outcomes, logged exceptions, trace events and the exceptions
the waits fail with; request-ops-test does the same for
ctx.waitUntil().
These differences from C++ are accepted, none visible to Workers:
" (I/O type: ...)" suffix in which C++ IoOwn names the type it holds.
ends, not when the reactions are collected.
rather than logged as C++ jsg::exceptionToJs() logs it.
the watcher then settles nothing.
Compatibility: no compatibility flag. Only tests call
IoContext::add_wait_until() and await_js(); nothing exposed to Workers
uses them yet.