kotlin-http-client

Asynchronous HTTP client offering DSL-style request builders, configurable engines, interceptors, streaming responses, multipart support, and extensible plugins for concise, testable network code.

#io
#http-client
#http
#dsl
#client

Suggest an edit

Android

JVM

iOS

macOS

watchOS

Linux

Windows

GitHub stars0

Authorsthe-inkwell

Dependents2

LicenseMIT License

Creation dateover 2 years ago

Last activity18 days ago

Latest release1.20.2 (11 months ago)

GitHub repository

Kotlin HTTP Client

A Kotlin Multiplatform helper for Ktor Client, providing ready-to-use configuration and dependencies to quickly spin up a working HttpClient, without rewriting the same boilerplate in every project.

This library is built around an expect/actual template: you get a single createClient() factory on the common side, while the concrete implementation (Ktor engine, target platform, etc.) is provided by each target (Android, iOS, JVM, JS...).

✨ Features

Create a Ktor Multiplatform HttpClient via a simple createClient() function
Centralized configuration through a Configuration data class (timeouts, logging, cookies, proxy, JSON...)
Pre-configured JSON serialization with kotlinx.serialization
Hooks to customize authentication (onAuth) and each request (onRequest)
Optional support for WebSockets, cookies, and proxies
Compatible with the main Kotlin Multiplatform targets

📦 Compatibility

Dependency	Supported version
Ktor	`3.0.1`

🚀 Installation

Add the repository and dependency to your build.gradle.kts (commonMain module):

repositories {
    mavenCentral()
    // or the appropriate repository if published via GitHub Packages / local Maven
}

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("com.the-inkwell:kotlin-http-client:<version>")
            }
        }
    }
}

Replace <version> with the latest version available in the project's releases.

🔧 Usage

Create a client with the default configuration

val client = createClient()

Create a client with a custom configuration

val client = createClient(
    configuration = Configuration(
        enableLogs = true,
        connectTimeoutMillis = 5000,
        requestTimeoutMillis = 10000,
        installCookies = true,
    ),
    onAuth = {
        // Configure Ktor authentication (bearer, basic, etc.)
    },
    onRequest = { request ->
        // Customize each request (headers, parameters, etc.)
        request.header("X-App-Version", "1.0.0")
    }
)

⚙️ Configuration

The Configuration class centralizes all available options:

data class Configuration(
    val json: Json = Json {
        encodeDefaults = true
        ignoreUnknownKeys = true
        prettyPrint = true
    },
    val enableLogs: Boolean = false,
    val enableSocket: Boolean = false,

    val connectTimeoutMillis: Long = 12000,
    val requestTimeoutMillis: Long = 12000,
    val socketTimeoutMillis: Long = 12000,

    val followRedirects: Boolean = true,

    val installCookies: Boolean = false,
    val cookieStorage: CookiesStorage? = null,

    val proxyConfiguration: ProxyConfiguration? = null,
)

Parameter	Type	Default	Description
`json`	`Json`	encode/ignore/pretty enabled	`kotlinx.serialization.json.Json` instance used by the client
`enableLogs`	`Boolean`	`false`	Enables Ktor's logging plugin
`enableSocket`	`Boolean`	`false`	Enables WebSocket support
`connectTimeoutMillis`	`Long`	`12000`	Connection timeout (ms)
`requestTimeoutMillis`	`Long`	`12000`	Overall request timeout (ms)
`socketTimeoutMillis`	`Long`	`12000`	Socket timeout (ms)
`followRedirects`	`Boolean`	`true`	Automatically follows HTTP redirects
`installCookies`	`Boolean`	`false`	Enables cookie storage
`cookieStorage`	`CookiesStorage?`	`null`	Custom cookie storage (if `installCookies` is enabled)
`proxyConfiguration`	`ProxyConfiguration?`	`null`	Outgoing proxy configuration

🧩 API

expect fun createClient(
    configuration: Configuration = Configuration(),
    onAuth: AuthConfig.() -> Unit = { },
    onRequest: ((request: HttpRequestBuilder) -> Unit)? = null
): HttpClient

Parameter	Description
`configuration`	Global client configuration (see above)
`onAuth`	Configuration block for Ktor's `Auth` plugin
`onRequest`	Callback executed on every request via `HttpRequestBuilder`, allowing you to add headers, query params, etc.

Returns a ready-to-use HttpClient (Ktor Multiplatform) instance.

🖥️ Supported platforms

As a Kotlin Multiplatform library based on the expect/actual pattern, each target provides its own implementation (underlying Ktor engine: OkHttp, Darwin, CIO, Js, etc.) while exposing the same common API.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or a pull request.

📄 License

This project is distributed under the MIT license.