HttpCache class

An in-memory, LRU, shared HTTP cache following RFC 9111.

It decides (lookup) and stores (store, refresh); moving bytes is the job of a relay such as CachingHttpRelay. Only GET (and HEAD, served from GET entries) of HTTP/1.1 requests without Authorization, Range or a body participate; see whyNotStorable for what is kept.

Constructors

HttpCache(HttpCacheOptions options, {HttpCacheBudget? budget, DateTime now()?}): Creates a cache with options, optionally sharing budget.

Properties

budget → HttpCacheBudget?: The shared budget this cache also counts against, if any.
final
hashCode → int: The hash code for this object.
no setterinherited
now → DateTime Function(): The clock.
final
options → HttpCacheOptions: The cache's behaviour and limits.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
stats → HttpCacheStats: The current counters.
no setter

Methods

canServeStaleOnError(HttpCacheEntry entry, HttpRequestHead request, {DateTime? at}) → bool: Whether stale entry may answer request because the origin failed (RFC 5861 stale-if-error=N, in the response or the request): it must be at most N seconds past its freshness lifetime.
clear() → void: Drops every entry (e.g. when the owning tunnel closes).
invalidate(String key) → void: Drops every variant stored under key.
lookup(HttpRequestHead request, {DateTime? at}) → CacheLookup: Decides how request uses the cache at at (default: now).
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
recordBypass() → void: Counts a bypassed request.
recordHit() → void: Counts a served hit.
recordMiss() → void: Counts a miss.
recordRevalidated() → void: Counts a successful revalidation.
refresh(HttpCacheEntry entry, HttpResponseHead notModified, {required DateTime requestTime, required DateTime responseTime}) → void: Refreshes entry from a 304 Not Modified notModified (RFC 9111 §4.3.4): its fields replace the stored ones and freshness restarts. An update that makes the entry no-store drops it.
store({required HttpRequestHead request, required HttpResponseHead response, required Uint8List body, required DateTime requestTime, required DateTime responseTime}) → HttpCacheEntry?: Stores response (with its raw body) to request, if storable. requestTime is when the request was forwarded, responseTime when the response head arrived. Returns the new entry, or null.
toString() → String: A string representation of this object.
inherited
whyNotStorable(HttpRequestHead request, HttpResponseHead response, {required int bodyBytes, DateTime? responseTime}) → String?: Why response to request may not be stored, or null when it may.

Operators

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

Static Methods

isRepresentationField(String name) → bool: Whether name describes (or frames) the stored body rather than the response as a whole: every Content-* field except Content-Location, plus Transfer-Encoding and Trailer. A 304 never updates these.
keyFor(HttpRequestHead request) → String: The primary key for request: lower-cased Host + request target. HEAD and GET share keys so a HEAD can be answered from a GET.