Ktor 1.6.3 Help

Engines

The Ktor HTTP client can be used on different platforms, including JVM, Android, JavaScript, and Native (iOS and desktop). A specific platform may require a specific engine that processes network requests. For example, you can use Apache, Jetty, or CIO for JVM, OkHttp for Android, and so on. Different engines may have specific features and provide different configuration options.

Add an engine dependency

Besides the ktor-client-core artifact, the Ktor client requires adding a specific dependency for each engine. For each of the supported platform, you can see the available engines and required dependencies in a corresponding section:

Create a client with a specified engine

To create the HTTP client with a specific engine, pass an engine class as an argument to the HttpClient constructor. For example, you can create a client with the CIO engine as follows:

import io.ktor.client.* import io.ktor.client.engine.cio.* val client = HttpClient(CIO)

Default engine

If you call the HttpClient constructor without an argument, the client will choose an engine automatically depending on the artifacts added in a build script.

import io.ktor.client.* val client = HttpClient()

This can be useful for multiplatform projects. For example, for a project targeting both Android and iOS, you can add the Android dependency to the androidMain source set and the Ios dependency to the iosMain source set. The necessary dependency will be selected at compile time.

Configure an engine

You can configure an engine using the engine method. All engines share several common properties exposed by HttpClientEngineConfig, for example:

HttpClient() { engine { // this: [[[HttpClientEngineConfig|https://api.ktor.io/ktor-client/ktor-client-core/ktor-client-core/io.ktor.client.engine/-http-client-engine-config/index.html]]] threadsCount = 4 pipelining = true } }

To learn how to configure a specific engine, see a corresponding section below.

JVM and Android

In this section, we'll take a look on engines available for JVM/Android and their configurations.

Apache (JVM)

The Apache engine supports HTTP/1.1 and provides multiple configuration options. To use it, follow the steps below:

  1. Add the ktor-client-apache dependency:

    implementation "io.ktor:ktor-client-apache:$ktor_version"
    implementation("io.ktor:ktor-client-apache:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-apache</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the Apache class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.apache.* val client = HttpClient(Apache)
  3. To configure an engine, pass settings exposed by ApacheEngineConfig to the engine method:

    import io.ktor.client.* import io.ktor.client.engine.apache.* import org.apache.http.HttpHost val client = HttpClient(Apache) { engine { // this: [[[ApacheEngineConfig|https://api.ktor.io/ktor-client/ktor-client-apache/ktor-client-apache/io.ktor.client.engine.apache/-apache-engine-config/index.html]]] followRedirects = true socketTimeout = 10_000 connectTimeout = 10_000 connectionRequestTimeout = 20_000 customizeClient { // this: HttpAsyncClientBuilder setProxy(HttpHost("127.0.0.1", 8080)) setMaxConnTotal(1000) setMaxConnPerRoute(100) // ... } customizeRequest { // this: RequestConfig.Builder } } }

Java (JVM)

The Java engine uses the Java HTTP Client introduced in Java 11. To use it, follow the steps below:

  1. Add the ktor-client-java dependency:

    implementation "io.ktor:ktor-client-java:$ktor_version"
    implementation("io.ktor:ktor-client-java:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the Java class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.java.* val client = HttpClient(Java)
  3. To configure an engine, pass settings exposed by JavaHttpConfig to the engine method:

    import io.ktor.client.* import io.ktor.client.engine.* import io.ktor.client.engine.java.* val client = HttpClient(Java) { engine { // this: [[[JavaHttpConfig|https://api.ktor.io/ktor-client/ktor-client-java/ktor-client-java/io.ktor.client.engine.java/-java-http-config/index.html]]] threadsCount = 8 pipelining = true proxy = ProxyBuilder.http("http://proxy-server.com/") } }

Jetty (JVM)

The Jetty engine supports only HTTP/2 and can be configured in the following way:

  1. Add the ktor-client-jetty dependency:

    implementation "io.ktor:ktor-client-jetty:$ktor_version"
    implementation("io.ktor:ktor-client-jetty:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-jetty</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the Jetty class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.jetty.* val client = HttpClient(Jetty)
  3. To configure an engine, pass settings exposed by JettyEngineConfig to the engine method:

    import io.ktor.client.* import io.ktor.client.engine.jetty.* import org.eclipse.jetty.util.ssl.SslContextFactory val client = HttpClient(Jetty) { engine { // this: [[[JettyEngineConfig|https://api.ktor.io/ktor-client/ktor-client-jetty/ktor-client-jetty/io.ktor.client.engine.jetty/-jetty-engine-config/index.html]]] sslContextFactory = SslContextFactory.Client() clientCacheSize = 12 } }

CIO (JVM and Android)

CIO is a fully asynchronous coroutine-based engine that can be used for both JVM and Android platforms. It supports only HTTP/1.x for now. To use it, follow the steps below:

  1. Add the ktor-client-cio dependency:

    implementation "io.ktor:ktor-client-cio:$ktor_version"
    implementation("io.ktor:ktor-client-cio:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the CIO class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.cio.* val client = HttpClient(CIO)
  3. To configure an engine, pass settings exposed by CIOEngineConfig to the engine method:

    import io.ktor.client.* import io.ktor.client.engine.cio.* import io.ktor.network.tls.* val client = HttpClient(CIO) { engine { // this: [[[CIOEngineConfig|https://api.ktor.io/ktor-client/ktor-client-cio/ktor-client-cio/io.ktor.client.engine.cio/-c-i-o-engine-config/index.html]]] maxConnectionsCount = 1000 endpoint { // this: [[[EndpointConfig|https://api.ktor.io/ktor-client/ktor-client-cio/ktor-client-cio/io.ktor.client.engine.cio/-endpoint-config/index.html]]] maxConnectionsPerRoute = 100 pipelineMaxSize = 20 keepAliveTime = 5000 connectTimeout = 5000 connectAttempts = 5 } https { // this: [[[TLSConfigBuilder|https://api.ktor.io/ktor-network/ktor-network-tls/ktor-network-tls/io.ktor.network.tls/-t-l-s-config-builder/index.html]]] serverName = "api.ktor.io" cipherSuites = CIOCipherSuites.SupportedSuites trustManager = myCustomTrustManager random = mySecureRandom addKeyStore(myKeyStore, myKeyStorePassword) } } }

Android (Android)

The Android engine targets Android and can be configured in the following way:

  1. Add the ktor-client-android dependency:

    implementation "io.ktor:ktor-client-android:$ktor_version"
    implementation("io.ktor:ktor-client-android:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-android</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the Android class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.android.* val client = HttpClient(Android)
  3. To configure an engine, pass settings exposed by AndroidEngineConfig to the engine method:

    import io.ktor.client.* import io.ktor.client.engine.android.* import java.net.Proxy import java.net.InetSocketAddress val client = HttpClient(Android) { engine { // this: [[[AndroidEngineConfig|https://api.ktor.io/ktor-client/ktor-client-android/ktor-client-android/io.ktor.client.engine.android/-android-engine-config/index.html]]] connectTimeout = 100_000 socketTimeout = 100_000 proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", 8080)) } }

OkHttp (Android)

The OkHttp engine is based on OkHttp can be configured in the following way:

  1. Add the ktor-client-okhttp dependency:

    implementation "io.ktor:ktor-client-okhttp:$ktor_version"
    implementation("io.ktor:ktor-client-okhttp:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-okhttp</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the OkHttp class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.okhttp.* val client = HttpClient(OkHttp)
  3. To configure an engine, pass settings exposed by OkHttpConfig to the engine method:

    import io.ktor.client.* import io.ktor.client.engine.okhttp.* val client = HttpClient(OkHttp) { engine { // this: [[[OkHttpConfig|https://api.ktor.io/ktor-client/ktor-client-okhttp/ktor-client-okhttp/io.ktor.client.engine.okhttp/-ok-http-config/index.html]]] config { // this: OkHttpClient.Builder followRedirects(true) // ... } addInterceptor(interceptor) addNetworkInterceptor(interceptor) preconfigured = okHttpClientInstance } }

JavaScript

The Js engine can be used for JavaScript projects. This engine uses the fetch API for browser applications and node-fetch for Node.js. To use it, follow the steps below:

  1. Add the ktor-client-js dependency:

    implementation "io.ktor:ktor-client-js:$ktor_version"
    implementation("io.ktor:ktor-client-js:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-js</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the Js class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.js.* val client = HttpClient(Js)

    You can also call the JsClient function to get the Js engine singleton:

    import io.ktor.client.engine.js.* val client = JsClient()

Native

In this section, we'll have a look on how to configure engines targeted for Kotlin/Native.

iOS

The iOS engine targets iOS and uses NSURLSession internally. To use it, follow the steps below:

  1. Add the ktor-client-ios dependency:

    implementation "io.ktor:ktor-client-ios:$ktor_version"
    implementation("io.ktor:ktor-client-ios:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-ios</artifactId> <version>${ktor_version}</version> </dependency>

  2. Pass the Ios class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.ios.* val client = HttpClient(Ios)
  3. To configure an engine, pass settings exposed by IosClientEngineConfig to the engine method:

    val client = HttpClient(Ios) { engine { // this: IosClientEngineConfig configureRequest { // this: NSMutableURLRequest } } }

Desktop

For desktop platforms, Ktor provides the Curl engine. This engine is supported for the following platforms: linuxX64, macosX64, mingwX64. To use the Curl engine, follow the steps below:

  1. Install the curl library.

  2. Add the ktor-client-curl dependency:

    implementation "io.ktor:ktor-client-curl:$ktor_version"
    implementation("io.ktor:ktor-client-curl:$ktor_version")
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-curl</artifactId> <version>${ktor_version}</version> </dependency>

  3. Pass the Curl class as an argument to the HttpClient constructor:

    import io.ktor.client.* import io.ktor.client.engine.curl.* val client = HttpClient(Curl)
  4. To configure an engine, pass settings exposed by CurlClientEngineConfig to the engine method:

    import io.ktor.client.* import io.ktor.client.engine.curl.* val client = HttpClient(Curl) { engine { // this: CurlClientEngineConfig sslVerify = true } }

Testing

Ktor provides the MockEngine for testing the HttpClient. To learn how to use it, see MockEngine for testing.

Last modified: 28 May 2021