ktor(client Engines)

Ktor HTTPClient는

JVM, Android, JavaScript 및 Native를 포함한 다양한 플랫폼에서 사용할 수 있습니다.

특정 플랫폼에는 네트워크 요청을 처리하는 특정 엔진이 필요할 수 있습니다.

예를 들어,

JVM 애플리케이션의 경우 Apache 또는 Jetty,

Android의 경우 OkHttp

Android, Kotlin/Native를 대상으로 하는 데스크톱 애플리케이션의 경우 Curl  사용할 수 있습니다.

 

엔진마다 특정 기능이 있고 다른 구성 옵션을 제공이 가능하다

Android/Java

제한 사항

클라이언트 구성 및 특정 플러그인 사용에 영향을 미치는 아래 제한 사항을 고려해야 합니다.

 

- 엔진이 HTTP/2를 지원하는 경우 엔진 구성을 사용자 정의하여 활성화할 수 있습니다.
-  Ktor 클라이언트에서 SSL을 구성하려면 선택한 엔진의 구성을 사용자 정의해야 합니다.
- 일부 엔진은 프록시를 지원하지 않습니다.
- Logging 플러그인은 플랫폼에 따라 다양한 로거 유형을 제공합니다.
- HttpTimeout 플러그인에는 특정 엔진에 대한 몇 가지 제한 사항이 있습니다.
- XML 직렬 변환기는 JVM에서만 지원됩니다.

 

*ktor-client-core 아티팩트와 별도 Ktor 클라이언트는 각 엔진에 대한 특정 종속성을 추가해야 합니다. 

엔진의 경우 Ktor는 -jvm 또는 -js와 같은 접미사가 있는 플랫폼별 아티팩트를 제공합니다(예: ktor-client-cio-jvm).

Gradle은 주어진 플랫폼에 적합한 아티팩트를 해결하지만 Maven은 이 기능을 지원하지 않습니다.

즉, Maven의 경우 플랫폼별 접미사를 수동으로 추가해야 합니다.

Create a client with a specified engine

특정 엔진을 선택하여 클라이언트 생성.

import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

특정 엔진을 선택하지 않고 클라이언트 생성.

 

인수 없이 HttpClient 생성자를 호출하면 클라이언트는 빌드 스크립트에 추가된 아티팩트에 따라 자동으로 엔진을 선택합니다.

 

multiplatform project에 유용할 수 있습니다.

예를 들어 Android와 iOS를 모두 대상으로 하는 프로젝트의 경우,

androidMain 소스 세트에 Android 종속성을 추가하고 iosMain 소스 세트에 Darwin 종속성을 추가할 수 있습니다.

필요한 종속성은 컴파일 시간에 선택된다.

 

HttpClient() {
    engine {
        // this: HttpClientEngineConfig
        threadsCount = 4
        pipelining = true
    }
}

 

engine{ ... } 사용하여 엔진을 구성할 수 있다

모든 엔진은 HttpClientEngineConfig에 의해 노출되는 몇 가지 공통 속성을 공유합니다. 

 

JVM platform Engines

Apache

-  HTTP/1.1을 지원

-  기타 구성 옵션을 제공

import io.ktor.client.*
import io.ktor.client.engine.apache.*
import org.apache.http.HttpHost

val client = HttpClient(Apache) {
    engine {
        // this: ApacheEngineConfig
        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

Java 엔진은 Java 11에 도입된 Java HTTP 클라이언트를 사용

import io.ktor.client.*
import io.ktor.client.engine.*
import io.ktor.client.engine.java.*

val client = HttpClient(Java) {
    engine {
        // this: JavaHttpConfig
        threadsCount = 8
        pipelining = true
        proxy = ProxyBuilder.http("http://proxy-server.com/")
        config {
            version(java.net.http.HttpClient.Version.HTTP_2)
        }
    }
}

Jetty

Jetty 엔진은 HTTP/2 지원하며 다음과 같이 구성할 수 있습니다.

import io.ktor.client.*
import io.ktor.client.engine.jetty.*
import org.eclipse.jetty.util.ssl.SslContextFactory

val client = HttpClient(Jetty) {
    engine {
        // this: JettyEngineConfig
        sslContextFactory = SslContextFactory.Client()
        clientCacheSize = 12
    }
}

JVM and Android platform Engines

CIO

 - CIO는 JVM과 Android 플랫폼 모두에 사용할 수 있는 완전히 비동기식 코루틴 기반 엔진

- 현재로서는 HTTP/1.x만 지원

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.network.tls.*

val client = HttpClient(CIO) {
    engine {
        // this: CIOEngineConfig
        maxConnectionsCount = 1000
        endpoint {
            // this: EndpointConfig
            maxConnectionsPerRoute = 100
            pipelineMaxSize = 20
            keepAliveTime = 5000
            connectTimeout = 5000
            connectAttempts = 5
        }
        https {
            // this: TLSConfigBuilder
            serverName = "api.ktor.io"
            cipherSuites = CIOCipherSuites.SupportedSuites
            trustManager = myCustomTrustManager
            random = mySecureRandom
            addKeyStore(myKeyStore, myKeyStorePassword)
        }
    }
}

Android

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
        connectTimeout = 100_000
        socketTimeout = 100_000
        proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", 8080))
    }
}

OkHttp

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*

val client = HttpClient(OkHttp) {
    engine {
        // this: OkHttpConfig
        config {
            // this: OkHttpClient.Builder
            followRedirects(true)
            // ...
        }
        addInterceptor(interceptor)
        addNetworkInterceptor(interceptor)

        preconfigured = okHttpClientInstance
    }
}

JavaScript platform Engines

Js 엔진은 JavaScript 프로젝트에 사용할 수 있습니다. 이 엔진은 브라우저 애플리케이션에 대해 fetch API를 사용하고 Node.js에 대해 node-fetch를 사용합니다. 

import io.ktor.client.*
import io.ktor.client.engine.js.*

val client = HttpClient(Js)

Native platform Engines (Kotlin / Native)

 

Darwin

Darwin 엔진은 Darwin 기반 운영 체제(macOS, iOS, tvOS 등)를 대상으로 하며 내부적으로 NSURLSession을 사용합니다.

val client = HttpClient(Darwin) {
    engine {
        configureRequest {
            setAllowsCellularAccess(true)
        }
    }
}

Curl

데스크탑 플랫폼  Ktor는 Curl 엔진도 제공

linuxX64, macosX64, macosArm64, mingwX64 플랫폼에서 지원됩니다. 

val client = HttpClient(Curl) {
    engine {
        sslVerify = false
    }
}

 

다중 플랫폼 모바일 프로젝트에서 엔진을 구성하는 방법

멀티플랫폼 모바일 프로젝트에서 엔진별 옵션을 설정하기 위해 expect/actual declarations을 사용할 수 있습니다

 

shared/src/commonMain/kotlin/com/example/kmmktor/Platform.kt 

클라이언트 구성을 수락하고 HttpClient를 반환하는 expect 최상위 httpClient 함수를 추가합니다.

 

fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient

shared/src/androidMain/kotlin/com/example/kmmktor/Platform.kt

Android 모듈에 대한 httpClient 함수의 actual 선언을 추가

 

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*
import java.util.concurrent.TimeUnit

actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(OkHttp) {
   config(this)

   engine {
      config {
         retryOnConnectionFailure(true)
         connectTimeout(0, TimeUnit.SECONDS)
      }
   }
}

shared/src/iosMain/kotlin/com/example/kmmktor/Platform.kt를

iOS 모듈에 대한 httpClient 함수의 actual 선언을 추가

import io.ktor.client.*
import io.ktor.client.engine.darwin.*

actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(Darwin) {
   config(this)
   engine {
      configureRequest {
         setAllowsCellularAccess(true)
      }
   }
}