iroh_netbench/
event.rs

1//! Progress events emitted during a benchmark.
2
3use std::time::Duration;
4
5use serde::{Deserialize, Serialize};
6
7use crate::{NetBenchReport, PathKind};
8
9/// Fine-grained benchmark-flow negotiation and path progress.
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11pub enum FlowStage {
12    /// The host-routed reliable bidirectional control stream became active.
13    ControlStreamReady,
14    /// Client versions and capabilities were sent.
15    ClientHelloSent,
16    /// The server selected a compatible version.
17    ServerHelloReceived {
18        /// Negotiated wire version.
19        version: u16,
20    },
21    /// A selected transport path was observed.
22    PathObserved {
23        /// Current selected path.
24        path: PathKind,
25    },
26    /// A direct path was selected after the business flow started.
27    DirectPathSelected {
28        /// Time since the business flow started.
29        elapsed: Duration,
30    },
31    /// Direct-path waiting expired and Relay remains selected.
32    RelayRetained {
33        /// Time spent waiting for Direct.
34        waited: Duration,
35    },
36}
37
38/// Business-flow details available after protocol negotiation and path stabilization.
39#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
40pub struct FlowInfo {
41    /// Time spent negotiating the benchmark protocol.
42    pub negotiation_time: Duration,
43    /// Path observed at measurement start.
44    pub path: PathKind,
45}
46
47/// One RTT observation.
48#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
49pub struct LatencySample {
50    /// Monotonic sequence number within the test.
51    pub sequence: u64,
52    /// Round-trip duration.
53    pub rtt: Duration,
54}
55
56/// Cumulative loss-probe progress.
57#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
58pub struct LossSample {
59    /// Probes sent so far.
60    pub sent: u64,
61    /// Echoes received so far.
62    pub received: u64,
63    /// Sent probes which have not yet produced a unique echo.
64    pub outstanding: u64,
65}
66
67/// Throughput traffic direction.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
69pub enum ThroughputDirection {
70    /// Server to client.
71    Download,
72    /// Client to server.
73    Upload,
74}
75
76/// One interval throughput observation.
77#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
78pub struct ThroughputSample {
79    /// Traffic direction.
80    pub direction: ThroughputDirection,
81    /// Time elapsed in the accounted measurement window.
82    pub elapsed: Duration,
83    /// Payload bytes received by the measuring side so far.
84    pub received_bytes: u64,
85    /// Rate for the most recent sampling interval.
86    pub interval_bps: f64,
87}
88
89/// Progress emitted by [`crate::NetBenchTest`].
90#[allow(
91    clippy::large_enum_variant,
92    reason = "the public API intentionally exposes Finished(NetBenchReport)"
93)]
94#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
95pub enum NetBenchEvent {
96    /// One detailed business-flow negotiation/path milestone.
97    FlowStage(FlowStage),
98    /// Business-flow negotiation completed.
99    Ready(FlowInfo),
100    /// Idle latency measurement started.
101    LatencyStarted,
102    /// One idle RTT was observed.
103    LatencySample(LatencySample),
104    /// Datagram timeout measurement started.
105    LossStarted,
106    /// Datagram timeout progress changed.
107    LossSample(LossSample),
108    /// Download warm-up traffic started.
109    DownloadWarmupStarted,
110    /// Download measurement started.
111    DownloadStarted,
112    /// Download rate was sampled.
113    DownloadSample(ThroughputSample),
114    /// Upload warm-up traffic started.
115    UploadWarmupStarted,
116    /// Upload measurement started.
117    UploadStarted,
118    /// Upload rate was sampled.
119    UploadSample(ThroughputSample),
120    /// The complete report is available.
121    Finished(NetBenchReport),
122}
iroh_netbench/event.rs

iroh_netbench/
event.rs
