retrostash-ktor/dev.logickoder.retrostash.ktor

Package-level declarations

Types

Configuration for RetrostashPlugin. Set within install(RetrostashPlugin) { ... }:

Direct cache control for the Ktor adapter — peek, update, invalidate*, clearAll. All methods are suspend; call from any coroutine. Mirror surface of RetrostashOkHttpCache but uses scopeName: String instead of Class<*> for KMP compatibility, and stores raw bytes (no envelope — Ktor doesn't synthesize HTTP responses on cache hit, the plugin hands the bytes back via RetrostashCachedPayloadKey).

RetrostashKtorMetadata

data class RetrostashKtorMetadata(val scopeName: String, val queryTemplate: String? = null, val maxAgeMs: Long = 0, val bindings: Map<String, String> = emptyMap(), val bodyBytes: ByteArray? = null, val invalidateTemplates: List<String> = emptyList(), val tagTemplates: List<String> = emptyList(), val invalidateTagTemplates: List<String> = emptyList())

Per-request Retrostash metadata attached to a Ktor HttpRequestBuilder via retrostash, retrostashQuery, or retrostashMutate. Read by RetrostashPlugin on request and response hooks to drive cache lookup, persistence, and invalidation.

RetrostashKtorRuntime

class RetrostashKtorRuntime(val engine: RetrostashEngine, keyResolver: CoreKeyResolver = CoreKeyResolver())

Thin adapter that translates RetrostashKtorMetadata into QueryMetadata for the underlying RetrostashEngine. Used by RetrostashPlugin; can also be used directly for testing without spinning up a Ktor HttpClient.

Properties

RetrostashCachedPayloadKey

val RetrostashCachedPayloadKey: AttributeKey<ByteArray>

Attribute key set by RetrostashPlugin on cache hits. Read after the request completes to branch on cache vs network:

RetrostashMetadataKey

val RetrostashMetadataKey: AttributeKey<RetrostashKtorMetadata>

Attribute key used to attach RetrostashKtorMetadata to a Ktor request.

RetrostashPlugin

val RetrostashPlugin: ClientPlugin<RetrostashConfig>

Ktor HttpClient plugin that adds annotation-style query caching and mutation invalidation.

Functions

retrostash

fun HttpRequestBuilder.retrostash(metadata: RetrostashKtorMetadata): HttpRequestBuilder

Attaches or merges metadata onto this request. Existing metadata fields are preserved when incoming values are blank/null/empty.

retrostashMutate

fun HttpRequestBuilder.retrostashMutate(scopeName: String, invalidateTemplates: List<String> = emptyList(), bindings: Map<String, String> = emptyMap(), bodyBytes: ByteArray? = null, invalidateTags: List<String> = emptyList()): HttpRequestBuilder

Marks this request as a Retrostash mutation. On a 2xx response, RetrostashPlugin resolves each entry in invalidateTemplates against bindings / bodyBytes and removes matching cache entries.

retrostashQuery

fun HttpRequestBuilder.retrostashQuery(scopeName: String, template: String, bindings: Map<String, String> = emptyMap(), bodyBytes: ByteArray? = null, maxAgeMs: Long = 0, tags: List<String> = emptyList()): HttpRequestBuilder

Marks this request as a Retrostash query. On hit, the plugin returns the cached payload via RetrostashCachedPayloadKey. On miss, the response is persisted (if maxAgeMs> 0) on a 2xx status code.