Update docs, add helper

Author: MukjepScarlet

README.md

@@ -60,25 +60,41 @@ Here is an example of how to use the library to create a simple "Hello, World!"
 ```kotlin
 import com.google.gson.JsonObject
 import net.ccbluex.netty.http.HttpServer
-import net.ccbluex.netty.http.util.httpOk
+import net.ccbluex.netty.http.routing.Routing
+import net.ccbluex.netty.http.routing.RoutingContext
 
 suspend fun main() {
     val server = HttpServer()
 
     server.routing {
-        get("/hello") {
-            httpOk(JsonObject().apply {
-                addProperty("message", "Hello, World!")
-            })
-        }
+        helloRoutes()
     }
 
     server.start(8080)  // Start the server on port 8080
 }
+
+fun Routing.helloRoutes() {
+    get("/hello") { getHello() }
+}
+
+private suspend fun RoutingContext.getHello() {
+    respond(JsonObject().apply {
+        addProperty("message", "Hello, World!")
+    })
+}
 ```
 
 In this example, the server listens on port `8080` and responds with a JSON message `"Hello, World!"` when accessing the `/hello` endpoint.
 
+### Responding and aborting
+
+`RoutingContext` handlers should either:
+
+1. Call `respond(...)`, `respondNoContent()`, `respondFile(...)`, or `respondFileStream(...)`, or
+2. Abort with `badRequest(...)`, `forbidden(...)`, `unauthorized(...)`, `notFound(...)`, `serviceUnavailable(...)`, or `internalServerError(...)`.
+
+The abort helpers throw an internal `ResponseException` to stop the handler immediately, so they should not be wrapped in a broad `catch (Exception)` unless you rethrow that control-flow exception.
+
 ### Examples
 
 You can find additional examples in the `/examples` folder of the repository. These include:
@@ -119,4 +135,3 @@ Netty HttpServer is developed and maintained by CCBlueX. It was originally part
 ---
 
 Feel free to explore the examples provided and adapt them to your specific needs. Happy coding!
-

src/main/kotlin/net/ccbluex/netty/http/application/ApplicationCall.kt

@@ -2,6 +2,7 @@ package net.ccbluex.netty.http.application
 
 import com.google.gson.Gson
 import com.google.gson.JsonElement
+import io.netty.buffer.PooledByteBufAllocator
 import io.netty.handler.codec.http.FullHttpResponse
 import io.netty.handler.codec.http.HttpHeaders
 import io.netty.handler.codec.http.HttpMethod
@@ -15,9 +16,14 @@ import net.ccbluex.netty.http.util.httpInternalServerError
 import net.ccbluex.netty.http.util.httpNoContent
 import net.ccbluex.netty.http.util.httpNotFound
 import net.ccbluex.netty.http.util.httpResponse
+import net.ccbluex.netty.http.util.httpServiceUnavailable
 import net.ccbluex.netty.http.util.httpUnauthorized
+import net.ccbluex.netty.http.util.inputStream
+import net.ccbluex.netty.http.util.outputStream
+import net.ccbluex.netty.http.util.tika
 import java.io.File
 import java.io.InputStream
+import java.io.OutputStream
 
 open class ApplicationCall(
     val uri: String,
@@ -75,6 +81,23 @@ open class ApplicationCall(
         respond(httpFileStream(stream, contentType, contentLength))
     }
 
+    @JvmOverloads
+    fun respondOutputStream(
+        contentType: String? = null,
+        status: HttpResponseStatus = HttpResponseStatus.OK,
+        contentLength: Int = 256,
+        producer: OutputStream.() -> Unit,
+    ) {
+        val allocator = PooledByteBufAllocator.DEFAULT
+        val buf = allocator.buffer(contentLength)
+
+        buf.outputStream().use {
+            producer(it)
+        }
+
+        respond(httpResponse(status, contentType ?: tika.detect(buf.duplicate().inputStream()), buf))
+    }
+
     fun takeResponse(): FullHttpResponse {
         return response ?: throw IllegalStateException("Route handler completed without responding for $method $path")
     }
@@ -87,6 +110,8 @@ open class ApplicationCall(
 
     fun notFound(path: String, reason: String): Nothing = abort(httpNotFound(path, reason))
 
+    fun serviceUnavailable(reason: String): Nothing = abort(httpServiceUnavailable(reason))
+
     fun internalServerError(reason: String): Nothing = abort(httpInternalServerError(reason))
 
     private fun abort(response: FullHttpResponse): Nothing = throw ResponseException(response)

src/main/kotlin/net/ccbluex/netty/http/routing/RoutingContext.kt

@@ -9,7 +9,6 @@ import net.ccbluex.netty.http.application.ApplicationCall
 import net.ccbluex.netty.http.rest.Node
 import java.io.File
 import java.io.InputStream
-import java.lang.reflect.Type
 
 typealias RoutingHandler = suspend RoutingContext.() -> Unit
 
@@ -56,5 +55,6 @@ class RoutingContext(
     fun forbidden(reason: String): Nothing = call.forbidden(reason)
     fun unauthorized(reason: String): Nothing = call.unauthorized(reason)
     fun notFound(path: String, reason: String): Nothing = call.notFound(path, reason)
+    fun serviceUnavailable(reason: String): Nothing = call.serviceUnavailable(reason)
     fun internalServerError(reason: String): Nothing = call.internalServerError(reason)
 }

src/main/kotlin/net/ccbluex/netty/http/util/HttpResponse.kt

@@ -169,7 +169,7 @@ fun httpBadRequest(reason: String): FullHttpResponse {
     return httpResponse(HttpResponseStatus.BAD_REQUEST, ResponseBody(reason))
 }
 
-private val tika = Tika()
+internal val tika = Tika()
 
 /**
  * Creates an HTTP response for the given file.

src/test/kotlin/HttpServerTest.kt

@@ -122,6 +122,14 @@ class HttpServerTest {
         get("/v/:name") { param() }
         get("/r/:value1/:value2") { params() }
         get("/o/:value1/in/:value2") { params() }
+        route("/errors") {
+            get("/bad-request") {
+                badRequest("Bad request")
+            }
+            get("/service-unavailable") {
+                serviceUnavailable("Service unavailable")
+            }
+        }
     }
 
     private fun Routing.nestedRoutes() {
@@ -355,6 +363,29 @@ class HttpServerTest {
         assertEquals(404, response.code, "Expected status code 404")
     }
 
+    @Test
+    fun testBadRequestAbortEndpoint() {
+        val response = makeRequest("/errors/bad-request")
+        assertEquals(400, response.code, "Expected status code 400")
+
+        val responseBody = response.body?.string()
+        assertNotNull(responseBody, "Response body should not be null")
+        assertTrue(responseBody.contains("\"reason\":\"Bad request\""), "Response should contain the abort reason")
+    }
+
+    @Test
+    fun testServiceUnavailableAbortEndpoint() {
+        val response = makeRequest("/errors/service-unavailable")
+        assertEquals(503, response.code, "Expected status code 503")
+
+        val responseBody = response.body?.string()
+        assertNotNull(responseBody, "Response body should not be null")
+        assertTrue(
+            responseBody.contains("\"reason\":\"Service unavailable\""),
+            "Response should contain the abort reason"
+        )
+    }
+
     @Test
     fun testFileEndpoint() {
         testFileEndpoint("/abc")