fix: interceptors contract, annotation on experimental status

Author: y9vad9

router-core/src/commonMain/kotlin/com.y9vad9.rsocket.router/Route.kt

@@ -2,6 +2,7 @@
 
 package com.y9vad9.rsocket.router
 
+import com.y9vad9.rsocket.router.annotations.ExperimentalInterceptorsApi
 import com.y9vad9.rsocket.router.annotations.ExperimentalRouterApi
 import com.y9vad9.rsocket.router.interceptors.Preprocessor
 import com.y9vad9.rsocket.router.interceptors.RouteInterceptor
@@ -13,41 +14,42 @@ import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.withContext
 import kotlin.coroutines.CoroutineContext
 
-@OptIn(ExperimentalRouterApi::class)
+@OptIn(ExperimentalInterceptorsApi::class, ExperimentalRouterApi::class)
 public data class Route internal constructor(
     val path: String,
     @property:ExperimentalRouterApi
     internal val requests: Requests,
-    val preprocessors: List<Preprocessor<*, *>>,
-    val interceptors: List<RouteInterceptor<*, *>>,
+    @property:ExperimentalInterceptorsApi
+    val preprocessors: List<Preprocessor>,
+    @property:ExperimentalInterceptorsApi
+    val interceptors: List<RouteInterceptor>,
 ) {
-    public suspend fun fireAndForgetOrThrow(rSocket: RSocket, payload: Payload) {
+    public suspend fun fireAndForgetOrThrow(payload: Payload) {
         processPayload(payload) { payload ->
-            requests.fireAndForget?.invoke(rSocket, payload)
+            requests.fireAndForget?.invoke(payload)
                 ?: throwInvalidRequestOnRoute("fireAndForget")
         }
     }
 
-    public suspend fun requestResponseOrThrow(rSocket: RSocket, payload: Payload): Payload {
+    public suspend fun requestResponseOrThrow(payload: Payload): Payload {
         return processPayload(payload) { payload ->
-            requests.requestResponse?.invoke(rSocket, payload)
+            requests.requestResponse?.invoke(payload)
                 ?: throwInvalidRequestOnRoute("requestResponse")
         }
     }
 
-    public suspend fun requestStreamOrThrow(rSocket: RSocket, payload: Payload): Flow<Payload> {
+    public suspend fun requestStreamOrThrow(payload: Payload): Flow<Payload> {
         return processPayload(payload) { payload ->
-            requests.requestStream?.invoke(rSocket, payload)
+            requests.requestStream?.invoke(payload)
                 ?: throwInvalidRequestOnRoute("requestStream")
         }
     }
 
     public suspend fun requestChannelOrThrow(
-        rSocket: RSocket,
         initPayload: Payload,
         payloads: Flow<Payload>,
     ): Flow<Payload> = processPayload(initPayload) { initialPayload ->
-        requests.requestChannel?.invoke(rSocket, initialPayload, payloads)
+        requests.requestChannel?.invoke(initialPayload, payloads)
             ?: throwInvalidRequestOnRoute("requestChannel")
     }
 
@@ -57,9 +59,9 @@ public data class Route internal constructor(
         val payload =
             interceptors.fold(payload) { acc, interceptor ->
                 when (interceptor) {
-                    is RouteInterceptor.Modifier -> interceptor.intercept(acc)
+                    is RouteInterceptor.Modifier -> interceptor.intercept(path, acc)
                     is RouteInterceptor.CoroutineContext -> {
-                        coroutineContext = interceptor.intercept(coroutineContext, acc)
+                        coroutineContext = interceptor.intercept(path, coroutineContext, acc)
                         acc
                     }
                 }
@@ -71,12 +73,19 @@ public data class Route internal constructor(
     }
 
     internal data class Requests(
-        val fireAndForget: (suspend RSocket.(payload: Payload) -> Unit)? = null,
-        val requestResponse: (suspend RSocket.(payload: Payload) -> Payload)? = null,
-        val requestStream: (suspend RSocket.(payload: Payload) -> Flow<Payload>)? = null,
-        val requestChannel: (suspend RSocket.(initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>)? = null,
+        val fireAndForget: (suspend (payload: Payload) -> Unit)? = null,
+        val requestResponse: (suspend (payload: Payload) -> Payload)? = null,
+        val requestStream: (suspend (payload: Payload) -> Flow<Payload>)? = null,
+        val requestChannel: (suspend (initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>)? = null,
     )
 }
 
 private fun Route.throwInvalidRequestOnRoute(requestType: String): Nothing =
-    throw RSocketError.Invalid("No `$requestType` is registered for `$path` route.")
+    throw RSocketError.Invalid("No `$requestType` is registered for `$path` route.")
+
+@OptIn(ExperimentalInterceptorsApi::class)
+public class MyRouteInterceptor : RouteInterceptor.Modifier {
+    override fun intercept(route: String, input: Payload): Payload {
+        return Payload.Empty // just for example
+    }
+}

router-core/src/commonMain/kotlin/com.y9vad9.rsocket.router/Router.kt

@@ -1,5 +1,6 @@
 package com.y9vad9.rsocket.router
 
+import com.y9vad9.rsocket.router.annotations.ExperimentalInterceptorsApi
 import io.ktor.utils.io.core.*
 import com.y9vad9.rsocket.router.annotations.ExperimentalRouterApi
 import com.y9vad9.rsocket.router.annotations.InternalRouterApi
@@ -28,14 +29,14 @@ public sealed interface Router {
      * Preprocessors are always run before any processing from router. They're
      * experimental due to considerations of better API.
      */
-    @ExperimentalRouterApi
-    public val preprocessors: List<Preprocessor<*, *>>
+    @ExperimentalInterceptorsApi
+    public val preprocessors: List<Preprocessor>
 
     /**
      * The list of interceptors that are shared to all the routes.
      */
-    @ExperimentalRouterApi
-    public val sharedInterceptors: List<RouteInterceptor<*, *>>
+    @ExperimentalInterceptorsApi
+    public val sharedInterceptors: List<RouteInterceptor>
 
     /**
      * Retrieves route based on given [path].
@@ -66,22 +67,22 @@ public fun router(builder: RouterBuilder.() -> Unit): Router = RouterBuilder().a
 public fun Router.installOn(handlerBuilder: RSocketRequestHandlerBuilder): Unit = with(handlerBuilder) {
     requestResponse { payload ->
         routeAtOrFail(getRoutePathFromMetadata(payload.metadata))
-            .requestResponseOrThrow(this, payload)
+            .requestResponseOrThrow(payload)
     }
 
     requestStream { payload ->
         routeAtOrFail(getRoutePathFromMetadata(payload.metadata))
-            .requestStreamOrThrow(this, payload)
+            .requestStreamOrThrow(payload)
     }
 
     requestChannel { initPayload, payloads ->
         routeAtOrFail(getRoutePathFromMetadata(initPayload.metadata))
-            .requestChannelOrThrow(this, initPayload, payloads)
+            .requestChannelOrThrow(initPayload, payloads)
     }
 
     fireAndForget { payload ->
         routeAtOrFail(getRoutePathFromMetadata(payload.metadata))
-            .fireAndForgetOrThrow(this, payload)
+            .fireAndForgetOrThrow(payload)
     }
 }
 
@@ -104,12 +105,12 @@ public fun Router.routeAtOrFail(path: String): Route =
 
 // -- internal implementation --
 
-internal class RouterImpl @ExperimentalRouterApi constructor(
+internal class RouterImpl @[ExperimentalRouterApi ExperimentalInterceptorsApi] constructor(
     override val routeSeparator: Char,
     @property:ExperimentalRouterApi
-    override val preprocessors: List<Preprocessor<*, *>>,
+    override val preprocessors: List<Preprocessor>,
     @property:ExperimentalRouterApi
-    override val sharedInterceptors: List<RouteInterceptor<*, *>>,
+    override val sharedInterceptors: List<RouteInterceptor>,
     private val routes: Map<String, Route>,
     private var routeProvider: suspend (metadata: ByteReadPacket?) -> String,
 ) : Router {

router-core/src/commonMain/kotlin/com.y9vad9.rsocket.router/builders/DeclarableRoutingBuilder.kt

@@ -1,5 +1,6 @@
 package com.y9vad9.rsocket.router.builders
 
+import com.y9vad9.rsocket.router.annotations.ExperimentalInterceptorsApi
 import io.rsocket.kotlin.RSocket
 import io.rsocket.kotlin.payload.Payload
 import com.y9vad9.rsocket.router.annotations.ExperimentalRouterApi
@@ -17,7 +18,7 @@ public interface DeclarableRoutingBuilder : RoutingBuilder {
      *              This lambda is responsible for processing the payload and generating the response.
      * @return The response Payload from the server.
      */
-    public fun requestResponse(block: suspend RSocket.(payload: Payload) -> Payload)
+    public fun requestResponse(block: suspend (payload: Payload) -> Payload)
 
     /**
      * Makes a stream request to the RSocket with the provided [Payload] and returns a [Flow] of [Payload] as the response.
@@ -31,7 +32,7 @@ public interface DeclarableRoutingBuilder : RoutingBuilder {
      *
      * @throws Exception if any error occurs during the stream request or handling.
      */
-    public fun requestStream(block: suspend RSocket.(payload: Payload) -> Flow<Payload>)
+    public fun requestStream(block: suspend (payload: Payload) -> Flow<Payload>)
 
     /**
      * Requests a channel within RSocket in current route.
@@ -42,7 +43,7 @@ public interface DeclarableRoutingBuilder : RoutingBuilder {
      *              The block should return a flow of payloads received from the channel.
      * @return A flow of payloads received from the channel.
      */
-    public fun requestChannel(block: suspend (RSocket.(initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>))
+    public fun requestChannel(block: suspend (initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>)
 
     /**
      * Executes the given [block] in a fire-and-forget manner.
@@ -55,14 +56,14 @@ public interface DeclarableRoutingBuilder : RoutingBuilder {
      *              It takes an RSocket instance and a Payload object as parameters.
      *              The block is responsible for processing the Payload object accordingly.
      */
-    public fun fireAndForget(block: suspend RSocket.(payload: Payload) -> Unit)
+    public fun fireAndForget(block: suspend (payload: Payload) -> Unit)
 
     /**
      * Registers interceptor for current route and its sub-routes.
      *
      * **Experimental** due to considering better design for API.
      */
-    @ExperimentalRouterApi
+    @ExperimentalInterceptorsApi
     public fun interceptors(
         builder: RouteInterceptorsBuilder.() -> Unit,
     )
@@ -73,28 +74,28 @@ public interface DeclarableRoutingBuilder : RoutingBuilder {
 
 public fun DeclarableRoutingBuilder.requestResponse(
     route: String,
-    block: suspend RSocket.(payload: Payload) -> Payload
+    block: suspend (payload: Payload) -> Payload
 ): Unit = route(route) {
     requestResponse(block)
 }
 
 public fun DeclarableRoutingBuilder.requestChannel(
     route: String,
-    block: suspend (RSocket.(initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>)
+    block: suspend (initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>
 ): Unit = route(route) {
     requestChannel(block)
 }
 
 public fun DeclarableRoutingBuilder.requestStream(
     route: String,
-    block: suspend RSocket.(payload: Payload) -> Flow<Payload>
+    block: suspend (payload: Payload) -> Flow<Payload>
 ): Unit = route(route) {
     requestStream(block)
 }
 
 public fun DeclarableRoutingBuilder.fireAndForget(
     route: String,
-    block: suspend RSocket.(payload: Payload) -> Unit
+    block: suspend (payload: Payload) -> Unit
 ): Unit = route(route) {
     fireAndForget(block)
 }

router-core/src/commonMain/kotlin/com.y9vad9.rsocket.router/builders/RouterBuilder.kt

@@ -3,6 +3,7 @@ package com.y9vad9.rsocket.router.builders
 import io.ktor.utils.io.core.*
 import com.y9vad9.rsocket.router.Router
 import com.y9vad9.rsocket.router.RouterImpl
+import com.y9vad9.rsocket.router.annotations.ExperimentalInterceptorsApi
 import com.y9vad9.rsocket.router.annotations.ExperimentalRouterApi
 import com.y9vad9.rsocket.router.annotations.InternalRouterApi
 import com.y9vad9.rsocket.router.annotations.RouterDsl
@@ -14,10 +15,10 @@ import com.y9vad9.rsocket.router.interceptors.builder.RouteInterceptorsBuilder
 
 @RouterDsl
 public class RouterBuilder @InternalRouterApi constructor() {
-    @ExperimentalRouterApi
-    private var preprocessors: List<Preprocessor<*, *>>? = null
-    @ExperimentalRouterApi
-    private var sharedInterceptors: List<RouteInterceptor<*, *>>? = null
+    @ExperimentalInterceptorsApi
+    private var preprocessors: List<Preprocessor>? = null
+    @ExperimentalInterceptorsApi
+    private var sharedInterceptors: List<RouteInterceptor>? = null
 
     private var routingConfiguration: (RoutingBuilder.() -> Unit)? = null
 
@@ -42,13 +43,13 @@ public class RouterBuilder @InternalRouterApi constructor() {
      *
      * @param builder The lambda function where the preprocessors are configured using the `PreprocessorsBuilder`.
      */
-    @ExperimentalRouterApi
+    @ExperimentalInterceptorsApi
     public fun preprocessors(builder: PreprocessorsBuilder.() -> Unit) {
         require(preprocessors == null) { "preprocessors should be defined once." }
         preprocessors = PreprocessorsBuilder().apply(builder).build()
     }
 
-    @ExperimentalRouterApi
+    @ExperimentalInterceptorsApi
     public fun sharedInterceptors(builder: RouteInterceptorsBuilder.() -> Unit) {
         require(sharedInterceptors == null) { "sharedInterceptors should be defined once." }
         sharedInterceptors = RouteInterceptorsBuilder().apply(builder).build()
@@ -66,7 +67,7 @@ public class RouterBuilder @InternalRouterApi constructor() {
         routingConfiguration = block
     }
 
-    @OptIn(ExperimentalRouterApi::class)
+    @OptIn(ExperimentalRouterApi::class, ExperimentalInterceptorsApi::class)
     @InternalRouterApi
     public fun build(): Router {
         require(routingConfiguration != null) { "routing should be defined" }

router-core/src/commonMain/kotlin/com.y9vad9.rsocket.router/builders/impl/DeclarableRoutingBuilderScopeImpl.kt

@@ -14,35 +14,35 @@ import kotlinx.coroutines.flow.Flow
 internal class DeclarableRoutingBuilderScopeImpl(
     private val path: String,
     private val separator: Char,
-    private val inheritedInterceptors: List<RouteInterceptor<*, *>>,
-    private val preprocessors: List<Preprocessor<*, *>>,
+    private val inheritedInterceptors: List<RouteInterceptor>,
+    private val preprocessors: List<Preprocessor>,
 ) : DeclarableRoutingBuilder {
-    private var currentInterceptors: List<RouteInterceptor<*, *>>? = null
+    private var currentInterceptors: List<RouteInterceptor>? = null
     private var requests = Route.Requests()
     private val subRoutes = mutableMapOf<String, Route>()
 
-    override fun requestResponse(block: suspend RSocket.(payload: Payload) -> Payload) {
+    override fun requestResponse(block: suspend (payload: Payload) -> Payload) {
         require(requests.requestResponse == null) { "Request-Response is already defined." }
         requests = requests.copy(
             requestResponse = block,
         )
     }
 
-    override fun requestStream(block: suspend RSocket.(payload: Payload) -> Flow<Payload>) {
+    override fun requestStream(block: suspend (payload: Payload) -> Flow<Payload>) {
         require(requests.requestResponse == null) { "Request-Stream is already defined." }
         requests = requests.copy(
             requestStream = block,
         )
     }
 
-    override fun requestChannel(block: suspend RSocket.(initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>) {
+    override fun requestChannel(block: suspend (initPayload: Payload, payloads: Flow<Payload>) -> Flow<Payload>) {
         require(requests.requestChannel == null) { "Request-Channel is already defined." }
         requests = requests.copy(
             requestChannel = block,
         )
     }
 
-    override fun fireAndForget(block: suspend RSocket.(payload: Payload) -> Unit) {
+    override fun fireAndForget(block: suspend (payload: Payload) -> Unit) {
         require(requests.fireAndForget == null) { "Fire-and-Forget is already defined." }
         requests = requests.copy(
             fireAndForget = block,

router-core/src/commonMain/kotlin/com.y9vad9.rsocket.router/builders/impl/RoutingBuilderScopeImpl.kt

@@ -10,8 +10,8 @@ import com.y9vad9.rsocket.router.interceptors.RouteInterceptor
 @OptIn(ExperimentalRouterApi::class)
 internal class RoutingBuilderScopeImpl(
     private val separator: Char,
-    private val sharedInterceptors: List<RouteInterceptor<*, *>>,
-    private val preprocessors: List<Preprocessor<*, *>>,
+    private val sharedInterceptors: List<RouteInterceptor>,
+    private val preprocessors: List<Preprocessor>,
 ) : RoutingBuilder {
     private val subRoutes = mutableMapOf<String, Route>()