Migrating from 2.2.x to 3.0.x
This guide provides instructions on how to migrate your Ktor application from the 2.2.x version to 3.0.x.
Ktor Server
ApplicationEngine, ApplicationEnvironment, and Application
Several design changes have been introduced to improve configurability and provide a more defined separation between the ApplicationEngine
, ApplicationEnvironment
and Application
instances.
Before v3.0.0, ApplicationEngine
managed ApplicationEnvironment
, which in turn managed Application
.
In the current design, however, Application
is responsible for creating, owning, and initiating both ApplicationEngine
and ApplicationEnvironment
.
This restructuring comes with the following set of breaking changes:
ApplicationEngineEnvironmentBuilder
andapplicationEngineEnvironment
classes are renamed..start()
andstop()
methods are removed fromApplicationEngineEnvironment
.embeddedServer()
returnsEmbeddedServer
instead ofApplicationEngine
.
These changes will impact existing code that relies on the previous model.
Renamed classes
Package | 2.x.x | 3.0.x |
---|---|---|
|
|
|
|
|
|
start() and stop() methods are removed from ApplicationEngineEnvironment
With the merge of AplicationEngineEnvironment
to ApplicationEnvironment
, the start()
and stop()
methods are now only accessible through ApplicationEngine
.
2.x.x | 3.0.x |
---|---|
|
|
|
|
Additionally, in the following table you can see the list of removed properties and their current corresponding ownership:
2.x.x | 3.0.x |
---|---|
|
|
|
|
|
|
|
|
|
|
The ownership changes can be illustrated through the following example:
Introduction of ApplicationPropertiesBuilder
A new entity, ApplicationPropertiesBuilder
, is introduced for configuring Application
properties represented by the ApplicationProperties
class. The class contains properties, previously available in ApplicationEnvironment
.
Introduction of EmbeddedServer
The class EmbeddedServer
is introduced and used to replace ApplicationEngine
as a return type of the embeddedServer()
function.
For more details about the model change, see issue KTOR-3857 on YouTrack.
ktor-server-host-common module has been removed
Due to Application
requiring knowledge of ApplicationEngine
, the contents of ktor-server-host-common
module have been merged into ktor-server-core
, namely the io.ktor.server.engine
package.
Ensure that your dependencies are updated accordingly. In most cases, you can simply remove the ktor-server-host-common
dependency.
Locations plugin has been removed
The Locations
plugin for the Ktor server has been removed. To create type-safe routing, use the Resources plugin instead. This requires the following changes:
Replace the
io.ktor:ktor-server-locations
artifact withio.ktor:ktor-server-resources
.The
Resources
plugin depends on the Kotlin serialization plugin. To add the serialization plugin, see the kotlinx.serialization setup.Update the plugin import from
io.ktor.server.locations.*
toio.ktor.server.resources.*
.Additionally, import the
Resource
module fromio.ktor.resources
.
The following example shows how to implement these changes:
For more information on working with Resources
, refer to Type-safe routing.
Session encryption method update
The encryption method offered by the Sessions
plugin has been updated to enhance security.
Specifically, the SessionTransportTransformerEncrypt
method, which previously derived the MAC from the decrypted session value, now computes it from the encrypted value.
To ensure compatibility with existing sessions, Ktor has introduced the backwardCompatibleRead
property. For current configurations, include the property in the constructor of SessionTransportTransformerEncrypt
:
For more information on session encryption in Ktor, see Sign and encrypt session data.