background_http_client

Flutter plugin for executing HTTP requests in the background with a Dio-like interface.

Features

• Dio-like interface (GET, POST, PUT, DELETE, PATCH, HEAD)
• Background request execution
• Saving requests and responses to files
• Request status tracking
• Getting responses by request ID

Usage

Basic Usage

import 'package:background_http_client/background_http_client.dart';

final client = BackgroundHttpClient();

// GET request
final requestInfo = await client.get('https://api.example.com/data');

// POST request
final postInfo = await client.post(
  'https://api.example.com/data',
  data: {'key': 'value'},
);

// Get request status
final status = await client.getRequestStatus(requestInfo.requestId);

// Get response
final response = await client.getResponse(requestInfo.requestId);
if (response != null) {
  print('Status Code: ${response.statusCode}');
  print('Response File: ${response.responseFilePath}');
}

Request Methods

• get(url, {headers, queryParameters, timeout, requestId, retries}) - GET request
• post(url, {data, headers, queryParameters, timeout, requestId, retries}) - POST request
• put(url, {data, headers, queryParameters, timeout, requestId, retries}) - PUT request
• delete(url, {headers, queryParameters, timeout, requestId, retries}) - DELETE request
• patch(url, {data, headers, queryParameters, timeout, requestId, retries}) - PATCH request
• head(url, {headers, queryParameters, timeout, requestId, retries}) - HEAD request
• postMultipart(url, {fields, files, headers, queryParameters, timeout, requestId, retries}) - Multipart request

Retries

For automatic retries on errors (timeouts, network errors, server errors), use the retries parameter:

// Request with 3 retries
final requestInfo = await client.get(
  'https://api.example.com/data',
  retries: 3, // From 0 to 10
);

How it works:

• On error (timeout, network errors, HTTP status >= 400) the request is automatically retried
• Exponential backoff is used between retries: 2, 4, 8, 16, 32, 64, 128, 256, 512 seconds (max 512)
• Request status is updated to "in progress" during retry wait
• After all retries are exhausted, the request is marked as FAILED

Handling No Internet Connection

Android:

• When there's no internet, WorkManager automatically waits for network availability thanks to NetworkType.CONNECTED constraint
• The task will be automatically executed when internet becomes available, even if the app is closed
• On network errors (SocketException, ConnectException, UnknownHostException) the task is automatically retried when network becomes available

iOS:

• When there's no internet, URLSession automatically handles network errors
• If the app is in background (minimized), the request will be automatically retried when network becomes available
• After complete app termination, iOS may limit task execution

Request Statuses

• RequestStatus.inProgress - request is in progress
• RequestStatus.completed - response received from server
• RequestStatus.failed - request failed with error

Architecture

The plugin works according to the following flow:

1. Request is executed via get, post, etc. methods
2. Manager saves a file for the request, returns ID and file path
3. Manager is responsible for sending, has 3 statuses: in progress, response received, error
4. Server response is saved to a file
5. By ID you can get the server response and path to the response file

Background Work

Android

• Uses WorkManager for executing requests in the background
• Requests continue to execute even after the app is closed
• Retries: When using retries, retry attempts are scheduled via WorkManager with delay, ensuring execution even when the app is closed
• WorkManager automatically manages task execution in the background

iOS

• Uses URLSession with background configuration for background work
• Requests continue to execute when the app is in background (minimized)
• Retries: When using retries, retry attempts work when the app is in background (minimized), but may not work after complete app termination
• Important: After complete app termination, iOS may limit task execution. For guaranteed background work, it's recommended to keep the app minimized rather than completely closing it.

Platforms

The plugin requires native implementation for Android and iOS. Method channel background_http_client is used for communication between Dart and native code.