Compression

Ktor provides the capability to compress outgoing content by using the Compression plugin. You can use different compression algorithms, including gzip and deflate, specify the required conditions for compressing data (such as a content type or response size), or even compress data based on specific request parameters. Ktor provides the capability to compress response body and decompress request body by using the Compression plugin. You can use different compression algorithms, including gzip and deflate, specify the required conditions for compressing data (such as a content type or response size), or even compress data based on specific request parameters.

Add dependencies

To use Compression, you need to include the ktor-server-compression artifact in the build script:

implementation("io.ktor:ktor-server-compression:$ktor_version")

implementation "io.ktor:ktor-server-compression:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-server-compression-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Install Compression

To install the Compression plugin to the application, pass it to the install function in the specified module. The code snippets below show how to install Compression...

... inside the embeddedServer function call.
... inside the explicitly defined module, which is an extension function of the Application class.

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

This enables the gzip, deflate, and identity encoders on a server. In the next chapter, we'll see how to enable only specific encoders and configure conditions for compressing data. Note that every added encoder will be used to decompress request body if needed.

Configure compression settings

You can configure compression in multiple ways: enable only specific encoders, specify their priorities, compress only specific content types, and so on.

Add specific encoders

To enable only specific encoders, call the corresponding extension functions, for example:

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

You can specify the priority for each compression algorithm by establishing the priority property:

install(Compression) {
    gzip {
        priority = 0.9
    }
    deflate {
        priority = 1.0
    }
}

In the example above, deflate has a higher priority value and takes precedence over gzip. Note that the server first looks at the quality values within the Accept-Encoding header and then takes into account the specified priorities.

Configure content type

By default, Ktor doesn't compress specific content types, such as audio, video, image, and text/event-stream. You can choose the content types to compress by calling matchContentType or exclude the desired media types from compression by using excludeContentType. The code snippet below shows how to compress JavaScript code using gzip and all text subtypes using deflate:

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

You can find the full example here: compression.

Configure response size

The Compression plugin allows you to disable compression for responses whose size doesn't exceed the specified value. To do this, pass the desired value (in bytes) to the minimumSize function:

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

Specify custom conditions

If necessary, you can provide a custom condition using the condition function and compress data depending on the specific request parameters. The code snippet below shows how to compress requests for the specified URI:

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

HTTPS security

HTTPS with the enabled compression is vulnerable to the BREACH attack. You can use various ways to mitigate this attack. For example, you can disable compression whenever the referrer header indicates a cross-site request. In Ktor, this can be done by checking the referrer header value:

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

Implement custom encoder

If necessary, you can provide your own encoder by implementing the ContentEncoder interface. See GzipEncoder as an example of implementation.

Last modified: 30 April 2024