압축(Compression)
필수 의존성: io.ktor:ktor-server-compression
코드 예제: compression
네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✖️
Ktor는 Compression 플러그인을 사용하여 응답 본문(response body)을 압축하고 요청 본문(request body)을 압축 해제하는 기능을 제공합니다.
Compression 플러그인을 사용하면 다음과 같은 작업을 수행할 수 있습니다:
gzip,zstd,deflate를 비롯한 다양한 압축 알고리즘을 사용합니다.- 콘텐츠 타입(content type)이나 응답 크기 등 데이터를 압축하기 위한 조건을 지정합니다.
- 특정 요청 파라미터에 따라 데이터를 압축합니다.
현재 Compression 플러그인은 SSE 응답을 지원하지 않습니다.
Ktor에서 사전 압축된 정적 파일을 제공하는 방법을 알아보려면 사전 압축된 파일을 참조하세요.
의존성 추가
Compression을 사용하려면 빌드 스크립트에 ktor-server-compression 아티팩트를 추가하세요:
implementation(ktorLibs.server.compression)implementation ktorLibs.server.compression<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-compression-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Zstandard 압축을 포함하려면 ktor-server-compression-zstd 의존성을 추가하세요:
implementation(ktorLibs.server.compression.zstd)implementation ktorLibs.server.compression.zstd<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-compression-zstd-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Compression 설치
애플리케이션에 Compression 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 전달하세요. 다음 예제는 Compression을 설치하는 방법을 보여줍니다:
embeddedServer()함수 호출 내에서 설치.Application클래스에 명시적으로 정의된module()확장 함수 내에서 설치.
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(Compression)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
install(Compression)
// ...
}이렇게 하면 서버에서 gzip, deflate, identity 인코더가 활성화됩니다.
압축 설정 구성
특정 인코더만 활성화하거나, 인코더의 우선순위를 지정하고, 특정 콘텐츠 타입만 압축하는 등 여러 가지 방식으로 압축을 구성할 수 있습니다.
특정 인코더 추가
특정 인코더만 활성화하려면 해당 확장 함수를 호출합니다. 예를 들면 다음과 같습니다:
install(Compression) {
gzip()
deflate()
zstd()
}priority 프로퍼티를 설정하여 각 압축 알고리즘의 우선순위를 지정할 수 있습니다:
install(Compression) {
gzip {
priority = 0.9
}
deflate {
priority = 1.0
}
zstd {
priority = 0.8
}
}위의 예에서 deflate는 더 높은 우선순위 값을 가지므로 gzip 및 zstd보다 우선 적용됩니다. 서버는 먼저 Accept-Encoding 헤더 내의 품질(quality) 값을 확인한 다음, 지정된 우선순위를 고려합니다.
콘텐츠 타입 구성
기본적으로 Ktor는 audio, video, image, text/event-stream과 같은 특정 콘텐츠 타입을 압축하지 않습니다. matchContentType을 호출하여 압축할 콘텐츠 타입을 선택하거나, excludeContentType을 사용하여 압축에서 제외할 미디어 타입을 지정할 수 있습니다. 아래 코드 스니펫은 gzip을 사용하여 JavaScript 코드를 압축하고, deflate를 사용하여 모든 텍스트 하위 타입을 압축하는 방법을 보여줍니다:
install(Compression) {
gzip {
matchContentType(
ContentType.Application.JavaScript
)
}
deflate {
matchContentType(
ContentType.Text.Any
)
}
}전체 예제는 여기에서 확인할 수 있습니다: compression.
응답 크기 구성
Compression 플러그인을 사용하면 지정된 값을 초과하지 않는 크기의 응답에 대해 압축을 비활성화할 수 있습니다. 이를 구성하려면 minimumSize 함수에 원하는 값(바이트 단위)을 전달합니다:
install(Compression) {
deflate {
minimumSize(1024)
}
}커스텀 조건 지정
필요한 경우 condition 함수를 사용하여 커스텀 조건을 제공하고, 특정 요청 파라미터에 따라 데이터를 압축할 수 있습니다. 아래 코드 스니펫은 지정된 URI에 대한 요청을 압축하는 방법을 보여줍니다:
install(Compression) {
gzip {
condition {
request.uri == "/orders"
}
}
}HTTPS 보안
압축이 활성화된 HTTPS는 BREACH 공격에 취약합니다. 다양한 방법을 사용하여 이 공격을 완화할 수 있습니다. 예를 들어 referrer 헤더가 교차 사이트(cross-site) 요청을 나타낼 때마다 압축을 비활성화할 수 있습니다. Ktor에서는 referrer 헤더 값을 확인하여 이를 처리할 수 있습니다:
install(Compression) {
gzip {
condition {
request.headers[HttpHeaders.Referrer]?.startsWith("https://my.domain/") == true
}
}
}Zstandard 압축 레벨
level 파라미터를 사용하여 zstd의 압축 레벨을 구성할 수 있습니다. 기본 압축 레벨은 3이지만 필요에 따라 조정할 수 있습니다.
install(Compression) {
// 기본값은 level = 3
zstd(level = 20)
}압축 해제(Decompression)
기본적으로 Compression 플러그인은 서버 응답을 압축합니다. 요청 압축 해제를 활성화하려면 mode 프로퍼티를 CompressionConfig.Mode.DecompressRequest로 설정하세요:
install(Compression) {
mode = CompressionConfig.Mode.DecompressRequest
gzip()
}요청 압축 해제가 활성화되면, 플러그인은 역직렬화(deserialization) 및 멀티파트(multipart) 처리와 같은 다른 수신 변환(receive transformation) 작업으로 처리되기 전에 구성된 디코더를 사용하여 요청 본문의 압축을 해제합니다.
커스텀 인코더 구현
필요한 경우 ContentEncoder 인터페이스를 구현하여 자체 인코더를 제공할 수 있습니다. 구현 예시는 GzipEncoder를 참조하세요.
