httpio_client - Flutter Networking Package #

httpio_client is a powerful, unified networking package for Flutter that provides a consistent interface for both Dio and http packages. It handles common tasks like token refresh, retries, logging, and offline queuing with minimal configuration.

🏗 Architecture #

httpio_client follows a layered architecture to ensure flexibility and maintainability.

graph TD
    App[App Developer] --> HTTPio[HttpioClient Factory]
    HTTPio --> Config[NetworkConfig]
    HTTPio --> Client[NetworkClient Interface]
    Client --> Dio[DioNetworkClient]
    Client --> Http[HttpNetworkClient]
    
    Dio --> Interceptors[Interceptors/Middleware]
    Http --> Interceptors
    
    Interceptors --> Auth[Auth / Token Refresh]
    Interceptors --> Retry[Retry Logic]
    Interceptors --> Log[Logging]
    Interceptors --> Offline[Offline Queue]
    Interceptors --> Cache[Caching]
    
    Interceptors --> Server((API Server))
    Server --> Response[Standardized ApiResponse]
    Response --> App

🔄 Request Flow #

1. Pre-Request: Attach global/request headers, auth token, and query parameters.
2. Offline Check: If offline and queuing is enabled, wait for connectivity.
3. Execution: Send request via chosen client (Dio or http).
4. Error Handling:
   • 401 Unauthorized: Trigger TokenRefreshHandler, queue concurrent requests, and retry.
   • 403 Forbidden: Return ForbiddenException.
   • 404 Not Found: Return NotFoundException.
   • Transient Errors (5xx, Network): Apply RetryConfig with exponential backoff.
5. Standardization: Wrap response/error into ApiResponse<T>.

🚀 Features #

• ✅ Unified Interface: Switch between Dio and http seamlessly.
• ✅ WASM Compatible: Works across all platforms including Web (WASM).
• ✅ Token Refresh: Automatic handling of 401 errors with concurrent request queuing.
• ✅ Retry Logic: Configurable retries with exponential backoff for network and server errors.
• ✅ Logging: Detailed request/response logging with sensitive info masking.
• ✅ Offline Queuing: Optionally wait for internet connection before sending requests.
• ✅ Caching: Built-in support for caching GET requests.
• ✅ Standardized Responses: Every request returns an ApiResponse<T> with data, message, and result flag.
• ✅ Multipart Support: Platform-agnostic file uploads using HttpioFile.

📦 Installation #

Add the following to your pubspec.yaml:

dependencies:
  httpio_client: ^1.0.1

🛠 Usage #

Initialization #

final client = HttpioClient.create(NetworkConfig(
  clientType: ClientType.dio,
  baseUrl: 'https://api.example.com',
  token: 'initial_access_token',
  enableLogging: true,
  enableOfflineQueuing: true,
  retryConfig: RetryConfig(
    maxRetries: 3,
    retryDelays: [Duration(seconds: 1), Duration(seconds: 2), Duration(seconds: 4)],
  ),
  tokenRefreshHandler: () async {
    // Logic to refresh token
    return 'new_access_token';
  },
));

Making Requests #

// GET Request
final response = await client.get<Map<String, dynamic>>(
  '/user/profile',
  headers: {'X-Custom-Header': 'value'},
);

if (response.success) {
  print('User Data: ${response.data}');
} else {
  print('Error: ${response.message}');
}

// POST Request with Body
final postResponse = await client.post(
  '/posts',
  data: {'title': 'Hello', 'body': 'World'},
);

// Multipart File Upload
final uploadResponse = await client.multipart(
  '/upload',
  data: {
    'file': HttpioFile.fromPath('path/to/file.png', name: 'profile.png'),
    'type': 'image',
  },
  onSendProgress: (sent, total) {
    print('Progress: ${(sent / total * 100).toStringAsFixed(0)}%');
  },
);

⚙️ Configuration Options #