Add "Creating a WebSocket Chat with Ktor" hands-on tutorial

Author: SebastianAigner

Creating a WebSocket Chat with Ktor/00_description.md

@@ -0,0 +1,4 @@
+# Creating a WebSocket Chat with Ktor
+
+Learn how to create a simple Chat application using Ktor including both a JVM server and a JVM client. 
+

Creating a WebSocket Chat with Ktor/01_introduction.md

@@ -0,0 +1,26 @@
+# Introduction
+
+In this hands-on, we will learn how to create a simple chat application which uses WebSockets. We will develop both the client and server application using [Ktor](https://ktor.io/) – an asynchronous Kotlin framework for creating web applications.
+
+## What we will build
+
+Throughout this tutorial, we will implement a simple chat service, which will consist of two applications:
+
+- The **chat server application** will accept and manage connections from our chat users, receive messages, and distribute them to all connected clients.
+- The **chat client application** will allow users to join a common chat server, send messages to other users, and see messages from other users in the terminal.
+
+![app_in_action](./assets/app_in_action.gif)
+
+For both parts of the application, we will make use of Ktor's support for [WebSockets](https://ktor.io/docs/servers-features-websockets.html). Because Ktor is both a server-side and client-side framework, we will be able to reuse the knowledge we acquire building the chat server when it comes to building the client.
+
+After completing this hands-on, you should have a basic understanding of how to work with WebSockets using Ktor and Kotlin, how to exchange information between client and server, and get a basic idea of how to manage multiple connections at the same time.
+
+## Why WebSockets?
+
+WebSockets are a great fit for applications like chats or simple games. Chat sessions are usually long-lived, with the client receiving messages from other participants over a long period of time. Chat sessions are also bidirectional – clients want to send chat messages, and see chat messages from others.
+
+Unlike regular HTTP requests, WebSocket connections can be kept open for a long time and have an easy interface for exchanging data between client and server in the form of frames. We can think of frames as WebSocket messages which come in different types (text, binary, close, ping/pong). Because Ktor provides high-level abstractions over the WebSocket protocol, we can even concentrate on text and binary frames, and leave the handling of other frames to the framework.
+
+WebSockets are also a widely supported technology. All modern browsers can work with WebSockets out of the box, and frameworks to work with WebSockets exist in many programming languages and on many platforms.
+
+Now that we have confidence in the technology we want to use for the implementation of our project, let’s start with the set up!

Creating a WebSocket Chat with Ktor/02_Project_Setup.md

@@ -0,0 +1,64 @@
+# Project setup
+
+Because our application will be two independent parts (chat server and chat client) we structure our application as two separate Gradle projects. Since these two projects are completely independent, they could be created manually, via the online [Ktor Project Generator](https://start.ktor.io/#), or the [plugin for IntelliJ IDEA](https://plugins.jetbrains.com/plugin/10823-ktor).
+
+To skip over these configuration steps, a starter template is available for this specific tutorial, which includes all configuration and required dependencies for our two projects already.
+
+[**Please clone the repository from GitHub, and open it in IntelliJ IDEA.**](https://github.com/kotlin-hands-on/chat-app-websockets)
+
+The template repository contains two barebones Gradle projects for us to build our project: the `client` and `server` projects. Both of them are already preconfigured with the dependencies that we will need throughout the hands-on, so you **don't need to make any changes to the Gradle configuration.**
+
+It might still be beneficial to understand what artifacts are being used for the application, so let's have a closer look at the two projects and the dependencies they rely on.
+
+### Understanding the project configuration
+
+Our two projects both come with their individual sets of configuration files. Let's examine each one of them a bit closer.
+
+#### Dependencies for the `server` project
+
+The server application specifies three dependencies in its `server/build.gradle.kts` file:
+
+```kotlin
+dependencies {
+    implementation("io.ktor:ktor-server-netty:$ktor_version")
+    implementation("io.ktor:ktor-websockets:$ktor_version")
+    implementation("ch.qos.logback:logback-classic:$logback_version")
+}
+```
+
+- `ktor-server-netty` adds Ktor together with the Netty engine, allowing us to use server functionality without having to rely on an external application container.
+- `ktor-websockets` allows us to use the [WebSocket Ktor feature](https://ktor.io/docs/servers-features-websockets.html), the main communication mechanism for our chat.
+- `logback-classic` provides an implementation of [SLF4J](http://www.slf4j.org/), allowing us to see nicely formatted logs in our console.
+
+#### Configuration for the `server` project
+
+Ktor uses a [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md) configuration file to set up its basic behavior, like its entry point and deployment port. It can be found at `server/src/main/resources/application.conf`:
+
+```kotlin
+ktor {
+    deployment {
+        port = 8080
+    }
+    application {
+        modules = [ com.jetbrains.handson.chat.ApplicationKt.module ]
+    }
+}
+```
+
+Alongside this file is also a barebones `logback.xml` file, which sets up the `logback-classic` implementation.
+
+#### Dependencies for the `client` project
+
+The client application specifies two dependencies in its `client/build.gradle.kts` file:
+
+```kotlin
+dependencies {
+    implementation("io.ktor:ktor-client-websockets:$ktor_version")
+    implementation("io.ktor:ktor-client-cio:$ktor_version")
+}
+```
+
+- `ktor-client-cio` provides a [client implementation of Ktor](https://ktor.io/clients/http-client/engines.html#cio) on top of coroutines ("Coroutine-based I/O").
+- `ktor-client-websockets` is the counterpart to the `ktor-websockets` dependency on the server, and allows us to consume [WebSockets from the client](https://ktor.io/docs/clients-websockets.html) with the same API as the server.
+
+Now that we have some understanding of the parts that will make our project run, it's time to start building our project! Let's start by implementing a simple WebSocket echo server!

Creating a WebSocket Chat with Ktor/03_A_first_echo.md

@@ -0,0 +1,39 @@
+# A first echo server
+
+### Implementing an echo server
+
+Let’s start our server development journey by building a small “echo” service which accepts WebSocket connections, receives text content, and sends it back to the client. We can implement this service with Kotlin and Ktor by adding the following implementation for `Application.module()` to `server/src/main/kotlin/com/jetbrains/handson/chat/server/Application.kt`:
+
+```kotlin
+fun Application.module() {
+    install(WebSockets)
+    routing {
+        webSocket("/chat") {
+            send("You are connected!")
+            for(frame in incoming) {
+                frame as? Frame.Text ?: continue
+                val receivedText = frame.readText()
+                send("You said: $receivedText")
+            }
+        }
+    }
+}
+```
+
+We first enable WebSocket-related functionality provided by the Ktor framework by installing the `WebSockets` Ktor feature. This allows us to define endpoints in our routing which respond to the WebSocket protocol (in our case, the route is `/chat`). Within the scope of the `webSocket` route function, we can use various methods for interacting with our clients (via the `DefaultWebSocketServerSession` receiver type). This includes convenience methods to send messages and iterate over received messages.
+
+Because we are only interested in text content, we skip any non-text `Frame`s we receive when iterating over the incoming channel. We can then read any received text, and send it right back to the user with the prefix `"You said:"`.
+
+At this point, we have already built a fully-functioning echo server – a little service that just sends back whatever we send it. Let's try it out!
+
+### Trying out the echo server
+
+For now, we can use a web-based WebSocket client to connect to our echo service, send a message, and receive the echoed reply. Once we have finished implementing the server-side functionality, we will also build our own chat client in Kotlin.
+
+Let's start the server by pressing the play button in the gutter next to the definition of fun main in our server's Application.kt. After our project has finished compiling, we should see a confirmation that the server is running in IntelliJ IDEAs "Run" window: `Application - Responding at http://0.0.0.0:8080`. To try out the service, we can open the WebSocket client provided at https://www.websocket.org/echo.html and use it to connect to `ws://localhost:8080/chat`.
+
+![image-20201022122125926](./assets/image-20201022122125926.png)
+
+Then, we can enter any kind of message in the "Message" window, and send it to our local server. If everything has gone according to plan, we should see the `SENT` and `RECEIVED` messages and in the logs, indicating that our echo-server is functioning just as intended.
+
+With this, we now have a solid foundation for bidirectional communication through WebSockets. Next, let's expand our program more closely resemble a chat server, allowing multiple participants to share messages with others.

Creating a WebSocket Chat with Ktor/04_Exchanging_messages.md

@@ -0,0 +1,64 @@
+# Exchanging messages
+
+Let’s turn our echo server into a real chat server! To do this, we need to make sure messages from the same user are all tagged with the same username. Also, we want to make sure that messages are actually broadcast – sent to all other connected users.
+
+### Modeling connections
+
+Both of these features need us to be able to keep track of the connections our server is holding – to know which user is sending the messages, and to know who to broadcast them to.
+
+Ktor manages a WebSocket connection with an object of the type `DefaultWebSocketSession`, which contains everything required for communicating via WebSockets, including the `incoming` and `outgoing` channels, convenience methods for communication, and more. For now, we can simplify the problem of assigning user names, and just give each participant an auto-generated user name based on a counter. Add the following implementation to a new file in `server/src/main/kotlin/com/jetbrains/handson/chat/server/` called `Connection.kt`: 
+
+```kotlin
+import io.ktor.http.cio.websocket.*
+import java.util.concurrent.atomic.*
+
+class Connection(val session: DefaultWebSocketSession) {
+    companion object {
+        var lastId = AtomicInteger(0)
+    }
+    val name = "user${lastId.getAndIncrement()}"
+}
+```
+
+Note that we are using `AtomicInteger` as a thread-safe data structure for the counter. This ensures that two users will never receive the same ID for their username – even when their two Connection objects are created simultaneously on separate threads.
+
+### Implementing connection handling and message propagation
+
+We can now adjust our server's program to keep track of our Connection objects, and send messages to all connected clients, prefixed with the correct user name. Adjust the implementation of the `routing` block in `server/src/main/kotlin/com/jetbrains/handson/chat/server/Application.kt` to the following code:
+
+```kotlin
+routing {
+    val connections = Collections.synchronizedSet<Connection?>(LinkedHashSet())
+    webSocket("/chat") {
+        println("Adding user!")
+        val thisConnection = Connection(this)
+        connections += thisConnection
+        try {
+            send("You are connected! There are ${connections.count()} users here.")
+            for (frame in incoming) {
+                frame as? Frame.Text ?: continue
+                val receivedText = frame.readText()
+                val textWithUsername = "[${thisConnection.name}]: $receivedText"
+                connections.forEach {
+                    it.session.send(textWithUsername)
+                }
+            }
+        } catch (e: Exception) {
+            println(e.localizedMessage)
+        } finally {
+            println("Removing $thisConnection!")
+            connections -= thisConnection
+        }
+    }
+}
+```
+
+Our server now stores a (thread-safe) collection of `Connection`s. When a user connects, we create their `Connection` object (which also assigns itself a unique username), and add it to the collection. We then greet our user and let them know how many users are currently connecting. When we receive a message from the user, we prefix it with the unique name associated with their `Connection` object, and send it to all currently active connections. Finally, we remove the client's `Connection` object from our collection when the connection is terminated – either gracefully, when the incoming channel gets closed, or with an `Exception` when the network connection between client and server gets interrupted unexpectedly.
+
+To see that our server is now behaving correctly – assigning user names and broadcasting them to everybody connected – we can once again run our application using the play button in the gutter and use the browser-based WebSocket client on https://www.websocket.org/echo.html to connect to `ws://localhost:8080/chat`. This time, we can use two separate browser tabs to validate that messages are exchanged properly.
+
+![image-20201111155400473](./assets/image-20201111155400473.png)
+
+As we can see, our finished chat server can now receive and send messages with multiple participants. Feel free to open a few more browser windows and play around with what we have built here!
+
+In the next chapter, we will write a Kotlin chat client for our server, which will allow us to send and receive messages directly from the command line. Because our clients will also be implemented using Ktor, we will get to reuse much of what we learned about managing WebSockets in Kotlin.