feat(events): migrate game-creation and bot flows to Redis Streams NCS-89 (#62)

Replace synchronous account→core game-creation HTTP call and plain
pub/sub bot game-start events with Redis Streams using consumer groups,
XACK, retry, and a Dead Letter Queue for at-least-once delivery and
observability.

- account: GameCreationStreamClient publishes game-creation requests and
  correlates responses via a per-instance consumer group (NCS-91)
- core: GameCreationStreamListener consumes requests, calls
  GameCreationService, publishes response events, retries, and routes
  exhausted/unparseable events to the DLQ (NCS-91, NCS-93, NCS-94)
- official-bots: bot game-start events migrated from pub/sub to Streams
  with consumer group, XACK, retry, and DLQ (NCS-92)
- account EventPublisher dual-writes to the stream and legacy pub/sub
  channel for backward compatibility
- all flows use the typed EventEnvelope (eventId/type/payload/timestamp/
  correlationId) with DLQ error context (eventType, error, attempt)
- register new DTOs and EventEnvelope/EventType for native reflection

Closes NCS-91, NCS-92, NCS-93, NCS-94

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Janis Eccarius <eccariusjanis@gmail.com>
Reviewed-on: #62

modules/core/build.gradle.kts

@@ -138,6 +138,8 @@ tasks.withType(org.gradle.api.tasks.scala.ScalaCompile::class).configureEach {
             exclude("**/resource/GameDtoMapper.scala")
             exclude("**/resource/GameResource.scala")
             exclude("**/redis/GameRedis*.scala")
+            exclude("**/redis/GameCreationStreamListener.scala")
+            exclude("**/service/GameCreationService.scala")
         }
     }
 }

modules/core/src/main/scala/de/nowchess/chess/config/NativeReflectionConfig.scala

@@ -2,6 +2,7 @@ package de.nowchess.chess.config
 
 import de.nowchess.api.board.{CastlingRights, Color, File, Piece, PieceType, Rank, Square}
 import de.nowchess.api.dto.*
+import de.nowchess.api.event.{EventEnvelope, EventType}
 import de.nowchess.api.game.{DrawReason, GameContext, GameMode, GameResult}
 import de.nowchess.api.move.{Move, MoveType, PromotionPiece}
 import de.nowchess.chess.registry.GameCacheDto
@@ -13,6 +14,10 @@ import io.quarkus.runtime.annotations.RegisterForReflection
     classOf[GameCacheDto],
     classOf[ClockDto],
     classOf[CreateGameRequestDto],
+    classOf[GameCreationRequestDto],
+    classOf[GameCreationResponseDto],
+    classOf[EventEnvelope],
+    classOf[EventType],
     classOf[ErrorEventDto],
     classOf[GameWritebackEventDto],
     classOf[GameFullDto],

modules/core/src/main/scala/de/nowchess/chess/redis/GameCreationStreamListener.scala

@@ -0,0 +1,146 @@
+package de.nowchess.chess.redis
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import de.nowchess.api.dto.{GameCreationRequestDto, GameCreationResponseDto}
+import de.nowchess.api.event.{EventEnvelope, EventType}
+import de.nowchess.chess.config.RedisConfig
+import de.nowchess.chess.service.GameCreationService
+import io.quarkus.redis.datasource.RedisDataSource
+import io.quarkus.redis.datasource.stream.{StreamMessage, XAddArgs, XGroupCreateArgs, XReadGroupArgs}
+import io.quarkus.runtime.StartupEvent
+import jakarta.enterprise.context.ApplicationScoped
+import jakarta.enterprise.event.Observes
+import jakarta.inject.Inject
+import org.eclipse.microprofile.config.inject.ConfigProperty
+import org.eclipse.microprofile.context.ManagedExecutor
+import org.jboss.logging.Logger
+import scala.compiletime.uninitialized
+import scala.jdk.CollectionConverters.*
+import scala.util.{Failure, Success, Try}
+import java.time.Duration
+import java.util.UUID
+
+@ApplicationScoped
+class GameCreationStreamListener:
+
+  // scalafix:off DisableSyntax.var
+  @Inject var redis: RedisDataSource               = uninitialized
+  @Inject var objectMapper: ObjectMapper           = uninitialized
+  @Inject var creationService: GameCreationService = uninitialized
+  @Inject var executor: ManagedExecutor            = uninitialized
+  @Inject var redisConfig: RedisConfig             = uninitialized
+  @ConfigProperty(name = "nowchess.game-creation-stream.enabled", defaultValue = "true")
+  private var streamEnabled: Boolean = true
+  // scalafix:on DisableSyntax.var
+
+  private val log          = Logger.getLogger(classOf[GameCreationStreamListener])
+  private val groupName    = "core-game-creation"
+  private val consumerId   = UUID.randomUUID().toString
+  private val maxRetries   = 3
+  private val maxStreamLen = 1000L
+
+  private def requestStream: String  = s"${redisConfig.prefix}:game-creation"
+  private def responseStream: String = s"${redisConfig.prefix}:game-creation-response"
+  private def dlqStream: String      = s"${redisConfig.prefix}:dlq"
+
+  def start(@Observes _ev: StartupEvent): Unit =
+    if streamEnabled then
+      createGroupIfAbsent()
+      executor.submit(
+        new Runnable:
+          def run(): Unit = pollLoop(),
+      )
+      log.infof("Game-creation request listener started (consumer=%s)", consumerId)
+
+  private def createGroupIfAbsent(): Unit =
+    Try(
+      redis
+        .stream(classOf[String])
+        .xgroupCreate(requestStream, groupName, "0", new XGroupCreateArgs().mkstream()),
+    ) match
+      case Failure(ex) if Option(ex.getMessage).exists(_.contains("BUSYGROUP")) => ()
+      case Failure(ex) => log.warnf(ex, "Failed to create game-creation consumer group")
+      case Success(_)  => ()
+
+  private def pollLoop(): Unit =
+    while true do
+      Try {
+        val messages = redis
+          .stream(classOf[String])
+          .xreadgroup(
+            groupName,
+            consumerId,
+            requestStream,
+            ">",
+            new XReadGroupArgs().count(10).block(Duration.ofSeconds(2)),
+          )
+        Option(messages).foreach(_.forEach(handleMessage))
+      } match
+        case Failure(ex) => log.warnf(ex, "Error in game-creation poll loop")
+        case Success(_)  => ()
+
+  private def handleMessage(msg: StreamMessage[String, String, String]): Unit =
+    val json    = msg.payload().get("data")
+    val attempt = Option(msg.payload().get("attempt")).flatMap(_.toIntOption).getOrElse(0)
+    Try(objectMapper.readValue(json, classOf[EventEnvelope])) match
+      case Failure(ex) =>
+        log.errorf(ex, "Unparseable game-creation event, sending to DLQ: %s", json)
+        toDlq(EventType.GameCreationRequest.toString, json, ex, attempt)
+        ack(msg.id())
+      case Success(envelope) =>
+        processEnvelope(msg, envelope, json, attempt)
+
+  private def processEnvelope(
+      msg: StreamMessage[String, String, String],
+      envelope: EventEnvelope,
+      json: String,
+      attempt: Int,
+  ): Unit =
+    Try {
+      val req   = objectMapper.treeToValue(envelope.payload, classOf[GameCreationRequestDto])
+      val entry = creationService.createGame(req)
+      publishResponse(envelope.correlationId, GameCreationResponseDto(Some(entry.gameId)))
+    } match
+      case Success(_) => ack(msg.id())
+      case Failure(ex) if attempt + 1 < maxRetries =>
+        log.warnf(ex, "Game creation failed (attempt %d), retrying", attempt)
+        retry(json, attempt + 1)
+        ack(msg.id())
+      case Failure(ex) =>
+        log.errorf(ex, "Game creation failed after %d attempts, sending to DLQ", maxRetries)
+        publishResponse(envelope.correlationId, GameCreationResponseDto(None, Some("Game creation failed")))
+        toDlq(envelope.`type`.toString, json, ex, attempt)
+        ack(msg.id())
+
+  private def publishResponse(correlationId: Option[String], resp: GameCreationResponseDto): Unit =
+    val payload  = objectMapper.valueToTree[com.fasterxml.jackson.databind.JsonNode](resp)
+    val envelope = EventEnvelope.of(EventType.GameCreationResponse, payload, correlationId)
+    xadd(responseStream, Map("data" -> objectMapper.writeValueAsString(envelope)))
+
+  private def retry(json: String, attempt: Int): Unit =
+    xadd(requestStream, Map("data" -> json, "attempt" -> attempt.toString))
+
+  private def toDlq(eventType: String, json: String, error: Throwable, attempt: Int): Unit =
+    xadd(
+      dlqStream,
+      Map(
+        "data"      -> json,
+        "eventType" -> eventType,
+        "error"     -> Option(error.getMessage).getOrElse(error.getClass.getName),
+        "attempt"   -> (attempt + 1).toString,
+      ),
+    )
+
+  private def ack(id: String): Unit =
+    Try(redis.stream(classOf[String]).xack(requestStream, groupName, id)) match
+      case Failure(ex) => log.warnf(ex, "Failed to ack message %s", id)
+      case Success(_)  => ()
+
+  private def xadd(key: String, fields: Map[String, String]): Unit =
+    Try(
+      redis
+        .stream(classOf[String])
+        .xadd(key, new XAddArgs().maxlen(maxStreamLen).nearlyExactTrimming(), fields.asJava),
+    ) match
+      case Failure(ex) => log.errorf(ex, "Failed to publish to stream %s", key)
+      case Success(_)  => ()

modules/core/src/main/scala/de/nowchess/chess/service/GameCreationService.scala

@@ -0,0 +1,71 @@
+package de.nowchess.chess.service
+
+import de.nowchess.api.dto.{GameCreationRequestDto, PlayerInfoDto, TimeControlDto}
+import de.nowchess.api.game.{GameContext, GameMode, TimeControl}
+import de.nowchess.api.player.{PlayerId, PlayerInfo}
+import de.nowchess.chess.engine.GameEngine
+import de.nowchess.chess.grpc.RuleSetGrpcAdapter
+import de.nowchess.chess.redis.GameRedisSubscriberManager
+import de.nowchess.chess.registry.{GameEntry, GameRegistry}
+import jakarta.enterprise.context.ApplicationScoped
+import jakarta.inject.Inject
+import org.jboss.logging.Logger
+import scala.compiletime.uninitialized
+
+@ApplicationScoped
+class GameCreationService:
+
+  private val log = Logger.getLogger(classOf[GameCreationService])
+
+  // scalafix:off DisableSyntax.var
+  @Inject var registry: GameRegistry                        = uninitialized
+  @Inject var ruleSetAdapter: RuleSetGrpcAdapter            = uninitialized
+  @Inject var subscriberManager: GameRedisSubscriberManager = uninitialized
+  // scalafix:on DisableSyntax.var
+
+  private val DefaultWhite = PlayerInfo(PlayerId("p1"), "Player 1")
+  private val DefaultBlack = PlayerInfo(PlayerId("p2"), "Player 2")
+
+  def createGame(req: GameCreationRequestDto): GameEntry =
+    val white = playerInfoFrom(req.white, DefaultWhite)
+    val black = playerInfoFrom(req.black, DefaultBlack)
+    val tc    = toTimeControl(req.timeControl)
+    val mode  = req.mode.getOrElse(GameMode.Open)
+    val entry = newEntry(GameContext.initial, white, black, tc, mode)
+    registry.store(entry)
+    subscriberManager.subscribeGame(entry.gameId)
+    log.infof(
+      "Game %s created — white=%s black=%s mode=%s",
+      entry.gameId,
+      white.displayName,
+      black.displayName,
+      mode.toString,
+    )
+    entry
+
+  private def playerInfoFrom(dto: Option[PlayerInfoDto], default: PlayerInfo): PlayerInfo =
+    dto.fold(default)(d => PlayerInfo(PlayerId(d.id), d.displayName))
+
+  private def toTimeControl(dto: Option[TimeControlDto]): TimeControl =
+    dto match
+      case None => TimeControl.Unlimited
+      case Some(tc) =>
+        tc.daysPerMove match
+          case Some(d) => TimeControl.Correspondence(d)
+          case None =>
+            tc.limitSeconds.fold(TimeControl.Unlimited)(l => TimeControl.Clock(l, tc.incrementSeconds.getOrElse(0)))
+
+  private def newEntry(
+      ctx: GameContext,
+      white: PlayerInfo,
+      black: PlayerInfo,
+      tc: TimeControl,
+      mode: GameMode,
+  ): GameEntry =
+    GameEntry(
+      registry.generateId(),
+      GameEngine(initialContext = ctx, ruleSet = ruleSetAdapter, timeControl = tc),
+      white,
+      black,
+      mode = mode,
+    )

modules/core/src/test/resources/application.yml

@@ -18,6 +18,8 @@ nowchess:
       enabled: false
   coordinator:
     enabled: false
+  game-creation-stream:
+    enabled: false
   redis:
     host: localhost
     port: 6379

modules/core/src/test/scala/de/nowchess/chess/service/GameCreationServiceTest.scala

@@ -0,0 +1,68 @@
+package de.nowchess.chess.service
+
+import de.nowchess.api.dto.{GameCreationRequestDto, PlayerInfoDto, TimeControlDto}
+import de.nowchess.api.game.{GameMode, TimeControl}
+import de.nowchess.api.player.PlayerType
+import de.nowchess.chess.client.CombinedExportResponse
+import de.nowchess.chess.grpc.IoGrpcClientWrapper
+import de.nowchess.chess.redis.GameRedisSubscriberManager
+import io.quarkus.test.InjectMock
+import io.quarkus.test.junit.QuarkusTest
+import jakarta.inject.Inject
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.{BeforeEach, DisplayName, Test}
+import org.mockito.ArgumentMatchers.any
+import org.mockito.Mockito.{verify, when}
+import scala.compiletime.uninitialized
+
+// scalafix:off
+@QuarkusTest
+@DisplayName("GameCreationService")
+class GameCreationServiceTest:
+
+  @Inject
+  var service: GameCreationService = uninitialized
+
+  @InjectMock
+  var subscriberManager: GameRedisSubscriberManager = uninitialized
+
+  @InjectMock
+  var ioWrapper: IoGrpcClientWrapper = uninitialized
+
+  @BeforeEach
+  def setup(): Unit =
+    when(ioWrapper.exportCombined(any()))
+      .thenReturn(CombinedExportResponse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", ""))
+
+  private def player(id: String, name: String): PlayerInfoDto =
+    PlayerInfoDto(id, name, PlayerType.Human)
+
+  @Test
+  def createsGameAndSubscribes(): Unit =
+    val req =
+      GameCreationRequestDto(Some(player("w", "White")), Some(player("b", "Black")), None, Some(GameMode.Authenticated))
+    val entry = service.createGame(req)
+    assertNotNull(entry.gameId)
+    assertEquals("White", entry.white.displayName)
+    assertEquals("Black", entry.black.displayName)
+    assertEquals(GameMode.Authenticated, entry.mode)
+    verify(subscriberManager).subscribeGame(entry.gameId)
+
+  @Test
+  def defaultsToOpenModeAndDefaultPlayers(): Unit =
+    val entry = service.createGame(GameCreationRequestDto(None, None, None, None))
+    assertEquals(GameMode.Open, entry.mode)
+    assertEquals("Player 1", entry.white.displayName)
+    assertEquals("Player 2", entry.black.displayName)
+
+  @Test
+  def mapsClockTimeControl(): Unit =
+    val tc    = TimeControlDto(Some(300), Some(5), None)
+    val entry = service.createGame(GameCreationRequestDto(None, None, Some(tc), None))
+    assertEquals(TimeControl.Clock(300, 5), entry.engine.timeControl)
+
+  @Test
+  def mapsCorrespondenceTimeControl(): Unit =
+    val tc    = TimeControlDto(None, None, Some(3))
+    val entry = service.createGame(GameCreationRequestDto(None, None, Some(tc), None))
+    assertEquals(TimeControl.Correspondence(3), entry.engine.timeControl)