Skip to main content

flutter_turbo_fetch 0.0.5 copy "flutter_turbo_fetch: ^0.0.5" to clipboard
flutter_turbo_fetch: ^0.0.5 copied to clipboard

High-performance HTTP/2 batch fetch and zero-copy transform plugin for Dio.

flutter_turbo_fetch #

pub package License: MIT

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 TransferableTypedData offloading.
  • 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 OkHttp3 are 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, mapper should be a top-level function, static method, or pure closure without capturing external mutable state.
  • Typed Factories: Use TurboOptions.json, TurboOptions.bytes, or TurboOptions.plain to automatically bind responseType and type mapper parameters (e.g. Uint8List for Protobuf/FlatBuffers).
  • Defensive Payload Guard: Terminate oversized responses early with TurboOptions(maxResponseBytes: 10 * 1024 * 1024).
  • Standard Dio Features: Fully supports Dio's CancelToken, sendTimeout, and receiveTimeout.

🔧 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:

  1. 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)
);
  1. Increase maxConcurrentIsolates for Heavy Burst Concurrency: When issuing 10+ concurrent heavy JSON requests simultaneously over high-speed networks, scaling maxConcurrentIsolates to match the device's physical performance cores (e.g., 4 to 6) 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). See example/ 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:

For internal development specifications and agent directives (maintained in Japanese), refer to specs/.


📄 License #

This project is licensed under the MIT License.

0
likes
160
points
918
downloads

Documentation

API reference

Publisher

verified publisherhogelab.net

Weekly Downloads

High-performance HTTP/2 batch fetch and zero-copy transform plugin for Dio.

Repository (GitHub)
View/report issues

Topics

#dio #http2 #networking #performance #isolate

License

MIT (license)

Dependencies

dio, flutter

More

Packages that depend on flutter_turbo_fetch

Packages that implement flutter_turbo_fetch