caterktor

0.3.0indexed

Application-level networking layer offering typed NetworkResult, structured NetworkError, ordered interceptor pipeline (auth single‑flight refresh, retry, circuit breaker), redacted logging, converters, test doubles.

AndroidJSJVMNative·oyedsamu/caterktor

Stars

—

Used by

dependents

Health

/ 100

CaterKtor

The application networking layer built on Ktor.

Why CaterKtor instead of Ktor directly?

Ktor is an excellent HTTP engine. It handles TCP, TLS, HTTP/1.1, HTTP/2 — the transport layer — very well. What it deliberately does not handle is everything above the transport:

CaterKtor solves all of this — on top of Ktor's engines, without replacing them.

Your App
    │
    ▼
NetworkClient  (CaterKtor)
├── Auth interceptor       ← single-flight 401 refresh, budgeted
├── Retry interceptor      ← exponential backoff, jitter, Retry-After
├── Circuit breaker        ← fail fast when downstream is broken
├── Logging interceptor    ← structured, redacted
└── Transport              ← KtorTransport → OkHttp / Darwin / CIO

One object. Explicit ordering. Typed results. Correct concurrency semantics.

Installation

Version catalog (recommended)

Kotlin Multiplatform (shared module)

// shared/build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.caterktor.core)
            implementation(libs.caterktor.ktor)
            implementation(libs.caterktor.auth)
            implementation(libs.caterktor.logging)
            implementation(libs.caterktor.serialization.json)
        }
        androidMain.dependencies {
            implementation(libs.caterktor.engine.okhttp)
        }
        iosMain.dependencies {
            implementation(libs.caterktor.engine.darwin)
        }
        jvmMain.dependencies {
            implementation(libs.caterktor.engine.cio)
        }
        commonTest.dependencies {
            implementation(libs.caterktor.testing)
        }
    }
}

Android-only project

// app/build.gradle.kts
dependencies {
    implementation("io.github.oyedsamu:caterktor-core:0.2.0")
    implementation("io.github.oyedsamu:caterktor-ktor:0.2.0")
    implementation("io.github.oyedsamu:caterktor-engine-okhttp:0.2.0")
    implementation("io.github.oyedsamu:caterktor-auth:0.2.0")
    implementation("io.github.oyedsamu:caterktor-serialization-json:0.2.0")
    implementation("io.github.oyedsamu:caterktor-logging:0.2.0")
    implementation("io.github.oyedsamu:caterktor-connectivity:0.2.0")
    testImplementation("io.github.oyedsamu:caterktor-testing:0.2.0")
}

JVM server / CLI

dependencies {
    implementation("io.github.oyedsamu:caterktor-core:0.2.0")
    implementation("io.github.oyedsamu:caterktor-ktor:0.2.0")
    implementation("io.github.oyedsamu:caterktor-engine-cio:0.2.0")
    implementation("io.github.oyedsamu:caterktor-serialization-json:0.2.0")
    implementation("io.github.oyedsamu:caterktor-websocket:0.2.0")
    implementation("io.github.oyedsamu:caterktor-sse:0.2.0")
    testImplementation("io.github.oyedsamu:caterktor-testing:0.2.0")
}

Quick start

A CI-compiled, runnable version of this exact sample lives in caterktor-sample/. Run it locally: ./gradlew :caterktor-sample:jvmRun. The sample also prints source-backed upload and streaming download progress events.

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport    = OkHttpTransport()
    baseUrl      = "https://api.example.com"

    addConverter(KotlinxJsonConverter())

    auth {
        bearer  { tokenProvider { tokenStore.accessToken() } }
        refresh { refreshToken  { tokenStore.refreshAccessToken() } }
    }

    addInterceptor(RetryInterceptor(maxAttempts = ))
    addInterceptor(LoggerInterceptor(level = LogLevel.Headers) { line -> println(line) })
}

 result: NetworkResult<User> = client.()

 (result) {
     NetworkResult.Success -> showProfile(result.body)
     NetworkResult.Failure ->  ( error = result.error) {
         NetworkError.Http        ->  (error.status == HttpStatus.Unauthorized) reLogin()
         NetworkError.Timeout     -> showRetryPrompt()
         NetworkError.ConnectionFailed -> showOfflineBanner()
                                -> reportUnexpected(error)
    }
}

Typed helpers also build query strings without manual concatenation:

val page: NetworkResult<PokemonResponse> = client.get(
    url = "pokemon",
    queryParams = QueryParameters {
        add("limit", 20)
        add("offset", 40)
        add("type", "electric")
        add("type", "flying")
    },
)

queryParameters(mapOf("limit" to 20, "offset" to 40)) is available when a map is the more natural shape. null values are omitted, repeated names are preserved, and names/values are percent-encoded.

Core concepts

`NetworkResult<T>` — exactly two outcomes

Every call returns a sealed NetworkResult<T>. There is no third state, no thrown exception to catch, no null to guard.

Extension functions cover the common patterns without unwrapping manually:

val user = result.getOrThrow()                     // throws on Failure
val user = result.getOrDefault(User.ANONYMOUS)     // fallback on Failure
result.onSuccess { user -> render(user) }
       .onFailure { error -> log(error) }
val mapped = result.map { user -> UserUiModel(user) }

`NetworkError` — branch on kind, not message

CancellationException is never wrapped as a Failure. It propagates directly through the pipeline to the calling coroutine. If coroutine cancellation can reach your call site, let it.

The interceptor pipeline

Interceptors run in the order they are added. The terminal transport is always last.

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport = OkHttpTransport()

    addInterceptor(DefaultHeadersInterceptor("User-Agent" to "MyApp/1.0"))
    addInterceptor(AuthRefreshInterceptor(...))   // auth before retry — intentional
    addInterceptor(RetryInterceptor())
    addInterceptor(LoggerInterceptor(LogLevel.Body) { println(it) })
}

// Print the exact execution order at any time:
println(client.describePipeline())
// [0] DefaultHeadersInterceptor
// [1] AuthRefreshInterceptor
// [2] RetryInterceptor
// [3] LoggerInterceptor
// [4] Transport(KtorTransport)

Ordering matters. Auth before retry means a refreshed token is used on the retry attempt. Logging after retry means you see exactly what was sent on each attempt, not just the first.

Auth

Bearer token injection

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport = OkHttpTransport()
    auth {
        bearer { tokenProvider { tokenStore.accessToken() } }
    }
}

Bearer + single-flight 401 refresh

When ten concurrent requests all receive a 401, exactly one refresh call is made. The other nine suspend on the same Deferred<Token> and resume with the refreshed token without racing.

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport = OkHttpTransport()
    auth {
        bearer {
            tokenProvider { tokenStore.accessToken() }
        }
        refresh {
            refreshToken {
                // Called at most once per budget window, regardless of concurrency
                tokenStore.refreshAccessToken()
            }
            budget(maxRefreshes = 1, windowMs = 60_000L)  // default: 1 refresh per 60 s
            onRefreshFailed { cause ->
                // Fires exactly once when the budget is exhausted or refresh throws
                navigator.navigateToLogin()
            }
        }
    }
}

To call auth endpoints through the same client without triggering the auth interceptor:

client.post<Token>(
    url = "auth/refresh",
    attributes = Attributes { put(CaterKtorKeys.SKIP_AUTH, true) },
)

Retry

@OptIn(ExperimentalCaterktor::class)
addInterceptor(
    RetryInterceptor(
        maxAttempts = 3,
        policy = ExponentialBackoffPolicy(
            baseDelayMs   = 200L,
            maxDelayMs    = 10_000L,
            jitterFactor  = 1.0,  // full jitter — default and recommended
        ),
        retryNonIdempotent = false,  // set true + add Idempotency-Key for POST/PATCH
    )
)

Default behaviour out of the box:

Retries on NetworkError.Timeout, NetworkError.ConnectionFailed, and HTTP 502 / 503 / 504

Circuit breaker

@OptIn(ExperimentalCaterktor::class)
addInterceptor(
    CircuitBreaker(
        failureThreshold = 5,
        openDurationMs   = 30_000L,
    )
)

After failureThreshold consecutive failures the circuit opens and rejects all calls with NetworkError.CircuitOpen until the open window expires. The next probe attempt moves it to HalfOpen. A successful probe closes it; a failed probe reopens it. State transitions surface as NetworkEvent.CircuitBreakerTransition.

Serialization

JSON (most common)

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport = OkHttpTransport()
    addConverter(KotlinxJsonConverter())        // lenient defaults
    // or with custom Json instance:
    addConverter(KotlinxJsonConverter(Json { ignoreUnknownKeys = true }))
}

@Serializable data class User(val id: String, val name: String)
val result: NetworkResult<User> = client.get("/users/me")

Multiple formats via content negotiation

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport = OkHttpTransport()
    contentNegotiation {
        register("application/json",       KotlinxJsonConverter(),     quality = 1.0)
        register("application/x-protobuf", KotlinxProtobufConverter(), quality = 0.9)
        register("application/cbor",       KotlinxCborConverter(),     quality = 0.8)
    }
}

The Accept header is constructed automatically from registered converters and their quality values. The response Content-Type drives decode dispatch — no branching in app code.

Response envelope unwrapping

Many APIs wrap responses in an outer envelope. Unwrap it before decode:

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport = OkHttpTransport()
    addConverter(KotlinxJsonConverter())
    responseUnwrapper = DataFieldUnwrapper("data")  // unwraps {"data": {...}}
}

Built-in unwrappers: DataFieldUnwrapper, PagedUnwrapper. Implement ResponseUnwrapper for custom shapes. Override per-request via NetworkRequest.attributes.

Logging and redaction

@OptIn(ExperimentalCaterktor::class)
addInterceptor(
    LoggerInterceptor(
        level  = LogLevel.Body,
        logger = { line -> Napier.d(line) },  // wire any logger
        redaction = RedactionEngine(
            headerNames    = setOf("Authorization", "X-Session-Token"),
            queryParams    = setOf("api_key", "token"),
            jsonBodyFields = setOf("password", "ssn", "cardNumber"),
        ),
    )
)

Redaction is on by default when logging is enabled. The default RedactionEngine redacts Authorization, Cookie, Set-Cookie, Proxy-Authorization, , and headers automatically. Add fields; you cannot globally disable. Transport failures (DNS, TLS, timeout) are logged as on the failure path, not only on successful responses.

Log levels:

Level	What you see

Testing

CaterKtor ships a dedicated testing artifact so your repository tests never touch a real network.

Fast unit tests — `FakeNetworkClient`

@OptIn(ExperimentalCaterktor::class)
  {
    
     = runTest {
         fake = FakeNetworkClient {
            addConverter(KotlinxJsonConverter())
        }
        fake.enqueue(jsonResponse())

         repo = UserRepository(fake.client)
         user = repo.getUser()

        assertEquals(, user.name)
        assertEquals(, fake.requests.size)
    }

    
     = runTest {
         fake = FakeNetworkClient()
        fake.enqueue(testResponse(status = HttpStatus.Unauthorized))

         repo = UserRepository(fake.client)
        assertIs<NetworkResult.Failure>(repo.getUser())
    }
}

Route-scripted tests — `CaterktorTestServer`

@OptIn(ExperimentalCaterktor::class)
class UserApiTest {
    @Test
    fun fetchesUserFromRoute() = runTest {
        val server = CaterktorTestServer()
        server.route(HttpMethod.GET, "/users/me", jsonResponse("""{"id":"1","name":"Ada"}"""))

        val client = server.client { addConverter(KotlinxJsonConverter()) }
         result = client.<User>()

        assertIs<NetworkResult.Success<User>>(result)
        assertEquals(, result.body.name)
    }
}

Rules can also match path templates and expose path parameters:

val fake = FakeTransport {
    get("/users/{id}") { match ->
        jsonResponse("""{"id":"${match.pathParameters["id"]}"}""")
    }
}

Test helpers at a glance:

testResponse(status = HttpStatus.OK, body = byteArrayOf())  // blank 200
jsonResponse("""{"key":"value"}""")                          // 200 + Content-Type: application/json
httpFailure(HttpStatus.NotFound)                             // NetworkError.Http pre-built

Observability

NetworkClient.events is a SharedFlow<NetworkEvent>. Collect it to wire any observability backend — structured logs, metrics, traces — without coupling to the interceptor chain.

@OptIn(ExperimentalCaterktor::class)
scope.launch {
    client.events.collect { event ->
        when (event) {
            is NetworkEvent.CallStart      -> metrics.requestStarted(event.requestId)
            is NetworkEvent.CallSuccess    -> metrics.recordLatency(event.requestId, event.durationMs)
            is NetworkEvent.CallFailure    -> metrics.recordError(event.requestId, event.error)
            is NetworkEvent.UploadProgress ->
                metrics.uploaded(event.requestId, event.bytesSent, event.totalBytes)
             NetworkEvent.DownloadProgress ->
                metrics.downloaded(event.requestId, event.bytesRead, event.totalBytes)
             NetworkEvent.ResponseReceived -> {}
             NetworkEvent.CircuitBreakerTransition ->
                log.warn()
        }
    }
}

Progress totals are nullable because chunked requests, generated streams, and some server responses do not know their final length up front. Treat null as indeterminate progress:

fun percent(done: Long, total: Long?): Int? =
    total?.takeIf { it > 0L }?.let { ((done * 100) / it).toInt() }

caterktor-logging also includes an event-derived logger for the same flow:

val eventLogger = NetworkEventLogger { line -> println(line) }

scope.launch {
    client.events.collect(eventLogger::log)
}

requestId is consistent across all events for the same logical call — start, retries, refresh waits, and final outcome all share one ID, making log correlation across interceptors exact.

Streaming Downloads

For large responses, use the Ktor-backed block-scoped streaming API. The body source is one-shot and must be consumed inside the block; Ktor releases the underlying response resources when the block returns.

val bytesWritten = transport.download(
    NetworkRequest(HttpMethod.GET, "https://cdn.example.com/archive.zip"),
    requestId = "archive-download",
    onDownloadProgress = { progress ->
        val label = progress.totalBytes?.let { "${progress.bytesRead}/$it" }
            ?: "${progress.bytesRead} bytes"
        println("download ${progress.requestId}: $label")
    },
) { response ->
     source = response.body.source()
     {
        source.transferTo(fileSink)
    }  {
        source.close()
    }
}

If you are already using NetworkClient.events, a streaming ResponseBody.Source returned by a custom transport also emits NetworkEvent.DownloadProgress as the source is consumed. The Ktor-specific callback above exists for the lower-level KtorTransport.download(...) escape hatch, which runs outside the NetworkClient.events flow.

Typed helpers such as client.get<T>() still buffer up to maxBodyDecodeBytes before decoding, which is the right behavior for JSON/protobuf models. Use KtorTransport.download(...) for file or blob downloads.

Form and Multipart Bodies

Use RequestBody.Form for application/x-www-form-urlencoded requests:

val body = RequestBody.Form(
    RequestBody.Form.Field("grant_type", "refresh_token"),
    RequestBody.Form.Field("refresh_token", refreshToken),
)

Use RequestBody.Multipart for form-data uploads:

val body = RequestBody.Multipart(
    RequestBody.Multipart.Part.field("title", "avatar"),
    RequestBody.Multipart.Part.formData(
        name = "file",
        filename = "avatar.png",
        body = RequestBody.Source(
            sourceFactory = { imageSource() },
            contentType = "image/png",
        ),
    ),
)

Source-backed multipart parts stream through KtorTransport without first materializing the file body. When the request goes through NetworkClient, source-backed parts also emit NetworkEvent.UploadProgress:

val uploadEvents = scope.launch {
    client.events.collect { event ->
        if (event is NetworkEvent.UploadProgress) {
            println("uploaded ${event.bytesSent} of ${event.totalBytes ?: "unknown"}")
        }
    }
}

client.execute(
    NetworkRequest(
        method = HttpMethod.POST,
        url = "https://api.example.com/profile/avatar",
        body = body,
    ),
)

Use contentLength when you know it. That gives progress UIs a determinate total; omit it for chunked or generated streams:

RequestBody.Source(
    sourceFactory = { fileSystem.source(path) },
    contentType = "application/octet-stream",
    contentLength = fileSize,
)

Timeouts

@OptIn(ExperimentalCaterktor::class)
val client = CaterKtor {
    transport = OkHttpTransport()
    timeout {
        requestTimeoutMs = 30_000L   // per attempt
    }
}

Per-call deadlines are passed to typed helpers through the deadline parameter and propagate through Chain, so retry delays and auth refresh waits can honor the same logical budget.

Conventions

Always handle both variants. NetworkResult is sealed. The compiler will warn on a non-exhaustive when. Do not suppress the warning — handle the Failure branch.

Do not catch CancellationException. CaterKtor never wraps it. If a coroutine is cancelled mid-request, the exception propagates to the scope that owns the coroutine. Catching it breaks structured concurrency.

Keep the NetworkClient as a singleton. Constructing a new client per request creates a new Ktor HttpClient and its underlying engine thread pool. One client per logical backend (API, CDN, internal service) is the right granularity.

Use describePipeline() when debugging ordering issues. The output is the contract — the list matches the exact execution order at runtime.

Scope @OptIn(ExperimentalCaterktor::class) to the file, not the module. This makes it easy to find and update call sites when surfaces stabilise.

What's next

CaterKtor is moving from 0.2.0 into 0.3.0. The next release is a maturity release: progress telemetry lands, while adapter/platform candidates ship only when their release gates are proven locally.

0.2.0 expanded the transport, testing, observability, platform, and realtime surfaces while keeping the core pipeline BCV-gated.

`0.2.0` — streaming, testing, observability, realtime

`0.3.0` — progress, adapter decisions, platform polish

Upload/download byte-level progress events via NetworkEvent
KtorTransport.download(...) progress callback for lower-level streaming downloads
OpenTelemetry tracing adapter go/no-go; no placeholder artifact will be published
Ktorfit declarative adapter go/no-go; no forked annotation processor will be introduced
wasmJs go/no-go based on deterministic local wasmJsTest and publication gates

`1.0.0` — API stability

Interceptor and Chain graduate out of @ExperimentalCaterktor
Full semver breaking-change guarantee

Explicit non-goals

These are out of scope and will not be added:

XML serialization — bring your own BodyConverter implementation
gRPC — different transport protocol, separate project
Our own annotation processor / codegen — the Ktorfit adapter is the declarative path, not a fork
DI framework integrations — CaterKtor composes into any DI container; it requires none

Known limitations

These are honest limitations of the current release, not bugs that slipped through:

Contributing

Contributions are welcome. Before opening a pull request:

See CONTRIBUTING.md for the full guide, and CODE_OF_CONDUCT.md for community standards. Security issues should follow the process in SECURITY.md.

License

Copyright 2024 Samuel Oyedele

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance  the License.
You may obtain a copy of the License at

    http:

Unless   applicable law  agreed to  writing, software
distributed under the License  distributed  an  BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express  implied.
See the License  the specific language governing permissions 
limitations under the License.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

kotlin-multiplatform-oidc★ 153

kalinjulLightweight implementation of OpenID Connect/OAuth 2.0 supporting Authorization Code Grant Flow, discovery, PKCE, and simple JWT parsing. Includes Android, iOS, desktop support, and OkHttp/Ktor integration.Shared: okhttp, ktor-client, http-client

jsonpath4k★ 24

a-sit-plusSupports querying JSON data using JSONPath expressions, enabling node selection and path normalization. Allows adding and removing custom function extensions while leveraging popular libraries for logging, testing, and serialization.Shared: test, logging, kotlin-serialization

NetMock★ 31

DenisBronxSimplifies unit testing of network requests by offering mock-like APIs compatible with various network libraries. Features `netmock-server` for localhost server testing and `netmock-engine` for lighter, library-specific testing with `MockEngine`.Shared: test, okhttp, ktor-client

vck★ 69

a-sit-plusImplements verifiable credentials for issuing, presentation, and validation across various applications, supporting W3C and ISO standards, ARIES protocols, OpenID, and customizable cryptographic operations.Shared: test, logging, kotlin-serialization

CoinGecko-Kotlin★ 43

DrewCarlsonWrapper for CoinGecko API, facilitating cryptocurrency data retrieval. Utilizes Ktor for making API requests. Supports various platforms, ensuring versatile integration.Shared: ktor-client, http-client, client

Axer★ 34

orioneeeMonitors HTTP requests, records exceptions, and inspects Room databases in real-time. Offers Room database inspection and custom query execution. Inspired by Chucker, but extends functionality.Shared: okhttp, logging, ktor-client

caterktor

CaterKtor

Why CaterKtor instead of Ktor directly?

Installation

Version catalog (recommended)

Kotlin Multiplatform (shared module)

Android-only project

JVM server / CLI

Quick start

Core concepts

NetworkResult<T> — exactly two outcomes

NetworkError — branch on kind, not message

The interceptor pipeline

Auth

Bearer token injection

Bearer + single-flight 401 refresh

Retry

Circuit breaker

Serialization

JSON (most common)

Multiple formats via content negotiation

Response envelope unwrapping

Logging and redaction

Testing

Fast unit tests — FakeNetworkClient

Route-scripted tests — CaterktorTestServer

Observability

Streaming Downloads

Form and Multipart Bodies

Timeouts

Conventions

What's next

0.2.0 — streaming, testing, observability, realtime

0.3.0 — progress, adapter decisions, platform polish

1.0.0 — API stability

Explicit non-goals

Known limitations

Contributing

License

Related libraries

CaterKtor

Why CaterKtor instead of Ktor directly?

Installation

Version catalog (recommended)

Kotlin Multiplatform (shared module)

Android-only project

JVM server / CLI

Quick start

Core concepts

NetworkResult<T> — exactly two outcomes

NetworkError — branch on kind, not message

The interceptor pipeline

Auth

Bearer token injection

Bearer + single-flight 401 refresh

Retry

Circuit breaker

Serialization

JSON (most common)

Multiple formats via content negotiation

Response envelope unwrapping

Logging and redaction

Testing

Fast unit tests — FakeNetworkClient

Route-scripted tests — CaterktorTestServer

Observability

Streaming Downloads

Form and Multipart Bodies

Timeouts

Conventions

What's next

0.2.0 — streaming, testing, observability, realtime

0.3.0 — progress, adapter decisions, platform polish

1.0.0 — API stability

Explicit non-goals

Known limitations

Contributing

License

Related libraries

`NetworkResult<T>` — exactly two outcomes

`NetworkError` — branch on kind, not message

Fast unit tests — `FakeNetworkClient`

Route-scripted tests — `CaterktorTestServer`

`0.2.0` — streaming, testing, observability, realtime

`0.3.0` — progress, adapter decisions, platform polish

`1.0.0` — API stability

`NetworkResult<T>` — exactly two outcomes

`NetworkError` — branch on kind, not message

Fast unit tests — `FakeNetworkClient`

Route-scripted tests — `CaterktorTestServer`

`0.2.0` — streaming, testing, observability, realtime

`0.3.0` — progress, adapter decisions, platform polish

`1.0.0` — API stability