flutter_turbo_fetch
A high-performance, non-blocking networking plugin for Flutter (package:dio).
flutter_turbo_fetch replaces traditional Dart-based HTTP streaming bottlenecks with platform-native batch reception (Android OkHttp3 / iOS & macOS URLSession / Windows WinHTTP / Linux libcurl) and zero-copy Isolate offloading (TransferableTypedData + semaphore-governed Isolate.run). It guarantees a silky-smooth 60/120 FPS UI thread even under heavy parallel HTTP/2 JSON, text, or binary workloads.
✨ Features
- Native HTTP/2 Batch Reception: Zero per-chunk FFI overhead via OS-level buffering (OkHttp3, URLSession, WinHTTP, & libcurl).
- Non-Blocking UI Thread: Eliminates jank on large payloads (>= 24KB) through zero-copy
TransferableTypedDataoffloading. - In-Worker Model Mapping: Directly parses and instantiates domain models inside worker Isolates.
- Full Dio Compatibility: Drop-in replacement supporting all 4 standard
ResponseTypes.
📋 Requirements & Compatibility
| Platform / Dependency | Supported Version | Status |
|---|---|---|
| Flutter | >= 3.24.0 |
Supported |
| Dart | >= 3.5.0 |
Supported |
| Dio | ^5.4.0 |
Supported |
| Android | minSdk = 24 (Android 7.0+) • okhttp:4.12.0 |
Tested & Benchmarked |
| iOS | iOS 13.0+ • URLSession (SPM & CocoaPods) |
Tested & Benchmarked (iPhone 17, Release) |
| macOS | macOS 10.15+ • URLSession (SPM & CocoaPods) |
Tested (Benchmarking Pending) |
| Windows | Windows 10 (1809+) (64-bit) • WinHTTP (winhttp.dll) |
Tested & Benchmarked |
| Linux | Ubuntu 20.04+ / Debian 11+ (64-bit) • libcurl |
Tested (Benchmarking Pending) |
| Web | Not Supported | Out of Scope |
Note
- iOS Status: A physical-device Release benchmark report documents measured tradeoffs and protocol details.
- macOS & Linux Status: Native implementations are complete and unit/integration-tested; formal end-to-end performance benchmarking reports are pending.
- Web: Web is not supported due to native OS transport requirements.
📦 Installation
Add flutter_turbo_fetch and dio to your Flutter project:
flutter pub add flutter_turbo_fetch dio
Or add them directly to your pubspec.yaml:
dependencies:
dio: ^5.4.0
flutter_turbo_fetch: ^0.0.4
⚙️ Platform Setup
Android
Ensure internet permission is declared in your app's android/app/src/main/AndroidManifest.xml:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
</manifest>
R8 / ProGuard: Rules for
OkHttp3are automatically bundled. No manual configuration is required unless using strict R8 full mode.
iOS
No special permissions are needed for HTTPS endpoints. If testing locally with cleartext HTTP or self-signed certificates, configure NSAppTransportSecurity in ios/Runner/Info.plist:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsLocalNetworking</key>
<true/>
</dict>
macOS
For macOS apps running with App Sandbox enabled (the default in Flutter), ensure outgoing network connections are permitted in both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:
<key>com.apple.security.network.client</key>
<true/>
Windows
No additional setup or external libraries are required. The plugin links directly against the Windows OS system component winhttp.dll.
Linux
Ensure libcurl and OpenSSL development headers are installed on your build machine:
sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev
💡 Quick Start
Configure a single Dio instance once at application startup.
TurboOptions inherits Dio's standard responseType = ResponseType.json default. By passing mapper, JSON decoding and domain model instantiation (.fromJson) execute entirely inside a Worker Isolate for payloads >= 24KB, returning typed objects to the UI thread in $O(1)$:
import 'package:dio/dio.dart';
import 'package:flutter_turbo_fetch/flutter_turbo_fetch.dart';
final dio = Dio()
..httpClientAdapter = TurboHttpAdapter()
..transformer = TurboTransformer();
// 1. Define your domain model
class UserModel {
UserModel.fromJson(Map<String, dynamic> json)
: id = json['id'] as int,
name = json['name'] as String;
final int id;
final String name;
}
// 2. Fetch directly as a typed model (parsed in a background Isolate)
final response = await dio.get<UserModel>(
'https://api.example.com/users/1',
options: TurboOptions.json<UserModel>(
mapper: (json) => UserModel.fromJson(json as Map<String, dynamic>),
),
);
final UserModel user = response.data!;
print('User: ${user.name}');
Tip
- In-Isolate Mapper: To run inside worker Isolates,
mappershould be a top-level function,staticmethod, or pure closure without capturing external mutable state. - Typed Factories: Use
TurboOptions.json,TurboOptions.bytes, orTurboOptions.plainto automatically bindresponseTypeand typemapperparameters (e.g.Uint8Listfor Protobuf/FlatBuffers). - Defensive Payload Guard: Terminate oversized responses early with
TurboOptions(maxResponseBytes: 10 * 1024 * 1024). - Standard Dio Features: Fully supports Dio's
CancelToken,sendTimeout, andreceiveTimeout.
🔧 Configuration & Tuning Parameters
TurboHttpAdapter
Configured once on the Dio instance to manage connection pools and transport security:
| Parameter | Type | Default | Description |
|---|---|---|---|
maxRequestsPerHost |
int |
32 |
Maximum concurrent HTTP/2 requests per host. On Android, OkHttp's dispatcher maxRequests is automatically scaled if greater than 64. |
allowBadCertificates |
bool |
false |
Allows self-signed certificates for local development and mock servers. |
TurboTransformer
Controls Isolate dispatching and thread concurrency:
| Parameter | Type | Default | Description |
|---|---|---|---|
isolateThresholdBytes |
int |
24 * 1024 (24KB) |
Payloads below this threshold are decoded synchronously on the Main Isolate (< 0.5ms). Payloads at or above this threshold are dispatched to Worker Isolates via zero-copy TransferableTypedData. |
maxConcurrentIsolates |
int? |
max(2, cores - 2) |
Maximum concurrent worker Isolates permitted by the internal semaphore, preventing CPU thread starvation during 10-20x burst requests. |
Tip
💡 Performance Tuning for High-End Devices (Apple Silicon / Flagship Phones):
The default configuration (24KB threshold, conservative semaphore) prioritizes UI frame safety on entry-level and mid-range mobile devices. On high-performance hardware (e.g., iPhone 15/16/17 with Apple Silicon, or modern flagship Android chips), consider these adjustments for maximum throughput:
- Increase
isolateThresholdBytes(Sweet spot: 128KB – 256KB): Modern high-end CPU cores decode JSON synchronously on the Main Isolate in < 0.7ms for 100KB and ~1.0ms for 200KB. Raising the threshold to 128KB–256KB avoids worker Isolate spawning and semaphore dispatch overhead (~1.0ms), matching the physical break-even point while keeping Main Isolate blocking safely below the strict 120 FPS frame budget (8.33ms).
// Example: Maximize throughput on high-end mobile devices
dio.transformer = TurboTransformer(
isolateThresholdBytes: 128 * 1024, // 128KB threshold (up to 256KB)
);
- Increase
maxConcurrentIsolatesfor Heavy Burst Concurrency: When issuing 10+ concurrent heavy JSON requests simultaneously over high-speed networks, scalingmaxConcurrentIsolatesto match the device's physical performance cores (e.g.,4to6) reduces semaphore queue wait times and maximizes parallel parsing throughput.
(Note: macOS applications running on Apple Silicon may also benefit from similar tuning.)
📊 Performance & Benchmarks
Compared to traditional HTTP/1.1 and streaming Dart adapters, flutter_turbo_fetch delivers:
- Up to 3x faster end-to-end response times under high concurrency.
- Zero UI frame drops (60/120 FPS preserved) during multi-megabyte JSON decoding and model mapping.
- Minimal memory footprints via native Okio/CFNetwork/WinHTTP buffering and zero-copy Isolate transfers.
To run benchmarks locally or view full empirical metrics on physical/emulator hardware:
- Microbenchmarks: Run
flutter test test/turbo_benchmark_test.dart - iOS Physical Device: iOS Benchmark Report documents empirical measurements on an iPhone 17 (Release mode). TurboFetch delivers 1.6x to 5.8x faster throughput than pure Dart HTTP/2 (
dio_http2) under a controlled split-pipeline protocol. - End-to-End Suite: Uses a local Node.js HTTP/2 mock server with self-signed TLS (
allowBadCertificates: true). Seeexample/for server setup and Benchmark Results for detailed metrics.
📚 Technical Documentation
For in-depth architecture and design rationale, see the docs/ directory in the GitHub repository:
- Design Rationale & Bottleneck Analysis: Technical justifications behind avoiding stream FFI, native JSON parsing, and persistent worker pools.
- Benchmark Results & Performance Analysis: Cross-platform empirical measurements, split-pipeline analysis, and hardware evaluations on Android, Windows, and iOS.
- TurboTransformer Implementation Reference: In-depth guide to zero-copy Isolate transformations and semaphore governance.
For internal development specifications and agent directives (maintained in Japanese), refer to specs/.
📄 License
This project is licensed under the MIT License.