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 policy and loader the 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 ttl and a Lookup.Missing for its missTtl, 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. maxWeight bounds the total weight of the stored entries: a Found weighs what it reports (1 by the one-argument constructor), a Missing weighs 1, and the least recently used entries are evicted when the bound is reached (counted in CacheStats.evictions). A Found heavier than maxWeight is delivered to its waiters and never stored, so the bound holds at every instant.

  • maxAge. A stored entry older than the call's maxAge is 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.failure or thrown Exception is the call's failure, the same instance for every waiter; a loader's Error is rethrown to every waiter as the same instance; a loader's own cancellation (a withTimeout expiring inside it, a thrown or returned CancellationException) is Result.failure(IllegalStateException(…, cause)), never a CancellationException and never Closed. 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, CoroutineName and other context elements do not reach it, and a caller's cancellation cancels only that caller; Caffeine's maintenance runs on maintenanceExecutor, 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 with Result.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: INFO once on creation (maxWeight) and once on close(); DEBUG once per load end with the key's id and parameter names, the outcome kind and whether it was stored; WARN once for a load coroutine that failed outside the loader (a loadDispatcher that 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, loadDispatcher and maintenanceExecutor, each with a production default, so one virtual clock drives the cache under test.

Types

Link copied to clipboard

Collects the properties of a CaffeineResponseCache. Not thread-safe; use it only inside the factory's lambda. Stable Core.

Link copied to clipboard
object Companion

The builder's default.

Functions

Link copied to clipboard
open override fun close()

Releases the cache's resources. Idempotent, non-suspending, does not throw. The default does nothing.

Link copied to clipboard
open suspend override fun <V : Any> getOrLoad(key: CacheKey<V>, policy: CachePolicy, maxAge: Duration, loader: suspend () -> Result<Lookup<V>>): Result<Lookup<V>>

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.

open suspend fun <V : Any> getOrLoad(key: CacheKey<V>, policy: CachePolicy, loader: suspend () -> Result<Lookup<V>>): Result<Lookup<V>>

getOrLoad accepting any live entry (maxAge is Duration.INFINITE).

Link copied to clipboard
open override fun invalidate(key: CacheKey<*>)

Drops key's stored or in-flight entry (contract point 7): the next call for key loads anew, and a load in flight still completes for the calls already waiting without being stored. Never throws; a no-op after close.

Link copied to clipboard
open override fun invalidateAll()

Drops every stored or in-flight entry (contract point 7), as invalidate does for one key. Never throws; a no-op after close.

Link copied to clipboard
open override fun stats(): CacheStats

Reads the four counts (contract point 8).

Link copied to clipboard
open override fun toString(): String

A diagnostic string for logs: the maximum weight and whether the cache is closed. Its format is not part of the API and may change.