From 279bc5ed3209d1cad1a03fdde15d958e61a31fc9 Mon Sep 17 00:00:00 2001 From: Daymon Date: Tue, 26 Apr 2022 15:26:42 -0500 Subject: [PATCH] Hello World! --- README.md | 59 ++++ build.gradle.kts | 68 +++++ contributing.md | 41 +++ gradle.properties | 8 + gradle/wrapper/gradle-wrapper.jar | Bin 0 -> 59536 bytes gradle/wrapper/gradle-wrapper.properties | 5 + gradlew | 185 ++++++++++++ gradlew.bat | 89 ++++++ settings.gradle.kts | 1 + .../kotlin/com/daymxn/dchat/Application.kt | 111 +++++++ .../com/daymxn/dchat/DatabaseManager.kt | 270 ++++++++++++++++++ .../com/daymxn/dchat/datamodel/Activity.kt | 74 +++++ .../kotlin/com/daymxn/dchat/datamodel/Chat.kt | 74 +++++ .../com/daymxn/dchat/datamodel/DATAMODELS.md | 58 ++++ .../com/daymxn/dchat/datamodel/Datamodel.kt | 20 ++ .../com/daymxn/dchat/datamodel/Message.kt | 67 +++++ .../kotlin/com/daymxn/dchat/datamodel/User.kt | 82 ++++++ .../daymxn/dchat/routes/DeleteChatRoute.kt | 51 ++++ .../daymxn/dchat/routes/GetActivityRoute.kt | 52 ++++ .../com/daymxn/dchat/routes/GetChatsRoute.kt | 50 ++++ .../kotlin/com/daymxn/dchat/routes/Headers.kt | 92 ++++++ .../com/daymxn/dchat/routes/HealthRoute.kt | 25 ++ .../com/daymxn/dchat/routes/LoginRoute.kt | 54 ++++ .../kotlin/com/daymxn/dchat/routes/ROUTES.md | 127 ++++++++ .../com/daymxn/dchat/routes/RegisterRoute.kt | 54 ++++ .../kotlin/com/daymxn/dchat/routes/Routes.kt | 39 +++ .../com/daymxn/dchat/routes/StartChatRoute.kt | 55 ++++ .../routes/websockets/GetChatHistoryRoute.kt | 53 ++++ .../websockets/GetUsersForSubstringRoute.kt | 44 +++ .../routes/websockets/SendMessageRoute.kt | 66 +++++ .../dchat/routes/websockets/WEBSOCKETS.md | 88 ++++++ .../routes/websockets/WebSocketMainRoute.kt | 41 +++ .../daymxn/dchat/service/ActivityService.kt | 126 ++++++++ .../com/daymxn/dchat/service/ChatService.kt | 162 +++++++++++ .../daymxn/dchat/service/MessageService.kt | 123 ++++++++ .../com/daymxn/dchat/service/SERVICES.md | 80 ++++++ .../com/daymxn/dchat/service/UserService.kt | 119 ++++++++ .../com/daymxn/dchat/util/Annotations.kt | 23 ++ .../daymxn/dchat/util/ApplicationConfig.kt | 43 +++ .../com/daymxn/dchat/util/ApplicationError.kt | 160 +++++++++++ .../com/daymxn/dchat/util/BetterKotlin.kt | 47 +++ .../com/daymxn/dchat/util/BetterResult.kt | 40 +++ .../com/daymxn/dchat/util/BetterWebSockets.kt | 129 +++++++++ .../com/daymxn/dchat/util/DatabaseError.kt | 83 ++++++ .../com/daymxn/dchat/util/JWTManager.kt | 61 ++++ .../com/daymxn/dchat/util/RouteState.kt | 46 +++ src/main/resources/logback.xml | 12 + src/test/TESTS.md | 114 ++++++++ .../dchat/routes/DeleteChatRouteTest.kt | 70 +++++ .../dchat/routes/GetActivityRouteTest.kt | 70 +++++ .../daymxn/dchat/routes/GetChatsRouteTest.kt | 71 +++++ .../com/daymxn/dchat/routes/LoginRouteTest.kt | 81 ++++++ .../daymxn/dchat/routes/RegisterRouteTest.kt | 66 +++++ .../daymxn/dchat/routes/StartChatRouteTest.kt | 80 ++++++ .../websockets/GetChatHistoryRouteTest.kt | 70 +++++ .../GetUsersForSubstringRouteTest.kt | 69 +++++ .../routes/websockets/SendMessageRouteTest.kt | 78 +++++ .../dchat/util/ApplicationTestManager.kt | 65 +++++ .../daymxn/dchat/util/GenerateMockObjects.kt | 31 ++ .../com/daymxn/dchat/util/MockDatabase.kt | 34 +++ .../daymxn/dchat/util/WebSocketTestManager.kt | 40 +++ 61 files changed, 4296 insertions(+) create mode 100644 README.md create mode 100644 build.gradle.kts create mode 100644 contributing.md create mode 100644 gradle.properties create mode 100644 gradle/wrapper/gradle-wrapper.jar create mode 100644 gradle/wrapper/gradle-wrapper.properties create mode 100644 gradlew create mode 100644 gradlew.bat create mode 100644 settings.gradle.kts create mode 100644 src/main/kotlin/com/daymxn/dchat/Application.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/DatabaseManager.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/datamodel/Activity.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/datamodel/Chat.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/datamodel/DATAMODELS.md create mode 100644 src/main/kotlin/com/daymxn/dchat/datamodel/Datamodel.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/datamodel/Message.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/datamodel/User.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/DeleteChatRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/GetActivityRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/GetChatsRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/Headers.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/HealthRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/LoginRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/ROUTES.md create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/RegisterRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/Routes.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/StartChatRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/websockets/WEBSOCKETS.md create mode 100644 src/main/kotlin/com/daymxn/dchat/routes/websockets/WebSocketMainRoute.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/service/ActivityService.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/service/ChatService.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/service/MessageService.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/service/SERVICES.md create mode 100644 src/main/kotlin/com/daymxn/dchat/service/UserService.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/Annotations.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/ApplicationConfig.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/ApplicationError.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/BetterKotlin.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/BetterResult.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/BetterWebSockets.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/DatabaseError.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/JWTManager.kt create mode 100644 src/main/kotlin/com/daymxn/dchat/util/RouteState.kt create mode 100644 src/main/resources/logback.xml create mode 100644 src/test/TESTS.md create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/DeleteChatRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/GetActivityRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/GetChatsRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/LoginRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/RegisterRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/StartChatRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRouteTest.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/util/ApplicationTestManager.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/util/GenerateMockObjects.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/util/MockDatabase.kt create mode 100644 src/test/kotlin/com/daymxn/dchat/util/WebSocketTestManager.kt diff --git a/README.md b/README.md new file mode 100644 index 0000000..7490afb --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ + +

+dChat logo +

+ +![GitHub release (latest by date)](https://img.shields.io/github/v/release/daymxn/dChat?style=flat-square) +![GitHub last commit (branch)](https://img.shields.io/github/last-commit/daymxn/dChat/master?style=flat-square) +![GitHub issues](https://img.shields.io/github/issues/daymxn/dChat?style=flat-square) +![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/daymxn/dChat?style=flat-square) +![GitHub](https://img.shields.io/github/license/daymxn/dChat?style=flat-square) +# dChat + +Desktop messaging platform, developed and designed completely in Kotlin! +## Notable features + +- Fully documented API +- End-to-End markdown writeups +- Industry standard practices +- Functional and modular implementations +- Clean and Readable code +- Business layer testing + + +## Roadmap + +- Client implementation +- Disconnect socket connections when JWT tokens expire +- Notify online chats about users going offline + + +## Documentation + +[Datamodels](/src/main/kotlin/com/daymxn/dchat/datamodel/DATAMODELS.md) + +[Routes](/src/main/kotlin/com/daymxn/dchat/routes/ROUTES.md) + +[WebSockets](/src/main/kotlin/com/daymxn/dchat/routes/websockets/WEBSOCKETS.md) + +[Services](/src/main/kotlin/com/daymxn/dchat/service/SERVICES.md) + +[Tests](/src/test/TESTS.md) + +## Contributing + +Contributions are always welcome! + +See [contributing.md](/contributing.md) for ways to get started. + +## Running tests + +To run tests, run the following with Gradle + +```Bash +./gradlew test +``` + +## License + +[Apache 2.0](/LICENSE) diff --git a/build.gradle.kts b/build.gradle.kts new file mode 100644 index 0000000..4d31232 --- /dev/null +++ b/build.gradle.kts @@ -0,0 +1,68 @@ +import org.jetbrains.kotlin.gradle.tasks.KotlinCompile + +val ktorVersion: String by project +val kotlinVersion: String by project +val logbackVersion: String by project +val exposedVersion: String by project +val webSocketKtorVersion: String by project +val kotestVersion: String by project +val mockkVersion: String by project + +plugins { + application + kotlin("jvm") version "1.6.20" + kotlin("plugin.serialization") version "1.6.20" +} + +group = "com.daymxn" +version = "1.0.0" +application { + mainClass.set("com.daymxn.ApplicationKt") + + val isDevelopment: Boolean = project.ext.has("development") + applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment") +} + +tasks.withType().configureEach { + kotlinOptions.freeCompilerArgs += "-opt-in=io.ktor.locations.KtorExperimentalLocationsAPI" +} + +tasks.withType().configureEach { + useJUnitPlatform() +} + +repositories { + mavenCentral() + maven { + url = uri("https://maven.pkg.jetbrains.space/public/p/ktor/eap") + name = "ktor-eap" + } +} + +dependencies { + implementation("ch.qos.logback:logback-classic:$logbackVersion") + implementation("com.zaxxer:HikariCP:5.0.1") + implementation("mysql:mysql-connector-java:8.0.28") + + implementation("org.jetbrains.exposed:exposed-core:$exposedVersion") + implementation("org.jetbrains.exposed:exposed-dao:$exposedVersion") + implementation("org.jetbrains.exposed:exposed-jdbc:$exposedVersion") + + implementation("io.ktor:ktor-server-content-negotiation-jvm:$ktorVersion") + implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion") + implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion") + implementation("io.ktor:ktor-server-core-jvm:$ktorVersion") + implementation("io.ktor:ktor-server-websockets-jvm:$ktorVersion") + implementation("io.ktor:ktor-server-auth-jvm:$ktorVersion") + implementation("io.ktor:ktor-server-auth-jwt-jvm:$ktorVersion") + implementation("io.ktor:ktor-server-sessions-jvm:$ktorVersion") + implementation("io.ktor:ktor-server-cio-jvm:$ktorVersion") + implementation("io.ktor:ktor-server-content-negotiation:$ktorVersion") + implementation("io.ktor:ktor-server-resources:$ktorVersion") + + testImplementation("io.kotest:kotest-runner-junit5:$kotestVersion") + testImplementation("io.kotest:kotest-assertions-core:$kotestVersion") + testImplementation("io.ktor:ktor-server-tests-jvm:$ktorVersion") + testImplementation("io.ktor:ktor-server-test-host:$ktorVersion") + testImplementation("io.mockk:mockk:$mockkVersion") +} diff --git a/contributing.md b/contributing.md new file mode 100644 index 0000000..7d3f1a9 --- /dev/null +++ b/contributing.md @@ -0,0 +1,41 @@ +# Contributing + +Any and all contributions are entirely welcomed! Before you contribute though, there are +some things you should know. + +## Getting started + +*[Almost]* Every subdirectory has a markdown file with explanations on how code is +structured and designed in that layer. It will give you a brief overview of what the layer +is, and then walk you through on how to contribute to it. You can use the table below to +quickly navigate to any of them. + +- [Datamodels](/src/main/kotlin/com/daymxn/dchat/datamodel/DATAMODELS.md) +- [Routes](/src/main/kotlin/com/daymxn/dchat/routes/ROUTES.md) +- [WebSockets](/src/main/kotlin/com/daymxn/dchat/routes/websockets/WEBSOCKETS.md) +- [Services](/src/main/kotlin/com/daymxn/dchat/service/SERVICES.md) +- [Tests](/src/test/TESTS.md) + +## Making changes + +To make changes, clone the repo to your local disk + +`git clone git@github.com:daymxn/dChat.git` + +Then, checkout to a new feature branch labeled in the following format + +`git checkout -b NAME-CATEGORY-FEATURE` + +Where `NAME` is your *firstLast* name or your *github* username. `CATEGORY` is something like; feature or bugfix. +And `FEATURE` is the title of the new feature (or bug) you're contributing for. + +After you've made changes to your local branch, and you want to submit, you can open a Pull Request (PR) +via the [GitHub web panel](https://github.com/daymxn/dChat/compare). + +> Note that making public contributions to this repo means you accept the LICENSE in place, and are contributing code that also respects that same license + +### Code Formatting + +Code in this repo is formatted with the ktfmt tool for google-java-format. You can enable +this formatting in IntelliJ by downloading and installing the +[ktfmt plugin](https://github.com/facebookincubator/ktfmt). diff --git a/gradle.properties b/gradle.properties new file mode 100644 index 0000000..e54a797 --- /dev/null +++ b/gradle.properties @@ -0,0 +1,8 @@ +ktorVersion=2.0.0 +kotlinVersion=1.6.20 +logbackVersion=1.2.11 +kotlin.code.style=official +exposedVersion=0.37.3 +kotestVersion=5.2.2 +mockkVersion=1.12.3 + diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar new file mode 100644 index 0000000000000000000000000000000000000000..7454180f2ae8848c63b8b4dea2cb829da983f2fa GIT binary patch literal 59536 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 QuEJmfE|#`Dqx|px0L@K;Y5)KL literal 0 HcmV?d00001 diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties new file mode 100644 index 0000000..69a9715 --- /dev/null +++ b/gradle/wrapper/gradle-wrapper.properties @@ -0,0 +1,5 @@ +distributionBase=GRADLE_USER_HOME +distributionPath=wrapper/dists +distributionUrl=https\://services.gradle.org/distributions/gradle-7.1-bin.zip +zipStoreBase=GRADLE_USER_HOME +zipStorePath=wrapper/dists diff --git a/gradlew b/gradlew new file mode 100644 index 0000000..744e882 --- /dev/null +++ b/gradlew @@ -0,0 +1,185 @@ +#!/usr/bin/env sh + +# +# Copyright 2015 the original author or authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +############################################################################## +## +## Gradle start up script for UN*X +## +############################################################################## + +# Attempt to set APP_HOME +# Resolve links: $0 may be a link +PRG="$0" +# Need this for relative symlinks. +while [ -h "$PRG" ] ; do + ls=`ls -ld "$PRG"` + link=`expr "$ls" : '.*-> \(.*\)$'` + if expr "$link" : '/.*' > /dev/null; then + PRG="$link" + else + PRG=`dirname "$PRG"`"/$link" + fi +done +SAVED="`pwd`" +cd "`dirname \"$PRG\"`/" >/dev/null +APP_HOME="`pwd -P`" +cd "$SAVED" >/dev/null + +APP_NAME="Gradle" +APP_BASE_NAME=`basename "$0"` + +# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' + +# Use the maximum available, or set MAX_FD != -1 to use that value. +MAX_FD="maximum" + +warn () { + echo "$*" +} + +die () { + echo + echo "$*" + echo + exit 1 +} + +# OS specific support (must be 'true' or 'false'). +cygwin=false +msys=false +darwin=false +nonstop=false +case "`uname`" in + CYGWIN* ) + cygwin=true + ;; + Darwin* ) + darwin=true + ;; + MSYS* | MINGW* ) + msys=true + ;; + NONSTOP* ) + nonstop=true + ;; +esac + +CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar + + +# Determine the Java command to use to start the JVM. +if [ -n "$JAVA_HOME" ] ; then + if [ -x "$JAVA_HOME/jre/sh/java" ] ; then + # IBM's JDK on AIX uses strange locations for the executables + JAVACMD="$JAVA_HOME/jre/sh/java" + else + JAVACMD="$JAVA_HOME/bin/java" + fi + if [ ! -x "$JAVACMD" ] ; then + die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." + fi +else + JAVACMD="java" + which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." +fi + +# Increase the maximum file descriptors if we can. +if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then + MAX_FD_LIMIT=`ulimit -H -n` + if [ $? -eq 0 ] ; then + if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then + MAX_FD="$MAX_FD_LIMIT" + fi + ulimit -n $MAX_FD + if [ $? -ne 0 ] ; then + warn "Could not set maximum file descriptor limit: $MAX_FD" + fi + else + warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" + fi +fi + +# For Darwin, add options to specify how the application appears in the dock +if $darwin; then + GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" +fi + +# For Cygwin or MSYS, switch paths to Windows format before running java +if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then + APP_HOME=`cygpath --path --mixed "$APP_HOME"` + CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` + + JAVACMD=`cygpath --unix "$JAVACMD"` + + # We build the pattern for arguments to be converted via cygpath + ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` + SEP="" + for dir in $ROOTDIRSRAW ; do + ROOTDIRS="$ROOTDIRS$SEP$dir" + SEP="|" + done + OURCYGPATTERN="(^($ROOTDIRS))" + # Add a user-defined pattern to the cygpath arguments + if [ "$GRADLE_CYGPATTERN" != "" ] ; then + OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" + fi + # Now convert the arguments - kludge to limit ourselves to /bin/sh + i=0 + for arg in "$@" ; do + CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` + CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option + + if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition + eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` + else + eval `echo args$i`="\"$arg\"" + fi + i=`expr $i + 1` + done + case $i in + 0) set -- ;; + 1) set -- "$args0" ;; + 2) set -- "$args0" "$args1" ;; + 3) set -- "$args0" "$args1" "$args2" ;; + 4) set -- "$args0" "$args1" "$args2" "$args3" ;; + 5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; + 6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; + 7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; + 8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; + 9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; + esac +fi + +# Escape application args +save () { + for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done + echo " " +} +APP_ARGS=`save "$@"` + +# Collect all arguments for the java command, following the shell quoting and substitution rules +eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS" + +exec "$JAVACMD" "$@" diff --git a/gradlew.bat b/gradlew.bat new file mode 100644 index 0000000..107acd3 --- /dev/null +++ b/gradlew.bat @@ -0,0 +1,89 @@ +@rem +@rem Copyright 2015 the original author or authors. +@rem +@rem Licensed under the Apache License, Version 2.0 (the "License"); +@rem you may not use this file except in compliance with the License. +@rem You may obtain a copy of the License at +@rem +@rem https://www.apache.org/licenses/LICENSE-2.0 +@rem +@rem Unless required by applicable law or agreed to in writing, software +@rem distributed under the License is distributed on an "AS IS" BASIS, +@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +@rem See the License for the specific language governing permissions and +@rem limitations under the License. +@rem + +@if "%DEBUG%" == "" @echo off +@rem ########################################################################## +@rem +@rem Gradle startup script for Windows +@rem +@rem ########################################################################## + +@rem Set local scope for the variables with windows NT shell +if "%OS%"=="Windows_NT" setlocal + +set DIRNAME=%~dp0 +if "%DIRNAME%" == "" set DIRNAME=. +set APP_BASE_NAME=%~n0 +set APP_HOME=%DIRNAME% + +@rem Resolve any "." and ".." in APP_HOME to make it shorter. +for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi + +@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m" + +@rem Find java.exe +if defined JAVA_HOME goto findJavaFromJavaHome + +set JAVA_EXE=java.exe +%JAVA_EXE% -version >NUL 2>&1 +if "%ERRORLEVEL%" == "0" goto execute + +echo. +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:findJavaFromJavaHome +set JAVA_HOME=%JAVA_HOME:"=% +set JAVA_EXE=%JAVA_HOME%/bin/java.exe + +if exist "%JAVA_EXE%" goto execute + +echo. +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:execute +@rem Setup the command line + +set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar + + +@rem Execute Gradle +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %* + +:end +@rem End local scope for the variables with windows NT shell +if "%ERRORLEVEL%"=="0" goto mainEnd + +:fail +rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of +rem the _cmd.exe /c_ return code! +if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 +exit /b 1 + +:mainEnd +if "%OS%"=="Windows_NT" endlocal + +:omega diff --git a/settings.gradle.kts b/settings.gradle.kts new file mode 100644 index 0000000..b8e5bb0 --- /dev/null +++ b/settings.gradle.kts @@ -0,0 +1 @@ +rootProject.name = "ChatBackend" \ No newline at end of file diff --git a/src/main/kotlin/com/daymxn/dchat/Application.kt b/src/main/kotlin/com/daymxn/dchat/Application.kt new file mode 100644 index 0000000..0ff13f0 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/Application.kt @@ -0,0 +1,111 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn + +import com.auth0.jwt.JWT +import com.auth0.jwt.algorithms.Algorithm +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.routes.* +import com.daymxn.dchat.routes.websockets.webSocketMain +import com.daymxn.dchat.util.ApplicationConfig +import io.ktor.serialization.kotlinx.* +import io.ktor.serialization.kotlinx.json.* +import io.ktor.server.application.* +import io.ktor.server.auth.* +import io.ktor.server.auth.jwt.* +import io.ktor.server.cio.* +import io.ktor.server.engine.* +import io.ktor.server.plugins.contentnegotiation.* +import io.ktor.server.resources.* +import io.ktor.server.routing.* +import io.ktor.server.websocket.* +import kotlinx.serialization.json.Json + +/** Entry point for the application */ +fun main() { + DatabaseManager.connect() + embeddedServer(CIO, port = 8080, host = "0.0.0.0") { + configureSerialization() + configureAuthentication() + configureRouting() + } + .start(wait = true) +} + +/** Configuration for hooking up all the routing with KTOR */ +fun Application.configureRouting() { + install(Resources) + routing { + health() + login() + register() + authenticate("auth-jwt") { + getChatsForUser() + startChat() + deleteChat() + webSocketMain() + } + authenticate("auth-jwt-admin") { getActivity() } + } +} + +/** Configuration for authentication methods with KTOR */ +fun Application.configureAuthentication() { + authentication { + jwt("auth-jwt") { + verifier( + JWT + .require(Algorithm.HMAC256(ApplicationConfig.JWT.secret)) + .withAudience(ApplicationConfig.JWT.audience) + .withIssuer(ApplicationConfig.JWT.issuer) + .build() + ) + validate { + it.payload + .getClaim("id") + .asLong() + .runCatching { DatabaseManager.getUserById(this) } + .getOrNull() + } + } + + jwt("auth-jwt-admin") { + verifier( + JWT + .require(Algorithm.HMAC256(ApplicationConfig.JWT.secret)) + .withAudience(ApplicationConfig.JWT.audience) + .withIssuer(ApplicationConfig.JWT.issuer) + .build() + ) + + validate { + it.payload + .getClaim("id") + .asLong() + .runCatching { DatabaseManager.getUserById(this) } + .getOrNull() + ?.takeIf { it.isAdmin } + } + } + } +} + +/** Configuration for JSON serialization with [EndpointHeader] and [WebSocketHeader] messages */ +fun Application.configureSerialization() { + install(ContentNegotiation) { json() } + install(WebSockets) { contentConverter = KotlinxWebsocketSerializationConverter(Json) } +} diff --git a/src/main/kotlin/com/daymxn/dchat/DatabaseManager.kt b/src/main/kotlin/com/daymxn/dchat/DatabaseManager.kt new file mode 100644 index 0000000..ae84aa7 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/DatabaseManager.kt @@ -0,0 +1,270 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat + +import com.daymxn.dchat.datamodel.* +import com.daymxn.dchat.service.ActivityService +import com.daymxn.dchat.service.ChatService +import com.daymxn.dchat.service.MessageService +import com.daymxn.dchat.service.UserService +import com.daymxn.dchat.util.* +import com.zaxxer.hikari.HikariConfig +import com.zaxxer.hikari.HikariDataSource +import io.ktor.util.date.* +import org.jetbrains.exposed.sql.Database +import org.jetbrains.exposed.sql.SchemaUtils +import org.jetbrains.exposed.sql.StdOutSqlLogger +import org.jetbrains.exposed.sql.addLogger +import org.jetbrains.exposed.sql.transactions.transaction + +/** + * Static object that facilitates communication with service providers for the database. + * + * Application logic is kept to a minimum, and should instead reside in route handlers. + */ +object DatabaseManager { + private val hikariConfig = + HikariConfig().apply { + ApplicationConfig.Database.let { + jdbcUrl = it.jdbcUrl + driverClassName = it.driverClassName + username = it.username + password = it.password + maximumPoolSize = it.maximumPoolSize + } + } + + /** Connects to the database and does some initial init tasks */ + fun connect() { + Database.connect(HikariDataSource(hikariConfig)).also { createTablesIfAbsent() } + } + + /** Ensures that tables are always present, as to avoid any potential errors */ + private fun createTablesIfAbsent() { + transaction { + addLogger(StdOutSqlLogger) + + arrayOf(UserTable, ChatTable, MessageTable, ActivityTable).forEach { SchemaUtils.create(it) } + } + } + + /** + * Validation method for KTOR to call on when receiving an authentication request. + * + * Ensures that the user exists and matches the provided username and password. + * + * @param user the [User] to validate with + * + * @return a [User] object with data of the validated user + * + * @throws ApplicationError if the username or password is incorrect + */ + suspend fun validateUser(user: User): User = + UserService.getByUsername(user.username) + .check { + if (it == null) validationError("Invalid username") + if (it.password != user.password) validationError("Invalid password") + } + .onSuccess { createActivity(Activity(-1, it.id, ActivityType.USER_LOGGED_IN, currentTime())) } + .mapError { it.toApplicationError() } + .getOrThrow() + + private fun currentTime(): Long = System.currentTimeMillis() + + /** + * Inserts a new [User] into the database + * + * @param user the new object to insert + * + * @return the newly created [User], with an up-to-date ID + * + * @throws ApplicationError if the username is already in use + */ + suspend fun createUser(user: User): User = + UserService.insert(user) + .check { if (it == null) validationError("Could not insert user in database") } + .mapError { it.toApplicationError("Username already in use") } + .getOrThrow() + + /** + * Retrieves a [User] from the database by their ID + * + * @param id the ID to filter for + * + * @return the [User] found + * + * @throws ApplicationError if the user is not found + */ + suspend fun getUserById(id: Long): User = + UserService.getById(id) + .check { if (it == null) validationError("User not found") } + .mapError { it.toApplicationError() } + .getOrThrow() + + /** + * Retrieves all [User] objects in the database + * + * @return a list of [User] objects + */ + @NotCurrentlyInUse suspend fun getAllUsers(): List = UserService.getAll() + + /** + * Retrieves all [Activity] for the [USER_LOGGED_IN][ActivityType.USER_LOGGED_IN] event, within a + * specified time frame + * + * @param since UNIX epoch specifying the max date and time to retrieve from + * + * @return a list of the [Activity] found + */ + suspend fun getUsersLoggedInActivities(since: Long): List = + ActivityService.getByTypeAndAfter(ActivityType.USER_LOGGED_IN, since) + + /** + * Retrieves all [Activity] for the [MESSAGE_SENT][ActivityType.MESSAGE_SENT] event, within a + * specified time frame + * + * @param since UNIX epoch specifying the max date and time to retrieve from + * + * @return a list of the [Activity] found + */ + suspend fun getMessagesSentActivities(since: Long): List = + ActivityService.getByTypeAndAfter(ActivityType.MESSAGE_SENT, since) + + /** + * Inserts a new [Activity] into the database + * + * @param activity the new object to insert + * + * @return the newly created [Activity], with an up-to-date ID + * + * @throws ApplicationError if something goes wrong + */ + private suspend fun createActivity(activity: Activity): Activity = + ActivityService.insert(activity) + .check { if (it == null) validationError("Could not insert activity in database") } + .mapError { it.toApplicationError() } + .getOrThrow() + + /** + * Retrieves all [Chat] for the specified [User], within a specified time frame + * + * @param user the user to fetch chats for + * @param since UNIX epoch specifying the max date and time to retrieve from + * + * @return a list of the [Chat] found + */ + suspend fun getChatsForUserSince(user: User, since: Long = 0L): List = + ChatService.getByUserAndAfter(user.id, since) + + /** + * Creates a new [Chat] between two [User] + * + * @param user the initiating user + * @param receipt the ID of the user to start a chat with + * + * @return the created [Chat] + * + * @throws ApplicationError if there already exists a chat between the two users + */ + suspend fun startChatForUserWith(user: User, receipt: Long): Chat = + ChatService.insert( + Chat( + id = -1, + owner = user.id, + receiver = getUserById(receipt).id, + lastActivity = getTimeMillis() + ) + ) + .check { if (it == null) validationError("Could not create chat in database") } + .mapError { it.toApplicationError("You already have a chat opened with that user") } + .getOrThrow() + + /** + * Fetches all [User] whose username is a substring of a specified [String] + * + * Utilized on the client-side to search for users + * + * @param substring what to filter usernames for + * + * @return a list of [UserHead] whose username matches the substring + */ + suspend fun getUsersForSubstring(substring: String): List = + UserService.getByUsernameLike(substring).map { + UserHead(id = it.id, username = it.username, isAdmin = it.isAdmin) + } + + /** + * Removes a [Chat] from the database + * + * Note that [Message] objects linked to the [Chat] will **not** be deleted. The enacting client + * must also be a part of the [Chat] to delete it. + * + * @param user the client wanting to delete the chat + * @param chat the ID of the chat to delete + * + * @return whether the chat was deleted or not + */ + suspend fun deleteChat(user: User, chat: Long): Boolean = + ChatService.deleteIfUserApartOf(user.id, chat) + + /** + * Creates a new [Message] in the database + * + * Also calls out to create a new [Activity] for [MESSAGE_SENT][ActivityType.MESSAGE_SENT], if the + * operation is successful + * + * @param message the new object to insert + * + * @return the newly created [Message], with an up-to-date ID + * + * @throws ApplicationError if something goes wrong + */ + suspend fun createMessage(message: Message): Message = + MessageService.insert(message) + .check { if (it == null) validationError("Could not save message in database") } + .onSuccess { + createActivity(Activity(-1, it.sender, ActivityType.MESSAGE_SENT, currentTime())) + } + .mapError { it.toApplicationError() } + .getOrThrow() + + /** + * Retrieves a [Chat] from the database by ID + * + * @param id the ID to filter for + * + * @return the [Chat] found + * + * @throws ApplicationError if the chat is not found + */ + suspend fun getChatById(id: Long): Chat = + ChatService.getById(id) + .check { if (it == null) validationError("Chat not found") } + .mapError { it.toApplicationError() } + .getOrThrow() + + /** + * Retrieves all [Message] for the specified [Chat], that were sent within a specified time frame + * + * @param chat the ID of the [Chat] to filter messages from + * @param since UNIX epoch specifying the max date and time to retrieve from + * + * @return a list of the [Message] found + */ + suspend fun getMessagesForChatSince(chat: Long, since: Long): List = + MessageService.getByChatAndAfter(chat, since) +} diff --git a/src/main/kotlin/com/daymxn/dchat/datamodel/Activity.kt b/src/main/kotlin/com/daymxn/dchat/datamodel/Activity.kt new file mode 100644 index 0000000..5ea3aff --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/datamodel/Activity.kt @@ -0,0 +1,74 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.datamodel + +import com.daymxn.dchat.datamodel.ActivityTable.id +import com.daymxn.dchat.datamodel.ActivityTable.owner +import com.daymxn.dchat.datamodel.ActivityTable.primaryKey +import com.daymxn.dchat.datamodel.ActivityTable.timestamp +import com.daymxn.dchat.datamodel.ActivityTable.type +import kotlinx.serialization.Serializable +import org.jetbrains.exposed.sql.Table + +/** + * Database table schema for [Activity] + * + * @property id unique [Long] column index, automatically created and incremented for each entry + * @property owner **indexed** [Long] column foreign key pointing to the [User] that created the + * entry + * @property type enum for [ActivityType] + * @property timestamp epoch UNIX [Long] column + * @property primaryKey primary key constraint pointing to the id property + */ +object ActivityTable : Table() { + val id = long("id").autoIncrement() + val owner = long("owner_id").index() + val type = enumeration("type", ActivityType::class) + val timestamp = long("timestamp") + + override val primaryKey = PrimaryKey(id, name = "pk_activity_id") +} + +/** + * Loggable actions committed by [User] + * + * Activities are the primary source of data collection for the application. Take a look at + * [ActivityType] to get an idea of all the possible data points. + * + * @property id unique [Long] assigned to each [Activity] from the database + * @property owner the ID of the [User] the committed the action that created this [Activity] + * @property type the specific [ActivityType] that this [Activity] represents + * @property timestamp epoch UNIX [Long] representing the creation date of this [Activity] + */ +@Serializable +data class Activity( + val id: Long, + val owner: Long, + val type: ActivityType, + val timestamp: Long, +) : Datamodel + +/** Enum representations of all possible data points to be collected for [Activity] creation */ +@Serializable +enum class ActivityType { + + /** Represents a successful authentication for a [User] */ + USER_LOGGED_IN, + + /** Represents a successful [Message] creation for a [User] in a [Chat] */ + MESSAGE_SENT +} diff --git a/src/main/kotlin/com/daymxn/dchat/datamodel/Chat.kt b/src/main/kotlin/com/daymxn/dchat/datamodel/Chat.kt new file mode 100644 index 0000000..4859be8 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/datamodel/Chat.kt @@ -0,0 +1,74 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.datamodel + +import com.daymxn.dchat.datamodel.ChatTable.id +import com.daymxn.dchat.datamodel.ChatTable.lastActivity +import com.daymxn.dchat.datamodel.ChatTable.owner +import com.daymxn.dchat.datamodel.ChatTable.primaryKey +import com.daymxn.dchat.datamodel.ChatTable.receiver +import kotlinx.serialization.Serializable +import org.jetbrains.exposed.sql.Table + +/** + * Database table schema for [Chat] + * + * Note that there exists a composite index against [owner] and [receiver] + * + * @property id unique [Long] column index, automatically created and incremented for each entry + * @property owner **indexed** [Long] column foreign key pointing to the [User] that created the + * entry + * @property receiver **indexed** [Long] column foreign key pointing to the [User] that was sent + * this entry + * @property lastActivity epoch UNIX [Long] column + * @property primaryKey primary key constraint pointing to the id property + */ +object ChatTable : Table() { + val id = long("id").autoIncrement() + val owner = long("owner_id").index() + val receiver = long("receiver_id").index() + val lastActivity = long("last_activity") + + override val primaryKey = PrimaryKey(id, name = "pk_chat_id") + + init { + uniqueIndex("owner_and_receiver", owner, receiver) + } +} + +/** + * Rooms created to facilitate the creation and retrieval of [Message] objects between [User] + * objects + * + * While chats are currently limited to two [User] objects, this can be expanded in the future to + * support groups of [User] objects. + * + * Keep in mind that all [Message] point to a given [Chat]. + * + * @property id unique [Long] assigned to each [Chat] from the database + * @property owner the ID of the [User] that started this [Chat] + * @property receiver the ID of the [User] that this [Chat] was started with + * @property lastActivity epoch UNIX [Long] representing the last interaction with this [Chat] (eg; + * creation or messages sent) + */ +@Serializable +data class Chat( + val id: Long, + val owner: Long, + val receiver: Long, + val lastActivity: Long, +) : Datamodel diff --git a/src/main/kotlin/com/daymxn/dchat/datamodel/DATAMODELS.md b/src/main/kotlin/com/daymxn/dchat/datamodel/DATAMODELS.md new file mode 100644 index 0000000..ba7db07 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/datamodel/DATAMODELS.md @@ -0,0 +1,58 @@ +# Datamodels + +Datamodels serve as the connection between the **Service Layer** and the **Database Layer**. + +A Datamodel file will have at least *two* class definitions: the `Table` class and the `Datamodel` +class. These two classes work in tangent with one another. The `Table` class serves as A schema for Exposed to apply to +the Database. The `Datamodel` class serves as a representation of what the same Database table may look like to the rest +of the code. + +For example, say we have the Database table below: + +```Kotlin +====== +User +====== +--> LONG AUTO PK [id] +--> VARCHAR UNIQUE[username] +--> VARCHAR [password] +--> BOOL [is_admin] +``` + +The way we might represent this as a schema is like so: + +```Kotlin +object UserTable : Table() { + val id = long("id").autoIncrement() + val username = varchar("username", length = 50).uniqueIndex() + val password = varchar("password", length = 50) + val isAdmin = bool("is_admin").default(false) + + override val primaryKey = PrimaryKey(id, name = "pk_user_id") +} +``` + +In turn, the way we might represent this same *database schema* to the codebase is like so: + +```Kotlin +@Serializable +data class User( + val id: Long, + val username: String, + val password: String, + val isAdmin: Boolean = false, +) : Datamodel +``` + +So in conclusion; + +`Table` - Schema (or an outline) of how the table looks in the Database. Also directly utilized at the **Service Layer** +to interact with the Database. + +`Datamodel` - Data class that defines the primary structure of the model, and how it will be represented in the rest of +the code. Used as actual instances of Database entries. + +## Migration support + +Exposed does not actually (at least at the time of this writing) have native support for migrations. This may be a +deal-breaker for some, and is something that should be explored in the future. diff --git a/src/main/kotlin/com/daymxn/dchat/datamodel/Datamodel.kt b/src/main/kotlin/com/daymxn/dchat/datamodel/Datamodel.kt new file mode 100644 index 0000000..c8d9d98 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/datamodel/Datamodel.kt @@ -0,0 +1,20 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.datamodel + +/** Parent type that encompasses all Database related models */ +interface Datamodel diff --git a/src/main/kotlin/com/daymxn/dchat/datamodel/Message.kt b/src/main/kotlin/com/daymxn/dchat/datamodel/Message.kt new file mode 100644 index 0000000..51e1dc9 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/datamodel/Message.kt @@ -0,0 +1,67 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.datamodel + +import com.daymxn.dchat.datamodel.MessageTable.chat +import com.daymxn.dchat.datamodel.MessageTable.content +import com.daymxn.dchat.datamodel.MessageTable.id +import com.daymxn.dchat.datamodel.MessageTable.primaryKey +import com.daymxn.dchat.datamodel.MessageTable.sender +import com.daymxn.dchat.datamodel.MessageTable.sentAt +import kotlinx.serialization.Serializable +import org.jetbrains.exposed.sql.Table + +/** + * Database table schema for [Message] + * + * @property id unique [Long] column index, automatically created and incremented for each entry + * @property sender **indexed** [Long] column foreign key pointing to the [User] that created the + * entry + * @property sentAt epoch UNIX [Long] column + * @property chat **indexed** [Long] column foreign key point to the [Chat] that this entry was + * created for + * @property content [String] column containing the message itself, limited to a length of 300 + * characters + * @property primaryKey primary key constraint pointing to the id property + */ +object MessageTable : Table() { + val id = long("id").autoIncrement() + val sender = long("sender_id") + val sentAt = long("sent_at") + val chat = long("chat_id").index() + val content = varchar("username", length = 300) + + override val primaryKey = PrimaryKey(id, name = "pk_message_id") +} + +/** + * Content sent in a [Chat] between [User] objects + * + * @property id unique [Long] assigned to each [Message] from the database + * @property sender the ID of the [User] that sent this [Message] + * @property sentAt epoch UNIX [Long] representing the creation date of this [Message] + * @property chat the ID of the [Chat] that this [Message] was created under + * @property content the actual message that is to be displayed to either [User] + */ +@Serializable +data class Message( + val id: Long, + val sender: Long, + val sentAt: Long, + val chat: Long, + val content: String, +) : Datamodel diff --git a/src/main/kotlin/com/daymxn/dchat/datamodel/User.kt b/src/main/kotlin/com/daymxn/dchat/datamodel/User.kt new file mode 100644 index 0000000..498efe5 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/datamodel/User.kt @@ -0,0 +1,82 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.datamodel + +import com.daymxn.dchat.datamodel.UserTable.id +import com.daymxn.dchat.datamodel.UserTable.isAdmin +import com.daymxn.dchat.datamodel.UserTable.password +import com.daymxn.dchat.datamodel.UserTable.primaryKey +import com.daymxn.dchat.datamodel.UserTable.username +import io.ktor.server.auth.* +import kotlinx.serialization.Serializable +import org.jetbrains.exposed.sql.Table + +/** + * Database table schema for [User] + * + * @property id unique [Long] column index, automatically created and incremented for each entry + * @property username unique **indexed* [String] column provided for each entry + * @property password secret [String] column provided for each entry + * @property isAdmin [Boolean] column that defaults to false + * @property primaryKey primary key constraint pointing to the id property + */ +object UserTable : Table() { + val id = long("id").autoIncrement() + val username = varchar("username", length = 50).uniqueIndex() + val password = varchar("password", length = 50) + val isAdmin = bool("is_admin").default(false) + + override val primaryKey = PrimaryKey(id, name = "pk_user_id") +} + +/** + * An authenticated end-user for the application + * + * This differs from what the client may consume when fetching other users outside of + * authentication. For such scenarios, take a look at [UserHead], + * + * @property id unique [Long] assigned to each [Chat] from the database + * @property username unique [String] created by each end-user + * @property password hashed [String] representing the secret chosen by the end-user + * @property isAdmin [Boolean] that signifies if a [User] is and administrator of the application. + * Utilized for higher privilege actions. + */ +@Serializable +data class User( + val id: Long, + val username: String, + val password: String, + val isAdmin: Boolean = false, +) : Datamodel, Principal + +/** + * [User] object retrieved from the database, with sensitive data removed + * + * Especially useful in scenarios where end-users need [User] information, but should not have + * access to sensitive data stored for each entry. + * + * @property id unique [Long] assigned to each [Chat] from the database + * @property username unique [String] created by each end-user + * @property isAdmin [Boolean] that signifies if a [User] is and administrator of the application. + * Utilized for higher privilege actions. + */ +@Serializable +data class UserHead( + val id: Long, + val username: String, + val isAdmin: Boolean, +) : Datamodel diff --git a/src/main/kotlin/com/daymxn/dchat/routes/DeleteChatRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/DeleteChatRoute.kt new file mode 100644 index 0000000..fdb7a5e --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/DeleteChatRoute.kt @@ -0,0 +1,51 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.util.RouteHandler +import com.daymxn.dchat.util.handleApplicationErrors +import com.daymxn.dchat.util.routeState +import com.daymxn.dchat.util.validationError +import io.ktor.http.* +import io.ktor.server.routing.* + +fun Route.deleteChat() { + delete(DeleteChatRoute) { deleteChatRouteHandler(routeState()) } +} + +val deleteChatRouteHandler: RouteHandler = { + handleApplicationErrors(DeleteChatResponse::class) { + validateRequest(getRequest(), getUser()).also { + DatabaseManager.deleteChat(it.user, it.chat).apply { + if (this) respond(HttpStatusCode.Accepted, DeleteChatResponse()) + else respond(HttpStatusCode.BadRequest, DeleteChatResponse("Could not delete chat")) + } + } + } +} + +private fun validateRequest(request: DeleteChatRequest, user: User?): ValidatedDeleteChatRequest = + ValidatedDeleteChatRequest(validateUser(user), validateChat(request.chat)) + +private fun validateUser(user: User?) = + user ?: validationError("You must be logged in to access this.") + +private fun validateChat(id: ULong) = id.toLong() + +private data class ValidatedDeleteChatRequest(val user: User, val chat: Long) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/GetActivityRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/GetActivityRoute.kt new file mode 100644 index 0000000..f04514b --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/GetActivityRoute.kt @@ -0,0 +1,52 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.ActivityType +import com.daymxn.dchat.util.RouteHandler +import com.daymxn.dchat.util.handleApplicationErrors +import com.daymxn.dchat.util.routeState +import io.ktor.http.* +import io.ktor.server.routing.* + +fun Route.getActivity() { + get(GetActivityRoute) { getActivityRouteHandler(routeState()) } +} + +val getActivityRouteHandler: RouteHandler = { + handleApplicationErrors(GetActivityResponse::class) { + validateRequest(getRequest()).also { + when (it.activityType) { + ActivityType.USER_LOGGED_IN -> DatabaseManager.getUsersLoggedInActivities(it.since) + ActivityType.MESSAGE_SENT -> DatabaseManager.getMessagesSentActivities(it.since) + }.apply { respond(HttpStatusCode.Accepted, GetActivityResponse(this)) } + } + } +} + +private fun validateRequest(request: GetActivityRequest): ValidatedGetActivityRequest = + ValidatedGetActivityRequest( + validateActivityType(request.activityType), + validateSince(request.since) + ) + +private fun validateActivityType(activityType: ActivityType) = activityType + +private fun validateSince(since: ULong) = since.toLong() + +private data class ValidatedGetActivityRequest(val activityType: ActivityType, val since: Long) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/GetChatsRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/GetChatsRoute.kt new file mode 100644 index 0000000..f605069 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/GetChatsRoute.kt @@ -0,0 +1,50 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.util.RouteHandler +import com.daymxn.dchat.util.handleApplicationErrors +import com.daymxn.dchat.util.routeState +import com.daymxn.dchat.util.validationError +import io.ktor.http.* +import io.ktor.server.routing.* + +fun Route.getChatsForUser() { + get(GetChatsRoute) { getChatsRouteHandler(routeState()) } +} + +val getChatsRouteHandler: RouteHandler = { + handleApplicationErrors(GetChatsResponse::class) { + validateRequest(getRequest(), getUser()).also { + DatabaseManager.getChatsForUserSince(it.user, it.since).apply { + respond(HttpStatusCode.Accepted, GetChatsResponse(this)) + } + } + } +} + +private fun validateRequest(request: GetChatsRequest, user: User?): ValidatedGetChatsRequest = + ValidatedGetChatsRequest(validateUser(user), validateSince(request.since)) + +private fun validateUser(user: User?) = + user ?: validationError("You must be logged in to access this.") + +private fun validateSince(since: ULong) = since.toLong() + +private data class ValidatedGetChatsRequest(val user: User, val since: Long) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/Headers.kt b/src/main/kotlin/com/daymxn/dchat/routes/Headers.kt new file mode 100644 index 0000000..2a3f02c --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/Headers.kt @@ -0,0 +1,92 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.datamodel.* +import kotlinx.serialization.SerialName +import kotlinx.serialization.Serializable + +sealed interface EndpointHeader + +sealed interface Request : EndpointHeader + +sealed interface Response : EndpointHeader + +sealed interface WebSocketHeader + +@Serializable sealed class WebSocketRequest : WebSocketHeader, Request + +@Serializable sealed class WebSocketResponse : WebSocketHeader, Response + +@Serializable data class LoginRequest(val username: String, val password: String) : Request + +@Serializable +data class LoginResponse(val accessToken: String? = null, val error: String? = null) : Response + +@Serializable data class RegisterRequest(val username: String, val password: String) : Request + +@Serializable +data class RegisterResponse(val accessToken: String? = null, val error: String? = null) : Response + +@Serializable +data class GetActivityRequest(val activityType: ActivityType, val since: ULong = 0u) : Request + +@Serializable +data class GetActivityResponse(val activities: List? = null, val error: String? = null) : + Response + +@Serializable data class GetChatsRequest(val since: ULong = 0u) : Request + +@Serializable +data class GetChatsResponse(val chats: List? = null, val error: String? = null) : Response + +@Serializable data class StartChatRequest(val receipt: ULong) : Request + +@Serializable +data class StartChatResponse(val chat: Chat? = null, val error: String? = null) : Response + +@Serializable data class DeleteChatRequest(val chat: ULong) : Request + +@Serializable data class DeleteChatResponse(val error: String? = null) : Response + +@Serializable +@SerialName("GetUsersForSubstringRequest") +data class GetUsersForSubstringRequest(val search: String) : WebSocketRequest() + +@Serializable +@SerialName("GetUsersForSubstringResponse") +data class GetUsersForSubstringResponse( + val users: List? = null, + val error: String? = null +) : WebSocketResponse() + +@Serializable +@SerialName("SendMessageRequest") +data class SendMessageRequest(val chat: ULong, val message: String) : WebSocketRequest() + +@Serializable +@SerialName("SendMessageResponse") +data class SendMessageResponse(val error: String? = null) : WebSocketResponse() + +@Serializable +@SerialName("GetChatHistoryRequest") +data class GetChatHistoryRequest(val chat: ULong, val since: ULong) : WebSocketRequest() + +@Serializable +@SerialName("GetChatHistoryResponse") +data class GetChatHistoryResponse(val messages: List? = null, val error: String? = null) : + WebSocketResponse() diff --git a/src/main/kotlin/com/daymxn/dchat/routes/HealthRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/HealthRoute.kt new file mode 100644 index 0000000..38fe752 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/HealthRoute.kt @@ -0,0 +1,25 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import io.ktor.server.application.* +import io.ktor.server.response.* +import io.ktor.server.routing.* + +fun Route.health() { + post(HealthRoute) { call.respondText { "Healthy!" } } +} diff --git a/src/main/kotlin/com/daymxn/dchat/routes/LoginRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/LoginRoute.kt new file mode 100644 index 0000000..6bb7318 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/LoginRoute.kt @@ -0,0 +1,54 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.util.* +import io.ktor.http.* +import io.ktor.server.routing.* + +fun Route.login() { + post(LoginRoute) { loginRouteHandler(routeState()) } +} + +val loginRouteHandler: RouteHandler = { + handleApplicationErrors(LoginResponse::class) { + validateRequest(getRequest()).also { + DatabaseManager.validateUser(it.user).apply { + respond(HttpStatusCode.Accepted, LoginResponse(JWTManager.createToken(this))) + } + } + } +} + +private fun validateRequest(request: LoginRequest): ValidatedLoginRequest = + ValidatedLoginRequest( + User( + -1, + validateUsername(request.username), + JWTManager.hashPassword(validatePassword(request.password)) + ) + ) + +private fun validateUsername(username: String) = + username.takeIf { it.isNotBlank() } ?: validationError("Username is a required field") + +private fun validatePassword(password: String) = + password.takeIf { it.isNotBlank() } ?: validationError("Password is a required field") + +private data class ValidatedLoginRequest(val user: User) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/ROUTES.md b/src/main/kotlin/com/daymxn/dchat/routes/ROUTES.md new file mode 100644 index 0000000..8cfa7be --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/ROUTES.md @@ -0,0 +1,127 @@ +# Routes + +Routes are the core of dChat, they provide the majority of the business logic consumed throughout the application. +Routes live slightly adjacent to the **Service Layer** (as interactions with the service layer are actually facilitated +through the `DatabaseManager`), and are directly consumed by the **API Layer**. + +## Lifecycle + +Routes are initially consumed via the **API Layer**, more specifically through the +`Application.configureRouting()` module. This module also handles the *initial* +authentication for protected directories. Although, this does **not** mean verification should not also be handled by +the Route. You'll see some routes also performing their own checks for user authentication. The general methodology is; +if you need access to the +`User` session object, you should verify it's existence. Especially in a kotlin world, where we want to avoid any sort +of edge-case issues with nullability. + +Routes define their endpoint definitions (the URL that gets exposed via HTTP) through the +`Routes.kt` file. + +Routes then define their headers in the `Headers.kt` file. A route header refers to a data object that represents how an +acceptable request should be structured, and how responses from the Route will look as well. + +Finally, a file is created for the core logic of the route, such as; `RegisterRoute.kt` or +`LoginRoute.kt` + +To see a more definitive example, continue reading below. + +## Designing Routes + +Below, I'll walk you through the general thought process you should have when designing a new, or modifying an existing +Route. + +### Route endpoints + +Route endpoints live under the `routes/Routes.kt` file. + +Route endpoints should be labeled in **P**ascal**C**ase, regardless of the fact that they are constant values. + +Route endpoints should also try to minimize non-variable string literals. For example; + +Prefer this: + +```Kotlin +const val HelpRoute = "/help" +const val HelpTicketRoute = "$HelpRoute/ticket" +``` + +Over this: + +```Kotlin +const val HelpRoute = "/help" +const val HelpTicketRoute = "/help/ticket" +``` + +### Route headers + +Route headers live under the `routes/Headers.kt` file. + +Header Requests should describe, in the most strict sense, what is an acceptable request. For example, that may mean +using `ULong` in place of `Long` whenever the variable should never be less than zero. + +Header Responses should describe what a Response from the server might look like. All variables must be nullable and +default to null- as this allows our error handling utility method to automagically generate responses. Furthermore, +every Response should **at-least** define an error property. It is not required that a Response have a unique return +property- but it must always have an error property. + +### Route definitions + +Route logic follows a two path system; + +- Verify the request +- Handle the request + +That usually follows the principle of implementing a "verified" version of the Request object. Those familiar with +standard functional Scala principles will feel right at home with this. + +Once the request has been verified, its common to then interact with the `DatabaseManager`, and submit queries for the +data needed (or action being performed). + +A standard Route may look a little something like this: + +```Kotlin +fun Route.login() { + post(LoginRoute) { + loginRouteHandler(routeState()) + } +} + +val loginRouteHandler: RouteHandler = { + handleApplicationErrors(LoginResponse::class) { + validateRequest(getRequest()).also { + DatabaseManager.validateUser(it.user).apply { + respond( + HttpStatusCode.Accepted, + LoginResponse(JWTManager.createToken(this)) + ) + } + } + } +} + +private fun validateRequest(request: LoginRequest) = + ValidatedLoginRequest( + validateUsername(request.username), + validatePassword(request.password) + ) + +private fun validateUsername(username: String) = + username.takeIf { it.isNotBlank() } ?: validationError("Username is a required field") + +private fun validatePassword(password: String) = + password.takeIf { it.isNotBlank() } ?: validationError("Password is a required field") + +private data class ValidatedLoginRequest(val user: User) +``` + +A couple key things to note; + +- We extend KTOR's `Route` class to connect the **API Layer** with our route handler +- We define how our route will be exposed, by referencing the route endpoint through `post(LoginRoute)` +- We create a `RouteHandler`, which is just a method that get called with a `RouteState` object, and handles the logic + for the actual Route +- We wrap all of our logic in a `handleApplicationErrors` call where we specify what our response object will + be; `LoginResponse::class` +- We validate the request, and throw an error via `validationError()` when something goes wrong +- We respond to the request with an `HttpStatusCode` and an instance of the Response object for the request, containing + the data the user requested diff --git a/src/main/kotlin/com/daymxn/dchat/routes/RegisterRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/RegisterRoute.kt new file mode 100644 index 0000000..dbe802b --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/RegisterRoute.kt @@ -0,0 +1,54 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.util.* +import io.ktor.http.* +import io.ktor.server.routing.* + +fun Route.register() { + post(RegisterRoute) { registerRouteHandler(routeState()) } +} + +val registerRouteHandler: RouteHandler = { + handleApplicationErrors(RegisterResponse::class) { + validateRequest(getRequest()).also { + DatabaseManager.createUser(it.user).apply { + respond(HttpStatusCode.Created, RegisterResponse(JWTManager.createToken(this))) + } + } + } +} + +private fun validateRequest(request: RegisterRequest): ValidatedRegisterRequest = + ValidatedRegisterRequest( + User( + -1, + validateUsername(request.username), + JWTManager.hashPassword(validatePassword(request.password)) + ) + ) + +private fun validateUsername(username: String) = + username.takeIf { it.isNotBlank() } ?: validationError("Username is a required field") + +private fun validatePassword(password: String) = + password.takeIf { it.isNotBlank() } ?: validationError("Password is a required field") + +private data class ValidatedRegisterRequest(val user: User) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/Routes.kt b/src/main/kotlin/com/daymxn/dchat/routes/Routes.kt new file mode 100644 index 0000000..d146eae --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/Routes.kt @@ -0,0 +1,39 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.util.ApplicationConfig + +const val COMMON_ROUTE = "/${ApplicationConfig.API.endpoint}/${ApplicationConfig.API.version}" + +const val COMMON_DASHBOARD = "$COMMON_ROUTE/dashboard" + +const val LoginRoute = "$COMMON_ROUTE/login" + +const val RegisterRoute = "$COMMON_ROUTE/register" + +const val HealthRoute = "$COMMON_ROUTE/health" + +const val GetActivityRoute = "$COMMON_DASHBOARD/getActivity" + +const val GetChatsRoute = "$COMMON_DASHBOARD/getChats" + +const val StartChatRoute = "$COMMON_DASHBOARD/startChat" + +const val DeleteChatRoute = "$COMMON_DASHBOARD/deleteChat" + +const val WebSocketMainRoute = "$COMMON_DASHBOARD/ws" diff --git a/src/main/kotlin/com/daymxn/dchat/routes/StartChatRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/StartChatRoute.kt new file mode 100644 index 0000000..6c6779e --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/StartChatRoute.kt @@ -0,0 +1,55 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.util.RouteHandler +import com.daymxn.dchat.util.handleApplicationErrors +import com.daymxn.dchat.util.routeState +import com.daymxn.dchat.util.validationError +import io.ktor.http.* +import io.ktor.server.routing.* + +fun Route.startChat() { + post(StartChatRoute) { startChatRouteHandler(routeState()) } +} + +val startChatRouteHandler: RouteHandler = { + handleApplicationErrors(StartChatResponse::class) { + validateRequest(getRequest(), getUser()).also { + DatabaseManager.startChatForUserWith(it.user, it.receipt).apply { + respond(HttpStatusCode.Accepted, StartChatResponse(this)) + } + } + } +} + +private fun validateRequest(request: StartChatRequest, user: User?): ValidatedStartChatRequest = + ValidatedStartChatRequest(validateUser(user), validateReceipt(request.receipt)).also { + validateNotSelf(it.user, it.receipt) + } + +private fun validateNotSelf(user: User, receiver: Long) = + user.takeIf { it.id != receiver } ?: validationError("You can not start a chat with yourself.") + +private fun validateUser(user: User?) = + user ?: validationError("You must be logged in to access this.") + +private fun validateReceipt(id: ULong) = id.toLong() + +private data class ValidatedStartChatRequest(val user: User, val receipt: Long) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRoute.kt new file mode 100644 index 0000000..906d659 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRoute.kt @@ -0,0 +1,53 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes.websockets + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.routes.GetChatHistoryRequest +import com.daymxn.dchat.routes.GetChatHistoryResponse +import com.daymxn.dchat.util.WebSocketConnection +import com.daymxn.dchat.util.validationError + +suspend fun WebSocketConnection.getChatHistoryRoute(request: GetChatHistoryRequest) { + validateRequest(request, user).also { validatedRequest -> + validateUserIsAPartOfChat(validatedRequest.chat, user).also { + DatabaseManager.getMessagesForChatSince(validatedRequest.chat, validatedRequest.since).also { + session.sendMessage(GetChatHistoryResponse(it)) + } + } + } +} + +private suspend fun validateUserIsAPartOfChat(chat: Long, user: User) { + DatabaseManager.getChatById(chat).also { + if (it.owner != user.id && it.receiver != user.id) + validationError("You are not apart of this chat") + } +} + +private fun validateRequest( + request: GetChatHistoryRequest, + user: User +): ValidatedGetChatHistoryRequest = + ValidatedGetChatHistoryRequest(validateChat(request.chat), validateSince(request.since)) + +private fun validateChat(chat: ULong): Long = chat.toLong() + +private fun validateSince(since: ULong): Long = since.toLong() + +private data class ValidatedGetChatHistoryRequest(val chat: Long, val since: Long) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRoute.kt new file mode 100644 index 0000000..d8d5287 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRoute.kt @@ -0,0 +1,44 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes.websockets + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.routes.GetUsersForSubstringRequest +import com.daymxn.dchat.routes.GetUsersForSubstringResponse +import com.daymxn.dchat.util.WebSocketConnection +import com.daymxn.dchat.util.validationError + +suspend fun WebSocketConnection.getUsersForSubstringRoute(request: GetUsersForSubstringRequest) { + validateRequest(request).also { validatedRequest -> + DatabaseManager.getUsersForSubstring(validatedRequest.search).also { + session.sendMessage(GetUsersForSubstringResponse(it)) + } + } +} + +private fun validateRequest( + request: GetUsersForSubstringRequest +): ValidatedGetUsersForSubstringRequest = + ValidatedGetUsersForSubstringRequest(validateSearch(request.search)) + +private fun validateSearch(search: String): String = + search.filter { it.isLetterOrDigit() }.also { + if (it.length < 3) + validationError("Search query can not be less than 3 alphanumeric characters.") + } + +private data class ValidatedGetUsersForSubstringRequest(val search: String) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRoute.kt new file mode 100644 index 0000000..858e6f7 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRoute.kt @@ -0,0 +1,66 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes.websockets + +import com.daymxn.dchat.DatabaseManager +import com.daymxn.dchat.datamodel.Chat +import com.daymxn.dchat.datamodel.Message +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.routes.SendMessageRequest +import com.daymxn.dchat.routes.SendMessageResponse +import com.daymxn.dchat.util.WebSocketConnection +import com.daymxn.dchat.util.WebSocketConnectionManager +import com.daymxn.dchat.util.validationError +import io.ktor.util.date.* + +suspend fun WebSocketConnection.sendMessageRoute(request: SendMessageRequest) { + validateRequest(request, user).also { validatedRequest -> + validateUserIsAPartOfChat(validatedRequest.message.chat, user).also { validatedChat -> + DatabaseManager.createMessage(validatedRequest.message).also { + session.sendMessage(SendMessageResponse()) + WebSocketConnectionManager.notifyClient(whichClientIsNotMe(validatedChat, user.id), request) + } + } + } +} + +private fun whichClientIsNotMe(chat: Chat, user: Long): Long = + if (chat.owner == user) chat.receiver else chat.owner + +private suspend fun validateUserIsAPartOfChat(chat: Long, user: User) = + DatabaseManager.getChatById(chat).also { + if (it.owner != user.id && it.receiver != user.id) + validationError("You are not apart of this chat") + } + +private fun validateRequest(request: SendMessageRequest, user: User): ValidatedSendMessageRequest = + ValidatedSendMessageRequest( + Message( + -1, + user.id, + getTimeMillis(), + validateChat(request.chat), + validateMessage(request.message) + ) + ) + +private fun validateChat(chat: ULong): Long = chat.toLong() + +private fun validateMessage(message: String): String = + message.ifBlank { validationError("Message can not be blank") } + +private data class ValidatedSendMessageRequest(val message: Message) diff --git a/src/main/kotlin/com/daymxn/dchat/routes/websockets/WEBSOCKETS.md b/src/main/kotlin/com/daymxn/dchat/routes/websockets/WEBSOCKETS.md new file mode 100644 index 0000000..5d876bf --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/websockets/WEBSOCKETS.md @@ -0,0 +1,88 @@ +# WebSockets + +WebSockets are technically a variant of Routes, and as such; are *very* similar in the way they are structured. The +biggest difference is that we at dChat actually control most of the lifecycle with WebSockets, versus with Routes where +KTOR handles the vast majority of the lifecycle. This *does* give us some freedom, but also means we have to structure +some things a bit differently. + +## Lifecycle + +> Note: This document assumes you have also read the `ROUTES.md` document, and will focus a bit more on the differences between WebSockets and Routes + +One of the more key things to note, is that WebSockets don't technically have an endpoint definition. So you won't +actually see any endpoints in `Routes.kt` for WebSockets. That's because of the way WebSockets are consumed. The user +initially connects to the `WebSocketMain` +route, and then send *messages* through the WebSocket, versus HTTP Request to the server. So then, how do we define what +that message *is* then? + +Through the `@SerialName` annotation! WebSocket headers are defined alongside Route headers in +`Headers.kt` and follow the same pattern. You'll notice though, that they have an additional annotation on them. + +```Kotlin +@Serializable +data class LoginRequest(val username: String, val password: String) : Request + +@Serializable +@SerialName("SendMessageRequest") +data class SendMessageRequest(val chat: ULong, val message: String) : WebSocketRequest() +``` + +This annotation allows us to define how the data class is translated through the WebSocket. The client can then create +an identical message (request) object to send through the WebSocket themselves. The typical pattern is to just annotate +the data class objects with the same name as their class names. + +Beyond that, Routes define their core logic the same as Routes, except that the file now lives under `routes/websockets` +instead of just `routes/`. There are *some* differences as far as how handlers are defined in WebSockets, but more on +that below. + +## Designing WebSockets + +Below, I'll walk you through the general thought process you should have when designing a new, or modifying an existing +WebSocket. + +### WebSocket endpoints + +WebSocket endpoints are defined alongside their headers in `Headers.kt`. They are exposed via the +`@SerialName()` annotation, and should be labeled the same as their class name. + +Endpoints should also not be nested, and so utilizing constant variables is not needed. + +### WebSocket headers + +WebSocket headers live under the `routes/Headers.kt` file. + +Header Requests and Responses should follow the same principle of standard Routes. + +### WebSocket definitions + +The only difference between WebSocket definitions and Route definitions, is the absence of a named Route handler +and `RouteState`. + +A standard WebSocket may look a little something like this: + +```Kotlin +suspend fun WebSocketConnection.getUsersForSubstringRoute(request: GetUsersForSubstringRequest) { + validateRequest(request).also { validatedRequest -> + DatabaseManager.getUsersForSubstring(validatedRequest.search).also { + session.sendMessage(GetUsersForSubstringResponse(it)) + } + } +} + +private fun validateRequest(request: GetUsersForSubstringRequest): ValidatedGetUsersForSubstringRequest = + ValidatedGetUsersForSubstringRequest(validateSearch(request.search)) + +private fun validateSearch(search: String): String = search.filter { it.isLetterOrDigit() }.also { + if (it.length < 3) validationError("Search query can not be less than 3 alphanumeric characters.") +} + +private data class ValidatedGetUsersForSubstringRequest(val search: String) +``` + +A couple key things to note; + +- WebSockets are extended through `WebSocketConnection`, and are natively wrapped in an error handler +- Inplace of a `RouteState`, WebSockets have a `WebSocketSession` object that facilitates various serializations +- WebSockets live directly under the extension, and are not split off into their own "handler" variable (like your + standard Route and `RouteHandler`) +- WebSocket responses do **not** have a status code diff --git a/src/main/kotlin/com/daymxn/dchat/routes/websockets/WebSocketMainRoute.kt b/src/main/kotlin/com/daymxn/dchat/routes/websockets/WebSocketMainRoute.kt new file mode 100644 index 0000000..398696d --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/routes/websockets/WebSocketMainRoute.kt @@ -0,0 +1,41 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes.websockets + +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.routes.WebSocketMainRoute +import com.daymxn.dchat.util.WebSocketConnectionManager +import io.ktor.http.* +import io.ktor.server.application.* +import io.ktor.server.auth.* +import io.ktor.server.response.* +import io.ktor.server.routing.* +import io.ktor.server.websocket.* + +fun Route.webSocketMain() { + webSocket(WebSocketMainRoute) { + val user = fetchUser(call) ?: return@webSocket + + WebSocketConnectionManager.keepSession(this, user).eventLoop() + } +} + +private suspend fun fetchUser(call: ApplicationCall): User? { + return call.principal().apply { + if (this == null) call.respond(HttpStatusCode.Unauthorized) // this shouldn't happen anyways + } +} diff --git a/src/main/kotlin/com/daymxn/dchat/service/ActivityService.kt b/src/main/kotlin/com/daymxn/dchat/service/ActivityService.kt new file mode 100644 index 0000000..15daa90 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/service/ActivityService.kt @@ -0,0 +1,126 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.service + +import com.daymxn.dchat.datamodel.Activity +import com.daymxn.dchat.datamodel.ActivityTable +import com.daymxn.dchat.datamodel.ActivityType +import com.daymxn.dchat.util.NotCurrentlyInUse +import com.daymxn.dchat.util.newQuery +import org.jetbrains.exposed.sql.* +import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction + +/** Static service provider that facilitates communication with [ActivityTable] */ +object ActivityService { + + /** + * Fetches all [Activity] from the database + * + * @return a [List] of all the [Activity] found + */ + @NotCurrentlyInUse + suspend fun getAll(): List = newSuspendedTransaction { + ActivityTable.selectAll().mapNotNull { it.toActivity() } + } + + /** + * Fetches an [Activity] from the database, by the ID + * + * @param id the ID to fetch an [Activity] for + * + * @return a [Result] of either the [Activity] if found, null if not found, or failed if an + * exception occurred + */ + @NotCurrentlyInUse + suspend fun getById(id: Long): Result = newQuery { + ActivityTable.select { ActivityTable.id eq id }.firstNotNullOfOrNull { it.toActivity() } + } + + /** + * Fetches all [Activity] from the database that match an [ActivityType] and are younger than a + * specified UNIX timestamp. + * + * @param type the [ActivityType] to filter for + * @param since a UNIX timestamp specifying the oldest [Activity] to fetch + * + * @return a list [Activity] that match the specified filters + */ + suspend fun getByTypeAndAfter(type: ActivityType, since: Long): List = + newSuspendedTransaction { + ActivityTable.select { + ActivityTable.type eq type + ActivityTable.timestamp greaterEq since + } + .mapNotNull { it.toActivity() } + } + + /** + * Fetches all [Activity] from the database that were created by a specified user + * + * @param owner ID of the user to filter for + * + * @return a list of [Activity] that were created by the specified owner + */ + @NotCurrentlyInUse + suspend fun getByOwner(owner: Long): List = newSuspendedTransaction { + ActivityTable.select { ActivityTable.owner eq owner }.mapNotNull { it.toActivity() } + } + + /** + * Updates an [Activity] in the database with new data + * + * @param activity the new object to update with + * + * @return whether the update was successful or not + */ + @NotCurrentlyInUse + suspend fun update(activity: Activity): Boolean = + newSuspendedTransaction { + ActivityTable.update({ ActivityTable.id eq activity.id }) { + it[owner] = activity.owner + it[type] = activity.type + it[timestamp] = activity.timestamp + } + } == 1 + + /** + * Inserts an [Activity] into the database + * + * @param activity the new object to insert + * + * @return a [Result] of either the new [Activity] if successful, null if something went wrong, or + * failed if an exception occurred + */ + suspend fun insert(activity: Activity): Result = newQuery { + ActivityTable.insert { + it[owner] = activity.owner + it[type] = activity.type + it[timestamp] = activity.timestamp + } + .resultedValues + ?.firstNotNullOfOrNull { it.toActivity() } + } + + /** Helper method to convert a retrieved [ResultRow] from the database to an [Activity] */ + private fun ResultRow.toActivity(): Activity = + Activity( + id = this[ActivityTable.id], + owner = this[ActivityTable.owner], + type = this[ActivityTable.type], + timestamp = this[ActivityTable.timestamp] + ) +} diff --git a/src/main/kotlin/com/daymxn/dchat/service/ChatService.kt b/src/main/kotlin/com/daymxn/dchat/service/ChatService.kt new file mode 100644 index 0000000..812aba8 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/service/ChatService.kt @@ -0,0 +1,162 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.service + +import com.daymxn.dchat.datamodel.Chat +import com.daymxn.dchat.datamodel.ChatTable +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.util.NotCurrentlyInUse +import com.daymxn.dchat.util.newQuery +import org.jetbrains.exposed.sql.* +import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction + +/** Static service provider that facilitates communication with [ChatTable] */ +object ChatService { + + /** + * Fetches all [Chat] from the database + * + * @return a [List] of all the [Chat] found + */ + @NotCurrentlyInUse + suspend fun getAll(): List = newSuspendedTransaction { + ChatTable.selectAll().mapNotNull { it.toChat() } + } + + /** + * Fetches a [Chat] from the database, by the ID + * + * @param id the ID to fetch a [Chat] for + * + * @return a [Result] of either the [Chat] if found, null if not found, or failed if an exception + * occurred + */ + @NotCurrentlyInUse + suspend fun getById(id: Long): Result = newQuery { + ChatTable.select { ChatTable.id eq id }.firstNotNullOfOrNull { it.toChat() } + } + + /** + * Fetches all [Chat] from the database that are used by a specified [User] and are younger than a + * specified UNIX timestamp. + * + * @param id the ID of the [User] to filter for + * @param since a UNIX timestamp specifying the oldest [Chat] to fetch + * + * @return a list [Chat] that match the specified filters + */ + suspend fun getByUserAndAfter(id: Long, since: Long): List = newSuspendedTransaction { + ChatTable.select { + (ChatTable.owner eq id) or (ChatTable.receiver eq id) + ChatTable.lastActivity greaterEq since + } + .mapNotNull { it.toChat() } + } + + /** + * Fetches all [Chat] from the database that were **created** by a specified [User] and are + * younger than a specified UNIX timestamp. + * + * @param owner the ID of the [User] to filter for + * @param since a UNIX timestamp specifying the oldest [Chat] to fetch + * + * @return a list [Chat] that match the specified filters + */ + @NotCurrentlyInUse + suspend fun getByOwnerAndAfter(owner: Long, since: Long): List = newSuspendedTransaction { + ChatTable.select { + ChatTable.owner eq owner + ChatTable.lastActivity greaterEq since + } + .mapNotNull { it.toChat() } + } + + /** + * Fetches all [Chat] from the database that were created by a specified user + * + * @param owner ID of the user to filter for + * + * @return a list of [Chat] that were created by the specified owner + */ + @NotCurrentlyInUse + suspend fun getByOwner(owner: Long): List = newSuspendedTransaction { + ChatTable.select { ChatTable.owner eq owner }.mapNotNull { it.toChat() } + } + + /** + * Removes a [Chat] from the database, first validating that the specified [User] is a part of the + * [Chat] + * + * Moving this to the service layer allows us to make the filter a part of the SQL query, which is + * much faster. + * + * @param user ID of the user to validate against + * @param id ID of the chat to remove + * + * @return whether the removal was successful or not + */ + suspend fun deleteIfUserApartOf(user: Long, id: Long): Boolean = newSuspendedTransaction { + ChatTable.deleteWhere { + (ChatTable.owner eq user) or (ChatTable.receiver eq user) + ChatTable.id eq id + } == 1 + } + + /** + * Updates a [Chat] in the database with new data + * + * @param chat the new object to update with + * + * @return whether the update was successful or not + */ + @NotCurrentlyInUse + suspend fun update(chat: Chat): Boolean = + newSuspendedTransaction { + ChatTable.update({ ChatTable.id eq chat.id }) { + it[owner] = chat.owner + it[receiver] = chat.receiver + it[lastActivity] = chat.lastActivity + } + } == 1 + + /** + * Inserts a [Chat] into the database + * + * @param chat the new object to insert + * + * @return a [Result] of either the new [Chat] if successful, null if something went wrong, or + * failed if an exception occurred + */ + suspend fun insert(chat: Chat): Result = newQuery { + ChatTable.insert { + it[owner] = chat.owner + it[receiver] = chat.receiver + it[lastActivity] = chat.lastActivity + } + .resultedValues + ?.firstNotNullOfOrNull { it.toChat() } + } + + /** Helper method to convert a retrieved [ResultRow] from the database to a [Chat] */ + private fun ResultRow.toChat(): Chat = + Chat( + id = this[ChatTable.id], + owner = this[ChatTable.owner], + receiver = this[ChatTable.receiver], + lastActivity = this[ChatTable.lastActivity] + ) +} diff --git a/src/main/kotlin/com/daymxn/dchat/service/MessageService.kt b/src/main/kotlin/com/daymxn/dchat/service/MessageService.kt new file mode 100644 index 0000000..2935f32 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/service/MessageService.kt @@ -0,0 +1,123 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.service + +import com.daymxn.dchat.datamodel.Chat +import com.daymxn.dchat.datamodel.Message +import com.daymxn.dchat.datamodel.MessageTable +import com.daymxn.dchat.util.NotCurrentlyInUse +import com.daymxn.dchat.util.newQuery +import org.jetbrains.exposed.sql.* +import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction + +/** Static service provider that facilitates communication with [MessageTable] */ +object MessageService { + + /** + * Fetches all [Message] from the database + * + * @return a [List] of all the [Message] found + */ + @NotCurrentlyInUse + suspend fun getAll(): List = newSuspendedTransaction { + MessageTable.selectAll().mapNotNull { it.toMessage() } + } + + /** + * Fetches a [Message] from the database, by the ID + * + * @param id the ID to fetch a [Message] for + * + * @return a [Result] of either the [Message] if found, null if not found, or failed if an + * exception occurred + */ + @NotCurrentlyInUse + suspend fun getById(id: Long): Result = newQuery { + MessageTable.select { MessageTable.id eq id }.firstNotNullOfOrNull { it.toMessage() } + } + + /** + * Fetches all [Message] from the database that are used by a specified [Chat] and are younger + * than a specified UNIX timestamp. + * + * @param chat the ID of the [Chat] to filter for + * @param since a UNIX timestamp specifying the oldest [Message] to fetch + * + * @return a list [Message] that match the specified filters + */ + suspend fun getByChatAndAfter(chat: Long, since: Long): List = newSuspendedTransaction { + MessageTable.select { + MessageTable.chat eq chat + MessageTable.sentAt greaterEq since + } + .mapNotNull { it.toMessage() } + } + + /** + * Removes a [Message] from the database + * + * @param id ID of the message to remove + * + * @return whether the removal was successful or not + */ + @NotCurrentlyInUse + suspend fun delete(id: Long): Boolean = newSuspendedTransaction { + MessageTable.deleteWhere { MessageTable.id eq id } == 1 + } + + /** + * Updates a [Message] in the database with new data + * + * @param message the new object to update with + * + * @return whether the update was successful or not + */ + @NotCurrentlyInUse + suspend fun update(message: Message): Boolean = + newSuspendedTransaction { + MessageTable.update({ MessageTable.id eq message.id }) { it[content] = message.content } + } == 1 + + /** + * Inserts a [Message] into the database + * + * @param message the new object to insert + * + * @return a [Result] of either the new [Message] if successful, null if something went wrong, or + * failed if an exception occurred + */ + suspend fun insert(message: Message): Result = newQuery { + MessageTable.insert { + it[sender] = message.sender + it[sentAt] = message.sentAt + it[chat] = message.chat + it[content] = message.content + } + .resultedValues + ?.firstNotNullOfOrNull { it.toMessage() } + } + + /** Helper method to convert a retrieved [ResultRow] from the database to a [Message] */ + private fun ResultRow.toMessage(): Message = + Message( + id = this[MessageTable.id], + sender = this[MessageTable.sender], + sentAt = this[MessageTable.sentAt], + chat = this[MessageTable.chat], + content = this[MessageTable.content] + ) +} diff --git a/src/main/kotlin/com/daymxn/dchat/service/SERVICES.md b/src/main/kotlin/com/daymxn/dchat/service/SERVICES.md new file mode 100644 index 0000000..921e3d6 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/service/SERVICES.md @@ -0,0 +1,80 @@ +# Services + +The **Service Layer** sits between the **Business Layer** (or routes) and the **Database Layer**. + +The main job of a Service is to expose short and simple type friendly methods for interacting with any given +Database `table` class defined in the `datamodel` directory. + +## Designing a service + +A Service is defined for each Database `table` that needs to be interacted with. All service interaction will be through +the `DatabaseManager` class, and as such; should not represent business logic. A Service function should be simple, +short, and non-specific. There *are* exceptions to that last rule though- and that would be when a more specific query +would improve processing times by a significant amount. + +A standard Service may look a little something like this: + +```Kotlin +object UserService { + + suspend fun getAll(): List = newSuspendedTransaction { + UserTable.selectAll().mapNotNull { + it.toUser() + } + } + + suspend fun getById(id: Long): Result = newQuery { + UserTable.select { + UserTable.id eq id + }.firstNotNullOfOrNull { + it.toUser() + } + } + + suspend fun getByUsernameLike(str: String): List = newSuspendedTransaction { + UserTable.select { + UserTable.username like "%$str%" + }.mapNotNull { + it.toUser() + } + } + + suspend fun getByUsername(username: String): Result = newQuery { + UserTable.select { + UserTable.username eq username + }.firstNotNullOfOrNull { + it.toUser() + } + } + + suspend fun update(user: User): Boolean = newSuspendedTransaction { + UserTable.update({ UserTable.id eq user.id }) { + it[username] = user.username + it[password] = user.password + } + } == 1 + + suspend fun insert(user: User): Result = newQuery { + UserTable.insert { + it[username] = user.username + it[password] = user.password + }.resultedValues?.firstNotNullOfOrNull { + it.toUser() + } + } + + private fun ResultRow.toUser(): User = User(id = this[UserTable.id], + username = this[UserTable.username], + password = this[UserTable.password], + isAdmin = this[UserTable.isAdmin]) +} +``` + +A couple key things to note; + +- When a response is a single object, we wrap it in a nullable result and use `newQuery` instead + of `newSuspendedTransaction` +- Since Database results come in a `ResultRow`, we create a private extension method to convert the results into a + Datamodel object (in this case, `ResultRow.toUser()`) +- Database queries are made through the `table` object from the `datamodel` subdirectory. We utilize exposed as our ORM + framework, so you can read their documentation to get a better idea of how queries are structured diff --git a/src/main/kotlin/com/daymxn/dchat/service/UserService.kt b/src/main/kotlin/com/daymxn/dchat/service/UserService.kt new file mode 100644 index 0000000..9bfd2e8 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/service/UserService.kt @@ -0,0 +1,119 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.service + +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.datamodel.UserTable +import com.daymxn.dchat.util.NotCurrentlyInUse +import com.daymxn.dchat.util.newQuery +import org.jetbrains.exposed.sql.* +import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction + +/** Static service provider that facilitates communication with [UserTable] */ +object UserService { + + /** + * Fetches all [User] from the database + * + * @return a [List] of all the [User] found + */ + suspend fun getAll(): List = newSuspendedTransaction { + UserTable.selectAll().mapNotNull { it.toUser() } + } + + /** + * Fetches a [User] from the database, by the ID + * + * @param id the ID to fetch a [User] for + * + * @return a [Result] of either the [User] if found, null if not found, or failed if an exception + * occurred + */ + suspend fun getById(id: Long): Result = newQuery { + UserTable.select { UserTable.id eq id }.firstNotNullOfOrNull { it.toUser() } + } + + /** + * Fetches all [User] from the database whose username contains a specified [String] + * + * This lives in the Service layer as to mitigate the complications that would arise out of + * fetching the entire [User] database for each search + * + * @param str a [String] to filter usernames against + * + * @return a list [User] that match the specified filters + */ + suspend fun getByUsernameLike(str: String): List = newSuspendedTransaction { + UserTable.select { UserTable.username like "%$str%" }.mapNotNull { it.toUser() } + } + + /** + * Fetches a [User] from the database, by the username + * + * Primarily utilized in authentication. + * + * @param username the ID to fetch a [User] for + * + * @return a [Result] of either the [User] if found, null if not found, or failed if an exception + * occurred + */ + suspend fun getByUsername(username: String): Result = newQuery { + UserTable.select { UserTable.username eq username }.firstNotNullOfOrNull { it.toUser() } + } + + /** + * Updates a [User] in the database with new data + * + * @param user the new object to update with + * + * @return whether the update was successful or not + */ + @NotCurrentlyInUse + suspend fun update(user: User): Boolean = + newSuspendedTransaction { + UserTable.update({ UserTable.id eq user.id }) { + it[username] = user.username + it[password] = user.password + } + } == 1 + + /** + * Inserts a [User] into the database + * + * @param user the new object to insert + * + * @return a [Result] of either the new [User] if successful, null if something went wrong, or + * failed if an exception occurred + */ + suspend fun insert(user: User): Result = newQuery { + UserTable.insert { + it[username] = user.username + it[password] = user.password + } + .resultedValues + ?.firstNotNullOfOrNull { it.toUser() } + } + + /** Helper method to convert a retrieved [ResultRow] from the database to a [User] */ + private fun ResultRow.toUser(): User = + User( + id = this[UserTable.id], + username = this[UserTable.username], + password = this[UserTable.password], + isAdmin = this[UserTable.isAdmin] + ) +} diff --git a/src/main/kotlin/com/daymxn/dchat/util/Annotations.kt b/src/main/kotlin/com/daymxn/dchat/util/Annotations.kt new file mode 100644 index 0000000..a4f4f5c --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/Annotations.kt @@ -0,0 +1,23 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +/** + * Annotation for API features that are not currently in use, but are practical enough that + * providing support now for future endeavors is a non-issue. + */ +@MustBeDocumented @Suppress("UNUSED_PARAMETER") annotation class NotCurrentlyInUse diff --git a/src/main/kotlin/com/daymxn/dchat/util/ApplicationConfig.kt b/src/main/kotlin/com/daymxn/dchat/util/ApplicationConfig.kt new file mode 100644 index 0000000..1475417 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/ApplicationConfig.kt @@ -0,0 +1,43 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +object ApplicationConfig { + object API { + const val version = "v1" + const val endpoint = "api" + } + + object Database { + const val jdbcUrl = "jdbc:mysql://localhost:3306/chat_backend" + const val driverClassName = "com.mysql.cj.jdbc.Driver" + const val username = "wgu" + const val password = "" + const val maximumPoolSize = 3 + } + + object Keys { + const val secret = "69" + } + + object JWT { + const val secret = "secret" + const val issuer = "http://0.0.0.0:8080" + const val audience = "http://0.0.0.0:8080/dashboard" + const val tokenDuration = 3600000 * 24 // 24 hours + } +} diff --git a/src/main/kotlin/com/daymxn/dchat/util/ApplicationError.kt b/src/main/kotlin/com/daymxn/dchat/util/ApplicationError.kt new file mode 100644 index 0000000..b7b89de --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/ApplicationError.kt @@ -0,0 +1,160 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.daymxn.dchat.routes.Response +import com.daymxn.dchat.routes.WebSocketResponse +import io.ktor.http.* +import io.ktor.server.application.* +import io.ktor.server.response.* +import io.ktor.util.pipeline.* +import kotlinx.coroutines.channels.ClosedReceiveChannelException +import kotlinx.serialization.SerializationException +import kotlin.reflect.KClass +import kotlin.reflect.full.findParameterByName +import kotlin.reflect.full.primaryConstructor + +/** + * Exception type that encompasses all Application specific errors for this project + * + * @property errorMessage a message describing the error + */ +data class ApplicationError(val errorMessage: String) : Throwable(errorMessage) + +/** + * Helper method to convert a [DatabaseError] to an [ApplicationError] + * + * @param errorMessage optional message to override with + * + * @return a newly created [ApplicationError] + */ +fun DatabaseError.toApplicationError(errorMessage: String = this.errorMessage): ApplicationError = + when (this) { + is ColumnAlreadyExists -> ApplicationError(errorMessage) + is UnknownDatabaseError -> ApplicationError("Internal database error") + } + +/** + * Helper method to convert a [Throwable] to an [ApplicationError] + * + * @param errorMessage optional message to override with + * + * @return a newly created [ApplicationError] + */ +fun Throwable.toApplicationError( + errorMessage: String = this.message ?: "Internal server error" +): ApplicationError = + when (this) { + is DatabaseError -> this.toApplicationError(errorMessage) + is ApplicationError -> this + else -> ApplicationError(errorMessage) + } + +/** + * Inline helper method that wraps a block in a try catch, and responds with a converted error + * + * This allows us to have much more readable code, and maintain more DRY principles- at the cost of + * implementing side effects. + * + * @param responseClass a subclass of [Response] to finish calls with on failure + * @param block the block to wrap around + */ +suspend inline fun PipelineContext<*, ApplicationCall> + .handleApplicationErrors( + responseClass: KClass, + block: () -> Unit, +) { + try { + block() + } catch (error: Throwable) { + this.call.respond(HttpStatusCode.BadRequest, constructResponseObject(responseClass, error)) + } +} + +suspend inline fun RouteState.handleApplicationErrors( + responseClass: KClass, + block: () -> Unit, +) { + try { + block() + } catch (error: Throwable) { + this.respond(HttpStatusCode.BadRequest, constructResponseObject(responseClass, error)) + } +} + +/** + * Inline helper method that wraps a block in a try catch, and responds with a converted error + * + * This allows us to have much more readable code, and maintain more DRY principles- at the cost of + * implementing side effects. + * + * @param responseClass a subclass of [WebSocketResponse] to finish calls with on failure + * @param block the block to wrap around + */ +suspend inline fun WebSocketConnection.handleApplicationError( + responseClass: KClass, + block: () -> Unit, +) { + try { + block() + } catch (error: ClosedReceiveChannelException) { + error.printStackTrace() + WebSocketConnectionManager.closeSession(this.user.id) + } catch (error: Throwable) { + this.session.sendMessage(constructResponseObject(responseClass, error)) + } +} + +/** + * Inline helper method that utilizes reflection to fill out the error property of [Response] based + * objects. + * + * This also applies to [WebSocketResponse] as well, as [WebSocketResponse] is a subclass of + * [Response]. + * + * @param responseClass a subclass of [Response] to construct a new object from + * @param error the error to implement in the response + */ +inline fun constructResponseObject( + responseClass: KClass, + error: Throwable +): T { + error.printStackTrace() + + val errorMessage = + when (error) { + is ApplicationError -> error.errorMessage + is SerializationException -> "Invalid argument for request." + else -> "Unknown error occurred." + } + + val primaryConstructor = responseClass.primaryConstructor!! + val param = primaryConstructor.findParameterByName("error")!! + + return responseClass.primaryConstructor?.callBy(mapOf(param to errorMessage))!! +} + +/** + * Helper method that just throws a new [ApplicationError] + * + * Allows for more idiomatic code. + * + * @param errorMessage the message to apply to the newly created [ApplicationError] + * + * @throws ApplicationError the newly created error + */ +fun validationError(errorMessage: String): Nothing = throw ApplicationError(errorMessage) diff --git a/src/main/kotlin/com/daymxn/dchat/util/BetterKotlin.kt b/src/main/kotlin/com/daymxn/dchat/util/BetterKotlin.kt new file mode 100644 index 0000000..e6c9251 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/BetterKotlin.kt @@ -0,0 +1,47 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +/** + * Inline helper method that wraps a block in [mapCatching], and handles null values + * + * Is highly useful in performing inline validations on retrieved data from the database. + * + * @param block the block to wrap around + * + * @return a [Result] that wraps the error thrown from the block as a failure, or the result as a + * success + */ +inline fun Result.check(block: (value: T?) -> Unit): Result = mapCatching { + block(it) + it ?: validationError("Unexpected null value.") +} + +/** + * Inline helper method that wraps a block in an infinite loop, within a [runCatching] + * + * Is very rarely used, but provides a more idiomatic interface on an otherwise ugly (but needed) + * implementation. + * + * @param block the block to wrap around + * + * @return a [Result] that wraps the error thrown from the block as a failure, or the result as a + * success + */ +inline fun runCatchingInfiniteLoop(block: () -> Unit): Result { + return runCatching { while (true) block() } +} diff --git a/src/main/kotlin/com/daymxn/dchat/util/BetterResult.kt b/src/main/kotlin/com/daymxn/dchat/util/BetterResult.kt new file mode 100644 index 0000000..a0b356c --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/BetterResult.kt @@ -0,0 +1,40 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +/** + * Inline helper method that performs a transform on an exception, wrapping it in a [Result] + * + * I'm very surprised this isn't already implemented in the [Result] library, as It's very commonly + * used- especially in other languages (eg; scala). + * + * @param transform a block to call for transforming an exception + * + * @return a [Result] that either wraps the error, or returns the result + */ +inline fun Result.mapError(transform: (throwable: Throwable) -> Throwable): Result { + return when (val exception = this.exceptionOrNull()) { + null -> this + else -> transform(exception).asFailure() + } +} + +/** Helper method that wraps a [Throwable] in a failed [Result] */ +fun Throwable.asFailure(): Result = Result.failure(this) + +/** Helper method that wraps a [Throwable] in a succeed [Result] */ +@NotCurrentlyInUse fun T.asSuccess(): Result = Result.success(this) diff --git a/src/main/kotlin/com/daymxn/dchat/util/BetterWebSockets.kt b/src/main/kotlin/com/daymxn/dchat/util/BetterWebSockets.kt new file mode 100644 index 0000000..2ae6563 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/BetterWebSockets.kt @@ -0,0 +1,129 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.routes.* +import com.daymxn.dchat.routes.websockets.getChatHistoryRoute +import com.daymxn.dchat.routes.websockets.getUsersForSubstringRoute +import com.daymxn.dchat.routes.websockets.sendMessageRoute +import io.ktor.server.websocket.* +import io.ktor.websocket.* +import java.util.* + +/** + * Static object that maintains a Synchronized Map of all active [WebSocketConnection] + * + * Is essentially just a *cleaner* wrapper around a single instance of [Collections.synchronizedMap] + */ +object WebSocketConnectionManager { + private val connections: MutableMap = + Collections.synchronizedMap(LinkedHashMap()) + + /** + * Creates a new [WebSocketConnection] to keep track of, limited to one per [User] + * + * Will close out any previously open [WebSocketConnection] for the specified [User] (if any at + * all). + * + * @param session the [DefaultWebSocketServerSession] to wrap around + * @param user the user to create a connection for + * + * @return the newly created [WebSocketConnection] + */ + suspend fun keepSession(session: DefaultWebSocketServerSession, user: User): WebSocketConnection = + with(WebSocketConnection(WebSocketSession(session), user)) { + closeSession(user.id) + connections[user.id] = this + this + } + + /** + * Closes out a [WebSocketConnection] by a [User] ID + * + * Will also send a [CloseReason] frame to the websocket, if it is still open. + * + * @param id the ID of the [User] to close + */ + suspend fun closeSession(id: Long) { + connections.remove(id)?.session?.close() + } + + /** + * Sends a message to a specified user, via a previously established [WebSocketConnection] + * + * Does nothing in the case that the [User] does not currently have a [WebSocketConnection] open. + * + * @param client the ID of the [User] to send the message to + * @param message the [WebSocketRequest] to send to the user + */ + suspend fun notifyClient(client: Long, message: WebSocketRequest) { + connections[client]?.session?.sendMessage(message) + } +} + +/** + * Wrapper around a [DefaultWebSocketServerSession] for a specified [User] + * + * Also exposes some lifecycle methods for the web socket. + * + * @property session the connected socket session + * @property user the user to whom this connection belongs + */ +class WebSocketConnection(val session: WebSocketSession, val user: User) { + + /** + * Waits in an infinite loop for a [WebSocketRequest], and responds accordingly + * + * This is the main lifecycle of a [WebSocketConnection], and should live in a unique coroutine + * per connection. The loop will also clean up after itself by catching exceptions as needed, and + * closing out the session from [WebSocketConnectionManager]. + */ + suspend fun eventLoop() { + runCatchingInfiniteLoop { waitForMessage() }.onFailure { + WebSocketConnectionManager.closeSession(user.id) + } + } + + /** + * Waits for a [WebSocketRequest], and processes it when received + * + * Will deserialize all incoming messages, and facilitate requests to their unique methods for + * handling the request. + */ + internal suspend fun waitForMessage() { + when (val request = session.waitForRequest()) { + is GetUsersForSubstringRequest -> + handleApplicationError(GetUsersForSubstringResponse::class) { + getUsersForSubstringRoute(request) + } + is SendMessageRequest -> + handleApplicationError(SendMessageResponse::class) { sendMessageRoute(request) } + is GetChatHistoryRequest -> + handleApplicationError(GetChatHistoryResponse::class) { getChatHistoryRoute(request) } + } + } +} + +class WebSocketSession(val session: DefaultWebSocketServerSession) { + suspend fun waitForRequest(): WebSocketRequest = session.receiveDeserialized() + + suspend fun sendMessage(message: WebSocketHeader) = session.sendSerialized(message) + + suspend fun close() = + session.close(CloseReason(CloseReason.Codes.NORMAL, "Server requested to close this socket.")) +} diff --git a/src/main/kotlin/com/daymxn/dchat/util/DatabaseError.kt b/src/main/kotlin/com/daymxn/dchat/util/DatabaseError.kt new file mode 100644 index 0000000..2b8f753 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/DatabaseError.kt @@ -0,0 +1,83 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import org.jetbrains.exposed.exceptions.ExposedSQLException +import org.jetbrains.exposed.sql.Transaction +import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction +import java.sql.SQLIntegrityConstraintViolationException + +/** + * Exception type that encompasses all Database specific errors for this project + * + * @property errorMessage a message describing the error + * @property cause an exception that caused the error to occur + */ +sealed class DatabaseError(val errorMessage: String, cause: Throwable) : + Throwable(errorMessage, cause) + +/** + * Subtype of [DatabaseError] for pre-existing columns on insertion operations. + * + * @property cause the [SQLIntegrityConstraintViolationException] that caused the error + */ +data class ColumnAlreadyExists(override val cause: SQLIntegrityConstraintViolationException) : + DatabaseError("Column already exists", cause) + +/** + * Subtype of [DatabaseError] for any unknown errors + * + * @property cause an exception that caused the error to occur + */ +data class UnknownDatabaseError(override val cause: Throwable) : + DatabaseError("Unknown database error: ${cause.message}", cause) + +/** + * Helper method that converts an [ExposedSQLException] to a [DatabaseError] + * + * @param exception the SQL exception to convert + */ +private fun fromSQLError(exception: ExposedSQLException): DatabaseError = + when (val cause = exception.cause) { + is SQLIntegrityConstraintViolationException -> ColumnAlreadyExists(cause) + else -> UnknownDatabaseError(exception) + } + +/** + * Helper method that converts a [Throwable] to a [DatabaseError] + * + * @param throwable the throwable to convert + */ +private fun fromThrowable(throwable: Throwable): DatabaseError = + when (throwable) { + is ExposedSQLException -> fromSQLError(throwable) + else -> UnknownDatabaseError(throwable) + } + +/** + * Helper method for creating a new [Transaction] that should be caught and converted to + * [DatabaseError] on failure. + * + * @param statement the block to execute within the [Transaction] + * + * @return a [Result] that wraps the result of the [Transaction] + */ +suspend fun newQuery(statement: suspend Transaction.() -> T): Result = + newSuspendedTransaction { kotlin.runCatching { statement() } }.mapError { + it.printStackTrace() + fromThrowable(it) + } diff --git a/src/main/kotlin/com/daymxn/dchat/util/JWTManager.kt b/src/main/kotlin/com/daymxn/dchat/util/JWTManager.kt new file mode 100644 index 0000000..dc4229e --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/JWTManager.kt @@ -0,0 +1,61 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.auth0.jwt.JWT +import com.auth0.jwt.algorithms.Algorithm +import com.daymxn.dchat.datamodel.User +import io.ktor.util.* +import java.util.* +import javax.crypto.Mac +import javax.crypto.spec.SecretKeySpec + +/** Static object that facilitates common [JWT] related operations */ +object JWTManager { + + /** + * Creates a new [JWT] token for the specified [User] + * + * @param user the user to create a token for + * + * @return a [String] representation of the token created + */ + fun createToken(user: User): String = + JWT + .create() + .withAudience(ApplicationConfig.JWT.audience) + .withIssuer(ApplicationConfig.JWT.issuer) + .withClaim("id", user.id) + .withExpiresAt(Date(System.currentTimeMillis() + ApplicationConfig.JWT.tokenDuration)) + .sign(Algorithm.HMAC256(ApplicationConfig.JWT.secret)) + + /** + * Hashes a [String] with application-specific hashing for passwords + * + * @param password the raw [String] to create a hash for + * + * @return a [String] representation of the hash created from the specified password + */ + fun hashPassword(password: String): String { + Mac.getInstance("HmacSHA1").run { + this.init(SecretKeySpec(hex(ApplicationConfig.Keys.secret), "HmacSHA1")) + return hex(this.doFinal(password.toByteArray(Charsets.UTF_8))) + } + } + + fun User.hashPassword(): User = this.copy(password = JWTManager.hashPassword(this.password)) +} diff --git a/src/main/kotlin/com/daymxn/dchat/util/RouteState.kt b/src/main/kotlin/com/daymxn/dchat/util/RouteState.kt new file mode 100644 index 0000000..f1c59e9 --- /dev/null +++ b/src/main/kotlin/com/daymxn/dchat/util/RouteState.kt @@ -0,0 +1,46 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.routes.Request +import com.daymxn.dchat.routes.Response +import io.ktor.http.* +import io.ktor.server.application.* +import io.ktor.server.auth.* +import io.ktor.server.request.* +import io.ktor.server.response.* +import io.ktor.util.pipeline.* +import kotlin.reflect.KClass + +typealias RouteHandler = suspend RouteState.() -> Unit + +typealias ApplicationPipeline = PipelineContext + +class RouteState(val pipeline: ApplicationPipeline) { + fun getUser(): User? = pipeline.call.principal() + + suspend fun getRequest(clazz: KClass): T = pipeline.call.receive(clazz) + + suspend inline fun getRequest(): T = getRequest(T::class) + + suspend fun respond(statusCode: HttpStatusCode, response: Response) { + pipeline.call.respond(statusCode, response) + } +} + +fun ApplicationPipeline.routeState() = RouteState(this) diff --git a/src/main/resources/logback.xml b/src/main/resources/logback.xml new file mode 100644 index 0000000..bdbb64e --- /dev/null +++ b/src/main/resources/logback.xml @@ -0,0 +1,12 @@ + + + + %d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + + + + + + + + diff --git a/src/test/TESTS.md b/src/test/TESTS.md new file mode 100644 index 0000000..bc336a1 --- /dev/null +++ b/src/test/TESTS.md @@ -0,0 +1,114 @@ +# Testing + +Testing in dChat follows a very simple philosophy; don't repeat yourself. Often-times when designing tests, people end +up just rewriting the code- but in a test. This leads to tightly coupled tests (which may or may not be what you want) +and takes a lot of time to maintain. So I decided against it. + +Tests in dChat exist at the business layer, leaving the rest of the infrastructure alone. But, in order for this +philosophy to be practical- it means that the system must be designed in a way that facilitates *most* logic to the +business layer. You can see this in practice with dChat, as services outside of routes live fairly idempotent. They're +modular, are very simple to follow and most importantly- they won't change often +(if at all). + +## Routes vs WebSockets + +Tests are split into [currently] two separate categories; Routes and WebSockets. + +Routes are the life-line of the application, and are seen as the core of dChat. They encompass the most important +logical operations, and connect the Database layer with the API layer. + +WebSockets are split off into their own category, even though they are technically routes, purely due to the fact that +they must be treated differently. While in design the systems are very similar, WebSocket implementation details differ +quite a bit from your standard Route. Primarily because a lot more of the lifecycle of WebSockets is managed by dChat, +where's the vast majority of the lifecycle of Routes is managed by KTOR. + +## Writing tests for Routes + +Route tests implement something called the `ApplicationTestManager`. This test manager class wraps around `RouteState` +objects, and facilitates interaction with the `RouteHandler`. + +The existence of this class is mainly for the sake of readability and consistency. Keeping implementation details +modular, and using the same core API, facilitates more consistent tests. + +We also take advantage of the `MockDatabaseService` class. As of this writing, the `MockDatabaseService` +merely lives as a toggle for Exposed mocks- but that may change in the future as implementation details grow. + +A standard Route test may look a little something like this: + +```Kotlin +class LoginRouteTest : FreeSpec({ + val testManager = ApplicationTestManager(loginRouteHandler) + MockDatabaseService.enable() + + suspend fun callHandler(request: LoginRequest): LoginResponse + + "request validation" - { + "fails on invalid username" {} + "fails on invalid password" {} + } + + "works as expected" {} +}) + +``` + +The test is label in a straight forward and repeatable way: `{ROUTENAME}Test` + +The test inherits from the Kotest `FreeSpec` + +The test saves a reference to a `ApplicationTestManager` to use throughout the test's lifecycle + +The test enables the database mocking services through `MockDatabaseService.enable()` + +And the tests themselves have been seperated as two straight forward categories; **request validation** +and **works as expected**. + +This is a common theme you'll see through-out all dChat tests, and is something you should strive to align with as +closely as possible. The more consistent tests are, the easier they are to write and maintain. + +## Writing tests for WebSockets + +WebSocket tests are very similar to **Route** tests, except that they have their own unique test +manager- `WebSocketTestManager`. + +The test manager will create its own `WebSocketSession` and `WebSocketConnection`, so writing tests are actually a bit +simpler (in comparison to Routes). + +A standard WebSocket test may look a little something like this: + +```Kotlin +class SendMessageRouteTest : FreeSpec({ + val testManager = WebSocketTestManager() + MockDatabaseService.enable() + + suspend fun callHandler(request: SendMessageRequest): SendMessageResponse + + "request validation" - { + "fails on user not apart of chat" {} + "fails on blank message" {} + } + + "works as expected" {} +}) + +``` + +Which is almost identical to how **Route** tests look, with the minor difference that you don't have to pass the method +we're testing into the test manager.* + +*The reason we can do this is because we facilitate most of the lifecycle of WebSockets, and can instead just mock the +method that handles the lifecycle with the `WebSocketRequest`. Where's with +**Routes**, we don't have enough control over the lifecycle to do that. + +## Key Terms + +`RouteHandler` - Typedef for core route logic, which should be tested upon. + +`RouteState` - A state object that exists for all routes, and provides an easy-to-mock dependency injection for tests. + +`ApplicationTestManager` - Route lifecycle manager, which facilitates interaction with the target method. + +`MockDatabaseService` - Exposed mocking service, which allows us to mock database tables. + +`WebSocketTestManager` - WebSocket lifecycle manager, similar to *ApplicationTestManager*, which facilitates interaction +with the target method. diff --git a/src/test/kotlin/com/daymxn/dchat/routes/DeleteChatRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/DeleteChatRouteTest.kt new file mode 100644 index 0000000..4b87b56 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/DeleteChatRouteTest.kt @@ -0,0 +1,70 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.service.ChatService +import com.daymxn.dchat.util.ApplicationTestManager +import com.daymxn.dchat.util.MockDatabaseService +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldBe +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery + +class DeleteChatRouteTest : + FreeSpec({ + val testManager = ApplicationTestManager(deleteChatRouteHandler) + MockDatabaseService().enable() + + suspend fun callHandler(request: DeleteChatRequest): DeleteChatResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + "request validation" - + { + "fails on user not logged in" { + testManager.setUserIsLoggedIn(false) + + val response = callHandler(DeleteChatRequest(1u)) + response.error shouldNotBe null + } + "fails on user not apart of chat" { + testManager.setUserIsLoggedIn() + + coEvery { ChatService.deleteIfUserApartOf(any(), any()) } returns false + + val response = callHandler(DeleteChatRequest(1u)) + response.error shouldNotBe null + } + "fails on internal database error" { + testManager.setUserIsLoggedIn() + + coEvery { ChatService.deleteIfUserApartOf(any(), any()) } throws Exception() + + val response = callHandler(DeleteChatRequest(1u)) + response.error shouldNotBe null + } + } + + "works as expected" { + testManager.setUserIsLoggedIn() + + coEvery { ChatService.deleteIfUserApartOf(any(), any()) } returns true + + val response = callHandler(DeleteChatRequest(1u)) + response.error shouldBe null + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/GetActivityRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/GetActivityRouteTest.kt new file mode 100644 index 0000000..43f5da0 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/GetActivityRouteTest.kt @@ -0,0 +1,70 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.datamodel.ActivityType +import com.daymxn.dchat.service.ActivityService +import com.daymxn.dchat.util.ApplicationTestManager +import com.daymxn.dchat.util.MockDatabaseService +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldBe +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery +import io.mockk.mockk + +class GetActivityRouteTest : + FreeSpec({ + val testManager = ApplicationTestManager(getActivityRouteHandler) + MockDatabaseService().enable() + + suspend fun callHandler(request: GetActivityRequest): GetActivityResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + "request validation" - + { + "fails on internal database error" { + testManager.setUserIsLoggedIn() + coEvery { ActivityService.getByTypeAndAfter(any(), any()) } throws Exception() + + val response = callHandler(GetActivityRequest(ActivityType.values().first())) + response.error shouldNotBe null + } + } + + "works as expected" - + { + "when there are no chats" { + testManager.setUserIsLoggedIn() + coEvery { ActivityService.getByTypeAndAfter(any(), any()) } answers { emptyList() } + + ActivityType.values().forEach { + val response = callHandler(GetActivityRequest(it)) + response.activities shouldNotBe null + } + } + "when there are chats" { + testManager.setUserIsLoggedIn() + coEvery { ActivityService.getByTypeAndAfter(any(), any()) } answers { listOf(mockk()) } + + ActivityType.values().forEach { + val response = callHandler(GetActivityRequest(it)) + response.activities?.isEmpty() shouldBe false + } + } + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/GetChatsRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/GetChatsRouteTest.kt new file mode 100644 index 0000000..b1236ef --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/GetChatsRouteTest.kt @@ -0,0 +1,71 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.service.ChatService +import com.daymxn.dchat.util.ApplicationTestManager +import com.daymxn.dchat.util.MockDatabaseService +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldBe +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery +import io.mockk.mockk + +class GetChatsRouteTest : + FreeSpec({ + val testManager = ApplicationTestManager(getChatsRouteHandler) + MockDatabaseService().enable() + + suspend fun callHandler(request: GetChatsRequest): GetChatsResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + "request validation" - + { + "fails on user not logged in" { + testManager.setUserIsLoggedIn(false) + + val response = callHandler(GetChatsRequest()) + response.error shouldNotBe null + } + "fails on internal database error" { + testManager.setUserIsLoggedIn() + coEvery { ChatService.getByUserAndAfter(any(), any()) } throws Exception() + + val response = callHandler(GetChatsRequest()) + response.error shouldNotBe null + } + } + + "works as expected" - + { + "when there are no chats" { + testManager.setUserIsLoggedIn() + coEvery { ChatService.getByUserAndAfter(any(), any()) } answers { emptyList() } + + val response = callHandler(GetChatsRequest()) + response.chats shouldNotBe null + } + "when there are chats" { + testManager.setUserIsLoggedIn() + coEvery { ChatService.getByUserAndAfter(any(), any()) } answers { listOf(mockk()) } + + val response = callHandler(GetChatsRequest()) + response.chats?.isEmpty() shouldBe false + } + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/LoginRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/LoginRouteTest.kt new file mode 100644 index 0000000..abc34e8 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/LoginRouteTest.kt @@ -0,0 +1,81 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.datamodel.Activity +import com.daymxn.dchat.service.ActivityService +import com.daymxn.dchat.service.UserService +import com.daymxn.dchat.util.* +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery +import io.mockk.mockk + +class LoginRouteTest : + FreeSpec({ + val testManager = ApplicationTestManager(loginRouteHandler) + MockDatabaseService().enable() + + suspend fun callHandler(request: LoginRequest): LoginResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + coEvery { ActivityService.insert(any()) } answers { firstArg().asSuccess() } + + "request validation" - + { + "fails when missing username" { + val response = callHandler(LoginRequest("", USER_PASSWORD_TESTS)) + response.error shouldNotBe null + } + "fails when missing password" { + val response = callHandler(LoginRequest(USER_USERNAME_TESTS, "")) + response.error shouldNotBe null + } + "fails when username does not exists" { + val localUser = GenerateMockObjects.localUser() + testManager.markUserAsNotFound(localUser) + + val response = callHandler(LoginRequest(localUser.username, localUser.password)) + response.error shouldNotBe null + } + "fails when password is incorrect" { + val localUser = GenerateMockObjects.localUser() + testManager.saveUser(localUser) + + val response = callHandler(LoginRequest(localUser.username, localUser.password + "xyz")) + response.error shouldNotBe null + } + "fails on internal database error" { + coEvery { UserService.getByUsername(any()) } answers + { + UnknownDatabaseError(mockk()).asFailure() + } + + val response = callHandler(LoginRequest(USER_USERNAME_TESTS, USER_PASSWORD_TESTS)) + response.error shouldNotBe null + } + } + + "works as expected" { + val localUser = GenerateMockObjects.localUser() + testManager.saveUser(localUser) + + val response = callHandler(LoginRequest(localUser.username, localUser.password)) + response.accessToken shouldNotBe null + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/RegisterRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/RegisterRouteTest.kt new file mode 100644 index 0000000..d6c0baf --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/RegisterRouteTest.kt @@ -0,0 +1,66 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.service.UserService +import com.daymxn.dchat.util.* +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery +import io.mockk.mockk + +class RegisterRouteTest : + FreeSpec({ + val testManager = ApplicationTestManager(registerRouteHandler) + MockDatabaseService().enable() + + suspend fun callHandler(request: RegisterRequest): RegisterResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + "request validation" - + { + "fails when missing username" { + val response = callHandler(RegisterRequest("", USER_PASSWORD_TESTS)) + response.error shouldNotBe null + } + "fails when missing password" { + val response = callHandler(RegisterRequest(USER_USERNAME_TESTS, "")) + response.error shouldNotBe null + } + "fails when username is already in use" { + coEvery { UserService.insert(any()) } answers { ColumnAlreadyExists(mockk()).asFailure() } + + val response = callHandler(RegisterRequest(USER_USERNAME_TESTS, USER_PASSWORD_TESTS)) + response.error shouldNotBe null + } + "fails on internal database error" { + coEvery { UserService.insert(any()) } answers { null.asSuccess() } + + val response = callHandler(RegisterRequest(USER_USERNAME_TESTS, USER_PASSWORD_TESTS)) + response.error shouldNotBe null + } + } + + "works as expected" { + coEvery { UserService.insert(any()) } answers { firstArg().asSuccess() } + + val response = callHandler(RegisterRequest(USER_USERNAME_TESTS, USER_PASSWORD_TESTS)) + response.accessToken shouldNotBe null + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/StartChatRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/StartChatRouteTest.kt new file mode 100644 index 0000000..5e7883e --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/StartChatRouteTest.kt @@ -0,0 +1,80 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes + +import com.daymxn.dchat.datamodel.Chat +import com.daymxn.dchat.service.ChatService +import com.daymxn.dchat.util.* +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery +import io.mockk.mockk + +class StartChatRouteTest : + FreeSpec({ + val testManager = ApplicationTestManager(startChatRouteHandler) + MockDatabaseService().enable() + + suspend fun callHandler(request: StartChatRequest): StartChatResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + "request validation" - + { + "fails on user not logged in" { + testManager.setUserIsLoggedIn(false) + + val response = callHandler(StartChatRequest(2u)) + response.error shouldNotBe null + } + "fails on starting chat with self" { + testManager.setUserIsLoggedIn() + + val response = callHandler(StartChatRequest(0u)) + response.error shouldNotBe null + } + "fails on internal database error" { + testManager.setUserIsLoggedIn() + testManager.saveUser(GenerateMockObjects.user(2)) + + coEvery { ChatService.insert(any()) } answers { null.asSuccess() } + + val response = callHandler(StartChatRequest(2u)) + response.error shouldNotBe null + } + "fails when a chat already exists" { + testManager.setUserIsLoggedIn() + testManager.saveUser(GenerateMockObjects.user(2)) + + coEvery { ChatService.insert(any()) } answers { ColumnAlreadyExists(mockk()).asFailure() } + + val response = callHandler(StartChatRequest(2u)) + response.error shouldNotBe null + } + } + + "works as expected" { + testManager.setUserIsLoggedIn() + val testUser = GenerateMockObjects.user(2) + testManager.saveUser(testUser) + + coEvery { ChatService.insert(any()) } answers { firstArg().asSuccess() } + + val response = callHandler(StartChatRequest(2u)) + response.chat shouldNotBe null + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRouteTest.kt new file mode 100644 index 0000000..051a504 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/websockets/GetChatHistoryRouteTest.kt @@ -0,0 +1,70 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes.websockets + +import com.daymxn.dchat.datamodel.Chat +import com.daymxn.dchat.datamodel.Message +import com.daymxn.dchat.routes.GetChatHistoryRequest +import com.daymxn.dchat.routes.GetChatHistoryResponse +import com.daymxn.dchat.service.ChatService +import com.daymxn.dchat.service.MessageService +import com.daymxn.dchat.service.UserService +import com.daymxn.dchat.util.MockDatabaseService +import com.daymxn.dchat.util.WebSocketTestManager +import com.daymxn.dchat.util.asSuccess +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldBe +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery + +class GetChatHistoryRouteTest : + FreeSpec({ + val testManager = WebSocketTestManager() + + MockDatabaseService().enable() + + suspend fun callHandler(request: GetChatHistoryRequest): GetChatHistoryResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + "request validation" - + { + "fails on user not apart of chat" { + val fakeChat = Chat(1, 1337, 1337, 1) + coEvery { ChatService.getById(any()) } answers { fakeChat.asSuccess() } + + val response = callHandler(GetChatHistoryRequest(1u, 1u)) + response.error shouldNotBe null + } + "fails on internal database error" { + coEvery { UserService.getByUsernameLike(any()) } throws Exception() + + val response = callHandler(GetChatHistoryRequest(1u, 1u)) + response.error shouldNotBe null + } + } + + "works as expected" { + val fakeMessage = Message(1, 1, 1, 1, "123") + val fakeChat = Chat(1, 0, 1, 1) + coEvery { MessageService.getByChatAndAfter(any(), any()) } answers { listOf(fakeMessage) } + coEvery { ChatService.getById(any()) } answers { fakeChat.asSuccess() } + + val response = callHandler(GetChatHistoryRequest(1u, 1u)) + response.messages?.isEmpty() shouldBe false + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRouteTest.kt new file mode 100644 index 0000000..166c1f8 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/websockets/GetUsersForSubstringRouteTest.kt @@ -0,0 +1,69 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes.websockets + +import com.daymxn.dchat.routes.GetUsersForSubstringRequest +import com.daymxn.dchat.routes.GetUsersForSubstringResponse +import com.daymxn.dchat.service.UserService +import com.daymxn.dchat.util.GenerateMockObjects +import com.daymxn.dchat.util.MockDatabaseService +import com.daymxn.dchat.util.WebSocketTestManager +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldBe +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery + +class GetUsersForSubstringRouteTest : + FreeSpec({ + val testManager = WebSocketTestManager() + + MockDatabaseService().enable() + + suspend fun callHandler(request: GetUsersForSubstringRequest): GetUsersForSubstringResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + "request validation" - + { + "fails on less than 3 chars" { + arrayOf("12", "1", "").forEach { + val response = callHandler(GetUsersForSubstringRequest(it)) + response.error shouldNotBe null + } + } + "removes non alphanumeric characters" { + val response = callHandler(GetUsersForSubstringRequest("__b__!+;'[]2")) + response.error shouldNotBe null + } + "fails on internal database error" { + coEvery { UserService.getByUsernameLike(any()) } throws Exception() + + val response = callHandler(GetUsersForSubstringRequest("hello world!")) + response.error shouldNotBe null + } + } + + "works as expected" { + coEvery { UserService.getByUsernameLike(any()) } answers + { + listOf(GenerateMockObjects.user()) + } + + val response = callHandler(GetUsersForSubstringRequest("hello world!")) + response.users?.isEmpty() shouldBe false + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRouteTest.kt b/src/test/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRouteTest.kt new file mode 100644 index 0000000..74dccfe --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/routes/websockets/SendMessageRouteTest.kt @@ -0,0 +1,78 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.routes.websockets + +import com.daymxn.dchat.datamodel.Activity +import com.daymxn.dchat.datamodel.Chat +import com.daymxn.dchat.datamodel.Message +import com.daymxn.dchat.routes.SendMessageRequest +import com.daymxn.dchat.routes.SendMessageResponse +import com.daymxn.dchat.service.ActivityService +import com.daymxn.dchat.service.ChatService +import com.daymxn.dchat.service.MessageService +import com.daymxn.dchat.util.MockDatabaseService +import com.daymxn.dchat.util.WebSocketTestManager +import com.daymxn.dchat.util.asSuccess +import io.kotest.core.spec.style.FreeSpec +import io.kotest.matchers.shouldBe +import io.kotest.matchers.shouldNotBe +import io.kotest.matchers.types.shouldBeInstanceOf +import io.mockk.coEvery + +class SendMessageRouteTest : + FreeSpec({ + val testManager = WebSocketTestManager() + + MockDatabaseService().enable() + + suspend fun callHandler(request: SendMessageRequest): SendMessageResponse = + testManager.invokeHandler(request).shouldBeInstanceOf() + + coEvery { ActivityService.insert(any()) } answers { firstArg().asSuccess() } + + "request validation" - + { + "fails on user not apart of chat" { + val fakeChat = Chat(0, 1337, 1337, 0) + coEvery { ChatService.getById(any()) } answers { fakeChat.asSuccess() } + + val response = callHandler(SendMessageRequest(0u, "hello world!")) + response.error shouldNotBe null + } + "fails on blank message" { + val response = callHandler(SendMessageRequest(0u, "")) + response.error shouldNotBe null + } + "fails on internal database error" { + val fakeChat = Chat(0, 1, 2, 0) + coEvery { ChatService.getById(any()) } answers { fakeChat.asSuccess() } + coEvery { MessageService.insert(any()) } answers { null.asSuccess() } + + val response = callHandler(SendMessageRequest(0u, "hello world!")) + response.error shouldNotBe null + } + } + + "works as expected" { + val fakeChat = Chat(0, 0, 1337, 0) + coEvery { ChatService.getById(any()) } answers { fakeChat.asSuccess() } + coEvery { MessageService.insert(any()) } answers { firstArg().asSuccess() } + + val response = callHandler(SendMessageRequest(0u, "hello world!")) + response.error shouldBe null + } + }) diff --git a/src/test/kotlin/com/daymxn/dchat/util/ApplicationTestManager.kt b/src/test/kotlin/com/daymxn/dchat/util/ApplicationTestManager.kt new file mode 100644 index 0000000..12e73c8 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/util/ApplicationTestManager.kt @@ -0,0 +1,65 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.daymxn.dchat.datamodel.User +import com.daymxn.dchat.routes.Request +import com.daymxn.dchat.routes.Response +import com.daymxn.dchat.service.UserService +import com.daymxn.dchat.util.JWTManager.hashPassword +import io.mockk.coEvery +import io.mockk.mockk +import io.mockk.slot + +class ApplicationTestManager(val routeHandler: RouteHandler) { + val routeState = mockRouteState() + + suspend inline fun invokeHandler(request: T): Response? { + coEvery { routeState.getRequest(T::class) } returns request + + val response = slot() + coEvery { routeState.respond(any(), capture(response)) } answers {} + + routeHandler.invoke(routeState) + + return if (response.isCaptured) response.captured else null + } + + fun setUserIsLoggedIn(isLoggedIn: Boolean = true) { + with(GenerateMockObjects.localUser()) { + if (isLoggedIn) { + coEvery { routeState.getUser() } returns this + saveUser(this) + } else { + coEvery { routeState.getUser() } returns null + markUserAsNotFound(this) + } + } + } + + fun saveUser(user: User, id: Long = user.id, username: String = user.username) { + coEvery { UserService.getById(id) } returns user.hashPassword().asSuccess() + coEvery { UserService.getByUsername(username) } returns user.hashPassword().asSuccess() + } + + fun markUserAsNotFound(user: User) { + coEvery { UserService.getById(user.id) } returns null.asSuccess() + coEvery { UserService.getByUsername(user.username) } returns null.asSuccess() + } +} + +fun mockRouteState(): RouteState = mockk {} diff --git a/src/test/kotlin/com/daymxn/dchat/util/GenerateMockObjects.kt b/src/test/kotlin/com/daymxn/dchat/util/GenerateMockObjects.kt new file mode 100644 index 0000000..0ff4f56 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/util/GenerateMockObjects.kt @@ -0,0 +1,31 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.daymxn.dchat.datamodel.User + +const val USER_USERNAME_TESTS = "username" +const val USER_PASSWORD_TESTS = "p@ssw0rd!" + +const val LOCAL_USER_USERNAME_TESTS = "user" +const val LOCAL_USER_PASSWORD_TESTS = USER_PASSWORD_TESTS + +internal object GenerateMockObjects { + fun user(id: Long = 1): User = User(id, USER_USERNAME_TESTS, USER_PASSWORD_TESTS) + + fun localUser(): User = User(0, LOCAL_USER_USERNAME_TESTS, LOCAL_USER_PASSWORD_TESTS) +} diff --git a/src/test/kotlin/com/daymxn/dchat/util/MockDatabase.kt b/src/test/kotlin/com/daymxn/dchat/util/MockDatabase.kt new file mode 100644 index 0000000..b0cd30d --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/util/MockDatabase.kt @@ -0,0 +1,34 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.daymxn.dchat.service.ActivityService +import com.daymxn.dchat.service.ChatService +import com.daymxn.dchat.service.MessageService +import com.daymxn.dchat.service.UserService +import io.mockk.mockkObject +import io.mockk.unmockkObject + +internal class MockDatabaseService { + fun enable() { + mockkObject(ActivityService, ChatService, MessageService, UserService) + } + + fun disable() { + unmockkObject(ActivityService, ChatService, MessageService, UserService) + } +} diff --git a/src/test/kotlin/com/daymxn/dchat/util/WebSocketTestManager.kt b/src/test/kotlin/com/daymxn/dchat/util/WebSocketTestManager.kt new file mode 100644 index 0000000..2ce74c3 --- /dev/null +++ b/src/test/kotlin/com/daymxn/dchat/util/WebSocketTestManager.kt @@ -0,0 +1,40 @@ +/* + * Copyright 2022 Daymon Littrell + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.daymxn.dchat.util + +import com.daymxn.dchat.routes.WebSocketRequest +import com.daymxn.dchat.routes.WebSocketResponse +import io.mockk.coEvery +import io.mockk.mockk +import io.mockk.slot + +internal class WebSocketTestManager { + val session = mockWebSocketSession() + val connection = WebSocketConnection(session, GenerateMockObjects.localUser()) + + suspend inline fun invokeHandler(request: WebSocketRequest): WebSocketResponse? { + val response = slot() + coEvery { session.sendMessage(capture(response)) } answers {} + coEvery { session.waitForRequest() } answers { request } + + connection.waitForMessage() + + return if (response.isCaptured) response.captured else null + } +} + +fun mockWebSocketSession(): WebSocketSession = mockk()