Engines

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.

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

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:

  1. HttpClient(MyHttpEngine) {
  2.     engine {
  3.         // this: MyHttpEngineConfig
  4.     }
  5. }

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

  1. val client = HttpClient(MyHttpEngine) {
  2.     engine {
  3.         threadsCount = 4
  4.         pipelining = true
  5.     }
  6. }

Apache

Apache HTTP client supports HTTP/1.1 and provides multiple configuration options. 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:

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:

  1. val client = HttpClient(CIO) {
  2.     engine {
  3.         /**
  4.          * Maximum number of socket connections.
  5.          */
  6.         maxConnectionsCount = 1000
  8.         /**
  9.          * Endpoint specific settings.
  10.          */
  11.         endpoint {
  12.             /**
  13.              */
  14.             maxConnectionsPerRoute = 100
  16.             /**
  17.              * Max size of scheduled requests per connection(pipeline queue size).
  18.              */
  19.             pipelineMaxSize = 20
  21.             /**
  23.              */
  24.             keepAliveTime = 5000
  26.             /**
  27.              * Number of milliseconds to wait trying to connect to the server.
  28.              */
  29.             connectTimeout = 5000
  31.             /**
  32.              * Maximum number of attempts for retrying a connection.
  33.              */
  34.             connectAttempts = 5
  35.         }
  37.         /**
  38.          * Https specific settings.
  39.          */
  40.         https {
  41.             /**
  42.             * Custom server name for TLS server name extension.
  43.              * See also: https://en.wikipedia.org/wiki/Server_Name_Indication
  44.              */
  45.             serverName = "api.ktor.io"
  47.             /**
  48.              * List of allowed [CipherSuite]s.
  49.              */
  50.             cipherSuites = CIOCipherSuites.SupportedSuites
  52.              * Custom [X509TrustManager] to verify server authority.
  53.              *
  54.              * Use system by default.
  55.              */
  56.             trustManager = myCustomTrustManager
  58.             /**
  59.              * [SecureRandom] to use in encryption.
  61.             random = mySecureRandom
  62.         }
  63.     }
  64. }

Jetty

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

A sample configuration would look like:

  1. val client = HttpClient(Jetty) {
  2.     engine {
  3.         sslContextFactory = SslContextFactory()
  4.     }
  5. }

JVM and Android

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:

  1. val client = HttpClient(Android) {
  2.     engine {
  3.         connectTimeout = 100_000
  4.         socketTimeout = 100_000
  6.         /**
  7.          * Proxy address to use.
  8.          */
  9.         proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", serverPort))
  10.     }
  11. }

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

  1. val client = HttpClient(Ios) {
  2.     /**
  3.      * Configure native NSUrlRequest.
  4.      */
  5.     configureRequest { // this: NSMutableURLRequest
  6.         setAllowsCellularAccess(true)
  7.         // ...
  8.     }
  9. }

Js (JavaScript)

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

Js engine has no custom configuration.

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

There is an engine based on Curl:

  1. 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

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