Skip to content
Server Plugin

압축(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 아티팩트를 추가하세요:

kotlin
implementation(ktorLibs.server.compression)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.server.compression
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-compression-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

Zstandard 압축을 포함하려면 ktor-server-compression-zstd 의존성을 추가하세요:

kotlin
implementation(ktorLibs.server.compression.zstd)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.server.compression.zstd
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-compression-zstd-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

Compression 설치 ​

애플리케이션에 Compression 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 전달하세요. 다음 예제는 Compression을 설치하는 방법을 보여줍니다:

  • embeddedServer() 함수 호출 내에서 설치.
  • Application 클래스에 명시적으로 정의된 module() 확장 함수 내에서 설치.
kotlin
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)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
    install(Compression)
    // ...
}

이렇게 하면 서버에서 gzip, deflate, identity 인코더가 활성화됩니다.

압축 설정 구성 ​

특정 인코더만 활성화하거나, 인코더의 우선순위를 지정하고, 특정 콘텐츠 타입만 압축하는 등 여러 가지 방식으로 압축을 구성할 수 있습니다.

특정 인코더 추가 ​

특정 인코더만 활성화하려면 해당 확장 함수를 호출합니다. 예를 들면 다음과 같습니다:

kotlin
install(Compression) {
    gzip()
    deflate()
    zstd()
}

priority 프로퍼티를 설정하여 각 압축 알고리즘의 우선순위를 지정할 수 있습니다:

kotlin
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를 사용하여 모든 텍스트 하위 타입을 압축하는 방법을 보여줍니다:

kotlin
install(Compression) {
    gzip {
        matchContentType(
            ContentType.Application.JavaScript
        )
    }
    deflate {
        matchContentType(
            ContentType.Text.Any
        )
    }
}

전체 예제는 여기에서 확인할 수 있습니다: compression.

응답 크기 구성 ​

Compression 플러그인을 사용하면 지정된 값을 초과하지 않는 크기의 응답에 대해 압축을 비활성화할 수 있습니다. 이를 구성하려면 minimumSize 함수에 원하는 값(바이트 단위)을 전달합니다:

kotlin
    install(Compression) {
    deflate {
        minimumSize(1024)
    }
}

커스텀 조건 지정 ​

필요한 경우 condition 함수를 사용하여 커스텀 조건을 제공하고, 특정 요청 파라미터에 따라 데이터를 압축할 수 있습니다. 아래 코드 스니펫은 지정된 URI에 대한 요청을 압축하는 방법을 보여줍니다:

kotlin
install(Compression) {
    gzip {
        condition {
            request.uri == "/orders"
        }
    }
}

HTTPS 보안 ​

압축이 활성화된 HTTPS는 BREACH 공격에 취약합니다. 다양한 방법을 사용하여 이 공격을 완화할 수 있습니다. 예를 들어 referrer 헤더가 교차 사이트(cross-site) 요청을 나타낼 때마다 압축을 비활성화할 수 있습니다. Ktor에서는 referrer 헤더 값을 확인하여 이를 처리할 수 있습니다:

kotlin
install(Compression) {
    gzip {
        condition {
            request.headers[HttpHeaders.Referrer]?.startsWith("https://my.domain/") == true
        }
    }
}

Zstandard 압축 레벨 ​

level 파라미터를 사용하여 zstd의 압축 레벨을 구성할 수 있습니다. 기본 압축 레벨은 3이지만 필요에 따라 조정할 수 있습니다.

kotlin
install(Compression) {
    // 기본값은 level = 3
    zstd(level = 20)
}

압축 해제(Decompression) ​

기본적으로 Compression 플러그인은 서버 응답을 압축합니다. 요청 압축 해제를 활성화하려면 mode 프로퍼티를 CompressionConfig.Mode.DecompressRequest로 설정하세요:

kotlin
install(Compression) { 
    mode = CompressionConfig.Mode.DecompressRequest
    gzip()
}

요청 압축 해제가 활성화되면, 플러그인은 역직렬화(deserialization) 및 멀티파트(multipart) 처리와 같은 다른 수신 변환(receive transformation) 작업으로 처리되기 전에 구성된 디코더를 사용하여 요청 본문의 압축을 해제합니다.

커스텀 인코더 구현 ​

필요한 경우 ContentEncoder 인터페이스를 구현하여 자체 인코더를 제공할 수 있습니다. 구현 예시는 GzipEncoder를 참조하세요.