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 (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 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.

📊 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). 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.