CaffeineResponseCache
The supplied ResponseCache: Caffeine 3 under the port's contract, built with the factory CaffeineResponseCache { } and usable without any opt-in (it is a supplied default, not a seam); final, with every policy number a property of its Builder.
Stable Core.
One load per key at a time. The first call for a key starts the load; every call for an equal key while it is in flight joins it and receives its outcome, whatever
policyandloaderthe joining call passed (the first caller's govern). A call that finds a live stored entry is a hit and runs nothing.Lifetimes. A Lookup.Found is stored for the policy's
ttland a Lookup.Missing for itsmissTtl, each measured from the load's completion, not its start. A zero TTL coalesces the loads in flight and stores nothing; Duration.INFINITE stores until evicted.The weight bound.
maxWeightbounds the total weight of the stored entries: aFoundweighs what it reports (1 by the one-argument constructor), aMissingweighs 1, and the least recently used entries are evicted when the bound is reached (counted in CacheStats.evictions). AFoundheavier thanmaxWeightis delivered to its waiters and never stored, so the bound holds at every instant.maxAge. A stored entry older than the call'smaxAgeis not served: the call reloads, or joins the load already in flight, which counts as fresh. Duration.ZERO serves only an entry stored at the same tick.Failures are never stored. A loader's
Result.failureor thrownExceptionis the call's failure, the same instance for every waiter; a loader'sErroris rethrown to every waiter as the same instance; a loader's own cancellation (awithTimeoutexpiring inside it, a thrown or returnedCancellationException) isResult.failure(IllegalStateException(…, cause)), never aCancellationExceptionand neverClosed. The next call for the key loads anew.Three execution contexts. A caller's coroutine only awaits; a loader runs in the cache's own scope on
loadDispatcher, so the caller's dispatcher,CoroutineNameand other context elements do not reach it, and a caller's cancellation cancels only that caller; Caffeine's maintenance runs onmaintenanceExecutor, which the cache never shuts down and which must outlive the cache's last write. The cache owns no thread, timer or pool. A loader must not wait for a load of its own key.close()is idempotent, non-suspending and never throws: it cancels the loads in flight, ends every waiting call withResult.failure(HttpFailure.Closed("cache"))without waiting for a loader to unwind, and drops every stored entry. Every later getOrLoad returns the same failure without running its loader; invalidate, invalidateAll and stats keep working.Thread safety. Every member may be called concurrently from any thread and any number of coroutines.
Logging, through the logger
com.spartanlabs.webtools.http.CaffeineResponseCache:INFOonce on creation (maxWeight) and once onclose();DEBUGonce per load end with the key's id and parameter names, the outcome kind and whether it was stored;WARNonce for a load coroutine that failed outside the loader (aloadDispatcherthat rejects the dispatch), with the exception's class name. Never a value, a parameter value, a header, a credential or a message text; nothing per hit or join.The builder's properties:
timeSource(the clock of every age and lifetime),maxWeight,loadDispatcherandmaintenanceExecutor, each with a production default, so one virtual clock drives the cache under test.
Types
Collects the properties of a CaffeineResponseCache. Not thread-safe; use it only inside the factory's lambda. Stable Core.
Functions
Returns the stored answer for key if one is live and no older than maxAge; otherwise joins the load in flight for key, or starts one with loader.
getOrLoad accepting any live entry (maxAge is Duration.INFINITE).
Drops every stored or in-flight entry (contract point 7), as invalidate does for one key. Never throws; a no-op after close.
Reads the four counts (contract point 8).