network_quality.hpp

1. Overview

The network_quality.hpp header defines the NetQuality struct, a lightweight, lock-free network quality estimator designed to provide fast, reactive decisions for latency-sensitive workflows (notably DNS resolution). The component maintains exponentially weighted moving averages (EWMA) for round-trip time (RTT) and loss rate, then derives a coarse network classification and recommends timeouts for DNS and HTTPS operations.

Functionally, NetQuality provides:

  • Lock-free EWMA tracking of RTT (milliseconds) and loss probability
  • Heuristic network classification (e.g., Wi-Fi vs. DSL vs. mobile-like)
  • Recommended timeout values for DNS and HTTPS requests
  • Quick identification of slow/mobile-like connectivity
  • Convenient accessors for the current EWMA values

2. Dependencies and Includes

#include <atomic>
#include <string>
#include <cmath>
#include <algorithm>
  • <atomic> – lock-free, thread-safe storage for EWMA values and sample count
  • <string> – return values for network classification
  • <cmath> – numeric utilities (general-purpose; optional depending on implementation)
  • <algorithm> – clamping of RTT samples to avoid unrealistic spikes

3. Data Structure and Scope

struct NetQuality

NetQuality is a simple, POD-like structure intended to be used as a shared metric aggregator. It relies on atomics and relaxed memory ordering to keep overhead minimal and avoid locking in hot paths.

4. Internal Metrics

std::atomic<double> ewma_rtt_ms{50.0};
std::atomic<double> ewma_loss{0.0};
std::atomic<int>    samples{3};
  • ewma_rtt_ms – EWMA of measured RTT in milliseconds (seeded to 50 ms)
  • ewma_loss – EWMA of observed failure probability (0.0 = no loss)
  • samples – number of ingested samples (seeded to 3 to avoid an “unknown” state)

5. Public Interface

5.1 Sample Ingestion

void update_sample(double rtt_ms, bool success);

Updates the EWMA metrics with a new observation. The algorithm is tuned for responsiveness using a relatively high smoothing factor (alpha), and clamps RTT values to a realistic range to avoid extreme outliers skewing the estimates.

Key behaviors:

  • Reactive EWMA: alpha = 0.55 prioritizes recent samples
  • RTT clamp: RTT is clamped to [1.0, 2000.0] ms
  • Loss EWMA: success contributes 0.0, failure contributes 1.0
  • Lock-free: uses relaxed atomics for minimal contention

5.2 Network Classification

std::string classify_network() const;

Classifies the current connection quality into a coarse label by applying thresholds over the EWMA RTT and EWMA loss values.

Possible outputs include:

  • bootstrap – insufficient sampling
  • fiber-ftth, ethernet, wifi, dsl/adsl, fwa-4g, 5g
  • unstable – high RTT and/or high loss

5.3 Recommended DNS Timeout

int recommended_dns_timeout() const;

Returns a recommended DNS timeout (milliseconds) derived from the current network classification. The intent is to keep DNS resolution responsive (< 100 ms where feasible) while remaining practical on slower links.

5.4 Recommended HTTPS Timeout

int recommended_https_timeout() const;

Returns a recommended HTTPS timeout (milliseconds) derived from the current network classification. Values are larger than DNS timeouts to account for TLS handshakes and request/response overhead.

5.5 Mobile-Like Shortcut

bool is_mobile_like() const;

Provides a fast predicate to identify slower or less stable connectivity, based on threshold checks of EWMA RTT and EWMA loss.

5.6 Metric Accessors

double rtt_ms() const;
double loss() const;

Returns the current EWMA RTT and EWMA loss values for telemetry, diagnostics, or adaptive tuning.

6. Timeout Policy

The timeout values are derived from the classification labels and reflect an opinionated tuning:

  • Lower DNS timeouts on fast networks (e.g., 60–80 ms)
  • Moderate DNS timeouts on Wi-Fi/DSL (120–160 ms)
  • Higher DNS timeouts on mobile-like or unstable networks (200–250 ms)
  • HTTPS timeouts scaled up to account for protocol and handshake overhead

7. Global Instance

extern NetQuality g_net_quality;

Declares a global instance (defined in network_quality.cpp) intended to provide a shared, process-wide view of network conditions.

8. Security and Operational Considerations

  • Heuristic nature: classification and timeouts are heuristic and should be treated as adaptive hints rather than strict guarantees
  • Sampling bias: quality depends on the representativeness of ingested RTT/loss samples; ensure samples reflect the real paths used by the application
  • Relaxed atomics: relaxed memory ordering improves performance but does not provide cross-thread ordering guarantees beyond atomicity; this is appropriate for telemetry-style metrics
  • Outlier control: RTT clamping limits extreme spikes, but sustained pathological values will still drive the EWMA upward as intended
  • Privacy: if metrics are logged or exported, ensure they are treated as operational data and handled according to applicable privacy and telemetry policies
Published on:
Last updated on: