smart_network library
smart_network
A smart, production-ready networking layer for Flutter.
Features:
- π Automatic Retry with Exponential / Linear / Constant Backoff
- ποΈ Multi-Strategy Cache (Memory + Hive): Cache-First, Network-First, Network-Only, Cache-Only, Stale-While-Revalidate
- π Request Deduplication β prevents duplicate in-flight requests
- π΅ Offline Queue β persists requests on disk, auto-retries on reconnect
- π Thread-safe JWT Auto Refresh using Lock + Completer pattern
- π¦ Request Batching β groups multiple calls into one HTTP request
- πͺ΅ Built-in structured logging
Usage:
import 'package:smart_network/smart_network.dart';
await SmartNetworkClient().initialize(SmartConfig(baseUrl: 'https://api.example.com'));
final response = await SmartNetworkClient().get<User>('/users/1', fromJson: User.fromJson);
Classes
- BackoffStrategy
- Abstract contract for all delay-calculation strategies used between retry attempts.
- BatchConfig
- Configuration for the request batching system.
- BatchEntry
- Represents a single request pending inside BatchProcessor.
- BatchProcessor
- Accumulates individual requests within a time window and dispatches them as a single batched HTTP call to BatchConfig.batchEndpoint.
- CacheEntry
- A single entry stored in the cache, wrapping the raw response data alongside metadata needed to evaluate freshness.
- CacheKeyBuilder
-
Builds deterministic, collision-resistant cache keys from
RequestOptions. - CachePolicy
- Controls how SmartNetwork caches GET responses.
- ConnectivityMonitor
- Monitors device connectivity and notifies listeners when the network status changes.
- ConstantBackoff
- Waits the same fixed delay before every retry attempt.
- Implements the "decorrelated jitter" algorithm from the AWS blog: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
- ExponentialBackoff
- Doubles the wait duration with each attempt and adds random jitter.
- HiveCache
-
Persistent cache backed by
Hiveβ the L2 (disk) cache layer. - InMemoryTokenStorage
- Default in-memory storage β suitable for testing and short-lived sessions.
- LinearBackoff
- Increases the wait duration by a constant step with each attempt.
- MemoryCache
- In-memory LRU cache (L1 layer).
- NetworkUtils
- A collection of stateless utility functions used across SmartNetwork.
- OfflineEntry
- Represents a single persisted request in the offline queue.
- OfflineQueue
- Persistent FIFO queue for storing network requests that could not be sent due to the device being offline.
- PendingRequest
- Holds the Completer for an in-flight request so that subsequent identical requests can share the same Future outcome.
- QueueProcessor
- Replays all entries in OfflineQueue against the network when connectivity is restored.
- RequestDeduplicator
- Manages a registry of in-flight requests to prevent duplicate HTTP calls.
- RetryEvaluator
-
Decides whether a failed
DioExceptionshould be retried given the current RetryPolicy and the number of attempts already made. - RetryPolicy
- Defines when and how SmartNetworkClient retries failed requests.
- SmartCache
- Abstract interface for all cache backends.
- SmartConfig
- Central configuration object for SmartNetworkClient.
- SmartLogger
- Structured logger for SmartNetwork.
- SmartNetworkClient
- The primary entry point for SmartNetwork.
- SmartRequest
- Represents a single outgoing network request before it is dispatched.
-
SmartResponse<
T> - The unified, type-safe response wrapper returned by SmartNetworkClient.
- TokenManager
- Thread-safe manager for JWT access tokens.
- TokenPair
- A pair of JWT tokens returned by the auth server.
- TokenRefresher
- Contract that the host application must implement to teach SmartNetwork how to refresh expired tokens.
- TokenStorage
- Abstract interface for persisting and retrieving token pairs.
Enums
- CacheStrategy
-
Determines the logic applied by
CacheInterceptorfor each GET request. - HttpMethod
- Supported HTTP methods.
- SmartExceptionType
- Categorises all possible failure modes from SmartNetwork.
Constants
- visibleForTesting β const _VisibleForTesting
Exceptions / Errors
- SmartException
- A unified exception thrown by SmartNetworkClient for all failure modes.