Skip to content
Client Plugin

타임아웃

코드 예제: client-timeout

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

  • 요청 타임아웃(request timeout) — 요청 전송부터 응답 수신까지, HTTP 호출을 처리하는 데 필요한 시간입니다.
  • 연결 타임아웃(connection timeout) — 클라이언트가 서버와의 연결을 수립해야 하는 시간입니다.
  • 소켓 타임아웃(socket timeout) — 서버와 데이터를 교환할 때 두 데이터 패킷 사이의 최대 비활성 시간입니다.

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

의존성 추가 ​

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

HttpTimeout 설치 ​

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

kotlin
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를 사용하여 요청 타임아웃을 설정하는 방법을 보여줍니다:

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

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

kotlin
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✅✖️✅