CachingHttpClientHive class

A persistent disk implementation of CachingHttpClient for GET requests using hive_ce.

Stores HTTP responses on disk in a Hive Box, retaining cache state across application restarts.

CAUTION for Cloud Run & Serverless environments: In Cloud Run or Cloud Functions, the local filesystem (e.g. /tmp) is an ephemeral in-memory filesystem (tmpfs). Writing files to local disk in Cloud Run directly consumes container RAM! Unless an external volume (such as Cloud Storage Volume Mount or Cloud Filestore NFS) is mounted, setting a large maxSizeBytes may cause Out-Of-Memory (OOM) errors. Use appropriate limits or mount a persistent volume.

Default parameters:

Cloud Run RAM presets:

  • Light container (512 MB – 1 GB RAM): maxSizeBytes = 50 MB – 100 MB.
  • Standard server (2 GB RAM): maxSizeBytes = 250 MB – 500 MB.
  • Heavy server (4 GB+ RAM): maxSizeBytes = 500 MB – 1 GB.
Inheritance

Constructors

CachingHttpClientHive({required Box box, Client? inner, Duration ttl = const Duration(minutes: 30), int maxEntrySizeBytes = 2 * 1024 * 1024, int maxSizeBytes = 50 * 1024 * 1024, Duration cacheCheckPeriod = const Duration(minutes: 10), CacheInvalidationStrategy invalidationStrategy = CacheInvalidationStrategy.smart, void onCacheHit(String url, CacheStats stats)?})

Properties

activeInnerClient → Client
Returns active inner HTTP client or throws StateError if missing.
no setterinherited
cacheCheckPeriod ↔ Duration
Interval between automatic cleanup sweeps of expired cache entries.
getter/setter pairinherited
cacheCount → int
Returns the current number of cached entries.
no setteroverride
currentSizeBytes ↔ int
Total size in bytes of all currently cached responses.
getter/setter pairinherited
hashCode → int
The hash code for this object.
no setterinherited
inner ↔ Client?
Underlying HTTP client instance.
getter/setter pairinherited
invalidationStrategy ↔ CacheInvalidationStrategy
Strategy used to invalidate cache when mutating HTTP requests occur.
getter/setter pairinherited
lastCleanupTime ↔ DateTime
Timestamp of the last expired cache entries cleanup sweep.
getter/setter pairinherited
maxEntrySizeBytes ↔ int
Maximum byte size allowed for a single cached response. Responses exceeding this limit will not be cached.
getter/setter pairinherited
maxSizeBytes ↔ int
Maximum total byte size allowed for all cached responses combined.
getter/setter pairinherited
onCacheHit → void Function(String url, CacheStats stats)?
Optional callback triggered when a request hits the cache, passing the request URL and current cache stats.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stats → CacheStats
Statistics for cache operations (hits, misses, ratios).
finalinherited
ttl ↔ Duration
Duration for which cached responses remain valid.
getter/setter pairinherited

Methods

clearCache() → Future<void>
Manually clears all cached responses.
override
close() → void
Closes the client and cleans up any resources associated with it.
inherited
delete(Uri url, {Map<String, String>? headers, Object? body, Encoding? encoding}) → Future<Response>
Sends an HTTP DELETE request with the given headers to the given URL.
inherited
get(Uri url, {Map<String, String>? headers}) → Future<Response>
Sends an HTTP GET request with the given headers to the given URL.
inherited
Sends an HTTP HEAD request with the given headers to the given URL.
inherited
invalidateUrl(String urlOrPrefix) → void
Removes a specific URL or all URLs matching a path prefix from the cache.
override
isMutatingRequest(BaseRequest request) → bool
Determines if an HTTP request is mutating (writes/updates/deletes data).
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
patch(Uri url, {Map<String, String>? headers, Object? body, Encoding? encoding}) → Future<Response>
Sends an HTTP PATCH request with the given headers and body to the given URL.
inherited
post(Uri url, {Map<String, String>? headers, Object? body, Encoding? encoding}) → Future<Response>
Sends an HTTP POST request with the given headers and body to the given URL.
inherited
put(Uri url, {Map<String, String>? headers, Object? body, Encoding? encoding}) → Future<Response>
Sends an HTTP PUT request with the given headers and body to the given URL.
inherited
read(Uri url, {Map<String, String>? headers}) → Future<String>
Sends an HTTP GET request with the given headers to the given URL and returns a Future that completes to the body of the response as a String.
inherited
readBytes(Uri url, {Map<String, String>? headers}) → Future<Uint8List>
Sends an HTTP GET request with the given headers to the given URL and returns a Future that completes to the body of the response as a list of bytes.
inherited
send(BaseRequest request) → Future<StreamedResponse>
Sends an HTTP request and asynchronously returns the response.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited