Ktor 1.5.0 Released

Hadi Hariri

We’re happy to announce the release of Ktor 1.5.0, which comes with new features, bug fixes, and new docs!

Features

1.5.0 is the third and final release for this year, inline with our promise to have three major or minor releases a year, and a minimum of one patch release a month. We’re happy to say that so far we’ve managed to more or less keep this promise, albeit with an ocassional delay at times.

In this minor update we have a series of new features including:

New Development Mode

Ktor provides a series of features targeted at development, such as for instance auto-reload as well as extended debug information. While both of these are useful during development, they can slow things down in production mode. With 1.5.0 we’re introducing a new development mode which enables this functionality with a simple configuration or flag. It also makes it easier to switch settings for production.

The feature can be activated using development=true in application.conf.

This is a breaking change (backwards compatible) as auto-reload is now only enabled in this new mode.

Support for Java HTTP Client

Java 11 introduces an HTTP Client based on reactive streams. Ktor client
now supports this when targeting the JVM.

In order to use it, simply pass in as parameter to HttpClient the value Java.

    HttpClient(Java)

It’s a given that you do need Java 11 for this!

Support for sending cookies via HttpRequestBuilder

If using the HttpRequestBuilder, you now have a new method named cookies which allows you to send cookies easily

 cookies {
    append("my_cookie", value = "My cookie Value")
}

Support for precompressed files

A lot of times you want to send files that are already compressed, and avoid Ktor trying to compress further the contents. With the preCompressed feature
you can now do that easily:

static {
    preCompressed {
        files(temp.parentFile)
    }
}

Thank you to our community contributor guicamest for their contribution.

Support for custom headers in CORS

We now have support for allowing custom headers in CORS requests. While it’s not generally advisable to allow any header in a request, you can specify with Ktor certain custom headers that follow a specific pattern:

 application.install(CORS) {
    anyHost()
    allowHeadersPrefixed("custom-")
}

Thanks to Joze for this contribution.

Experimental WebSocket and Deflate Extensions

We’ve introduced support for WebSocket and deflate extensions. This provides an implementation to RFC-7692.

To use it, install the feature

install(WebSockets) {
    extensions { 
        install(WebSocketDeflateExtension) { 

            // Deflate option
            compressionLevel = Deflater.DEFAULT_COMPRESSION
        }
    }
}

and simply reference it with one of the two new methods: extension and extensionOrNull

webSocket("/echo") {
    val myExtension = extension(MyWebSocketException) 
    // will throw if `MyWebSocketException` is not negotiated

    val myExtension = extensionOrNull(MyWebSocketException) ?: close() 
    // will close the session if `MyWebSocketException` is not negotiated
}

It’s important to note that this is an experimental API and we’d love to get some feedback on it

Support for sealed and nested classes in Server Sessions

You can now have sealed/nested classes in your server session object

data class MySession(val id: String, kind: UserInfo) 

sealed class UserInfo() {
    data class Admin(val drafts: List<String>) : UserInfo()
    data class Reader(val ids: List<String>) : UserInfo()
}

install(Sessions) {
    cookie<MySession>("SESSION") 
}

OkHttp WebSocket creation override

You can now provide an OkHttp WebSocket.Factory which will be taken into account when creating websockets, giving you more flexibility when working with OkHttp. Thank you to Chris for their contribution.

Proper exception handling

Ktor now handles unexpected exceptions correctly. If an exception occurs in the pipeiline, it is propagated to the host and returned as a 500 Internal Server Error with the actual exception object. This allos for better handling on exceptions by the application itself, and no longer requires that you have status pages configured for that particular status code.

In addition to the features outlined above, 1.5.0 also comes with other features and bug fixes

New Documentation

One of the items on our roadmap for 2020-2021 was to improve the onboarding experience which of course includes better documentation. In particular we’re rewriting much of the content and structuring it better. We’ve now completely roughly half of the contents and it’s available for you to consume and give feedback on. Please note that there are still legacy entries and as we push new
contents, some of these will be removed (and redirects put in place).

Acknowledgements

In addition to the contributions outlined above, we’d like to thank all contributors to Ktor, be it in the form of code contributions, as well as feedback and reporting issues.

Getting the bits

As usual, you can get the bits on Maven Central or use Package Search to search/manage Ktor dependencies directly in your project.

We hope you enjoy this release, and see you in 2021 with much more.

Happy Holidays!