MiniPavi-Kotlin

SDK pour le développement de services Minitel sur la plateforme MiniPavi en Kotlin.

Pourquoi ?

MiniPavi propose une API ainsi qu'un SDK pour le développement de services Minitel en PHP.

PHP, c'est sympa, mais mon truc, c'est Kotlin. Pourquoi ne donc pas proposer un SDK pour Kotlin se reposant sur l'API de MiniPavi, et permettre à mes ami·e·s développeur·euse·s Kotlin de créer des services Minitel ?

Vous trouverez donc ici le résultat de ces efforts : un SDK Kotlin pour MiniPavi, vous permettant enfin d'allier vos compétences en Kotlin et votre amour pour le GiscardPunk.

Non mais, pourquoi ?

Pourquoi pas ?

Services d'exemple

Vous pouvez consulter le contenu du module sample pour voir comment utiliser le SDK à l'aide d'exemples concrets.

Services en ligne

• 5422*MINITUS : Motus-like sur Minitel, avec un nouveau mot à trouver chaque jour.

Utilisation du SDK

Tout d'abord, je vous invite à lire la documentation de MiniPavi, disponible sur son site ainsi que sur son dépôt GitHub. Vous y trouverez des informations essentielles sur la topologie de MiniPavi. En lisant cette documentation, gardez en tête que vous pouvez substituer les références au développement PHP, que vous pourrez effectuer en Kotlin à la place.

MiniPavi-Kotlin est conçue pour être utilisée avec le framework Ktor. MiniPavi va appeler votre service, qui construira sa réponse avec le SDK, et la renverra à MiniPavi.

Ajoutez la dépendance à MiniPavi-Kotlin dans votre projet :

# libs.versions.toml

[versions]
minipavi-kotlin = "x.y.z"

[libraries]
minipavi-core = { module = "com.github.outadoc.minipavi-kotlin:core", version.ref = "minipavi-kotlin" }
minipavi-videotex = { module = "com.github.outadoc.minipavi-kotlin:videotex", version.ref = "minipavi-kotlin" }

// settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        maven("https://jitpack.io")
    }
}

// build.gradle.kts

dependencies {
    implementation(libs.minipavi.core)
    implementation(libs.minipavi.videotex)
}

Commencez par créer un serveur Ktor de base. Je vous recommande encore une fois de suivre la documentation de Ktor si vous n'êtes pas familièr·e avec ce framework.

import io.ktor.server.application.Application
import io.ktor.server.engine.embeddedServer
import io.ktor.server.netty.Netty

fun main() {
    embeddedServer(
        Netty,
        port = 8080,
        host = "0.0.0.0",
        module = Application::module,
    ).start(wait = true)
}

fun Application.module() {
    TODO("Votre service sera ici")
}

Ensuite, vous aurez besoin de définir une structure qui représentera l'état d'une session utilisateur. Cet état pourra être persisté au cours de la session, et peut être aussi simple ou aussi complexe que vous le souhaitez, du moment qu'il peut être serialisé et désérialisé par kotlinx.serialization.

import kotlinx.serialization.Serializable

// Un état tout simple, constant, pour une application stateless
@Serializable
object EtatSimple

// Un état un peu plus complexe, avec un compteur
@Serializable
data class EtatCompteur(val nbVisites: Int)

// Une structure avec plusieurs états définis
@Serializable
sealed class Etat {
    @Serializable
    @SerialName("formulaire")
    data object Formulaire : Etat()

    @Serializable
    @SerialName("resultat")
    data class AffichageResultat(
        val nom: String,
        val prenom: String,
    ) : Etat()
}

Une fois que vous avez votre état, vous pouvez commencer à définir votre service.

import fr.outadoc.minipavi.core.ktor.minitelService
import fr.outadoc.minipavi.core.model.ServiceResponse
import io.ktor.server.application.Application

fun Application.module() {
    // Le module ktor de tout à l'heure. On lui ajoute notre service.
    helloWorld()
}

fun Application.helloWorld() {
    minitelService<EtatSimple>(
        path = "/",
        version = "0.1",
        initialState = { EtatSimple },
    ) { request ->
        TODO("Votre logique de service sera ici")
    }
}

Le paramètre request de la lambda contient le contenu de la requête envoyée par la passerelle MiniPavi. Vous pouvez également accéder aux autres informations de la requête comme n'importe quelle définition de Route de Ktor.

Il ne vous reste plus qu'à construire votre réponse, en renvoyant une ServiceResponse :

import fr.outadoc.minipavi.core.ktor.minitelService
import fr.outadoc.minipavi.core.model.ServiceResponse
import fr.outadoc.minipavi.videotex.buildVideotex
import io.ktor.server.application.Application
import kotlinx.serialization.Serializable

@Serializable
object EtatSimple

fun Application.helloWorld() {
    minitelService<EtatSimple>(
        path = "/",
        version = "0.1",
        initialState = { EtatSimple },
    ) { request ->
        ServiceResponse(
            state = EtatSimple,
            content =
                buildVideotex {
                    appendLine("Bonjour le monde !")
                },
        )
    }
}

La fonction buildVideotex vous permet de construire une réponse au format Vidéotex. Vous pouvez y ajouter du texte, des couleurs, des caractères spéciaux, etc. Elle est disponible dans le module videotex.

Et voilà. Plus qu'à lancer votre serveur, et à le connecter à MiniPavi. 🎉