Module trace 

Live match-trace channel — RFC 006 (in-process) + RFC 009 (transport).

Architecture

 HTTP handler ──► TraceEmitter::emit()
                        │
             tokio::sync::broadcast (bounded, 1024)
                        │
          ┌─────────────┴──────────────┐
     in-process                  TraceTransport::accept_loop
     subscriber                  (UDS on Unix, TCP fallback)
                                       │
                                 up to 4 GUI connections
                                 (newline-delimited JSON)

Transport variants

TraceTransportConfig	Platform	Notes
Uds { path }	Unix/macOS	Default when available
Tcp { addr }	All	Portable fallback; addr = "127.0.0.1:0" assigns ephemeral port
Disabled	All	No out-of-process forwarding (default)

Back-pressure

RFC 073 S-06/D-02: this section used to describe a mechanism tokio::sync::broadcast does not have — Sender::send only fails when there are no receivers at all, never because the channel is “full” (a full channel instead evicts the oldest unread event for whichever receiver is slowest, which is a per-receiver event, not a send-time one). What’s true now, and implemented to match:

• TraceEmitter::emit increments a shared counter only when send fails outright (no receiver existed at that moment) — rare, and not what “back-pressure” usually means here.
• A slow out-of-process subscriber (UDS/TCP, via TraceTransport::accept_loop) gets RecvError::Lagged(n) on its own broadcast::Receiver when it falls behind by more than TRACE_CHANNEL_CAPACITY events; n is accumulated per subscriber and added to dropped_count on that subscriber’s next forwarded event — see forward_events’s doc comment. Two independently-lagging subscribers each see their own true count, not each other’s.
• A direct in-process subscriber (calling TraceEmitter::subscribe itself, bypassing the transport) gets the same RecvError::Lagged from its own receiver and is responsible for folding it into dropped_count the same way, since this crate has no way to patch an event already broadcast to that caller’s receiver — see subscribe’s own doc comment.

Subscriber cap

At most MAX_SUBSCRIBERS out-of-process connections are accepted. A fifth connection receives {"error":"max_subscribers_reached"} and is then closed.

Structs

MatchTraceEvent

A single request/response trace event.

RequestSummary

Key fields from the incoming HTTP request.

TraceConfig

Trace-channel behaviour configuration (RFC 023, extended by RFC 040).

TraceEmitter

Shared handle to the trace broadcast channel.

TraceTransport

Enums

HeaderRedactionMode

Which names get redacted before a trace event is built, or before a verbose console log line is printed (RFC 040 Q1, extended by RFC 073 S-05 to query-string parameters and JSON body keys — see DEFAULT_HEADER_DENYLIST’s doc comment).

Outcome

What the server decided to do with the request.

TraceTransportConfig

Configuration for the out-of-process transport layer.

Constants

DEFAULT_HEADER_DENYLIST

Built-in denylist of well-known credential-bearing names, applied by default (RFC 040 Q1). Compared case-insensitively.

MAX_SUBSCRIBERS

Maximum concurrent out-of-process subscriber connections.

REDACTED_HEADER_VALUE

Placeholder value substituted for a redacted header (RFC 040 Goal 4). The header name is kept so a consumer can tell “redacted” from “the request never sent this header” — only the value differs.

TRACE_CHANNEL_CAPACITY

Capacity of the broadcast channel (events).

Functions

now_ms

Current Unix time in milliseconds.