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 (Benchmarking Pending) |
| 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, 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. |
📊 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 - 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 and frame-timing evaluations on Android and Windows.
- 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.