feat(truapi-server): host-side wire debug tap and debugger

[decrypto21]

What

Implements the wire observability layer for TrUAPI: a payload-blind debug tap in the Rust host (truapi-server), correlated by the wire requestId. The host streams every product↔host frame, opaque, to a debugger it dials out to over loopback, which groups the frames into per-operation traces and renders them in a web inspector (op list, drill-down, aggregate strip). The tap carries the frame bytes untouched - the core never decodes them - so @parity/truapi (the product package) is left completely alone. Strictly dev-only: the tap is inert unless a host installs a sink, and the whole decode path is compiled out of production (the web host's dial reads import.meta.env.DEV), so no production bundle can ever enable it. Design doc: docs/design/wire-observability-debug-host.md (#315).

• Web inspector - aggregate summary strip, op list with filter/sort/channel pills and health badges (retry-storm, orphaned, live subscription):

• Per-frame drill-down - opening an op decodes every frame to its SCALE-typed value inline; no click-to-decode, no toggle (a dev-only tool decodes everything by default):

What's in it

• Rust tap + sinks (truapi-server) - the DebugSink trait + DebugEvent at the two frame choke points (receive_frame inbound, emit_frame outbound). Outbound forwards to the product before it emits; inbound emits before dispatch so a corrupt frame is still observed; every emit is wrapped in catch_unwind and is inert when no sink is installed (a lock-free has_debug fast path). Direction is product-vantage (out = left the product), pinned by a guard test; DebugEvent is #[non_exhaustive]. Ships a native WsDebugSink (loopback-only, gated behind the ws-bridge Cargo feature) with a byte- and count-bounded queue and counted drops, plus the wasm WasmDebugSink.
• Contract identity (truapi-codegen) - codegen emits one TRUAPI_WIRE_SCHEMA_HASH (a fingerprint over frame ids + method legs) into both the TS client and the Rust dispatcher, so a host built against a drifted frame table is caught rather than silently mis-decoded.
• TS engine (@parity/truapi-debugger, private, in-repo) - createWireDebugger groups frames into per-(channelId, requestId) WireTraces, segments recycled request ids into distinct generations, resolves lifecycle roles at ingest, detects retry storms, and bounds retention (LRU trace cap, per-trace frame + byte caps, surfaced eviction/drop counters).
• Web inspector - a Network-tab-style UI over /op-list·/op·/stats·/channels: aggregate strip, op list with filter/sort/channel switch, per-frame drill-down that decodes to the SCALE-typed value inline. Decode is refused for a channel whose wire schema hash did not match (codec drift), matching the gated /frame JSON endpoint.
• In-app engine (createInAppDebugger) - feed frames in-process and mount the same inspector; the surface a host embeds directly (see the companion dotli PR).

Verification

cargo test -p truapi-server --features ws-bridge (the tap covered in both directions, product-vantage convention pinned) and -p truapi-codegen (incl. golden) green; make wasm confirms the native ws-bridge deps stay out of the wasm graph; clippy + fmt clean. bun test green for the debugger and tsc -b clean.

Notes

• Decode-everything, dev-only. The debugger decodes every frame by default - there is no sensitive special-casing and no reveal/redact machinery (it was removed). The protection is not redaction, it is compile-out: the tap and decode are absent from every production bundle (import.meta.env.DEV), so there is nothing to arm in a shipped build.
• Off the critical path. The tap forwards before it emits, and emit never blocks, fails, or panics into dispatch (catch_unwind) - a slow, absent, or crashed debugger loses a trace, never a session.
• Confined. Sinks are loopback-only; the WS upgrade carries a CSWSH Origin gate and the HTTP routes a Host-header allowlist (blocks DNS-rebinding reads of decoded frames). WS maxPayloadLength + a true per-trace byte cap bound RSS now that decode retains bytes.
• Codec-drift guard. Every decode surface (/op, /view, /frame) decodes only for a channel whose wire schema hash affirmatively matched; a drifted/foreign host groups but shows no value, rather than decoding its frames against the wrong table.
• Residual exposure documented. Even confined, frame shape + timing is traffic-analysis metadata; loopback + unset-in-prod is confinement, not anonymity.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​parity/​truapi-debugger@​0.0.0	N/A	N/A	N/A	N/A	N/A

View full report