WebSockets serialization

Similar to the ContentNegotiation plugin, WebSockets allow you to serialize/deserialize text frames in a specific format. Ktor supports the following formats out-of-the-box: JSON, XML, CBOR, and ProtoBuf.

Add dependencies

Before using kotlinx.serialization converters, you need to add the Kotlin serialization plugin as described in the Setup section.

JSON

To serialize/deserialize JSON data, you can choose one of the following libraries: kotlinx.serialization, Gson, or Jackson.

Add the ktor-serialization-kotlinx-json artifact in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")

implementation "io.ktor:ktor-serialization-kotlinx-json:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Add the ktor-serialization-gson artifact in the build script:

implementation("io.ktor:ktor-serialization-gson:$ktor_version")

implementation "io.ktor:ktor-serialization-gson:$ktor_version"

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

Add the ktor-serialization-jackson artifact in the build script:

implementation("io.ktor:ktor-serialization-jackson:$ktor_version")

implementation "io.ktor:ktor-serialization-jackson:$ktor_version"

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

XML

To serialize/deserialize XML, add the ktor-serialization-kotlinx-xml in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-xml:$ktor_version")

implementation "io.ktor:ktor-serialization-kotlinx-xml:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

CBOR

To serialize/deserialize CBOR, add the ktor-serialization-kotlinx-cbor in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-cbor:$ktor_version")

implementation "io.ktor:ktor-serialization-kotlinx-cbor:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

ProtoBuf

To serialize/deserialize ProtoBuf, add the ktor-serialization-kotlinx-protobuf in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-protobuf:$ktor_version")

implementation "io.ktor:ktor-serialization-kotlinx-protobuf:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Configure a serializer

JSON serializer

To register the JSON serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the Json parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.*
import kotlinx.serialization.json.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(Json)
}

To register the Gson serializer, assign GsonWebsocketContentConverter to the contentConverter property:

import io.ktor.serialization.gson.*

install(WebSockets) {
    contentConverter = GsonWebsocketContentConverter()
}

To register the Jackson serializer, assign JacksonWebsocketContentConverter to the contentConverter property:

import io.ktor.serialization.jackson.*

install(WebSockets) {
    contentConverter = JacksonWebsocketContentConverter()
}

XML serializer

To register the XML serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the XML parameter and assign this instance to the contentConverter property:

import nl.adaptivity.xmlutil.serialization.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(XML)
}

CBOR serializer

To register the CBOR serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the Cbor parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.cbor.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(Cbor)
}

ProtoBuf serializer

To register the ProtoBuf serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the ProtoBuf parameter and assign this instance to the contentConverter property:

import kotlinx.serialization.protobuf.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(ProtoBuf)
}

Receive and send data

Create a data class

To serialize/deserialize frames into/from an object, you need to create a data class, for example:

data class Customer(val id: Int, val firstName: String, val lastName: String)

If you use kotlinx.serialization, make sure that this class has the @Serializable annotation:

@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

Receive data

To receive and convert a content of a text frame, call the receiveDeserialized function that accepts a data class as a parameter:

        webSocket("/customer") {
            val customer = receiveDeserialized<Customer>()
            println("A customer with id ${customer.id} is received by the server.")
        }

To receive deserialized frames from the incoming channel, use the WebsocketContentConverter.deserialize function. WebsocketContentConverter is available via the WebSocketServerSession.converter property.

Send data

To pass a data object in a text frame using a specified format, you can use the sendSerialized function:

        webSocket("/customer/1") {
            sendSerialized(Customer(1, "Jane", "Smith"))
        }

Last modified: 02 April 2024