ReviewOS

zig-utils/zig-js

Inspector: worker target discovery and cross-thread transport

#156
Closed chris opened this 10 days ago ·
10 days ago

Parent: #139 Decomposed from #154.

Implement explicit debugger targets for isolated JSWorkerRef runtimes. A worker has no parent JSContextRef today and runs on its own owner thread, so it must not be silently folded into an unrelated context session.

Acceptance:

  • Give every worker runtime a stable target identity and lifecycle metadata without exposing raw pointers.
  • Add target discovery/attach/detach protocol behavior and a documented embedder transport contract.
  • Marshal inspector commands to the worker owner thread and events back without invoking a context-affine callback on the wrong thread.
  • Support worker scripts, pause/resume, breakpoints, stepping, exceptions, call frames, scopes, evaluation, and remote objects with the same zero-hidden inventory as the main target.
  • Define continuation ownership for multiple sessions attached to one worker and independent simultaneous pauses across workers/main contexts.
  • Termination, close, session detach, and worker release must unblock pending inspector traffic and release every remote/root exactly once.
  • Add script/module workers, active-message handlers, termination-at-pause, GC, concurrency, and teardown transcripts plus real C host coverage.
  • Update README/API/inspector documentation and the machine-readable protocol inventory.

Until this lands, #154 documents and tests the honest isolation boundary: a parent context inspector does not claim independently-created workers as child targets, and workers continue their own message/termination lifecycle while the parent is paused.

10 days ago

Stable worker target identity/lifecycle is now on main in e14cf92. Script and module workers receive process-wide, non-zero IDs that never encode pointers or wrap into aliases, plus atomic starting → running → closing → closed metadata exposed by ZJSWorkerGetInspectorTargetInfo. The installed extension header now declares the full existing worker ABI as well. Coverage: 4/4 focused Zig cases, C API audit at 117/117 public symbols + 13 extensions, and the real C/C++ host gate passes. README/API/inspector/threading docs are current. Next slice is attach/detach plus command/event transport.

10 days ago

Cross-thread attach/dispatch/pump/release is now on main in 563ffe7. ZJSWorkerInspectorSession* copies commands to the isolated runtime, keeps servicing them while paused, and copies events back for an explicit owner-thread pump; callbacks never run on the worker Context thread. The end-to-end transcript attaches, enables Debugger, pauses inside an active message handler, dispatches resume from the owner callback, and returns the expected value. Plain script workers now register worker://<target-id>/script before evaluation. Gates: 3/3 focused cases, 117/117 public ABI + 17 extensions, and all real C/C++ hosts. README/API/inspector/threading docs are current.

10 days ago

The worker evidence matrix advanced in ce1aa3d, 07e23d9, and 55616207. A real first-statement debugger; loss was fixed by giving it a distinct AST node and bytecode nop boundary. New transcripts cover two-session continuation ownership (observer resume rejection), callback detach while paused, termination while paused, module graph publication/pause, and active handlers. Batched gates are 6/6 worker-inspector, 11/11 main debugger, and the protocol inventory guard. The machine-readable inventory now declares both implemented transports alongside the unchanged zero-hidden 20-command/8-event surface; README/API/inspector/thread docs are current.

10 days ago

Workers now create their Context with precise GC enabled by default, while still allowing the Zig API to override the Context policy through Worker.Options. The worker model/API/README documentation now says this explicitly.

Focused verification: 6/6 core worker tests and 6/6 worker-inspector tests pass.

Pushed to main: b52b2f1.

10 days ago

Worker protocol parity is now verified end-to-end over the owner-pump transport: target-URL breakpoints, step-over, caught-exception events/pauses, live call frames and scope expansion, live frame evaluation/mutation, retained remote objects, and property inspection. The test intentionally chains these commands during pauses to cover runtime-thread command ordering and owner-thread callbacks.

Focused verification: 2/2 selected tests pass with no leaks. README and inspector/worker docs are current.

Pushed to main: c67d109.

10 days ago

Continuation isolation is now fully exercised: two worker targets can be paused at the same time, an independently inspected main context can pause/resume while both remain stopped, and each worker resumes and completes separately. This complements the existing deterministic owner/observer coverage for two sessions on one worker.

Focused verification: 2/2 selected tests pass with no leaks. README and inspector/worker docs are current.

Pushed to main: 47fc5db.

10 days ago

Completed on main through 1060784.

Final evidence:

  • Stable script/module target identity and atomic lifecycle.
  • Owner-pumped, runtime-thread command transport with deterministic multi-session continuation ownership.
  • Breakpoint, stepping, exception, frame/scope evaluation, and remote-object parity.
  • Independent simultaneous pauses across two workers and a main context.
  • Termination, callback detach, handler close, worker-first release, pending-traffic closure, and exactly-once backend/root cleanup.
  • Precise GC enabled by default for workers.
  • 20-command / 8-event zero-hidden inventory remains current.
  • Full suite: 835/836 passed with the sole stale host-class layout invariant found and fixed in d4ad50e; focused layout/JSClass tests then pass. API audit is 117/117 plus 17 extensions, and real C/C++ hosts pass.
  • README, API, inspector, and worker docs are current.
10 days ago

Post-completion transport hardening landed via #871 in 516a8d59: worker inspector session handles are now tagged random capabilities, reject cross-transport/forged/stale/wrong-thread use before dereference, and preserve existing dispatch/pump semantics.

Sign in to comment on this issue.