Merge pull request #2 from SLNE-Development/copilot/implement-requests-and-responses

Add request-response pattern with timeout support

Author: twisti-dev

README.md

@@ -169,11 +169,175 @@ class MyPluginListener {
 }
 ```
 
+## Request-Response Pattern
+
+In addition to the event bus, surf-redis supports request-response patterns where a server can send a request and wait for a response with timeout support.
+
+### Quick Start
+
+```kotlin
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.launch
+import de.slne.redis.request.*
+
+// 1. Create your request and response (must be @Serializable)
+@Serializable
+data class GetPlayerRequest(val minLevel: Int) : RedisRequest()
+
+@Serializable
+data class PlayerListResponse(val players: List<String>) : RedisResponse()
+
+// 2. Create a request handler
+class PlayerRequestHandler {
+    @RequestHandler
+    fun handlePlayerRequest(context: RequestContext<GetPlayerRequest>) {
+        // Launch coroutine to respond asynchronously
+        context.coroutineScope.launch {
+            val players = fetchPlayersAsync(context.request.minLevel)
+            context.respond(PlayerListResponse(players))
+        }
+    }
+}
+
+// 3. Set up and use
+runBlocking {
+    val bus = RequestResponseBus("redis://localhost:6379")
+    
+    // Register handler (ServerA)
+    bus.registerRequestHandler(PlayerRequestHandler())
+    
+    // Send request and wait for response (ServerB or same server)
+    val response = bus.sendRequest<PlayerListResponse>(
+        GetPlayerRequest(minLevel = 5),
+        timeoutMs = 3000 // Default timeout is 3 seconds
+    )
+    println("Players: ${response.players}")
+}
+```
+
+### Features
+
+- 🔄 **Request-Response Pattern**: Send requests and receive typed responses
+- ⏱️ **Timeout Support**: Configurable timeout (default 3 seconds)
+- 🔀 **Bidirectional**: Any server can both send requests and respond to requests
+- 🚀 **Flexible Async**: Handlers control when to launch coroutines (not forced to be suspend)
+- 🎯 **Type-safe**: Request and response types are validated at compile time
+
+### Usage
+
+#### 1. Create Request and Response Classes
+
+```kotlin
+import de.slne.redis.request.RedisRequest
+import de.slne.redis.request.RedisResponse
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class GetPlayerRequest(val minLevel: Int) : RedisRequest()
+
+@Serializable
+data class PlayerListResponse(val players: List<String>) : RedisResponse()
+```
+
+#### 2. Create Request Handlers
+
+Handlers receive a `RequestContext` that provides:
+- `request`: The incoming request
+- `coroutineScope`: Scope for launching coroutines if needed
+- `respond(response)`: Method to send the response
+
+```kotlin
+import de.slne.redis.request.RequestHandler
+import de.slne.redis.request.RequestContext
+import kotlinx.coroutines.launch
+
+class MyRequestHandler {
+    @RequestHandler
+    fun handlePlayerRequest(context: RequestContext<GetPlayerRequest>) {
+        // Launch coroutine for async operations
+        context.coroutineScope.launch {
+            val players = fetchPlayersFromDatabaseAsync(context.request.minLevel)
+            context.respond(PlayerListResponse(players))
+        }
+    }
+}
+```
+
+#### 3. Register Handlers and Send Requests
+
+```kotlin
+import de.slne.redis.request.RequestResponseBus
+import kotlinx.coroutines.runBlocking
+
+fun main() = runBlocking {
+    val bus = RequestResponseBus("redis://localhost:6379")
+    
+    // Register handler (this server will respond to requests)
+    bus.registerRequestHandler(MyRequestHandler())
+    
+    // Send request and wait for response (with timeout)
+    try {
+        val response = bus.sendRequest<PlayerListResponse>(
+            GetPlayerRequest(minLevel = 10),
+            timeoutMs = 3000
+        )
+        println("Received ${response.players.size} players")
+    } catch (e: RequestTimeoutException) {
+        println("Request timed out: ${e.message}")
+    }
+    
+    bus.close()
+}
+```
+
+### Request-Response vs Events
+
+**Use Request-Response when:**
+- You need a reply/acknowledgment
+- You need data back from another server
+- You need to know if the operation succeeded
+- You want timeout handling
+
+**Use Events when:**
+- You want to broadcast information
+- You don't need a reply
+- Multiple servers should react to the same event
+- Fire-and-forget pattern is acceptable
+
+### Example Scenario
+
+**ServerA** (Lobby Server) and **ServerB** (Game Server):
+
+```kotlin
+// ServerA can handle requests
+class LobbyHandler {
+    @RequestHandler
+    fun getServerStatus(context: RequestContext<ServerStatusRequest>) {
+        // Respond using coroutine scope
+        context.coroutineScope.launch {
+            context.respond(ServerStatusResponse("Lobby-1", online = true, playerCount = 42))
+        }
+    }
+}
+
+// ServerB can also send requests to ServerA
+val response = bus.sendRequest<ServerStatusResponse>(
+    ServerStatusRequest("Lobby-1"),
+    timeoutMs = 3000
+)
+```
+
+Both servers can simultaneously:
+- Send requests to other servers
+- Respond to requests from other servers
+
 ## Example
 
 See the `de.slne.redis.example` package for complete examples:
 - `ExampleEvents.kt` - Example event definitions
 - `ExampleUsage.kt` - Example usage demonstrating async publishing and subscribing
+- `ExampleRequests.kt` - Example request/response definitions
+- `ExampleRequestResponseUsage.kt` - Example usage demonstrating request-response pattern
 
 ## API Reference
 
@@ -202,6 +366,46 @@ Main class for managing events with async support.
 - `fun unregisterListener(listener: Any)` - Unregister a listener and all its handlers
 - `fun close()` - Close connections and clean up resources
 
+### RedisRequest
+
+Base class for all requests. Extend this to create custom requests. Must be annotated with `@Serializable`.
+
+### RedisResponse
+
+Base class for all responses. Extend this to create custom responses. Must be annotated with `@Serializable`.
+
+### @RequestHandler
+
+Annotation for marking request handler methods. Methods must:
+- Have exactly one parameter of type `RequestContext<TRequest>`
+- Return void (Unit)
+- Handler controls when/how to respond using `context.respond()`
+
+### RequestContext<TRequest>
+
+Context object provided to request handlers containing:
+- `request: TRequest` - The incoming request
+- `coroutineScope: CoroutineScope` - Scope for launching coroutines if needed
+- `suspend fun respond(response: RedisResponse)` - Send the response
+
+### RequestResponseBus
+
+Main class for managing request-response patterns with async support and timeout handling.
+
+**Constructor:**
+- `RequestResponseBus(redisUri: String, coroutineScope: CoroutineScope = ...)` - Create a new request-response bus connected to Redis
+
+**Methods:**
+- `suspend fun <T : RedisResponse> sendRequest(request: RedisRequest, timeoutMs: Long = 3000): T` - Send a request and wait for response asynchronously
+- `fun <T : RedisResponse> sendRequestBlocking(request: RedisRequest, timeoutMs: Long = 3000): T` - Send a request and wait for response synchronously (blocking)
+- `fun registerRequestHandler(handler: Any)` - Register an object with @RequestHandler methods
+- `fun unregisterRequestHandler(handler: Any)` - Unregister a handler and all its request handlers
+- `fun close()` - Close connections and clean up resources
+
+### RequestTimeoutException
+
+Exception thrown when a request times out without receiving a response.
+
 ## License
 
 This project is open source and available under the MIT License.

build.gradle.kts

@@ -26,6 +26,9 @@ dependencies {
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor:1.7.3")
 
+    // Fastutil for high-performance collections
+    implementation("it.unimi.dsi:fastutil:8.5.12")
+    
     // Test dependencies
     testImplementation(kotlin("test"))
     testImplementation("org.junit.jupiter:junit-jupiter:5.10.1")

src/main/kotlin/de/slne/redis/example/request/ExampleRequestResponseUsage.kt

@@ -0,0 +1,98 @@
+package de.slne.redis.example.request
+
+import de.slne.redis.request.RequestContext
+import de.slne.redis.request.RequestHandler
+import de.slne.redis.request.RequestResponseBus
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
+
+/**
+ * Example request handler demonstrating how to handle requests and send responses.
+ */
+class ExampleRequestHandler {
+    
+    @RequestHandler
+    fun handlePlayerRequest(context: RequestContext<GetPlayerRequest>) {
+        // Launch coroutine to respond asynchronously (if needed)
+        context.coroutineScope.launch {
+            // Simulate some async work (e.g., database query)
+            delay(100)
+            
+            // Filter players based on minimum level
+            val allPlayers = listOf("Steve", "Alex", "Notch", "Herobrine", "Jeb")
+            val filteredPlayers = if (context.request.minLevel > 5) {
+                allPlayers.take(2)  // Only high-level players
+            } else {
+                allPlayers
+            }
+            
+            context.respond(PlayerListResponse(filteredPlayers))
+        }
+    }
+    
+    @RequestHandler
+    fun handleServerStatus(context: RequestContext<ServerStatusRequest>) {
+        // Respond synchronously by launching in runBlocking or use coroutineScope.launch for async
+        context.coroutineScope.launch {
+            // Simulate checking server status
+            delay(50)
+            
+            context.respond(ServerStatusResponse(
+                serverName = context.request.serverName,
+                online = true,
+                playerCount = 42
+            ))
+        }
+    }
+}
+
+/**
+ * Example usage of the RequestResponseBus demonstrating request/response pattern
+ */
+fun main() = runBlocking {
+    // Create request-response bus with Redis connection URI
+    val requestResponseBus = RequestResponseBus("redis://localhost:6379")
+    
+    // Register a request handler (this is the server that responds to requests)
+    val handler = ExampleRequestHandler()
+    requestResponseBus.registerRequestHandler(handler)
+    
+    println("Server ready - listening for requests...")
+    
+    // Simulate a client sending requests after a short delay
+    delay(500)
+    
+    try {
+        // Send a request and wait for response
+        println("Sending GetPlayerRequest with minLevel=5...")
+        val response1 = requestResponseBus.sendRequest<PlayerListResponse>(
+            GetPlayerRequest(minLevel = 5),
+            timeoutMs = 3000
+        )
+        println("Received response: ${response1.players}")
+        
+        // Send another request
+        println("\nSending ServerStatusRequest...")
+        val response2 = requestResponseBus.sendRequest<ServerStatusResponse>(
+            ServerStatusRequest("Lobby-1"),
+            timeoutMs = 3000
+        )
+        println("Server status: ${response2.serverName} - Online: ${response2.online}, Players: ${response2.playerCount}")
+        
+    } catch (e: Exception) {
+        println("Error: ${e.message}")
+        e.printStackTrace()
+    }
+    
+    // Keep the application running to handle more requests
+    println("\nPress Ctrl+C to exit")
+    
+    Runtime.getRuntime().addShutdownHook(Thread {
+        println("Shutting down...")
+        requestResponseBus.close()
+    })
+    
+    // Wait indefinitely
+    Thread.currentThread().join()
+}

src/main/kotlin/de/slne/redis/example/request/ExampleRequests.kt

@@ -0,0 +1,33 @@
+package de.slne.redis.example.request
+
+import de.slne.redis.request.RedisRequest
+import de.slne.redis.request.RedisResponse
+import kotlinx.serialization.Serializable
+
+/**
+ * Example request: Get players with a minimum level
+ */
+@Serializable
+data class GetPlayerRequest(val minLevel: Int) : RedisRequest()
+
+/**
+ * Example response: List of player names
+ */
+@Serializable
+data class PlayerListResponse(val players: List<String>) : RedisResponse()
+
+/**
+ * Example request: Get server status
+ */
+@Serializable
+data class ServerStatusRequest(val serverName: String) : RedisRequest()
+
+/**
+ * Example response: Server status information
+ */
+@Serializable
+data class ServerStatusResponse(
+    val serverName: String,
+    val online: Boolean,
+    val playerCount: Int
+) : RedisResponse()