Ktor — concepts clés, bibliothèque cliente et Kotlin Multiplatform

Qu'est-ce que Ktor?

Ktor est un framework pour créer des clients et serveurs HTTP en Kotlin, développé par JetBrains. Contrairement aux bibliothèques traditionnelles, Ktor a été conçu dès le départ pour le développement multiplateforme et fonctionne sur toutes les plateformes supportées par Kotlin.

Ktor utilise une approche de middleware, inspirée de l'architecture de Kodein et Express.js. Chaque requête passe par un pipeline de fonctions handler qui peuvent modifier la requête et la réponse. Cela offre une flexibilité indisponible dans les bibliothèques à architecture rigide basée sur les annotations.

La version actuelle Ktor 3.0 inclut le support de Kotlin 2.0, du compilateur K2 et d'un nouveau moteur CIO (Coroutine I/O) avec des performances améliorées. La bibliothèque est distribuée sous licence Apache 2.0 et est disponible pour une utilisation commerciale sans restrictions.

La partie cliente de Ktor est entièrement construite sur les coroutines Kotlin, offrant une exécution asynchrone efficace des requêtes sans blocage de threads. La partie serveur permet de créer des serveurs HTTP avec routage, traitement des requêtes et connexions WebSocket.

Ktor utilise une architecture de plugins: toutes les fonctionnalités supplémentaires (logging, sérialisation, authentification) sont connectées via des plugins. Cela rend la bibliothèque modulaire et permet de connecter uniquement les composants nécessaires, réduisant ainsi la taille de l'application finale.

Grâce à une API unifiée sur toutes les plateformes, le développeur n'a pas besoin d'apprendre différents clients HTTP pour iOS et Android. Dans un projet multiplateforme, le code de la couche réseau est entièrement partagé, et l'implémentation spécifique à la plateforme est cachée derrière le moteur HttpClient. Cela réduit le temps de développement et diminue le nombre d'erreurs liées aux différences entre plateformes.

Fonctionnalités clés de Ktor

Ktor fournit un ensemble de fonctionnalités qui en font un choix attrayant pour les projets Kotlin modernes, en particulier les projets multiplateformes.

Support multiplateforme

Ktor fonctionne sur JVM, Android, iOS, macOS, Windows, Linux, JavaScript et Wasm. Le même code de client HTTP s'exécute sur toutes les plateformes sans modification. C'est un avantage clé par rapport aux bibliothèques liées à OkHttp ou URLSession.

Asynchrone avec les coroutines

Les coroutines Kotlin offrent une asynchronie naturelle sans callbacks. Chaque requête est une fonction suspend qui peut être appelée depuis n'importe quelle coroutine. Ktor prend en charge le streaming des réponses via Flow, ce qui est pratique pour les connexions longues et WebSocket.

Architecture de plugins

Les plugins Ktor sont connectés via un bloc install et configurés séparément. Plugins principaux: ContentNegotiation pour la sérialisation, Logging pour la journalisation, Auth pour l'authentification et WebSockets pour la communication bidirectionnelle. Chaque plugin peut être activé ou désactivé indépendamment.

Gestion des erreurs et timeouts

La gestion des erreurs dans Ktor est basée sur les exceptions. La classe ClientRequestException est levée pour les codes 4xx, ServerResponseException pour les 5xx et IOException pour les pannes réseau. Les timeouts sont configurés via le plugin HttpTimeout, qui définit le délai d'attente pour la connexion, la lecture et l'écriture. Pour les tentatives, le plugin Retry est utilisé avec des paramètres de nombre de tentatives et de délai.

Comment fonctionne Ktor?

Ktor utilise une architecture de pipeline où chaque requête traverse une chaîne de handlers. Le client crée une configuration HttpClient avec des plugins installés, et chaque appel à get ou post traverse les plugins dans l'ordre de leur connexion.

Architecture HttpClient

L'objet HttpClient est créé avec un moteur spécifique à la plateforme: CIO pour JVM et Android, Darwin pour iOS et macOS, OkHttp pour la compatibilité Android, Js pour le navigateur. Le moteur peut être sélectionné explicitement ou laissé au choix automatique. Chaque requête retourne un HttpResponse contenant le corps de la réponse, les en-têtes et le statut.

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun fetchUsers(): List<User> {
    return client.get("https://api.example.com/users").body()
}

Installation et configuration de Ktor

L'installation de Ktor se fait via Gradle ou Maven. Pour les projets multiplateformes, les dépendances sont spécifiées dans les sourceSets pour chaque cible. Ktor est distribué via Maven Central.

Connexion via Gradle

Dans build.gradle.kts, ajoutez la dépendance ktor-client-core pour le code commun et un moteur pour la plateforme spécifique. La version de Ktor est définie via une variable dans gradle.properties. Ktor 3.x nécessite Kotlin 2.0+ et supporte le compilateur K2.

val ktorVersion = "3.0.3"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
    implementation("io.ktor:ktor-client-logging:$ktorVersion")
}

Configuration pour iOS

Pour iOS, le moteur Darwin est utilisé, qui encapsule URLSession natif. Dans Kotlin Multiplatform, cela offre des performances maximales et une intégration avec les mécanismes de cache système iOS. Le moteur est ajouté comme une dépendance distincte dans le sourceSet iOS.

Une fonctionnalité importante de Ktor est le support de différents formats de sérialisation via ContentNegotiation. En plus du JSON, le plugin supporte Protobuf, CBOR, XML et des formats personnalisés. Pour la sérialisation, les bibliothèques kotlinx.serialization ou Jackson sont utilisées, et le développeur peut basculer entre elles sans modifier le code des requêtes.

Exemples d'utilisation de Ktor

Les exemples ci-dessous montrent des scénarios typiques de travail avec le client Ktor: une requête GET basique, l'envoi de données et le travail avec du code multiplateforme.

Requête GET avec désérialisation JSON

Une requête GET simple avec désérialisation automatique de la réponse en data class. Ktor utilise le plugin ContentNegotiation avec kotlinx.serialization pour convertir le JSON en objets. Le code est concis et type-safe.

@Serializable
data class Post(
    val id: Int,
    val title: String,
    val body: String
)

suspend fun getPosts(): List<Post> {
    val response = client.get("https://jsonplaceholder.typicode.com/posts")
    return response.body()
}

Requête POST avec corps JSON

Une requête POST dans Ktor envoie une data class comme corps JSON via la méthode post avec contentType et setBody. Le plugin ContentNegotiation sérialise automatiquement l'objet en chaîne JSON. La réponse peut être traitée de manière synchrone ou asynchrone.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Nouvelle publication",
        body = "Contenu de la publication"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Upload de fichier via Multipart

La méthode submitFormWithBinaryData dans Ktor permet d'envoyer des fichiers et des formulaires au format multipart. Ktor divise automatiquement les données en parties et ajoute les en-têtes. Pour suivre la progression, onUpload est utilisé, qui reçoit les octets des données envoyées.

suspend fun uploadFile(fileBytes: ByteArray) {
    client.submitFormWithBinaryData(
        url = "https://api.example.com/upload",
        formData = formData {
            append("file", fileBytes, Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"photo.png\"")
            })
        }
    )
}

Ktor ou Retrofit: que choisir?

Le choix entre Ktor et Retrofit dépend de l'architecture du projet et des exigences multiplateformes. Retrofit reste la norme pour les projets Android uniquement, tandis que Ktor est le meilleur choix pour Kotlin Multiplatform.

Ktor offre également un support intégré pour WebSocket et SSE (Server-Sent Events), ce qui le rend pratique pour les applications en temps réel. Retrofit ne supporte pas directement WebSocket — une bibliothèque OkHttp WebSocket distincte est nécessaire. Ktor est également plus facile à configurer pour différents environnements grâce à son système de plugins, où chaque plugin est responsable d'une fonction.

Authentification dans Ktor

Le plugin Auth dans Ktor supporte l'authentification de base, les tokens Bearer, Digest et OAuth2. La configuration de l'authentification est effectuée de manière déclarative: le développeur spécifie le fournisseur, la source du token et la portée. Ktor ajoute automatiquement les en-têtes d'authentification aux requêtes et peut renouveler le token à son expiration.

Si un projet utilise Kotlin Multiplatform avec du code partagé sur iOS et Android, Ktor est la seule option qui fonctionne sur les deux plateformes sans couches supplémentaires. Retrofit est étroitement lié à OkHttp et JVM, ce qui le rend inadapté à iOS.

Pour les projets Android uniquement, Retrofit fournit une API plus mature, un plus grand nombre de convertisseurs et d'intercepteurs OkHttp. Ktor fonctionne également dans ce scénario, mais son écosystème de plugins est moins étendu. Les deux bibliothèques supportent les coroutines et offrent des performances comparables.