Add samples to README

Author: mduesterhoeft

README.md

@@ -18,7 +18,9 @@ The library addresses the following aspects:
 - ease implementation of cross cutting concerns for handlers
 - ease (local) testing of REST handlers
 
-## Getting Started
+## Reference
+
+### Getting Started
 
 To use the core module we need the following:
 
@@ -51,5 +53,64 @@ class MyRequestHandler : RequestHandler() {
 }
 ```
 
+### Content Negotiation
+
+The router DSL allows for configuration of the content types a handler
+- produces (according to the request's `Accept` header)
+- consumes (according to the request's `Content-Type` header)
+
+The router itself carries a default for both values.
+
+```kotlin
+var defaultConsuming = setOf("application/json")
+var defaultProducing = setOf("application/json")
+```
+
+These defaults can be overridden on the router level or on the handler level to specify the content types most of your handlers consume and produce.
+
+```kotlin
+router {
+    defaultConsuming = setOf("application/json")
+    defaultProducing = setOf("application/json")
+}
+```
+
+Exceptions from this default can be configured on a handler level.
+
+```kotlin
+router {
+    POST("/some") { r: Request<String> -> ResponseEntity.ok(MyResponse(r.body)) }
+        .producing("application/json")
+        .consuming("application/json")
+}
+```
+
+### Filters
+
+Filters are a means to add cross-cutting concerns to your request handling logic outside a handler function.
+Multiple filters can be used by composing them.
+
+```kotlin
+override val router = router {
+        filter = loggingFilter().then(mdcFilter())
+
+        GET("/some", controller::get)
+    }
+
+    private fun loggingFilter() = Filter { next -> {
+        request ->
+            log.info("Handling request ${request.apiRequest.httpMethod} ${request.apiRequest.path}")
+            next(request) }
+    }
+
+    private fun mdcFilter() = Filter { next -> {
+        request ->
+            MDC.put("requestId", request.apiRequest.requestContext?.requestId)
+            next(request) }
+    }
+}
+```
+
+
 
 

router-protobuf/build.gradle.kts

@@ -26,6 +26,7 @@ dependencies {
     testImplementation("org.slf4j:slf4j-simple:1.7.26")
 }
 
+
 protobuf {
     protoc {
         // The artifact spec for the Protobuf Compiler

router-protobuf/src/test/kotlin/io/moia/router/proto/RequestHandlerTest.kt

@@ -7,9 +7,9 @@ import io.moia.router.Request
 import io.moia.router.ResponseEntity
 import io.moia.router.Router.Companion.router
 import io.moia.router.bodyAsBytes
+import io.moia.router.proto.sample.SampleOuterClass.Sample
 import io.mockk.mockk
 import org.junit.jupiter.api.Test
-import com.github.mduesterhoeft.router.proto.sample.SampleOuterClass.Sample
 import java.util.Base64
 
 class RequestHandlerTest {
@@ -67,9 +67,12 @@ class RequestHandlerTest {
     class TestRequestHandler : ProtoEnabledRequestHandler() {
 
         override val router = router {
+            defaultProducing = setOf("application/x-protobuf")
+            defaultConsuming = setOf("application/x-protobuf")
+
             GET("/some-proto") { _: Request<Unit> ->
                 ResponseEntity.ok(Sample.newBuilder().setHello("Hello").build())
-            }
+            }.producing("application/x-protobuf", "application/json")
             POST("/some-proto") { r: Request<Sample> ->
                 ResponseEntity.ok(r.body)
             }

router-protobuf/src/test/proto/Sample.proto

@@ -1,6 +1,6 @@
 syntax = "proto3";
 
-package com.github.mduesterhoeft.router.proto.sample;
+package io.moia.router.proto.sample;
 
 message Sample {
     string hello = 1;

router/src/main/kotlin/io/moia/router/Router.kt

@@ -6,8 +6,8 @@ class Router {
 
     val routes = mutableListOf<RouterFunction<*, *>>()
 
-    var defaultConsuming = setOf("application/json", "application/x-protobuf")
-    var defaultProducing = setOf("application/json", "application/x-protobuf")
+    var defaultConsuming = setOf("application/json")
+    var defaultProducing = setOf("application/json")
 
     var filter: Filter = Filter.NoOp
 

router/src/test/kotlin/io/moia/router/RouterTest.kt

@@ -1,7 +1,6 @@
 package io.moia.router
 
 import assertk.assert
-import assertk.assertions.containsAll
 import assertk.assertions.hasSize
 import assertk.assertions.isEmpty
 import assertk.assertions.isEqualTo
@@ -24,7 +23,47 @@ class RouterTest {
             assert(method).isEqualTo("GET")
             assert(pathPattern).isEqualTo("/some")
             assert(consumes).isEmpty()
-            assert(produces).containsAll("application/json", "application/x-protobuf")
+            assert(produces).isEqualTo(setOf("application/json"))
+        }
+    }
+
+    @Test
+    fun `should register get route with specific content types`() {
+        val router = router {
+            POST("/some") { r: Request<Unit> ->
+                ResponseEntity.ok("""{"hello": "world", "request":"${r.body}"}""")
+            }
+                .producing("text/plain")
+                .consuming("text/plain")
+        }
+
+        assert(router.routes).hasSize(1)
+        with(router.routes.first().requestPredicate) {
+            assert(method).isEqualTo("POST")
+            assert(pathPattern).isEqualTo("/some")
+            assert(consumes).isEqualTo(setOf("text/plain"))
+            assert(produces).isEqualTo(setOf("text/plain"))
+        }
+    }
+
+    @Test
+    fun `should register get route with custom default content types`() {
+        val router = router {
+
+            defaultConsuming = setOf("text/plain")
+            defaultProducing = setOf("text/plain")
+
+            POST("/some") { r: Request<Unit> ->
+                ResponseEntity.ok("""{"hello": "world", "request":"${r.body}"}""")
+            }
+        }
+
+        assert(router.routes).hasSize(1)
+        with(router.routes.first().requestPredicate) {
+            assert(method).isEqualTo("POST")
+            assert(pathPattern).isEqualTo("/some")
+            assert(consumes).isEqualTo(setOf("text/plain"))
+            assert(produces).isEqualTo(setOf("text/plain"))
         }
     }
 
@@ -37,9 +76,7 @@ class RouterTest {
         }
         assert(router.routes).hasSize(1)
         with(router.routes.first().requestPredicate) {
-            assert(method).isEqualTo("POST")
             assertTrue(UriTemplate.from(pathPattern).matches("/some/sub/sub/sub/path"))
-            assert(produces).containsAll("application/json", "application/x-protobuf")
         }
     }
 }

samples/lambda-kotlin-request-router-sample/src/main/kotlin/io/moia/router/sample/MyRequestHandler.kt

@@ -1,18 +1,45 @@
 package io.moia.router.sample
 
+import io.moia.router.Filter
 import io.moia.router.Request
 import io.moia.router.RequestHandler
 import io.moia.router.ResponseEntity
 import io.moia.router.Router.Companion.router
+import io.moia.router.getHeaderCaseInsensitive
+import io.moia.router.then
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+import org.slf4j.MDC
+import kotlin.concurrent.timer
+import kotlin.system.measureTimeMillis
 
 class MyRequestHandler : RequestHandler() {
     private val controller = SomeController()
 
     override val router = router {
+        //use filters to add cross-cutting concerns to each request
+        filter = loggingFilter().then(mdcFilter())
+
         // functions can be externalized...
         GET("/some", controller::get)
 
         // simple handlers can also be declared inline
         POST("/some") { r: Request<Sample> -> ResponseEntity.ok(r.body) }
     }
+
+    private fun loggingFilter() = Filter { next -> {
+        request ->
+            log.info("Handling request ${request.apiRequest.httpMethod} ${request.apiRequest.path}")
+            next(request) }
+    }
+
+    private fun mdcFilter() = Filter { next -> {
+        request ->
+            MDC.put("requestId", request.apiRequest.requestContext?.requestId)
+            next(request) }
+    }
+
+    companion object {
+        val log: Logger = LoggerFactory.getLogger(MyRequestHandler::class.java)
+    }
 }