Lightweight toolkit for Ktor HTTP clients: retry schedules with Retry-After parsing, per-request timeouts, etiquette headers, and destructive body-prefix sampling for diagnostics.
kotlin-web-common is a Kotlin Multiplatform support library for Ktor-based HTTP clients.
It packages the pieces that tend to get reimplemented across small client wrappers:
retry schedules, Retry-After parsing, per-request timeout helpers, request etiquette headers,
and destructive body-prefix sampling for diagnostics.
The library is meant for people building their own API clients on top of Ktor, not for people looking for a complete HTTP client by itself. It does not choose an engine for you and it does not hide Ktor. Instead, it gives you a small shared toolkit for the repetitive parts around Ktor requests.
repositories {
mavenCentral()
}
dependencies {
implementation("one.wabbit:kotlin-web-common:1.1.0")
// Choose your own Ktor engine.
implementation("io.ktor:ktor-client-cio:3.3.0") // JVM / Android example
}
If you are targeting Apple platforms, use the appropriate Darwin engine instead of CIO.
2.3.103.3.021kotlin-web-common configures request-level timeouts through Ktor's HttpTimeout plugin, so those
timeouts only take effect when that plugin is installed and when the selected Ktor engine supports
the timeout type you are setting.
This is the smallest useful slice of the library: parsing Retry-After and compiling a retry
schedule.
import one.wabbit.web.common.Schedule
import one.wabbit.web.common.compile
import one.wabbit.web.common.parseRetryAfterHeader
import kotlin.random.Random
val retryAfter = parseRetryAfterHeader("2.5")
check(retryAfter != null)
val run = Schedule.retries(maxRetries = 1).compile(random = Random(1))
val firstDelay = run.next()
check(firstDelay != null)
Wrap a Ktor request so you get shared etiquette, shared timeouts, and response-status-based retry
behavior even when the client does not throw on 429 or 5xx.
import io.ktor.client.HttpClient
import io.ktor.client.request.get
import io.ktor.client.statement.bodyAsText
import one.wabbit.web.common.Etiquette
one.wabbit.web.common.Timeouts
one.wabbit.web.common.applyEtiquette
one.wabbit.web.common.applyTimeouts
one.wabbit.web.common.retryingIdempotentHttpResponseBodyCall
: String =
retryingIdempotentHttpResponseBodyCall(
request = {
client.(url) {
applyEtiquette(
Etiquette(
userAgent = ,
),
)
applyTimeouts(Timeouts())
}
},
transform = { response ->
response.bodyAsText()
},
)
Generated API docs can be built locally with Dokka. See API reference notes for the command.
The release-notes source of truth for this repository is CHANGELOG.md.
This library is maintained as shared infrastructure for the broader kotlin-web-* client family,
so changes are driven by real client usage first and then documented here as the public surface
stabilizes.
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) for open source use.
For commercial use, contact Wabbit Consulting Corporation at wabbit@wabbit.one.
Contributions are governed by the repository contribution policy and the Wabbit CLA. See
CONTRIBUTING.md and the files under legal/.
Etiquette plus applyEtiquette(...) for User-Agent, Referer, and validated extra headersTimeouts, applyTimeouts(...), and Timeouts.forStreaming(...) for per-request Ktor timeout configurationSchedule, RetryPolicy, runWithRetry(...), and parseRetryAfterHeader(...)retryingIdempotentHttpCall(...),
retryingIdempotentHttpResponseCall(...),
retryingIdempotentHttpResponseBodyCall(...)consumeBodyPrefixUtf8Sample(...),
consumeRawBodyPrefixUtf8(...),
consumeRawBodyPrefixUtf8OrNull(...),
responseBodySampleOrNull(...)retryingIdempotentHttpCall(...) is exception-driven. It only retries HTTP statuses when the
wrapped Ktor call throws response exceptions, which usually means expectSuccess = true or
custom response validation.expectSuccess = false, use retryingIdempotentHttpResponseCall(...) or
retryingIdempotentHttpResponseBodyCall(...) instead.408, 429,
all 5xx, timeout/connect failures, and generic IOException.consumeBodyPrefixUtf8Sample(...) and the string wrappers are destructive. They consume from
bodyAsChannel(), sample raw bytes, and decode as UTF-8 for diagnostics. They are not
charset-aware text helpers.Timeouts() defaults are request/response-oriented. For SSE, long-polling, or quiet streaming
responses, prefer Timeouts.forStreaming(...).Schedule.Exponential can overflow finite Duration values if you leave it unbounded.Surfaced from shared tags and platforms — no rankings paid for.