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.
DecorrelatedJitterBackoff
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 DioException should 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 CacheInterceptor for 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.