Module surb_telemetry 

Records SURB round-trips as network graph edge telemetry. Turns SURB round-trips into edge telemetry for the network graph.

A SURB rides a forward path to reach its destination and carries a return path for the reply to come back on. When the reply arrives, that is proof both legs passed end to end – evidence the graph already wants, produced by traffic a session was sending anyway. Unlike a probe it costs no extra packets and accrues at data rates, which is what lets a dead relayer be noticed in seconds rather than after a probe success rate has moved behind a path cache.

Why one layer owns both directions

Minting and consuming happen at opposite ends of the pipeline, but only together do they mean anything: the mint says what was expected, the reply says what was observed. Wrapping both codec halves keeps the SURB-to-path association private to this module, so nothing below has to carry a path identity it has no other use for.

Structs

Silence 🔒

Per-pair silence bookkeeping, carried between flushes.

SurbRoundTripCounters

Expected/observed counts for one pair of legs, accumulated between flushes.

SurbRoundTripRegistry

Round-trip counts keyed by the legs they were observed over.

SurbTelemetryCodec

Wraps a codec so the SURBs it mints and consumes are counted per pair of legs.

Enums

NoPathTelemetry

Counterpart to NoPeerTelemetry for the path half of record_edge.

NoPeerTelemetry

record_edge is generic over peer and path telemetry that a SURB observation does not carry.

Constants

FLUSHES_BETWEEN_REPLANS 🔒

Flushes a destination must wait before it can be re-planned again.

ME_SLOT_UNKNOWN 🔒

me_slot value meaning “this node’s slot has not been learned yet”.

MIN_EXPECTED_FOR_SILENCE 🔒

SURBs a pair must have minted in one flush before its silence counts as evidence.

PATH_ID_SLOTS 🔒

Slots in a [PathId], and therefore the longest leg that can be reported.

PENDING_SURB_TTL 🔒

How long a minted SURB stays eligible to be observed coming back.

SILENT_FLUSHES_BEFORE_DEGRADED 🔒

Consecutive silent flushes before a pair that used to deliver is called dead.

Functions

flush_into

Turns accumulated counts into graph observations.

no_path_slots

A resolver that places no node, so nothing is ever attributed.

path_id 🔒

Builds the [PathId] of a leg from the nodes it visits.

path_slots_of

Reads path slots out of a network graph.

pending_legs

Builds the shared pending map, bounded by capacity and TTL.

return_relayers 🔒

Relayers carrying the reply leg: everything between the destination and ourselves.

round_trip_paths 🔒

Derives both legs of a round-trip from the routing that produced the SURB.

Type Aliases

PathSlotResolver

Resolves a node to the slot it occupies in a [PathId].

PendingLegs

Legs each outstanding SURB was minted over, shared between the two codec halves.