ReviewOS

zig-utils/zig-js

Inspector: worker target discovery and cross-thread transport

#156
Closed chris opened this 9 days ago ·
9 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.

9 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.

9 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.

9 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.

9 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.

9 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.

9 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.

9 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.
9 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.