Skip to content

KotlinとKtorでWebSocketアプリケーションを作成する

コード例: tutorial-server-websockets

使用されているプラグイン: Static Contentスタイルシート、スクリプト、画像などの静的コンテンツを配信する方法を学びます。、 Content NegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。、WebSockets in Ktor ServerWebsockets プラグインを使用すると、サーバーとクライアント間で双方向の通信セッションを作成できます。、 kotlinx.serialization

この記事では、KotlinとKtorを使用してWebSocketアプリケーションを作成する手順を説明します。これは、「RESTful APIの作成Kotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。」チュートリアルで扱った内容を基にしています。

この記事では、以下の方法を学びます:

  • JSONシリアライゼーションを使用するサービスを作成する。
  • WebSocket接続を介してコンテンツを送受信する。
  • 複数のクライアントにコンテンツを同時にブロードキャストする。

前提条件

このチュートリアルは単独で進めることもできますが、Content NegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。やRESTに慣れるために、「RESTful APIの作成Kotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。」チュートリアルを事前に完了しておくことをお勧めします。

IntelliJ IDEAのインストールを推奨しますが、お好みの他のIDEを使用することもできます。

Hello WebSockets

このチュートリアルでは、「RESTful APIの作成Kotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。」チュートリアルで開発したタスクマネージャーサービスをベースに、WebSocket接続を通じてクライアントとTaskオブジェクトを交換する機能を追加します。これを実現するには、WebSocketsプラグインWebsockets プラグインを使用すると、サーバーとクライアント間で双方向の通信セッションを作成できます。を追加する必要があります。既存のプロジェクトに手動で追加することもできますが、このチュートリアルでは新しいプロジェクトを作成して最初から始めます。

プラグインを含む初期プロジェクトを作成する

  1. Ktor Project Generatorにアクセスします。

  2. Project artifactフィールドに、プロジェクトのアーティファクト名として com.example.ktor-websockets-task-app と入力します。 Ktor Project Generatorでプロジェクトアーティファクトに名前を付ける

  3. プラグインセクションで、Addボタンをクリックして以下のプラグインを検索し、追加します:

    1. Content Negotiation
    2. kotlinx.serialization
    3. WebSockets
    4. Static Content

    Ktor Project Generatorでプラグインを追加する

  4. プラグインを追加すると、プラグインセクションの右上に表示されます。

    その後、プロジェクトに追加されるすべてのプラグインのリストが表示されます: Ktor Project Generatorのプラグインリスト

  5. Downloadボタンをクリックして、Ktorプロジェクトを生成しダウンロードします。

スターターコードを追加する

ダウンロードが完了したら、IntelliJ IDEAでプロジェクトを開き、以下の手順に従ってください:

  1. src/main/kotlinに移動し、modelという名前の新しいサブパッケージを作成します。
  2. modelパッケージ内に、新しいTask.ktファイルを作成します。

  3. Task.ktファイルを開き、優先度を表すenumとタスクを表すdata classを追加します:

    kotlin
    package com.example.model
    
    import kotlinx.serialization.Serializable
    
    enum class Priority {
        Low, Medium, High, Vital
    }
    
    @Serializable
    data class Task(
        val name: String,
        val description: String,
        val priority: Priority
    )

    Taskクラスには、kotlinx.serializationライブラリのSerializableアノテーションが付与されていることに注意してください。これにより、インスタンスをJSONと相互変換できるようになり、その内容をネットワーク経由で転送できるようになります。

    WebSocketsプラグインを含めたため、ジェネレーターによってsrc/main/kotlin内のWebsockets.ktファイルと、Routing.ktファイル内にwebSocketルートが追加されています。

  4. Websockets.ktファイルを開き、既存の.configureWebsockets()関数を以下のように置き換えます:
    kotlin
    fun Application.configureWebsockets() {
        install(WebSockets) {
            contentConverter = KotlinxWebsocketSerializationConverter(Json)
            pingPeriod = 15.seconds
            timeout = 15.seconds
            maxFrameSize = Long.MAX_VALUE
            masking = false
        }
    }
    • WebSocketsプラグインがインストールされ、標準設定で構成されます。
    • contentConverterプロパティが設定され、プラグインがkotlinx.serializationライブラリを介して送受信されるオブジェクトをシリアライズできるようになります。
  5. Routing.ktファイルを開き、既存のApplication.configureRouting()関数を以下の実装に置き換えます:

    kotlin
    fun Application.configureRouting() {
        routing {
            webSocket("/tasks") {
                val tasks = listOf(
                    Task("cleaning", "Clean the house", Priority.Low),
                    Task("gardening", "Mow the lawn", Priority.Medium),
                    Task("shopping", "Buy the groceries", Priority.High),
                    Task("painting", "Paint the fence", Priority.Medium)
                )
    
                for (task in tasks) {
                    sendSerialized(task)
                    delay(1000.milliseconds)
                }
    
                close(CloseReason(CloseReason.Codes.NORMAL, "All done"))
            }
            staticResources("/static", "static")
        }
    }
    • 相対URLが/tasksとなる単一のエンドポイントでルーティングが構成されます。
    • リクエストを受信すると、タスクのリストがシリアライズされてWebSocket接続経由で送信されます。
    • すべてのアイテムが送信されると、サーバーは接続を閉じます。

    デモの目的で、タスクの送信間に1秒の遅延が導入されています。これにより、クライアント側でタスクが段階的に表示される様子を確認できます。この遅延がないと、この例は以前の記事で開発したRESTfulサービスKotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。やWebアプリケーションKtor と Thymeleaf テンプレートを使用して、Kotlin で Web サイトを構築する方法を学びます。とまったく同じように見えてしまいます。

    このイテレーションの最後のステップは、このエンドポイント用のクライアントを作成することです。Static Contentスタイルシート、スクリプト、画像などの静的コンテンツを配信する方法を学びます。プラグインを含めたため、Ktorプロジェクトジェネレーターによってsrc/main/resources/static内にindex.htmlファイルが追加されています。

  6. index.htmlファイルを開き、既存のコンテンツを以下に置き換えます:

    html
    <html>
    <head>
        <title>Using Ktor WebSockets</title>
        <script>
            function readAndDisplayAllTasks() {
                clearTable();
    
                const serverURL = 'ws://0.0.0.0:8080/tasks';
                const socket = new WebSocket(serverURL);
    
                socket.onopen = logOpenToConsole;
                socket.onclose = logCloseToConsole;
                socket.onmessage = readAndDisplayTask;
            }
    
            function readAndDisplayTask(event) {
                let task = JSON.parse(event.data);
                logTaskToConsole(task);
                addTaskToTable(task);
            }
    
            function logTaskToConsole(task) {
                console.log(`Received ${task.name}`);
            }
    
            function logCloseToConsole() {
                console.log("Web socket connection closed");
            }
    
            function logOpenToConsole() {
                console.log("Web socket connection opened");
            }
    
            function tableBody() {
                return document.getElementById("tasksTableBody");
            }
    
            function clearTable() {
                tableBody().innerHTML = "";
            }
    
            function addTaskToTable(task) {
                tableBody().appendChild(taskRow(task));
            }
    
    
            function taskRow(task) {
                return tr([
                    td(task.name),
                    td(task.description),
                    td(task.priority)
                ]);
            }
    
    
            function tr(children) {
                const node = document.createElement("tr");
                children.forEach(child => node.appendChild(child));
                return node;
            }
    
    
            function td(text) {
                const node = document.createElement("td");
                node.appendChild(document.createTextNode(text));
                return node;
            }
        </script>
    </head>
    <body>
    <h1>Viewing Tasks Via WebSockets</h1>
    <form action="javascript:readAndDisplayAllTasks()">
        <input type="submit" value="View The Tasks">
    </form>
    <table rules="all">
        <thead>
        <tr>
            <th>Name</th><th>Description</th><th>Priority</th>
        </tr>
        </thead>
        <tbody id="tasksTableBody">
        </tbody>
    </table>
    </body>
    </html>

    このページでは、すべてのモダンブラウザで利用可能なWebSocket型を使用しています。JavaScriptでこのオブジェクトを作成し、コンストラクターにエンドポイントのURLを渡します。続いて、onopen、onclose、およびonmessageイベントのイベントハンドラーをアタッチします。onmessageイベントが発生すると、documentオブジェクトのメソッドを使用してテーブルに行を追加します。

  7. IntelliJ IDEAで、実行ボタン (intelliJ IDEA run icon) をクリックしてアプリケーションを起動します。

  8. http://0.0.0.0:8080/static/index.htmlにアクセスします。ボタンと空のテーブルが表示されたフォームが表示されるはずです:

    1つのボタンがあるHTMLフォームを表示しているWebブラウザページ

    フォームのボタンをクリックすると、サーバーからタスクが読み込まれ、1秒に1つのペースで表示されます。その結果、テーブルに徐々にデータが追加されていきます。ブラウザのDeveloper Tools(開発者ツール)でJavaScript Consoleを開くことで、ログに記録されたメッセージを確認することもできます。

    ボタンクリックでリストアイテムを表示しているWebブラウザページ

    これで、サービスは期待どおりに動作しています。WebSocket接続が開かれ、アイテムがクライアントに送信され、接続が閉じられます。基盤となるネットワーク処理には多くの複雑さがありますが、Ktorはこれらすべてをデフォルトで処理します。

WebSocketの理解

次のイテレーションに進む前に、WebSocketの基本をいくつか確認しておくと役立つかもしれません。すでにWebSocketに精通している場合は、サービスの設計の改善にそのまま進むことができます。

以前のチュートリアルでは、クライアントはHTTPリクエストを送信し、HTTPレスポンスを受信していました。これはうまく機能し、インターネットのスケーラビリティと回復力を支えています。

しかし、以下のようなシナリオには適していません:

  • コンテンツが時間の経過とともに段階的に生成される。
  • イベントに応じてコンテンツが頻繁に変更される。
  • コンテンツが生成されるにつれて、クライアントがサーバーと対話する必要がある。
  • あるクライアントから送信されたデータを他のクライアントへ迅速に伝播させる必要がある。

これらのシナリオの例としては、株式取引、映画やコンサートのチケット購入、オンラインオークションでの入札、ソーシャルメディアのチャット機能などがあります。WebSocketは、このような状況を処理するために開発されました。

WebSocket接続はTCP上で確立され、長期間維持することができます。この接続は全二重通信(full duplex communication)を提供するため、クライアントはサーバーへメッセージを送信することとサーバーからメッセージを受信することを同時に行えます。

WebSocket APIは、4つのイベント(open、message、close、error)と2つのアクション(send、close)を定義しています。この機能へのアクセス方法は、言語やライブラリによって異なる場合があります。たとえばKotlinでは、受信メッセージのシーケンスをFlowとして処理できます。

設計の改善

次に、より高度な例に対応できるように既存のコードをリファクタリングします。

  1. modelパッケージ内に、新しいTaskRepository.ktファイルを作成します。

  2. TaskRepository.ktを開き、TaskRepository型を追加します:

    kotlin
    package com.example.model
    
    object TaskRepository {
        private val tasks = mutableListOf(
            Task("cleaning", "Clean the house", Priority.Low),
            Task("gardening", "Mow the lawn", Priority.Medium),
            Task("shopping", "Buy the groceries", Priority.High),
            Task("painting", "Paint the fence", Priority.Medium)
        )
    
        fun allTasks(): List<Task> = tasks
    
        fun tasksByPriority(priority: Priority) = tasks.filter {
            it.priority == priority
        }
    
        fun taskByName(name: String) = tasks.find {
            it.name.equals(name, ignoreCase = true)
        }
    
        fun addTask(task: Task) {
            if (taskByName(task.name) != null) {
                throw IllegalStateException("Cannot duplicate task names!")
            }
            tasks.add(task)
        }
    
        fun removeTask(name: String): Boolean {
            return tasks.removeIf { it.name == name }
        }
    }

    以前のチュートリアルでこのコードを見たことがあるかもしれません。

  3. src/main/kotlinに移動し、Routing.ktファイルを開きます。
  4. これで、TaskRepositoryを利用してApplication.configureRouting()のルーティングを簡素化できます:

    kotlin
    routing {
        webSocket("/tasks") {
            for (task in TaskRepository.allTasks()) {
                sendSerialized(task)
                delay(1000.milliseconds)
            }
            close(CloseReason(CloseReason.Codes.NORMAL, "All done"))
        }
        // ...
    }

WebSocket経由でメッセージを送信する

WebSocketの威力を示すために、次のような新しいエンドポイントを作成します:

  • クライアントが起動すると、既存のすべてのタスクを受信する。
  • クライアントがタスクを作成して送信できる。
  • 1つのクライアントがタスクを送信すると、他のクライアントに通知される。
  1. Routing.ktファイルで、現在の.configureRouting()メソッドを以下の実装に置き換えます:

    kotlin
    fun Application.configureRouting() {
        routing {
            val sessions =
                Collections.synchronizedList<WebSocketServerSession>(ArrayList())
    
            webSocket("/tasks") {
                sendAllTasks()
                close(CloseReason(CloseReason.Codes.NORMAL, "All done"))
            }
    
            webSocket("/tasks2") {
                sessions.add(this)
                sendAllTasks()
    
                while(true) {
                    ensureActive()
                    val newTask = receiveDeserialized<Task>()
                    TaskRepository.addTask(newTask)
                    for(session in sessions) {
                        session.sendSerialized(newTask)
                    }
                }
            }
            staticResources("/static", "static")
        }
    }
    
    private suspend fun DefaultWebSocketServerSession.sendAllTasks() {
        for (task in TaskRepository.allTasks()) {
            sendSerialized(task)
            delay(1000.milliseconds)
        }
    }

    このコードにより、以下の処理を行いました:

    • 既存のすべてのタスクを送信する機能をヘルパーメソッドにリファクタリングしました。
    • routing {}ブロック内で、すべてのクライアントを追跡するためのsessionオブジェクトのスレッドセーフなリストを作成しました。
    • 相対URLが/tasks2の新しいエンドポイントを追加しました。クライアントがこのエンドポイントに接続すると、対応するsessionオブジェクトがリストに追加されます。その後、サーバーは新しいタスクの受信を待機する無限ループに入ります。新しいタスクを受信すると、サーバーはそれをリポジトリに保存し、現在のクライアントを含むすべてのクライアントにコピーを送信します。

    この機能をテストするために、index.htmlの機能を拡張した新しいページを作成します。

  2. src/main/resources/static内に、wsClient.htmlという名前の新しいHTMLファイルを作成します。

  3. wsClient.htmlを開き、以下の内容を追加します:

    html
    <html>
    <head>
        <title>WebSocket Client</title>
        <script>
            let serverURL;
            let socket;
    
            function setupSocket() {
                serverURL = 'ws://0.0.0.0:8080/tasks2';
                socket = new WebSocket(serverURL);
    
                socket.onopen = logOpenToConsole;
                socket.onclose = logCloseToConsole;
                socket.onmessage = readAndDisplayTask;
            }
    
            function readAndDisplayTask(event) {
                let task = JSON.parse(event.data);
                logTaskToConsole(task);
                addTaskToTable(task);
            }
    
            function logTaskToConsole(task) {
                console.log(`Received ${task.name}`);
            }
    
            function logCloseToConsole() {
                console.log("Web socket connection closed");
            }
    
            function logOpenToConsole() {
                console.log("Web socket connection opened");
            }
    
            function tableBody() {
                return document.getElementById("tasksTableBody");
            }
    
            function addTaskToTable(task) {
                tableBody().appendChild(taskRow(task));
            }
    
            function taskRow(task) {
                return tr([
                    td(task.name),
                    td(task.description),
                    td(task.priority)
                ]);
            }
    
            function tr(children) {
                const node = document.createElement("tr");
                children.forEach(child => node.appendChild(child));
                return node;
            }
    
            function td(text) {
                const node = document.createElement("td");
                node.appendChild(document.createTextNode(text));
                return node;
            }
    
            function getFormValue(name) {
                return document.forms[0][name].value
            }
    
            function buildTaskFromForm() {
                return {
                    name: getFormValue("newTaskName"),
                    description: getFormValue("newTaskDescription"),
                    priority: getFormValue("newTaskPriority")
                }
            }
    
            function logSendingToConsole(data) {
                console.log("About to send",data);
            }
    
            function sendTaskViaSocket(data) {
                socket.send(JSON.stringify(data));
            }
    
            function sendTaskToServer() {
                let data = buildTaskFromForm();
                logSendingToConsole(data);
                sendTaskViaSocket(data);
                //prevent form submission
                return false;
            }
        </script>
    </head>
    <body onload="setupSocket()">
    <h1>Viewing Tasks Via WebSockets</h1>
    <table rules="all">
        <thead>
        <tr>
            <th>Name</th><th>Description</th><th>Priority</th>
        </tr>
        </thead>
        <tbody id="tasksTableBody">
        </tbody>
    </table>
    <div>
        <h3>Create a new task</h3>
        <form onsubmit="return sendTaskToServer()">
            <div>
                <label for="newTaskName">Name: </label>
                <input type="text" id="newTaskName"
                       name="newTaskName" size="10">
            </div>
            <div>
                <label for="newTaskDescription">Description: </label>
                <input type="text" id="newTaskDescription"
                       name="newTaskDescription" size="20">
            </div>
            <div>
                <label for="newTaskPriority">Priority: </label>
                <select id="newTaskPriority" name="newTaskPriority">
                    <option name="Low">Low</option>
                    <option name="Medium">Medium</option>
                    <option name="High">High</option>
                    <option name="Vital">Vital</option>
                </select>
            </div>
            <input type="submit">
        </form>
    </div>
    </body>
    </html>

    この新しいページには、ユーザーが新しいタスクの情報を入力できるHTMLフォームが導入されています。フォームを送信すると、sendTaskToServer()イベントハンドラーが呼び出されます。これにより、フォームデータからJavaScriptオブジェクトが構築され、WebSocketオブジェクトの.send()メソッドを使用してサーバーに送信されます。

  4. IntelliJ IDEAで、再実行ボタン (intelliJ IDEA rerun icon) をクリックしてアプリケーションを再起動します。

  5. この機能をテストするには、2つのブラウザを並べて開き、以下の手順に従ってください。

    1. ブラウザAで、 http://0.0.0.0:8080/static/wsClient.html にアクセスします。デフォルトのタスクが表示されるはずです。
    2. ブラウザAで新しいタスクを追加します。そのページのテーブルに新しいタスクが表示されます。
    3. ブラウザBで、 http://0.0.0.0:8080/static/wsClient.html にアクセスします。デフォルトのタスクに加えて、ブラウザAで追加した新しいタスクが表示されるはずです。
    4. いずれかのブラウザでタスクを追加します。両方のページに新しい項目が表示されることを確認してください。
    HTMLフォームによる新しいタスクの作成を示す、並べて表示された2つのWebブラウザページ

自動テストを追加する

QAプロセスを効率化し、高速で再現性が高く、手作業を不要にするために、Ktorに組み込まれている自動テストのサポート特別なテストエンジンを使用してサーバーアプリケーションをテストする方法を学びます。を利用できます。以下の手順に従ってください:

  1. Ktor Client内でContent NegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。のサポートを構成できるように、build.gradle.ktsに以下の依存関係を追加します:

    kotlin
    testImplementation(ktorLibs.client.contentNegotiation)
  2. IntelliJ IDEAで、エディターの右側にあるGradle通知アイコン (intelliJ IDEA gradle icon) をクリックしてGradleの変更を読み込みます。

  3. src/test/kotlinに移動し、ServerTest.ktファイルを開きます。

  4. 生成されたテストクラスを以下の実装に置き換えます:

    kotlin
    import com.example.model.Priority
    import com.example.model.Task
    import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
    import io.ktor.client.plugins.websocket.DefaultClientWebSocketSession
    import io.ktor.client.plugins.websocket.WebSockets
    import io.ktor.client.plugins.websocket.converter
    import io.ktor.client.plugins.websocket.webSocket
    import io.ktor.serialization.deserialize
    import io.ktor.serialization.kotlinx.KotlinxWebsocketSerializationConverter
    import io.ktor.serialization.kotlinx.json.json
    import io.ktor.server.testing.testApplication
    import kotlinx.coroutines.flow.consumeAsFlow
    import kotlinx.coroutines.flow.map
    import kotlinx.coroutines.flow.scan
    import kotlinx.serialization.json.Json
    import kotlin.test.Test
    import kotlin.test.assertEquals
    
    class ServerTest {
        @Test
        fun testRoot() = testApplication {
            configure()
    
            val client = createClient {
                install(ContentNegotiation) {
                    json()
                }
                install(WebSockets) {
                    contentConverter =
                        KotlinxWebsocketSerializationConverter(Json)
                }
            }
    
            val expectedTasks = listOf(
                Task("cleaning", "Clean the house", Priority.Low),
                Task("gardening", "Mow the lawn", Priority.Medium),
                Task("shopping", "Buy the groceries", Priority.High),
                Task("painting", "Paint the fence", Priority.Medium)
            )
            var actualTasks = emptyList<Task>()
    
            client.webSocket("/tasks") {
                consumeTasksAsFlow().collect { allTasks ->
                    actualTasks = allTasks
                }
            }
    
            assertEquals(expectedTasks.size, actualTasks.size)
            expectedTasks.forEachIndexed { index, task ->
                assertEquals(task, actualTasks[index])
            }
        }
    
        private fun DefaultClientWebSocketSession.consumeTasksAsFlow() = incoming
            .consumeAsFlow()
            .map {
                converter!!.deserialize<Task>(it)
            }
            .scan(emptyList<Task>()) { list, task ->
                list + task
            }
    }

    このセットアップにより、以下を行います:

    • サービスがテスト環境内で実行されるように構成し、JSONシリアライゼーションやWebSocketsなど、本番環境と同じ機能を有効にします。
    • Ktor ClientKtorクライアントの作成と設定方法について学びます。内でコンテンツネゴシエーションとWebSocketサポートを構成します。これがないと、クライアントはWebSocket接続を使用するときにオブジェクトをJSONとして(デ)シリアライズする方法を認識できません。
    • サービスから返送されると期待されるTasksのリストを宣言します。
    • clientオブジェクトの.webSocket関数を使用して、/tasksにリクエストを送信します。
    • 受信したタスクをFlowとして消費(処理)し、リストに段階的に追加します。
    • すべてのタスクを受信したら、通常の方法でexpectedTasksとactualTasksを比較します。

次のステップ

お疲れ様でした!WebSocket通信とKtor Clientによる自動テストを取り入れることで、タスクマネージャーサービスを大幅に強化できました。

次のチュートリアルExposed SQL ライブラリを使用して Ktor サービスをデータベースリポジトリに接続するプロセスを学びます。に進み、Exposedライブラリを使用してサービスがリレーショナルデータベースとシームレスに対話する方法を学びましょう。