Endpoint

class Endpoint<T : Any>(source)

One call an upstream offers: a stable id, the function that decodes its answer, and how the answer is cached, charged and classified. Build one with Endpoint("heroes", ::decodeHeroes) { ttl = 10.minutes; misses(404) }, once, and reuse it.

Stable Core. The decoder is the second argument, never the trailing lambda (that is the configuration); T is inferred from it, and Endpoint<Hero>("id", decode) also works. A miscall from another module (the decoder missing, or written as the trailing lambda) is reported as "Cannot access … it is internal" against the constructor: the class has no public constructor. T is invariant.

The id names the endpoint in the cache key and in logs. Two endpoints that share a cache must not share an id: the key's type parameter is a phantom, so one id serves one value type. The decoder sees only the responses classified for decoding (a 2xx that is not a declared miss and not a throttle) and runs in the cache's load coroutine (on the caller's coroutine with ResponseCache.Disabled and for a non-GET), so it is CPU-bound work with no blocking I/O; it must not capture per-call data, because a shared load runs the first caller's. It returns a Result: a failure that is an HttpFailure passes through, any other becomes HttpFailure.DecodeFailure; a decoder that throws is treated the same, except an Error, which propagates.

Equality is identity. toString() prints the id, name, ttl, missTtl, cost, the lane's name and the misses, never the decoder.

Type Parameters

T

the type of the decoded value.

Throws

if the id or name is blank, a duration is negative, cost is below 1, or a miss status is outside 100..599 or is 429; thrown through the factory function Endpoint(id, decode) { … }, the only way a consumer builds one. The message names the property and never a value.

Types

Link copied to clipboard

Collects the settings of an Endpoint. Not thread-safe; use it only inside the factory's lambda. Stable Core. Further optional settings, when they exist, are added here rather than to the factory's parameter list.

Properties

Link copied to clipboard
val cost: Int

The budget units one call of this endpoint charges. At least 1.

Link copied to clipboard
val id: String

The endpoint's stable id: the cache key's first part and the name in logs. Not blank.

Link copied to clipboard
val lane: Lane

The lane the endpoint's calls are charged to by default.

Link copied to clipboard
val misses: Set<Int>

The statuses that mean "nothing there" and become Lookup.Missing; a read-only copy. Each in 100..599 and none 429.

Link copied to clipboard

How long a confirmed miss is stored. Not negative.

Link copied to clipboard

A display name for logs and messages; the id by default. Not blank.

Link copied to clipboard

How long a decoded value is stored; zero stores nothing (loads in flight still coalesce). Not negative; Duration.INFINITE is allowed.

Functions

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

A diagnostic string for logs: id, name, ttl, missTtl, cost, the lane's name and the sorted misses, never the decoder. Its format is not part of the API and may change.