Client Plugin

타임아웃

코드 예제: client-timeout

HttpTimeout 플러그인을 사용하면 다음과 같은 타임아웃을 구성할 수 있습니다:

• 요청 타임아웃(request timeout) — HTTP 호출을 처리하는 데 필요한 시간으로, 요청을 보낼 때부터 응답을 받을 때까지의 기간입니다.
• 연결 타임아웃(connection timeout) — 클라이언트가 서버와 연결을 설정해야 하는 기간입니다.
• 소켓 타임아웃(socket timeout) — 서버와 데이터를 교환할 때 두 데이터 패킷 사이의 최대 유휴 시간입니다.

이러한 타임아웃은 모든 요청에 대해 지정하거나 특정 요청에 대해서만 지정할 수 있습니다.

의존성 추가

HttpTimeout은 ktor-client-core 아티팩트만 필요하며 별도의 특정 의존성은 필요하지 않습니다.

HttpTimeout 설치

HttpTimeout을 설치하려면 클라이언트 구성 블록 내부의 install 함수에 전달하세요:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    install(HttpTimeout)
}

타임아웃 구성

타임아웃을 구성하려면 해당 프로퍼티를 사용할 수 있습니다:

• requestTimeoutMillis는 요청 전송부터 응답 수신까지의 전체 HTTP 호출에 대한 타임아웃을 지정합니다.
• connectTimeoutMillis는 서버와의 연결 설정을 위한 타임아웃을 지정합니다.
• socketTimeoutMillis는 서버와 데이터를 주고받을 때 두 데이터 패킷 사이의 최대 시간 타임아웃을 지정합니다.

install 블록 내에서 모든 요청에 대한 타임아웃을 지정할 수 있습니다. 아래 코드 샘플은 requestTimeoutMillis를 사용하여 요청 타임아웃을 설정하는 방법을 보여줍니다:

val client = HttpClient(CIO) {
    install(HttpTimeout) {
        requestTimeoutMillis = 1000
    }
}

특정 요청에 대해서만 타임아웃을 설정해야 하는 경우, HttpRequestBuilder.timeout 프로퍼티를 사용하세요:

val response: HttpResponse = client.get("http://0.0.0.0:8080/path1") {
    timeout {
        requestTimeoutMillis = 3000
    }
}

특정 요청에 지정된 타임아웃은 install 블록의 전역 타임아웃보다 우선합니다.

타임아웃이 발생하는 경우 Ktor는 HttpRequestTimeoutException, ConnectTimeoutException 또는 SocketTimeoutException을 발생시킵니다.

제한 사항

HttpTimeout은 특정 엔진에 따라 일부 제한 사항이 있습니다. 아래 표는 해당 엔진에서 지원하는 타임아웃을 보여줍니다:

엔진	요청 타임아웃	연결 타임아웃	소켓 타임아웃
Darwin	✅️	✖️	✅️
JavaScript	✅	✖️	✖️
Curl	✅	✅️	✖️
MockEngine	✅	✖️	✅