HTTP Client Engines

预计阅读时间： 10 分钟

Ktor HTTP Client has a common interface but allows to specify an engine that processes the network request. Different engines have different configurations, dependencies and supporting features.

Table of contents:

Default engine
Configuring engines
JVM
- Apache
- CIO
- Jetty
JVM and Android
- OkHttp
- Android
iOS
Js (JavaScript)
Curl
- MockEngine

Default engine

By calling to the HttpClient method without specifying an engine, it uses a default engine.

val client = HttpClient()

In the case of the JVM, the default engine is resolved with a ServiceLoader, getting the first one available sorted in alphabetical order. Thus depends on the artifacts you have included.

For native, the engine detected during static linkage. Please provide one of the native engines in artifacts.

For js, it uses the predefined one.

Configuring engines

Ktor HttpClient lets you configure the parameters of each engine by calling:

HttpClient(MyHttpEngine) {
    engine {
        // this: MyHttpEngineConfig
    }
}

Every engine config has some common properties that can be set:

The threadsCount property is a recommendation to use by an engine. It can be ignored if an engine doesn’t require such amount of threads.
The pipelining is experimental flag to enable HTTP pipelining.

val client = HttpClient(MyHttpEngine) {
    engine {
        threadsCount = 4
        pipelining = true
    }
}

JVM

Apache

Apache is the most configurable HTTP client about right now. It supports HTTP/1.1 and HTTP/2. It is the only one that supports following redirects and allows you to configure timeouts, proxies among other things it is supported by org.apache.httpcomponents:httpasyncclient.

A sample configuration would look like:

val client = HttpClient(Apache) {
    engine {
        /**
         * Apache embedded http redirect, default = false. Obsolete by `HttpRedirect` feature.
         * It uses the default number of redirects defined by Apache's HttpClient that is 50.
         */
        followRedirects = true

        /**
         * Timeouts.
         * Use `0` to specify infinite.
         * Negative value mean to use the system's default value.
         */

        /**
         * Max time between TCP packets - default 10 seconds.
         */
        socketTimeout = 10_000

        /**
         * Max time to establish an HTTP connection - default 10 seconds.
         */
        connectTimeout = 10_000

        /**
         * Max time for the connection manager to start a request - 20 seconds.
         */
        connectionRequestTimeout = 20_000

        customizeClient {
            // this: HttpAsyncClientBuilder
            setProxy(HttpHost("127.0.0.1", 8080))

            // Maximum number of socket connections.
            setMaxConnTotal(1000)

            // Maximum number of requests for a specific endpoint route.
            setMaxConnPerRoute(100)

            // ...
        }
        customizeRequest {
            // this: RequestConfig.Builder from Apache.
        }
    }
}

本engine在构件 io.ktor:ktor-client-apache:$ktor_version 中的 io.ktor.client.engine.apache.Apache 类中定义。它包含传递依赖 org.apache.httpcomponents:httpasyncclient。

dependencies {
    implementation "io.ktor:ktor-client-apache:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-apache:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-apache</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

CIO

CIO (Coroutine-based I/O) is a Ktor implementation with no additional dependencies and is fully asynchronous. It only supports HTTP/1.x for now.

CIO provides maxConnectionsCount and a endpointConfig for configuring.

A sample configuration would look like:

val client = HttpClient(CIO) {
    engine {
        /**
         * Maximum number of socket connections.
         */
        maxConnectionsCount = 1000

        /**
         * Endpoint specific settings.
         */
        endpoint {
            /**
             * Maximum number of requests for a specific endpoint route.
             */
            maxConnectionsPerRoute = 100

            /**
             * Max size of scheduled requests per connection(pipeline queue size).
             */
            pipelineMaxSize = 20

            /**
             * Max number of milliseconds to keep iddle connection alive.
             */
            keepAliveTime = 5000

            /**
             * Number of milliseconds to wait trying to connect to the server.
             */
            connectTimeout = 5000

            /**
             * Maximum number of attempts for retrying a connection.
             */
            connectRetryAttempts = 5
        }

        /**
         * Https specific settings.
         */
        https {
            /**
            * Custom server name for TLS server name extension.
             * See also: https://en.wikipedia.org/wiki/Server_Name_Indication
             */
            serverName = "api.ktor.io"

            /**
             * List of allowed [CipherSuite]s.
             */
            cipherSuites = CIOCipherSuites.SupportedSuites

            /**
             * Custom [X509TrustManager] to verify server authority.
             *
             * Use system by default.
             */
            trustManager = myCustomTrustManager

            /**
             * [SecureRandom] to use in encryption.
             */
            random = mySecureRandom
        }
    }
}

本engine在构件 io.ktor:ktor-client-cio:$ktor_version 中的 io.ktor.client.engine.cio.CIO 类中定义。

dependencies {
    implementation "io.ktor:ktor-client-cio:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-cio:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-cio</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

Jetty

Jetty provides an additional sslContextFactory for configuring. It only supports HTTP/2 for now.

A sample configuration would look like:

val client = HttpClient(Jetty) {
    engine {
        sslContextFactory = SslContextFactory()
    }
}

本engine在构件 io.ktor:ktor-client-jetty:$ktor_version 中的 io.ktor.client.engine.jetty.Jetty 类中定义。它包含传递依赖 org.eclipse.jetty.http2:http2-client。

dependencies {
    implementation "io.ktor:ktor-client-jetty:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-jetty:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-jetty</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

JVM and Android

OkHttp

There is a engine based on OkHttp:

val client = HttpClient(OkHttp) {
    engine {
        // https://square.github.io/okhttp/3.x/okhttp/okhttp3/OkHttpClient.Builder.html
        config { // this: OkHttpClient.Builder ->
            // ...
            followRedirects(true)
            // ...
        }

        // https://square.github.io/okhttp/3.x/okhttp/okhttp3/Interceptor.html
        addInterceptor(interceptor)
        addNetworkInterceptor(interceptor)

        /**
         * Set okhttp client instance to use instead of creating one.
         */
        preconfigured = okHttpClientInstance
    }

}

本engine在构件 io.ktor:ktor-client-okhttp:$ktor_version 中的 io.ktor.client.engine.okhttp.OkHttp 类中定义。它包含传递依赖 com.squareup.okhttp3:okhttp。

dependencies {
    implementation "io.ktor:ktor-client-okhttp:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-okhttp:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-okhttp</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

Android

The Android engine doesn’t have additional dependencies and uses a ThreadPool with a normal HttpURLConnection, to perform the requests. And can be configured like this:

val client = HttpClient(Android) {
    engine {
        connectTimeout = 100_000
        socketTimeout = 100_000

        /**
         * Proxy address to use.
         */
        proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", serverPort))
    }
}

本engine在构件 io.ktor:ktor-client-android:$ktor_version 中的 io.ktor.client.engine.android.Android 类中定义。

dependencies {
    implementation "io.ktor:ktor-client-android:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-android:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-android</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

iOS

The iOS engine uses the asynchronous NSURLSession internally. And have no additional configuration.

val client = HttpClient(Ios) {
    /**
     * Configure native NSUrlRequest.
     */
    configureRequest { // this: NSMutableURLRequest
        setAllowsCellularAccess(true)
        // ...
    }
}

本engine在构件 io.ktor:ktor-client-ios:$ktor_version 中的 io.ktor.client.engine.ios.Ios 类中定义。

dependencies {
    implementation "io.ktor:ktor-client-ios:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-ios:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-ios</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

Js (JavaScript)

The Js engine, uses the fetch API internally(and node-fetch for node.js runtime).

Js engine has no custom configuration.

val client = HttpClient(Js) {
}

You can also call the JsClient() function to get the Js engine singleton.

本engine在构件 io.ktor:ktor-client-js:$ktor_version 中的 io.ktor.client.engine.js.Js 类中定义。

dependencies {
    implementation "io.ktor:ktor-client-js:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-js:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-js</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

Curl

There is an engine based on Curl:

val client = HttpClient(Curl)

Supported platforms: linux_x64, macos_x64, mingw_x64. Please note that to use the engine you must have the installed curl library at least version 7.63

本engine在构件 io.ktor:ktor-client-curl:$ktor_version 中的 io.ktor.client.engine.curl.Curl 类中定义。

dependencies {
    implementation "io.ktor:ktor-client-curl:$ktor_version"
}

dependencies {
    implementation("io.ktor:ktor-client-curl:$ktor_version")
}

<project>
    ...
    <dependencies>
        <dependency>
            <groupId>io.ktor</groupId>
            <artifactId>ktor-client-curl</artifactId>
            <version>${ktor.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>

MockEngine

The MockEngine is the common engine for testing. See also MockEngine for testing.