Server Plugin

압축

압축

필수 의존성: io.ktor:ktor-server-compression

코드 예제: compression

네이티브 서버

Ktor는 Kotlin/Native를 지원하며 추가 런타임이나 가상 머신 없이 서버를 실행할 수 있게 해줍니다.

지원: ✖️

Ktor는 Compression 플러그인을 사용하여 응답 본문을 압축하고 요청 본문의 압축을 해제하는 기능을 제공합니다.

Compression 플러그인을 사용하면 다음과 같은 작업을 수행할 수 있습니다:

• gzip, zstd, deflate를 포함한 다양한 압축 알고리즘을 사용합니다.
• 콘텐츠 유형(content type)이나 응답 크기와 같이 데이터 압축에 필요한 조건을 지정합니다.
• 특정 요청 매개변수를 기반으로 데이터를 압축합니다.

Compression 플러그인은 현재 SSE 응답을 지원하지 않습니다.

Ktor에서 미리 압축된 정적 파일을 제공하는 방법을 알아보려면 미리 압축된 파일을 참조하세요.

의존성 추가

Compression을 사용하려면 빌드 스크립트에 ktor-server-compression 아티팩트를 포함해야 합니다:

Gradle (Kotlin)Gradle (Groovy)Maven

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

Gradle (Kotlin)Gradle (Groovy)Maven

Compression 설치

애플리케이션에 Compression 플러그인을 설치하려면, 지정된

모듈

모듈을 사용하면 경로를 그룹화하여 애플리케이션을 구조화할 수 있습니다.

의 install 함수에 전달하세요. 아래 코드 스니펫은 Compression을 설치하는 방법을 보여줍니다...

• ... embeddedServer 함수 호출 내부에서 설치.
• ... Application 클래스의 확장 함수인 명시적으로 정의된 module 내부에서 설치.

embeddedServermodule

이렇게 하면 서버에서 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 request)임을 나타낼 때마다 압축을 비활성화할 수 있습니다. Ktor에서는 리퍼러 헤더 값을 확인하여 이를 수행할 수 있습니다:

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

Zstandard 압축 레벨

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

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

압축 해제

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

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

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

커스텀 인코더 구현

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