final commit for release

Author: AdMorgado

README.md

@@ -2,7 +2,22 @@
 ### Implemented in Kotlin
 ## Implementation
 
-![The architecture of the program](/docs/architecture.png)
+![The architecture of the program](./docs/architecture.png)
+
+Using kotlin coroutines, this is an implementation of a group chat server, 
+that accepts commands and takes use of the server's threads with use of
+suspending coroutines. 
+
+The server works by creating a server, that itself has one coroutine to accept
+new connections, which are then placed into sessions.
+After the server has the begun, it will begin a command phase, ready to accept
+commands from server administrator via console input (See Server Commands).  
+A session is composed of two coroutines, the Rx Coroutine and Tx Coroutine,
+while the Rx Coroutine is only responsible of reading data sent by the session client
+the Tx Coroutine is responsible of receiving Commands from it's suspending queue,
+stopping the session, joining and leaving rooms and 
+sending messages to the session client and to other sessions in the room that
+it occupies
 
 ## Starting the server
 You have the option of running via the Intellij Editor or creating a JAR artifact and running the jar in ```out/artifacts/pc_irc_jar```

docs/architecture.png

@@ -53,7 +53,10 @@ fun main(args: Array<String>) {
 
         runBlocking {
             server.run()
-            server.pollForCommands()
+            while(!server.hasStopped()) {
+                val input = readlnOrNull() ?: break
+                server.sendCommand(input)
+            }
         }
 
     } catch (ex: SQLException) {

docs/architecture.svg

@@ -1,10 +1,21 @@
 package server
 
+const val ALLOWED_SPECIAL_CHARACTERS = "/(){}[]!?#$%&='«»<>@£§"
+
+/**
+ * sanitizes a string and cleans it, used in user input
+ */
 fun String.sanitize(): String {
-    //TODO: improve sanitiation
-    return trim()
+    //TODO: improve sanitation
+    return trim().filter {
+        it.isLetterOrDigit() || it in ALLOWED_SPECIAL_CHARACTERS
+    }
 }
 
+/**
+ * @return a pair, the first token is the first word of the string passed, and the second token is the list of
+ * the other words
+ */
 fun String.toLineCommand(): Pair<String, List<String>> {
     if (isBlank()) return "" to emptyList()
 

src/main/kotlin/main.kt

@@ -21,6 +21,7 @@ class RoomSet {
         }
 
     /**
+     * gets a room in the RoomSet, if a room with [roomName] does not exist it creates one with that name
      * @return the room that has been joined
      */
     suspend fun getRoom(roomName: String): Room {

src/main/kotlin/server/Line.kt

@@ -70,6 +70,8 @@ class Server(
     private lateinit var serverSocket: AsynchronousServerSocketChannel
     private var state = State.NOT_STARTED
 
+    suspend fun hasStopped() = guard.withLock { state === State.STOPPED }
+
     /**
      *
      * @throws IllegalStateException if server has already started
@@ -85,6 +87,10 @@ class Server(
         }
     }
 
+    /**
+     * Begins a coroutine responsible of accepting new connections and creating sessions
+     * @return a Job that represent the accept loop coroutine
+     */
     private suspend fun acceptLoop(scope: CoroutineScope) =
         scope.launch {
             try {
@@ -109,26 +115,29 @@ class Server(
             }
         }
 
-    suspend fun pollForCommands() {
-        while (true) {
-            val input = readlnOrNull() ?: break
-            val sanitizedInput = input.sanitize()
-            val (cmd, args) = sanitizedInput.toLineCommand()
-            if (cmd.firstOrNull() != COMMAND_PROMPT) continue
-            when (cmd.drop(1)) {
-                "shutdown" -> {
-                    if (args.isEmpty()) continue
-                    val timeout = args.first().toLongOrNull() ?: continue
-                    shutdownAndJoin(timeout, TimeUnit.SECONDS)
+    /**
+     * Sends a command to be processed by the server, including shutting it down, sending commands is only allowed if
+     * the server is running and has not stopped
+     */
+    suspend fun sendCommand(input : String)  {
+        check(guard.withLock { state } === State.STARTED) { "Server has not started yet or has stopped!" }
+
+        val sanitizedInput = input.sanitize()
+        val (cmd, args) = sanitizedInput.toLineCommand()
+        if (cmd.firstOrNull() != COMMAND_PROMPT) return
+        when (cmd.drop(1)) {
+            "shutdown" -> {
+                if (args.isEmpty()) {
+                    logger.warn("Must pass timeout for shutdown command")
                 }
-                "exit" ->       shutdownAndJoin()
-                "rooms" ->      roomSet.printActiveUsers()
-                "threads" ->    logger.info("${executor.activeCount} active threads")
-                "sessions" ->   logger.info("${sessionManager.roaster.size} clients connected!")
-                else ->         logger.warn("Invalid command!")
+                val timeout = args.first().toLongOrNull() ?: return
+                shutdownAndJoin(timeout, TimeUnit.SECONDS)
             }
-            if (guard.withLock { state } === State.STOPPED)
-                break
+            "exit" ->       shutdownAndJoin()
+            "rooms" ->      roomSet.printActiveUsers()
+            "threads" ->    logger.info("${executor.activeCount} active threads")
+            "sessions" ->   logger.info("${sessionManager.roaster.size} clients connected!")
+            else ->         logger.warn("Invalid command!")
         }
     }
 
@@ -138,10 +147,11 @@ class Server(
             state = State.STOPPED
         }
 
-        sessionManager.roaster.forEach { it.stop() }
+        serverLoopJob.cancelAndJoin()
+
+        sessionManager.roaster.forEach { it.stop() };
 
         serverSocket.close()
-        serverLoopJob.cancelAndJoin()
     }
 
     /**

src/main/kotlin/server/RoomSet.kt

@@ -29,7 +29,6 @@ class SessionManager {
      */
     fun removeSession(id: Int) = openSessions.remove(id)
 
-
     /**
      *  Acquires a list of all open sessions created by this session manager
      */

src/main/kotlin/server/Server.kt

@@ -13,8 +13,9 @@ import kotlin.coroutines.resumeWithException
 
 const val INPUT_BUFFER_SIZE = 1024
 
-private val encoder = Charsets.UTF_8.newEncoder()
-private val decoder = Charsets.UTF_8.newDecoder()
+val CHARSET = Charsets.UTF_8
+private val encoder = CHARSET.newEncoder()
+private val decoder = CHARSET.newDecoder()
 
 /**
  *
@@ -39,7 +40,8 @@ suspend fun AsynchronousSocketChannel.suspendingWrite(line: String): Int {
 /**
  *  @param timeout
  *  @param unit
- *  @return returns the string sent by session client, an empty string if TODO
+ *  @return returns the string sent by session client, an empty string if a character coding exception occurred and
+ *  and null if the reading has timed out
  */
 suspend fun AsynchronousSocketChannel.suspendingRead(
     timeout: Long = 0,

src/main/kotlin/server/SessionManager.kt

@@ -0,0 +1,15 @@
+
+import server.ALLOWED_SPECIAL_CHARACTERS
+import server.sanitize
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class LineTest {
+    @Test
+    fun `Test sanitization`() {
+        val empty = ""
+        assertEquals(empty, empty.sanitize())
+        assertEquals(ALLOWED_SPECIAL_CHARACTERS, ALLOWED_SPECIAL_CHARACTERS.sanitize())
+        assertEquals(empty, "\\\"".sanitize()) //illegal characters
+    }
+}

src/main/kotlin/server/SocketExtensions.kt

@@ -9,6 +9,7 @@ import java.net.InetSocketAddress
 import java.util.concurrent.LinkedBlockingQueue
 import java.util.concurrent.ThreadPoolExecutor
 import java.util.concurrent.TimeUnit
+import kotlin.test.assertTrue
 
 class ServerTest {
 
@@ -19,7 +20,12 @@ class ServerTest {
     )
     @Test
     fun `Basic Server Test`() {
-        //val server = Server(defaultServerAddress)
+        val server = Server(defaultServerAddress, executor, 1)
+        runBlocking {
+            server.run()
+            server.sendCommand("/exit")
+            assertTrue { server.hasStopped() }
+        }
     }
 
     @Test
@@ -32,6 +38,11 @@ class ServerTest {
                 server.shutdownAndJoin()
             }
         }
+        assertThrows<IllegalStateException> {
+            runBlocking {
+                server.sendCommand("")
+            }
+        }
 
         runBlocking {
             server.run()
@@ -43,13 +54,6 @@ class ServerTest {
             }
         }
     }
-
-    @Test
-    fun `Stress test data races`() {
-        (0 .. 1_000_000).map {
-            val server = Server(defaultServerAddress, executor, 10);
-        }
-    }
 }