Caching headers

The CachingHeaders plugin adds the capability to configure the Cache-Control and Expires headers used for HTTP caching. You can configure caching in the following ways:

Configure different caching strategies for specific content types, such as images, CSS and JavaScript files, and so on.
Specify caching options on different levels: globally on the application level, on a route level, or for specific calls.

Add dependencies

To use CachingHeaders, you need to include the ktor-server-caching-headers artifact in the build script:

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

implementation "io.ktor:ktor-server-caching-headers:$ktor_version"

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

Install CachingHeaders

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

... 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.cachingheaders.*

                    fun main() {
                        embeddedServer(Netty, port = 8080) {
                            install(CachingHeaders)
                            // ...
                        }.start(wait = true)
                    }
                

                    import io.ktor.server.application.*
                    import io.ktor.server.plugins.cachingheaders.*
                    // ...
                    fun Application.module() {
                        install(CachingHeaders)
                        // ...
                    }
                

The CachingHeaders plugin can also be installed to specific routes. This might be useful if you need different CachingHeaders configurations for different application resources.

After installing CachingHeaders, you can configure caching settings for various content types.

Configure caching

To configure the CachingHeaders plugin, you need to define the options function to provide specified caching options for a given ApplicationCall and content type. The code snippet from the caching-headers example shows how to add the Cache-Control header with the max-age option for a plain text and HTML:

fun Application.module() {
    routing {
        install(CachingHeaders) {
            options { call, content ->
                when (content.contentType?.withoutParameters()) {
                    ContentType.Text.Plain -> CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 3600))
                    ContentType.Text.Html -> CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 60))
                    else -> null
                }
            }
        }
    }
}

The CachingOptions object accepts Cache-Control and Expires header values as parameters:

The cacheControl parameter accepts a CacheControl value. You can use CacheControl.MaxAge to specify the max-age parameter and related settings, such as visibility, revalidation options, and so on. You can disable caching by using CacheControl.NoCache/CacheControl.NoStore.
The expires parameter allows you to specify the Expires header as a GMTDate or ZonedDateTime value.

Route level

You can install plugins not only globally but also to specific routes. For instance, the example below shows how to add the specified caching header for the /index route:

        route("/index") {
            install(CachingHeaders) {
                options { call, content -> CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 1800)) }
            }
            get {
                call.respondText("Index page")
            }
        }

Call level

If you need more fine-grained caching setup, you can configure caching options on a call level using the ApplicationCall.caching property. The example below shows how to configure caching options depending on whether a user is logged in or not:

        route("/profile") {
            get {
                val userLoggedIn = true
                if(userLoggedIn) {
                    call.caching = CachingOptions(CacheControl.NoStore(CacheControl.Visibility.Private))
                    call.respondText("Profile page")
                } else {
                    call.caching = CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 900))
                    call.respondText("Login page")
                }
            }
        }

Last modified: 02 April 2024