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)
}

커스텀 인코더 구현

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