linkprobe_core/
lib.rs

1//! Protocol-agnostic network link measurement for Rust.
2//!
3//! `linkprobe-core` provides shared types, server discovery, measurement backends, and
4//! OpenMetrics formatting. The [`linkprobe`](https://github.com/rtmongold/linkprobe) CLI
5//! crate adds argument parsing, MQTT publish, and an HTTP scrape endpoint on top of this
6//! library.
7//!
8//! Use this crate when you want to embed link measurement in an agent, dashboard, or test
9//! harness. Use the CLI when you want a ready-made probe with JSON, Prometheus, and MQTT
10//! exporters.
11//!
12//! # Backends
13//!
14//! All engines implement [`MeasurementEngine`] and run **synchronously** (blocking HTTP or a
15//! subprocess). Pick the backend that matches your endpoint:
16//!
17//! | Backend | Type | Requires | Typical fields |
18//! | --- | --- | --- | --- |
19//! | LibreSpeed | [`LibreSpeedEngine`](backends::LibreSpeedEngine) | Outbound HTTPS | latency, jitter, download, upload |
20//! | iperf3 | [`Iperf3Engine`](backends::Iperf3Engine) | `iperf3` on `PATH` | latency, jitter, download, upload; UDP adds packet loss |
21//!
22//! Optional fields on [`Measurement`] mean the backend did not report that metric for the run
23//! (for example TCP iperf3 has no packet loss).
24//!
25//! # Example
26//!
27//! ```no_run
28//! use linkprobe_core::backends::LibreSpeedEngine;
29//! use linkprobe_core::{MeasurementEngine, Server};
30//!
31//! let server = Server::librespeed("https://example-librespeed/");
32//! let engine = LibreSpeedEngine::new()?;
33//! let measurement = engine.measure(&server)?;
34//!
35//! if let Some(ms) = measurement.latency_ms {
36//!     println!("latency: {ms:.1} ms");
37//! }
38//! # Ok::<(), linkprobe_core::Error>(())
39//! ```
40//!
41//! Discovery helpers such as [`fetch_librespeed_servers`] and [`rank_by_latency`] need a
42//! network connection. See [`FAILOVER_EXTRA`] for list rotation behavior used by the CLI.
43
44mod discovery;
45mod error;
46pub mod export;
47mod measurement;
48mod result;
49mod server;
50
51pub mod backends;
52
53pub use discovery::{
54    DEFAULT_IPERF3_SERVERS_URL, DEFAULT_LIBRESPEED_SERVERS_URL, FAILOVER_EXTRA,
55    failover_candidates, fetch_iperf3_servers, fetch_librespeed_servers, parse_iperf3_servers,
56    parse_librespeed_servers, pick_lowest_latency, rank_by_latency, server_by_id, servers_list_url,
57};
58pub use error::Error;
59pub use export::{format_openmetrics, format_openmetrics_failed};
60pub use measurement::{Measurement, Throughput};
61pub use result::RunResult;
62pub use server::Server;
63
64/// Runs latency, download, upload, and optional packet-loss measurement against a [`Server`].
65///
66/// A single call performs the full probe for that backend (ping/jitter plus throughput tests).
67/// Implement this trait to add new measurement protocols alongside
68/// [`LibreSpeedEngine`](backends::LibreSpeedEngine) and [`Iperf3Engine`](backends::Iperf3Engine).
69pub trait MeasurementEngine {
70    fn measure(&self, server: &Server) -> Result<Measurement, Error>;
71}
linkprobe_core/lib.rs

linkprobe_core/
lib.rs
