Module diagnostics 

Normal-path download diagnostics instrumentation.

Runtime-gated sidecar JSONL writer for ant file download --download-diagnostics <PATH>. One record is emitted per normal-path chunk fetch attempt (cache hit, per-peer attempt, lookup failure, or exhausted peer set) while the existing early-return / retry / adaptive-concurrency / stdout behaviour is preserved.

When the --download-diagnostics flag is absent, no channel, file, or writer is created and the download path is unchanged. The optional sender threaded through the file/chunk download path is None, so record construction is skipped entirely (no allocation, no I/O).

Schema v4: exact node/client request correlation

Peer-attempt records carry the request ID allocated by this client and the client’s local peer ID. The same request ID is encoded on the chunk GET, while the peer ID matches the serving node’s source_peer, permitting an exact join to node-side GET telemetry. Chunk-level records leave both fields null because no individual peer request was sent.

The stacked ant-protocol PR WithAutonomi/ant-protocol#32 exposes send_and_await_chunk_response_with_metadata, which returns a ChunkProtocolResponse { result, source_peer, transport_source }. The stacked saorsa-core PR WithAutonomi/saorsa-core#162 exposes P2PNode::classify_peer_transport_route(expected_peer, transport_source) returning a PeerRouteKind (direct/relay/lan/unverified/unknown). Schema v4 records the actual source_peer and transport_source from the observed response, classifies the route from the actual transport source against the peer’s typed DHT addresses, and attaches a route_note only when the route is unknown. A peer_connected_before_request sample (node.is_peer_connected(peer) called before the send) and an adaptive fetch_cap snapshot are included on every record.

TTFB limitation

The protocol event is emitted only after complete message reassembly, so this branch measures complete-response latency (response_elapsed_ms), not true network time-to-first-byte. ttfb_ms is always null, ttfb_available is false, and ttfb_unavailable_reason carries the explanation. This prevents complete-response latency being presented as TTFB.

Structs

DownloadDiagnosticsRecord

One JSONL record for a normal-path chunk fetch attempt.

DownloadDiagnosticsSender

A cloneable, bounded sender for diagnostic records.

Enums

DownloadDiagnosticsOutcome

The outcome of a single normal-path chunk fetch attempt.

Constants

DIAGNOSTICS_SCHEMA_VERSION

Current diagnostic record schema discriminator.

Functions

bounded_error

Bound an error message to DIAGNOSTICS_ERROR_MAX_CHARS chars, preserving a leading category if one is supplied.

spawn_download_diagnostics_writer

Open <path> for writing (truncated), spawn a dedicated OS thread that drains records from a bounded channel and writes one JSON line per record to a buffered writer, flushing on close.