zero_network_kit #

A Flutter plugin for network diagnostics: connectivity inspection, latency probing, DNS resolution, port checks, bandwidth measurement, quality scoring and micro-benchmarks — for Android, iOS, macOS, Windows, Linux and Web (partial).

🔔 Upgrade recommended: 1.0.1 adds partial Web support — the plugin now compiles and runs in the browser, and the capabilities the sandbox forbids degrade gracefully instead of failing. It also fixes the speed test on the web. Upgrade to ^1.0.1.

🌐 Official Website  ·  📦 View on pub.flutter-io.cn  ·  🔗 View on GitHub

Table of Contents #

• Features
• Getting started
  • Android permissions
• Usage
  • Connectivity
  • Ping
  • DNS
  • Speed test
  • Ports
  • Quality score
  • Full report
  • Benchmarks
• Testing your own code against it
• Platform support
• Documentation
• License

Features #

Design goals:

• Hermetic unit tests — every service accepts injected collaborators (ConnectivityAdapter, http.Client, PingService, …), so the whole test suite runs without touching the network.
• No hidden state — results are immutable value objects with toMap().
• Graceful degradation — a missing permission or an unreachable sub-service never throws through the public API; the corresponding field stays null.

Getting started #

dependencies:
  zero_network_kit: ^1.0.1

Android permissions #

The plugin manifest already declares INTERNET, ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE. Reading the Wi-Fi SSID additionally requires location permission (ACCESS_FINE_LOCATION) on Android 8.1+ and the Access WiFi Information entitlement plus location authorisation on iOS. Without it the snapshot simply reports ssid: null.

Usage #

The snippets below cover the common paths. For every method, parameter, default and result field, see the API guide.

import 'package:zero_network_kit/zero_network_kit.dart';

void main() {
  // Optional: apply global defaults once.
  ZeroNetworkKit.init(
    config: const NetworkDiagnosticConfig(
      pingHost: '1.1.1.1',
      dnsServers: <String>['1.1.1.1', '8.8.8.8'],
    ),
  );
  runApp(const MyApp());
}

Connectivity #

final info = await NetworkDiagnostic.checkConnection(probeReachability: true);

print('${info.type.label} · ${info.ipAddress} · ${info.signalStrength} dBm');
print('gateway=${info.gateway} vpn=${info.isVpn} reachable=${info.isReachable}');

await for (final change in NetworkDiagnostic.onConnectivityChanged) {
  print('now on ${change.type.id}');
}

Just need connectivity? You don't need init() or any of the other APIs — checkConnection() and onConnectivityChanged work out of the box. See the Connectivity-only: minimal example in the Connectivity chapter of API.md.

Ping #

final result = await NetworkDiagnostic.ping(host: '1.1.1.1', count: 5);

print('${result.received}/${result.sent} replies, '
      'loss ${result.packetLoss.toStringAsFixed(1)}%, '
      'avg ${result.averageTime.toStringAsFixed(1)} ms, '
      'jitter ${result.jitter.toStringAsFixed(2)} ms');

On desktop you can switch to the system ICMP binary:

await NetworkDiagnostic.ping(host: '1.1.1.1', mode: PingMode.icmp);

DNS #

final results = await NetworkDiagnostic.resolve(
  domain: 'example.com',
  dnsServers: const <String>['1.1.1.1', '8.8.8.8'],
  includeSystemResolver: true,
);

for (final r in results) {
  print('${r.server}: ${r.isSuccess ? r.resolvedIps.join(", ") : r.errorMessage}'
        ' (${r.responseTimeMs.toStringAsFixed(1)} ms)');
}

Speed test #

final speed = await NetworkDiagnostic.runSpeedTest(
  onProgress: (progress) => print(
    '${progress.phase.name}: ${progress.speedMbps.toStringAsFixed(1)} Mbps',
  ),
);

print('↓ ${speed.downloadSpeed.toStringAsFixed(2)} Mbps  '
      '↑ ${speed.uploadSpeed.toStringAsFixed(2)} Mbps');

Download and upload phases write a meaningful amount of traffic. Defaults point at the public Cloudflare speed endpoints; override downloadUrl / uploadUrl to use your own.

Ports #

if (await NetworkDiagnostic.isPortOpen(host: 'example.com', port: 443)) {
  print('HTTPS reachable');
}

final scan = await NetworkDiagnostic.scanPorts(
  host: 'example.com',
  ports: const <int>[22, 80, 443, 8080],
  concurrency: 8,
);

Quality score #

final score = await NetworkDiagnostic.evaluateQuality(includeSpeedTest: false);

print('${score.score}/100 (${score.level.label})');
for (final suggestion in score.suggestions) {
  print('• $suggestion');
}

The score is a weighted average of the metrics that are available:

Tune the ideal values with NetworkDiagnosticConfig(qualityTargets: ...).

Full report #

final report = await NetworkDiagnostic.diagnose(includePorts: true);

print(report); // NetworkDiagnosticReport(type: wifi, connected: true, score: 87.5)
print(report.toMap()); // JSON encodable

Benchmarks #

final suite = await NetworkBenchmark.runAll(iterations: 20, warmupIterations: 3);

for (final result in suite.results) {
  print('${result.testName}: avg '
        '${(result.averageDuration.inMicroseconds / 1000).toStringAsFixed(2)} ms, '
        '${result.operationsPerSecond.toStringAsFixed(1)} ops/s');
}

Benchmarks answer questions like "how expensive is one checkConnection() call on this device?" — useful when deciding whether a diagnostic belongs on the startup path.

Testing your own code against it #

Every service is injectable, so you can unit-test your integration points without a network:

class FakeConnectivityAdapter implements ConnectivityAdapter {
  @override
  Future<List<String>> checkConnectivity() async => <String>['wifi'];

  @override
  Stream<List<String>> get onConnectivityChanged => const Stream.empty();
}

NetworkDiagnostic.configure(
  connectivity: ConnectivityService(adapter: FakeConnectivityAdapter()),
);

NetworkDiagnostic.reset() restores the built-in defaults.

Platform support #

Web support #

The web build exposes the same static API. Capabilities that the browser sandbox forbids degrade gracefully — they return null or an "unavailable" result instead of throwing:

ZeroNetworkKit.getNativeNetworkDetails() returns null on the web and ZeroNetworkKit.getPlatformVersion() returns Web. Call NetworkCapabilities.current() to discover the supported set at runtime.

Documentation #

• API.md — complete usage guide: every public API with copy-paste examples, parameter defaults, model reference and common pitfalls.
• AGENTS.md — engineering contract: architecture, conventions and the new-feature checklist.
• CONTRIBUTING.md — how to set up and submit changes.
• CHANGELOG.md — release history.

License #

MPL-2.0 © Zero Labs

Third-party dependency, trademark and endorsement notices live in NOTICE.