Network Quality Estimator (NQE)

A cross-platform C++17 Network Quality Estimator inspired by Chromium's implementation, achieving ~100% feature parity with Chrome NQE.

Overview

This library provides comprehensive network quality estimation with support for:

• RTT (Round-Trip Time) measurement from multiple sources
• Downstream throughput tracking
• Effective Connection Type (ECT) classification
• Network change detection
• Cross-platform support (Windows, Linux, macOS, Android, iOS)

Key Features

✅ Chrome NQE Feature Parity (~100%)

• End-to-End RTT observation category
• 12+ granular observation sources
• HTTP RTT bounding and adjustment
• ECT-based throughput clamping
• Dual-factor observation weighting
• Window-level hanging detection
• Signal strength tracking infrastructure

✅ RTT Estimation

• HTTP RTT (TTFB via libcurl)
• Transport RTT (TCP_INFO / SIO_TCP_INFO)
• End-to-End RTT (full request-response cycle)
• QUIC/H2 PING support (adapter interface)
• Time-weighted median aggregation

✅ Throughput Analysis

• Request-based throughput tracking
• Chromium-style observation windows
• Hanging window detection (cwnd heuristic)
• ECT-based maximum clamping
• Configurable filtering

✅ Network Quality Classification

• ECT classification: SLOW_2G, 2G, 3G, 4G, UNKNOWN
• Configurable thresholds
• Intelligent recomputation triggers
• Observer pattern for ECT changes

✅ Cross-Platform Support

• Windows: SIO_TCP_INFO, WLAN/WWAN APIs
• Linux: TCP_INFO, netlink sockets
• macOS/iOS: TCP_INFO, SystemConfiguration
• Android: TCP_INFO, JNI integration, netlink

Quick Start

Automated Build (Recommended)

Windows:

setup_curl_windows.bat

macOS:

chmod +x setup_curl_macos.sh
./setup_curl_macos.sh

Linux:

chmod +x setup_curl_linux.sh
./setup_curl_linux.sh

These scripts will automatically:

• Download/install CURL (via package manager or from source)
• Configure CMake with correct paths
• Build all targets with optimizations
• Copy necessary libraries to output directory

Manual Build

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j

Basic Usage

#include "nqe/Nqe.h"

// Configure and create NQE
nqe::Nqe::Options opts;
opts.enable_http_rtt_bounding = true;
opts.enable_throughput_clamping = true;

nqe::Nqe estimator(opts);
estimator.startTransportSampler();

// Add observations
estimator.addSample(nqe::Source::TCP, 25.0, nqe::ObservationCategory::TRANSPORT_RTT);
estimator.addSample(nqe::Source::URL_REQUEST, 120.0, nqe::ObservationCategory::HTTP_RTT);

// Get estimates
auto estimate = estimator.getEstimate();
std::cout << "RTT: " << estimate.rtt_ms << "ms\n";
std::cout << "ECT: " << nqe::effectiveConnectionTypeToString(estimate.effective_type) << "\n";

Documentation

• English Documentation - Comprehensive guide with API reference
• 中文文档 - 完整的中文指南和 API 参考
• Chrome NQE Features - Detailed feature parity documentation
• Chrome NQE 功能特性 - Chrome NQE 功能详细说明
• Android Build Guide - Android integration instructions
• Benchmark Results - Performance benchmarks

Examples

The repository includes several example programs:

• libcurl_multi_nqe_example - Full integration with libcurl multi interface
• advanced_features_demo - Demonstrates Chrome NQE features (1-5)
• complete_features_demo - Demonstrates all 8 Chrome NQE features
• extended_features_test - ECT, throughput, and observer tests
• network_change_test - Network change detection tests
• http_rtt_example - Standalone HTTP RTT tracking
• ping_rtt_example - Standalone PING RTT tracking
• feature_test - Core library feature tests

Architecture

nqe/
├── include/nqe/           # Public API headers
│   ├── Nqe.h              # Main NQE interface
│   ├── EffectiveConnectionType.h
│   ├── ThroughputAnalyzer.h
│   ├── NetworkChangeNotifier.h
│   └── NetworkQualityObserver.h
├── src/                   # Implementation
│   ├── Nqe.cpp
│   ├── ThroughputAnalyzer.cpp
│   ├── NetworkChangeNotifier.cpp
│   ├── aggregators/       # Aggregation components
│   │   ├── Aggregator.h   # Shared aggregator (min/max/percentile)
│   │   ├── WeightedMedian.h  # Time-weighted median (deque-based)
│   │   └── Combiner.h     # RTT combination logic
│   └── platform/          # Platform-specific code
├── test/                  # Example programs and tests
├── chrome_nqe_src/        # Chrome NQE reference implementation
└── docs/                  # Documentation

Chrome NQE Feature Comparison

Requirements

• CMake 3.15 or higher
• C++17 compiler (GCC 7+, Clang 5+, MSVC 2017+)
• libcurl (optional, for examples)
• Platform-specific:
  • Windows: Windows 10+ (for SIO_TCP_INFO)
  • Linux: Kernel 2.6+ (for TCP_INFO)
  • Android: NDK r21+ (for JNI integration)

Performance

• Minimal overhead: ~2.7% compared to basic implementation
• Thread-safe: All public APIs are thread-safe
• Efficient: Time-weighted median with deque-based O(1) sample eviction
• Configurable: Adjustable decay rates, thresholds, and intervals

Platform Support

License

This project is licensed under the terms specified in the LICENSE file.

References

• Chromium Network Quality Estimator
• Effective Connection Type Specification
• Chrome NQE Design Document

Contributing

This is a demonstration project showcasing Chrome NQE feature implementation. For production use, please ensure thorough testing and validation for your specific use case.

Note: This implementation is inspired by Chromium's NQE but is a standalone library with no Chromium dependencies. It's designed for easy integration into any C++17 project.