task: refactor common router logic

Author: jwilkinson87

README.md

@@ -55,12 +55,24 @@ val api = Api.create()
 val response: List<Vehicle> = api.vehicles.all("your-session-token", "organisation-id", VehicleIncludes.SpecificationModel)
 ```
 
-## Example Usage
+## Examples of Usage
 
 ```kotlin
 Config.environment = Environment.STAGING
 val api = Api.create()
 
-val response = api.vehicles.all("sess-123", "org-123", VehicleIncludes.SpecificationModel)
+api.sessionToken = "sess-123"
+val response = api.vehicles.all("org-123", VehicleIncludes.SpecificationModel)
 println(response.size)
+```
+
+```kotlin
+Config.environment = Environment.STAGING
+val api = Api.create()
+
+with(api.vehicles) {
+    sessionToken = "sess-123"
+    val response = all("org-123", VehicleIncludes.SpecificationModel)
+    println(response.size)
+}
 ```

src/main/kotlin/com/ctrlhub/core/api/ApiException.kt

@@ -15,4 +15,6 @@ class ApiClientException(message: String, val response: HttpResponse, e: Throwab
     fun statusCode(): Int {
         return response.status.value
     }
-}
+}
+
+class MissingSessionTokenException : Exception("No session token provided")

src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouter.kt

@@ -1,25 +1,22 @@
 package com.ctrlhub.core.assets.vehicles
 
 import com.ctrlhub.core.Api
-import com.ctrlhub.core.Config
 import com.ctrlhub.core.api.ApiClientException
 import com.ctrlhub.core.api.ApiException
 import com.ctrlhub.core.assets.vehicles.response.Vehicle
 import com.ctrlhub.core.http.KtorClientFactory
 import com.ctrlhub.core.router.Router
+import com.ctrlhub.core.router.request.JsonApiIncludes
 import com.github.jasminb.jsonapi.ResourceConverter
 import com.github.jasminb.jsonapi.SerializationFeature
-import io.ktor.client.HttpClient
-import io.ktor.client.call.body
-import io.ktor.client.plugins.ClientRequestException
-import io.ktor.client.request.get
-import io.ktor.client.request.header
-import io.ktor.http.headers
+import io.ktor.client.*
+import io.ktor.client.call.*
+import io.ktor.client.plugins.*
 
 /**
  * Represents JSONAPI includes that are associated for vehicles
  */
-enum class VehicleIncludes(val value: String) {
+enum class VehicleIncludes(val value: String) : JsonApiIncludes {
     Status("status"),
     Assignee("assignee"),
     Equipment("equipment"),
@@ -28,41 +25,30 @@ enum class VehicleIncludes(val value: String) {
     EquipmentModelCategories("equipment.model.categories"),
     Specification("specification"),
     SpecificationModel("specification.model"),
-    SpecificationModelManufacturer("specification.model.manufacturer")
+    SpecificationModelManufacturer("specification.model.manufacturer");
+
+    override fun value(): String {
+        return value
+    }
 }
 
 /**
  * A vehicles router that deals with the vehicles realm of the Ctrl Hub API
  */
-class VehiclesRouter(httpClient: HttpClient) : Router(httpClient) {
+class VehiclesRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
 
     /**
      * Request all vehicles
      *
-     * @param sessionToken String A valid session token gained after authentication
      * @param organisationId String The organisation ID to retrieve all vehicles for
      * @param includes A variable list of any includes, to return in the response. For example, VehicleIncludes.Specification will provide additional Specification attributes
      *
      * @return A list of all vehicles
      */
-    suspend fun all(sessionToken: String, organisationId: String, vararg includes: VehicleIncludes): List<Vehicle> {
-        val includesQuery = if (includes.isNotEmpty()) {
-            "?include=${includes.joinToString(",") { it.value }}"
-        } else {
-            ""
-        }
-
-        return fetchAllVehicles(sessionToken, organisationId, includesQuery)
-    }
-
-    private suspend fun fetchAllVehicles(sessionToken: String, organisationId: String, includesQuery: String): List<Vehicle> {
+    suspend fun all(organisationId: String, vararg includes: VehicleIncludes = emptyArray()): List<Vehicle> {
         return try {
-            val rawResponse = httpClient.get("${Config.apiBaseUrl}/v3/orgs/$organisationId/assets/vehicles$includesQuery") {
-                headers {
-                    header("X-Session-Token", sessionToken)
-                }
-            }
-
+            val includesQuery = buildIncludesQueryString(*includes)
+            val rawResponse = performGet("/v3/orgs/$organisationId/assets/vehicles" + (if (includesQuery.isNotEmpty()) "?$includesQuery" else ""))
             val resourceConverter = ResourceConverter(Vehicle::class.java).apply {
                 enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
             }

src/main/kotlin/com/ctrlhub/core/auth/AuthRouter.kt

@@ -25,7 +25,7 @@ import kotlinx.serialization.json.Json
 /**
  * A router that deals with authenticating through the Ctrl Hub API
  */
-class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
+class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient, requiresAuthentication = false) {
 
     /**
      * Initiates a flow for authentication. This needs to be called first, before completing
@@ -48,18 +48,12 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
     /**
      * Provides a mechanism for refreshing a session
      *
-     * @param sessionToken String A valid session token obtained via authentication
-     *
      * @throws ApiClientException when a client based exception occurs, usually as a result of a non-200 HTTP response code
      * @throws ApiException when another type of exception occurs
      */
-    suspend fun refresh(sessionToken: String): AuthFlowResponse {
+    suspend fun refresh(): AuthFlowResponse {
         return try {
-            httpClient.get("${Config.authBaseUrl}/self-service/login/api?refresh=true") {
-                headers {
-                    header("X-Session-Token", sessionToken)
-                }
-            }.body()
+            performGet("${Config.authBaseUrl}/self-service/login/api?refresh=true").body()
         } catch (e: ClientRequestException) {
             throw ApiClientException("Failed to initiate auth", e.response, e)
         } catch (e: Exception) {
@@ -80,9 +74,7 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
      */
     suspend fun complete(flowId: String, payload: LoginPayload): CompleteResponse {
         return try {
-            httpClient.post("${Config.authBaseUrl}/self-service/login?flow=$flowId") {
-                setBody(Json.encodeToString(payload))
-            }.body()
+            performPost("${Config.authBaseUrl}/self-service/login?flow=$flowId", payload).body()
         } catch (e: ClientRequestException) {
             if (e.response.status == HttpStatusCode.BadRequest) {
                 val bodyAsString: String = e.response.body()
@@ -100,18 +92,14 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
     /**
      * Invalidates a session
      *
-     * @param sessionToken String A session token that will identify the session to be invalidated
-     *
-     * @return true if the session could be invalidated successfuly, false if not
+     * @return true if the session could be invalidated successfully, false if not
      * @throws ApiException If an exception occurred whilst attempting to invalidate a session
      */
-    suspend fun logout(sessionToken: String): Boolean {
+    suspend fun logout(): Boolean {
         return try {
-            val statusCode = httpClient.delete("${Config.authBaseUrl}/self-service/logout/api") {
-                setBody(Json.encodeToString(LogoutPayload(
-                    sessionToken = sessionToken
-                )))
-            }.status
+            val statusCode = performDelete("${Config.authBaseUrl}/self-service/logout/api", body = LogoutPayload(
+                sessionToken = sessionToken.toString()
+            )).status
 
             statusCode == HttpStatusCode.NoContent
         } catch (e: ClientRequestException) {

src/main/kotlin/com/ctrlhub/core/governance/OrganisationsRouter.kt

@@ -11,22 +11,16 @@ import com.github.jasminb.jsonapi.ResourceConverter
 import io.ktor.client.HttpClient
 import io.ktor.client.call.body
 import io.ktor.client.plugins.ClientRequestException
-import io.ktor.client.request.get
-import io.ktor.client.request.header
-import io.ktor.http.headers
 
 /**
  * An organisation router that deals with the organisations realm of the Ctrl Hub API
  */
-class OrganisationsRouter(httpClient: HttpClient) : Router(httpClient) {
-    suspend fun all(sessionToken: String): List<Organisation> {
-        return try {
-            val rawResponse = httpClient.get("${Config.apiBaseUrl}/v3/orgs") {
-                headers {
-                    header("X-Session-Token", sessionToken)
-                }
-            }
+class OrganisationsRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
+    private val endpoint = "${Config.apiBaseUrl}/v3/orgs"
 
+    suspend fun all(): List<Organisation> {
+        return try {
+            val rawResponse = performGet(endpoint)
             val resourceConverter = ResourceConverter(Organisation::class.java)
             val jsonApiResponse = resourceConverter.readDocumentCollection<Organisation>(
                 (rawResponse.body<ByteArray>()),

src/main/kotlin/com/ctrlhub/core/iam/IamRouter.kt

@@ -18,23 +18,16 @@ import io.ktor.http.headers
 /**
  * A router that deals with the Iam realm of the Ctrl Hub API
  */
-class IamRouter(httpClient: HttpClient) : Router(httpClient) {
+class IamRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
 
     /**
      * Returns information about the currently authenticated user, based on a session token
      *
-     * @param sessionToken String A valid session token obtained via authentication
-     *
      * @return A user object providing information about a currently authenticated user
      */
-    suspend fun whoami(sessionToken: String): User {
+    suspend fun whoami(): User {
         return try {
-            val rawResponse = httpClient.get("${Config.apiBaseUrl}/v3/iam/whoami") {
-                headers {
-                    header("X-Session-Token", sessionToken)
-                }
-            }
-
+            val rawResponse = performGet("${Config.apiBaseUrl}/v3/iam/whoami")
             val resourceConverter = ResourceConverter(User::class.java)
             val jsonApiResponse = resourceConverter.readDocument<User>(rawResponse.body<ByteArray>(), User::class.java)
 

src/main/kotlin/com/ctrlhub/core/router/Router.kt

@@ -1,5 +1,80 @@
 package com.ctrlhub.core.router
 
+import com.ctrlhub.core.api.MissingSessionTokenException
+import com.ctrlhub.core.router.request.JsonApiIncludes
 import io.ktor.client.HttpClient
+import io.ktor.client.request.delete
+import io.ktor.client.request.get
+import io.ktor.client.request.header
+import io.ktor.client.request.post
+import io.ktor.client.request.setBody
+import io.ktor.client.statement.HttpResponse
+import io.ktor.http.ContentType
+import io.ktor.http.contentType
+import io.ktor.http.headers
 
-abstract class Router(val httpClient: HttpClient)
+abstract class Router(val httpClient: HttpClient, val requiresAuthentication: Boolean) {
+    var sessionToken: String? = null
+
+    protected fun buildIncludesQueryString(vararg includes: JsonApiIncludes): String {
+        if (includes.isEmpty()) {
+            return ""
+        }
+        return "include=" + includes.joinToString(",") { it.value().lowercase() }
+    }
+
+    protected suspend fun performGet(endpoint: String): HttpResponse {
+        if (requiresAuthentication && sessionToken.isNullOrEmpty()) {
+            throw MissingSessionTokenException()
+        }
+
+        return httpClient.get(endpoint) {
+            if (requiresAuthentication && !sessionToken.isNullOrEmpty()) headers {
+                header("X-Session-Token", sessionToken!!)
+            }
+        }
+    }
+
+    protected suspend inline fun <reified T> performPost(endpoint: String, body: T): HttpResponse {
+        if (requiresAuthentication && sessionToken.isNullOrEmpty()) {
+            throw MissingSessionTokenException()
+        }
+        return httpClient.post(endpoint) {
+            contentType(ContentType.Application.Json)
+            setBody(body)
+
+            if (requiresAuthentication && !sessionToken.isNullOrEmpty()) headers {
+                header("X-Session-Token", sessionToken!!)
+            }
+        }
+    }
+
+    protected suspend inline fun <reified T> performDelete(endpoint: String, body: T): HttpResponse {
+        if (requiresAuthentication && sessionToken == null) {
+            throw MissingSessionTokenException()
+        }
+
+        return httpClient.delete(endpoint) {
+            contentType(ContentType.Application.Json)
+            setBody(body)
+
+            if (requiresAuthentication && !sessionToken.isNullOrEmpty()) headers {
+                header("X-Session-Token", sessionToken!!)
+            }
+        }
+    }
+
+    protected suspend inline fun <reified T> performDelete(endpoint: String): HttpResponse {
+        if (requiresAuthentication && sessionToken == null) {
+            throw MissingSessionTokenException()
+        }
+
+        return httpClient.delete(endpoint) {
+            contentType(ContentType.Application.Json)
+
+            if (requiresAuthentication && !sessionToken.isNullOrEmpty()) headers {
+                header("X-Session-Token", sessionToken!!)
+            }
+        }
+    }
+}

src/main/kotlin/com/ctrlhub/core/router/request/JsonApiIncludes.kt

@@ -0,0 +1,9 @@
+package com.ctrlhub.core.router.request
+
+/**
+ * A marker interface for includes options that can be specified
+ * when making a request
+ */
+interface JsonApiIncludes {
+    fun value(): String
+}

src/test/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouterTest.kt

@@ -30,9 +30,10 @@ class VehiclesRouterTest {
         }
 
         val vehiclesRouter = VehiclesRouter(httpClient = HttpClient(mockEngine).configureForTest())
+        vehiclesRouter.sessionToken = "sess-123"
 
         runBlocking {
-            val response = vehiclesRouter.all(sessionToken = "test-token", organisationId = "123")
+            val response = vehiclesRouter.all(organisationId = "123")
             assertIs<List<Vehicle>>(response)
             assertNotNull(response[0].id)
         }
@@ -52,9 +53,10 @@ class VehiclesRouterTest {
         }
 
         val vehiclesRouter = VehiclesRouter(httpClient = HttpClient(mockEngine).configureForTest())
+        vehiclesRouter.sessionToken = "sess-123"
 
         runBlocking {
-            val response = vehiclesRouter.all(sessionToken = "test-token", organisationId = "123", VehicleIncludes.SpecificationModel)
+            val response = vehiclesRouter.all(organisationId = "123", VehicleIncludes.SpecificationModel)
             assertIs<List<Vehicle>>(response)
             val first = response[0]
             assertNotNull(first.specification?.model)

src/test/kotlin/com/ctrlhub/core/auth/AuthRouterTest.kt

@@ -105,7 +105,7 @@ class AuthRouterTest {
 
         runBlocking {
             assertFailsWith<ApiException> {
-                authRouter.refresh("sess-123")
+                authRouter.refresh()
             }
         }
     }
@@ -123,7 +123,7 @@ class AuthRouterTest {
         val authRouter = AuthRouter(httpClient = HttpClient(mockEngine).configureForTest())
 
         runBlocking {
-            val response = authRouter.refresh("sess-123")
+            val response = authRouter.refresh()
             assertEquals("test-123", response.id)
         }
     }
@@ -141,7 +141,7 @@ class AuthRouterTest {
         val authRouter = AuthRouter(httpClient = HttpClient(mockEngine).configureForTest())
 
         runBlocking {
-            val result = authRouter.logout("dummy-session-token")
+            val result = authRouter.logout()
             assertTrue(result, "Logout should return true on success")
         }
     }
@@ -159,7 +159,7 @@ class AuthRouterTest {
         val authRouter = AuthRouter(httpClient = HttpClient(mockEngine).configureForTest())
 
         runBlocking {
-            val result = authRouter.logout("dummy-session-token")
+            val result = authRouter.logout()
             assertFalse(result, "Logout should return false on success")
         }
     }