feat(rule): Rules as a microservice (#39)

Co-authored-by: LQ63 <lkhermann@web.de>
Co-authored-by: TeamCity <teamcity@service.local>
Reviewed-on: #39

modules/rule/build.gradle.kts

@@ -1,6 +1,7 @@
 plugins {
     id("scala")
     id("org.scoverage") version "8.1"
+    id("io.quarkus")
 }
 
 group = "de.nowchess"
@@ -25,6 +26,10 @@ tasks.withType<ScalaCompile> {
     scalaCompileOptions.additionalParameters = listOf("-encoding", "UTF-8")
 }
 
+val quarkusPlatformGroupId: String by project
+val quarkusPlatformArtifactId: String by project
+val quarkusPlatformVersion: String by project
+
 dependencies {
 
     compileOnly("org.scala-lang:scala3-compiler_3") {
@@ -40,20 +45,56 @@ dependencies {
 
     implementation(project(":modules:api"))
 
+    implementation(platform("${quarkusPlatformGroupId}:${quarkusPlatformArtifactId}:${quarkusPlatformVersion}"))
+    implementation("io.quarkus:quarkus-rest")
+    implementation("io.quarkus:quarkus-hibernate-orm")
+    implementation("io.quarkus:quarkus-rest-client-jackson")
+    implementation("io.quarkus:quarkus-rest-client")
+    implementation("io.quarkus:quarkus-rest-jackson")
+    implementation("io.quarkus:quarkus-config-yaml")
+    implementation("io.quarkus:quarkus-smallrye-fault-tolerance")
+    implementation("io.quarkus:quarkus-smallrye-jwt")
+    implementation("io.quarkus:quarkus-smallrye-health")
+    implementation("io.quarkus:quarkus-micrometer")
+    implementation("io.quarkus:quarkus-arc")
+    implementation("com.fasterxml.jackson.module:jackson-module-scala_3:${versions["JACKSON_SCALA"]!!}")
+
     testImplementation(project(":modules:io"))
     testImplementation(platform("org.junit:junit-bom:5.13.4"))
     testImplementation("org.junit.jupiter:junit-jupiter")
     testImplementation("org.scalatest:scalatest_3:${versions["SCALATEST"]!!}")
     testImplementation("co.helmethair:scalatest-junit-runner:${versions["SCALATEST_JUNIT"]!!}")
+    testImplementation("io.quarkus:quarkus-junit5")
+    testImplementation("io.rest-assured:rest-assured")
 
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
 }
 
+configurations.matching { !it.name.startsWith("scoverage") }.configureEach {
+    resolutionStrategy.force("org.scala-lang:scala-library:${versions["SCALA_LIBRARY"]!!}")
+}
+configurations.scoverage {
+    resolutionStrategy.eachDependency {
+        if (requested.group == "org.scoverage" && requested.name.startsWith("scalac-scoverage-plugin_")) {
+            useTarget("${requested.group}:scalac-scoverage-plugin_2.13.16:2.3.0")
+        }
+    }
+}
+
+tasks.withType<JavaCompile> {
+    options.encoding = "UTF-8"
+    options.compilerArgs.add("-parameters")
+}
+
+tasks.withType<Jar>().configureEach {
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+}
+
 tasks.test {
     useJUnitPlatform {
-        includeEngines("scalatest")
+        includeEngines("scalatest", "junit-jupiter")
         testLogging {
-            events("skipped", "failed")
+            events("passed", "skipped", "failed")
         }
     }
     finalizedBy(tasks.reportScoverage)
@@ -61,3 +102,7 @@ tasks.test {
 tasks.reportScoverage {
     dependsOn(tasks.test)
 }
+
+tasks.jar {
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+}

modules/rule/src/main/docker/Dockerfile.jvm

@@ -0,0 +1,100 @@
+####
+# This Dockerfile is used in order to build a container that runs the Quarkus application in JVM mode
+#
+# Before building the container image run:
+#
+# ./gradlew build
+#
+# Then, build the image with:
+#
+# docker build -f src/main/docker/Dockerfile.jvm -t quarkus/backcore-jvm .
+#
+# Then run the container using:
+#
+# docker run -i --rm -p 8080:8080 quarkus/backcore-jvm
+#
+# If you want to include the debug port into your docker image
+# you will have to expose the debug port (default 5005 being the default) like this :  EXPOSE 8080 5005.
+# Additionally you will have to set -e JAVA_DEBUG=true and -e JAVA_DEBUG_PORT=*:5005
+# when running the container
+#
+# Then run the container using :
+#
+# docker run -i --rm -p 8080:8080 quarkus/backcore-jvm
+#
+# This image uses the `run-java.sh` script to run the application.
+# This scripts computes the command line to execute your Java application, and
+# includes memory/GC tuning.
+# You can configure the behavior using the following environment properties:
+# - JAVA_OPTS: JVM options passed to the `java` command (example: "-verbose:class") - Be aware that this will override
+# the default JVM options, use `JAVA_OPTS_APPEND` to append options
+# - JAVA_OPTS_APPEND: User specified Java options to be appended to generated options
+#   in JAVA_OPTS (example: "-Dsome.property=foo")
+# - JAVA_MAX_MEM_RATIO: Is used when no `-Xmx` option is given in JAVA_OPTS. This is
+#   used to calculate a default maximal heap memory based on a containers restriction.
+#   If used in a container without any memory constraints for the container then this
+#   option has no effect. If there is a memory constraint then `-Xmx` is set to a ratio
+#   of the container available memory as set here. The default is `50` which means 50%
+#   of the available memory is used as an upper boundary. You can skip this mechanism by
+#   setting this value to `0` in which case no `-Xmx` option is added.
+# - JAVA_INITIAL_MEM_RATIO: Is used when no `-Xms` option is given in JAVA_OPTS. This
+#   is used to calculate a default initial heap memory based on the maximum heap memory.
+#   If used in a container without any memory constraints for the container then this
+#   option has no effect. If there is a memory constraint then `-Xms` is set to a ratio
+#   of the `-Xmx` memory as set here. The default is `25` which means 25% of the `-Xmx`
+#   is used as the initial heap size. You can skip this mechanism by setting this value
+#   to `0` in which case no `-Xms` option is added (example: "25")
+# - JAVA_MAX_INITIAL_MEM: Is used when no `-Xms` option is given in JAVA_OPTS.
+#   This is used to calculate the maximum value of the initial heap memory. If used in
+#   a container without any memory constraints for the container then this option has
+#   no effect. If there is a memory constraint then `-Xms` is limited to the value set
+#   here. The default is 4096MB which means the calculated value of `-Xms` never will
+#   be greater than 4096MB. The value of this variable is expressed in MB (example: "4096")
+# - JAVA_DIAGNOSTICS: Set this to get some diagnostics information to standard output
+#   when things are happening. This option, if set to true, will set
+#  `-XX:+UnlockDiagnosticVMOptions`. Disabled by default (example: "true").
+# - JAVA_DEBUG: If set remote debugging will be switched on. Disabled by default (example:
+#    true").
+# - JAVA_DEBUG_PORT: Port used for remote debugging. Defaults to 5005 (example: "8787").
+# - CONTAINER_CORE_LIMIT: A calculated core limit as described in
+#   https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt. (example: "2")
+# - CONTAINER_MAX_MEMORY: Memory limit given to the container (example: "1024").
+# - GC_MIN_HEAP_FREE_RATIO: Minimum percentage of heap free after GC to avoid expansion.
+#   (example: "20")
+# - GC_MAX_HEAP_FREE_RATIO: Maximum percentage of heap free after GC to avoid shrinking.
+#   (example: "40")
+# - GC_TIME_RATIO: Specifies the ratio of the time spent outside the garbage collection.
+#   (example: "4")
+# - GC_ADAPTIVE_SIZE_POLICY_WEIGHT: The weighting given to the current GC time versus
+#   previous GC times. (example: "90")
+# - GC_METASPACE_SIZE: The initial metaspace size. (example: "20")
+# - GC_MAX_METASPACE_SIZE: The maximum metaspace size. (example: "100")
+# - GC_CONTAINER_OPTIONS: Specify Java GC to use. The value of this variable should
+#   contain the necessary JRE command-line options to specify the required GC, which
+#   will override the default of `-XX:+UseParallelGC` (example: -XX:+UseG1GC).
+# - HTTPS_PROXY: The location of the https proxy. (example: "myuser@127.0.0.1:8080")
+# - HTTP_PROXY: The location of the http proxy. (example: "myuser@127.0.0.1:8080")
+# - NO_PROXY: A comma separated lists of hosts, IP addresses or domains that can be
+#   accessed directly. (example: "foo.example.com,bar.example.com")
+#
+# You can find more information about the UBI base runtime images and their configuration here:
+# https://rh-openjdk.github.io/redhat-openjdk-containers/
+###
+FROM registry.access.redhat.com/ubi9/openjdk-21-runtime:1.24
+
+ENV LANGUAGE='en_US:en'
+
+
+# We make four distinct layers so if there are application changes the library layers can be re-used
+COPY --chown=185 build/quarkus-app/lib/ /deployments/lib/
+COPY --chown=185 build/quarkus-app/*.jar /deployments/
+COPY --chown=185 build/quarkus-app/app/ /deployments/app/
+COPY --chown=185 build/quarkus-app/quarkus/ /deployments/quarkus/
+
+EXPOSE 8080
+USER 185
+ENV JAVA_OPTS_APPEND="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
+ENV JAVA_APP_JAR="/deployments/quarkus-run.jar"
+
+ENTRYPOINT [ "/opt/jboss/container/java/run/run-java.sh" ]
+

modules/rule/src/main/docker/Dockerfile.legacy-jar

@@ -0,0 +1,96 @@
+####
+# This Dockerfile is used in order to build a container that runs the Quarkus application in JVM mode
+#
+# Before building the container image run:
+#
+# ./gradlew build -Dquarkus.package.jar.type=legacy-jar
+#
+# Then, build the image with:
+#
+# docker build -f src/main/docker/Dockerfile.legacy-jar -t quarkus/backcore-legacy-jar .
+#
+# Then run the container using:
+#
+# docker run -i --rm -p 8080:8080 quarkus/backcore-legacy-jar
+#
+# If you want to include the debug port into your docker image
+# you will have to expose the debug port (default 5005 being the default) like this :  EXPOSE 8080 5005.
+# Additionally you will have to set -e JAVA_DEBUG=true and -e JAVA_DEBUG_PORT=*:5005
+# when running the container
+#
+# Then run the container using :
+#
+# docker run -i --rm -p 8080:8080 quarkus/backcore-legacy-jar
+#
+# This image uses the `run-java.sh` script to run the application.
+# This scripts computes the command line to execute your Java application, and
+# includes memory/GC tuning.
+# You can configure the behavior using the following environment properties:
+# - JAVA_OPTS: JVM options passed to the `java` command (example: "-verbose:class") - Be aware that this will override
+# the default JVM options, use `JAVA_OPTS_APPEND` to append options
+# - JAVA_OPTS_APPEND: User specified Java options to be appended to generated options
+#   in JAVA_OPTS (example: "-Dsome.property=foo")
+# - JAVA_MAX_MEM_RATIO: Is used when no `-Xmx` option is given in JAVA_OPTS. This is
+#   used to calculate a default maximal heap memory based on a containers restriction.
+#   If used in a container without any memory constraints for the container then this
+#   option has no effect. If there is a memory constraint then `-Xmx` is set to a ratio
+#   of the container available memory as set here. The default is `50` which means 50%
+#   of the available memory is used as an upper boundary. You can skip this mechanism by
+#   setting this value to `0` in which case no `-Xmx` option is added.
+# - JAVA_INITIAL_MEM_RATIO: Is used when no `-Xms` option is given in JAVA_OPTS. This
+#   is used to calculate a default initial heap memory based on the maximum heap memory.
+#   If used in a container without any memory constraints for the container then this
+#   option has no effect. If there is a memory constraint then `-Xms` is set to a ratio
+#   of the `-Xmx` memory as set here. The default is `25` which means 25% of the `-Xmx`
+#   is used as the initial heap size. You can skip this mechanism by setting this value
+#   to `0` in which case no `-Xms` option is added (example: "25")
+# - JAVA_MAX_INITIAL_MEM: Is used when no `-Xms` option is given in JAVA_OPTS.
+#   This is used to calculate the maximum value of the initial heap memory. If used in
+#   a container without any memory constraints for the container then this option has
+#   no effect. If there is a memory constraint then `-Xms` is limited to the value set
+#   here. The default is 4096MB which means the calculated value of `-Xms` never will
+#   be greater than 4096MB. The value of this variable is expressed in MB (example: "4096")
+# - JAVA_DIAGNOSTICS: Set this to get some diagnostics information to standard output
+#   when things are happening. This option, if set to true, will set
+#  `-XX:+UnlockDiagnosticVMOptions`. Disabled by default (example: "true").
+# - JAVA_DEBUG: If set remote debugging will be switched on. Disabled by default (example:
+#    true").
+# - JAVA_DEBUG_PORT: Port used for remote debugging. Defaults to 5005 (example: "8787").
+# - CONTAINER_CORE_LIMIT: A calculated core limit as described in
+#   https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt. (example: "2")
+# - CONTAINER_MAX_MEMORY: Memory limit given to the container (example: "1024").
+# - GC_MIN_HEAP_FREE_RATIO: Minimum percentage of heap free after GC to avoid expansion.
+#   (example: "20")
+# - GC_MAX_HEAP_FREE_RATIO: Maximum percentage of heap free after GC to avoid shrinking.
+#   (example: "40")
+# - GC_TIME_RATIO: Specifies the ratio of the time spent outside the garbage collection.
+#   (example: "4")
+# - GC_ADAPTIVE_SIZE_POLICY_WEIGHT: The weighting given to the current GC time versus
+#   previous GC times. (example: "90")
+# - GC_METASPACE_SIZE: The initial metaspace size. (example: "20")
+# - GC_MAX_METASPACE_SIZE: The maximum metaspace size. (example: "100")
+# - GC_CONTAINER_OPTIONS: Specify Java GC to use. The value of this variable should
+#   contain the necessary JRE command-line options to specify the required GC, which
+#   will override the default of `-XX:+UseParallelGC` (example: -XX:+UseG1GC).
+# - HTTPS_PROXY: The location of the https proxy. (example: "myuser@127.0.0.1:8080")
+# - HTTP_PROXY: The location of the http proxy. (example: "myuser@127.0.0.1:8080")
+# - NO_PROXY: A comma separated lists of hosts, IP addresses or domains that can be
+#   accessed directly. (example: "foo.example.com,bar.example.com")
+#
+# You can find more information about the UBI base runtime images and their configuration here:
+# https://rh-openjdk.github.io/redhat-openjdk-containers/
+###
+FROM registry.access.redhat.com/ubi9/openjdk-21-runtime:1.24
+
+ENV LANGUAGE='en_US:en'
+
+
+COPY build/lib/* /deployments/lib/
+COPY build/*-runner.jar /deployments/quarkus-run.jar
+
+EXPOSE 8080
+USER 185
+ENV JAVA_OPTS_APPEND="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
+ENV JAVA_APP_JAR="/deployments/quarkus-run.jar"
+
+ENTRYPOINT [ "/opt/jboss/container/java/run/run-java.sh" ]

modules/rule/src/main/docker/Dockerfile.native

@@ -0,0 +1,29 @@
+####
+# This Dockerfile is used in order to build a container that runs the Quarkus application in native (no JVM) mode.
+#
+# Before building the container image run:
+#
+# ./gradlew build -Dquarkus.native.enabled=true
+#
+# Then, build the image with:
+#
+# docker build -f src/main/docker/Dockerfile.native -t quarkus/backcore .
+#
+# Then run the container using:
+#
+# docker run -i --rm -p 8080:8080 quarkus/backcore
+#
+# The ` registry.access.redhat.com/ubi9/ubi-minimal:9.7` base image is based on UBI 9.
+# To use UBI 8, switch to `quay.io/ubi8/ubi-minimal:8.10`.
+###
+FROM registry.access.redhat.com/ubi9/ubi-minimal:9.7
+WORKDIR /work/
+RUN chown 1001 /work \
+    && chmod "g+rwX" /work \
+    && chown 1001:root /work
+COPY --chown=1001:root --chmod=0755 build/*-runner /work/application
+
+EXPOSE 8080
+USER 1001
+
+ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]

modules/rule/src/main/docker/Dockerfile.native-micro

@@ -0,0 +1,32 @@
+####
+# This Dockerfile is used in order to build a container that runs the Quarkus application in native (no JVM) mode.
+# It uses a micro base image, tuned for Quarkus native executables.
+# It reduces the size of the resulting container image.
+# Check https://quarkus.io/guides/quarkus-runtime-base-image for further information about this image.
+#
+# Before building the container image run:
+#
+# ./gradlew build -Dquarkus.native.enabled=true
+#
+# Then, build the image with:
+#
+# docker build -f src/main/docker/Dockerfile.native-micro -t quarkus/backcore .
+#
+# Then run the container using:
+#
+# docker run -i --rm -p 8080:8080 quarkus/backcore
+#
+# The `quay.io/quarkus/ubi9-quarkus-micro-image:2.0` base image is based on UBI 9.
+# To use UBI 8, switch to `quay.io/quarkus/quarkus-micro-image:2.0`.
+###
+FROM quay.io/quarkus/ubi9-quarkus-micro-image:2.0
+WORKDIR /work/
+RUN chown 1001 /work \
+    && chmod "g+rwX" /work \
+    && chown 1001:root /work
+COPY --chown=1001:root --chmod=0755 build/*-runner /work/application
+
+EXPOSE 8080
+USER 1001
+
+ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]

modules/rule/src/main/resources/application.yml

@@ -0,0 +1,5 @@
+quarkus:
+  http:
+    port: 8082
+  application:
+    name: rule-service

modules/rule/src/main/scala/de/nowchess/rules/RuleSet.scala

@@ -1,41 +0,0 @@
-package de.nowchess.rules
-
-import de.nowchess.api.game.GameContext
-import de.nowchess.api.board.Square
-import de.nowchess.api.move.Move
-
-/** Extension point for chess rule variants (standard, Chess960, etc.). All rule queries are stateless: given a
-  * GameContext, return the answer.
-  */
-trait RuleSet:
-  /** All pseudo-legal moves for the piece on `square` (ignores check). */
-  def candidateMoves(context: GameContext)(square: Square): List[Move]
-
-  /** Legal moves for `square`: candidates that don't leave own king in check. */
-  def legalMoves(context: GameContext)(square: Square): List[Move]
-
-  /** All legal moves for the side to move. */
-  def allLegalMoves(context: GameContext): List[Move]
-
-  /** True if the side to move's king is in check. */
-  def isCheck(context: GameContext): Boolean
-
-  /** True if the side to move is in check and has no legal moves. */
-  def isCheckmate(context: GameContext): Boolean
-
-  /** True if the side to move is not in check and has no legal moves. */
-  def isStalemate(context: GameContext): Boolean
-
-  /** True if neither side has enough material to checkmate. */
-  def isInsufficientMaterial(context: GameContext): Boolean
-
-  /** True if halfMoveClock >= 100 (50-move rule). */
-  def isFiftyMoveRule(context: GameContext): Boolean
-
-  /** True if the same position has occurred 3 times (including current position). */
-  def isThreefoldRepetition(context: GameContext): Boolean
-
-  /** Apply a legal move to produce the next game context. Handles all special move types: castling, en passant,
-    * promotion. Updates castling rights, en passant square, half-move clock, turn, and move history.
-    */
-  def applyMove(context: GameContext)(move: Move): GameContext

modules/rule/src/main/scala/de/nowchess/rules/config/JacksonConfig.scala

@@ -0,0 +1,29 @@
+package de.nowchess.rules.config
+
+import com.fasterxml.jackson.core.Version
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.fasterxml.jackson.databind.module.SimpleModule
+import com.fasterxml.jackson.module.scala.DefaultScalaModule
+import de.nowchess.api.board.Square
+import de.nowchess.api.move.MoveType
+import de.nowchess.rules.json.*
+import io.quarkus.jackson.ObjectMapperCustomizer
+import jakarta.inject.Singleton
+
+@Singleton
+class JacksonConfig extends ObjectMapperCustomizer:
+  def customize(mapper: ObjectMapper): Unit =
+    mapper.registerModule(new DefaultScalaModule() {
+      override def version(): Version =
+        // scalafix:off DisableSyntax.null
+        new Version(2, 21, 1, null, "com.fasterxml.jackson.module", "jackson-module-scala")
+        // scalafix:on DisableSyntax.null
+    })
+    val mod = new SimpleModule()
+    mod.addKeySerializer(classOf[Square], new SquareKeySerializer())
+    mod.addKeyDeserializer(classOf[Square], new SquareKeyDeserializer())
+    mod.addSerializer(classOf[Square], new SquareSerializer())
+    mod.addDeserializer(classOf[Square], new SquareDeserializer())
+    mod.addSerializer(classOf[MoveType], new MoveTypeSerializer())
+    mod.addDeserializer(classOf[MoveType], new MoveTypeDeserializer())
+    mapper.registerModule(mod)

modules/rule/src/main/scala/de/nowchess/rules/config/NativeReflectionConfig.scala

@@ -0,0 +1,28 @@
+package de.nowchess.rules.config
+
+import de.nowchess.api.board.{CastlingRights, Color, File, Piece, PieceType, Rank, Square}
+import de.nowchess.api.game.{DrawReason, GameContext, GameResult}
+import de.nowchess.api.move.{Move, MoveType, PromotionPiece}
+import de.nowchess.rules.dto.{ContextMoveRequest, ContextSquareRequest}
+import io.quarkus.runtime.annotations.RegisterForReflection
+
+@RegisterForReflection(
+  targets = Array(
+    classOf[ContextSquareRequest],
+    classOf[ContextMoveRequest],
+    classOf[GameContext],
+    classOf[GameResult],
+    classOf[DrawReason],
+    classOf[Color],
+    classOf[Piece],
+    classOf[PieceType],
+    classOf[CastlingRights],
+    classOf[Square],
+    classOf[File],
+    classOf[Rank],
+    classOf[Move],
+    classOf[MoveType],
+    classOf[PromotionPiece],
+  ),
+)
+class NativeReflectionConfig

modules/rule/src/main/scala/de/nowchess/rules/dto/Dtos.scala

@@ -0,0 +1,8 @@
+package de.nowchess.rules.dto
+
+import de.nowchess.api.game.GameContext
+import de.nowchess.api.move.Move
+
+case class ContextSquareRequest(context: GameContext, square: String)
+
+case class ContextMoveRequest(context: GameContext, move: Move)

modules/rule/src/main/scala/de/nowchess/rules/json/MoveTypeDeserializer.scala

@@ -0,0 +1,19 @@
+package de.nowchess.rules.json
+
+import com.fasterxml.jackson.core.{JsonParseException, JsonParser}
+import com.fasterxml.jackson.databind.node.ObjectNode
+import com.fasterxml.jackson.databind.{DeserializationContext, JsonDeserializer}
+import de.nowchess.api.move.{MoveType, PromotionPiece}
+
+class MoveTypeDeserializer extends JsonDeserializer[MoveType]:
+  // scalafix:off DisableSyntax.throw
+  override def deserialize(p: JsonParser, ctx: DeserializationContext): MoveType =
+    val node = p.getCodec.readTree[ObjectNode](p)
+    node.get("type").asText() match
+      case "normal"          => MoveType.Normal(node.get("isCapture").asBoolean(false))
+      case "castleKingside"  => MoveType.CastleKingside
+      case "castleQueenside" => MoveType.CastleQueenside
+      case "enPassant"       => MoveType.EnPassant
+      case "promotion"       => MoveType.Promotion(PromotionPiece.valueOf(node.get("piece").asText()))
+      case t                 => throw new JsonParseException(p, s"Unknown move type: $t")
+  // scalafix:on DisableSyntax.throw

modules/rule/src/main/scala/de/nowchess/rules/json/MoveTypeSerializer.scala

@@ -0,0 +1,23 @@
+package de.nowchess.rules.json
+
+import com.fasterxml.jackson.core.JsonGenerator
+import com.fasterxml.jackson.databind.{JsonSerializer, SerializerProvider}
+import de.nowchess.api.move.MoveType
+
+class MoveTypeSerializer extends JsonSerializer[MoveType]:
+  override def serialize(value: MoveType, gen: JsonGenerator, provider: SerializerProvider): Unit =
+    gen.writeStartObject()
+    value match
+      case MoveType.Normal(isCapture) =>
+        gen.writeStringField("type", "normal")
+        gen.writeBooleanField("isCapture", isCapture)
+      case MoveType.CastleKingside =>
+        gen.writeStringField("type", "castleKingside")
+      case MoveType.CastleQueenside =>
+        gen.writeStringField("type", "castleQueenside")
+      case MoveType.EnPassant =>
+        gen.writeStringField("type", "enPassant")
+      case MoveType.Promotion(piece) =>
+        gen.writeStringField("type", "promotion")
+        gen.writeStringField("piece", piece.toString)
+    gen.writeEndObject()

modules/rule/src/main/scala/de/nowchess/rules/json/SquareDeserializer.scala

@@ -0,0 +1,9 @@
+package de.nowchess.rules.json
+
+import com.fasterxml.jackson.core.JsonParser
+import com.fasterxml.jackson.databind.{DeserializationContext, JsonDeserializer}
+import de.nowchess.api.board.Square
+
+class SquareDeserializer extends JsonDeserializer[Square]:
+  override def deserialize(p: JsonParser, ctx: DeserializationContext): Square =
+    Square.fromAlgebraic(p.getText).orNull

modules/rule/src/main/scala/de/nowchess/rules/json/SquareKeyDeserializer.scala

@@ -0,0 +1,8 @@
+package de.nowchess.rules.json
+
+import com.fasterxml.jackson.databind.{DeserializationContext, KeyDeserializer}
+import de.nowchess.api.board.Square
+
+class SquareKeyDeserializer extends KeyDeserializer:
+  override def deserializeKey(key: String, ctx: DeserializationContext): AnyRef =
+    Square.fromAlgebraic(key).orNull

modules/rule/src/main/scala/de/nowchess/rules/json/SquareKeySerializer.scala

@@ -0,0 +1,9 @@
+package de.nowchess.rules.json
+
+import com.fasterxml.jackson.core.JsonGenerator
+import com.fasterxml.jackson.databind.{JsonSerializer, SerializerProvider}
+import de.nowchess.api.board.Square
+
+class SquareKeySerializer extends JsonSerializer[Square]:
+  override def serialize(value: Square, gen: JsonGenerator, provider: SerializerProvider): Unit =
+    gen.writeFieldName(value.toString)

modules/rule/src/main/scala/de/nowchess/rules/json/SquareSerializer.scala

@@ -0,0 +1,9 @@
+package de.nowchess.rules.json
+
+import com.fasterxml.jackson.core.JsonGenerator
+import com.fasterxml.jackson.databind.{JsonSerializer, SerializerProvider}
+import de.nowchess.api.board.Square
+
+class SquareSerializer extends JsonSerializer[Square]:
+  override def serialize(value: Square, gen: JsonGenerator, provider: SerializerProvider): Unit =
+    gen.writeString(value.toString)

modules/rule/src/main/scala/de/nowchess/rules/resource/RuleSetResource.scala

@@ -0,0 +1,90 @@
+package de.nowchess.rules.resource
+
+import de.nowchess.api.board.Square
+import de.nowchess.api.game.GameContext
+import de.nowchess.api.move.Move
+import de.nowchess.rules.dto.*
+import de.nowchess.rules.sets.DefaultRules
+import jakarta.enterprise.context.ApplicationScoped
+import jakarta.ws.rs.*
+import jakarta.ws.rs.core.MediaType
+
+@Path("/api/rules")
+@ApplicationScoped
+class RuleSetResource:
+  private val rules = DefaultRules
+
+  // scalafix:off DisableSyntax.throw
+  private def parseSquare(s: String): Square =
+    Square.fromAlgebraic(s).getOrElse(throw new BadRequestException(s"Invalid square: $s"))
+  // scalafix:on DisableSyntax.throw
+
+  @POST
+  @Path("/candidate-moves")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def candidateMoves(req: ContextSquareRequest): List[Move] =
+    rules.candidateMoves(req.context)(parseSquare(req.square))
+
+  @POST
+  @Path("/legal-moves")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def legalMoves(req: ContextSquareRequest): List[Move] =
+    rules.legalMoves(req.context)(parseSquare(req.square))
+
+  @POST
+  @Path("/all-legal-moves")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def allLegalMoves(ctx: GameContext): List[Move] =
+    rules.allLegalMoves(ctx)
+
+  @POST
+  @Path("/is-check")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def isCheck(ctx: GameContext): Boolean =
+    rules.isCheck(ctx)
+
+  @POST
+  @Path("/is-checkmate")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def isCheckmate(ctx: GameContext): Boolean =
+    rules.isCheckmate(ctx)
+
+  @POST
+  @Path("/is-stalemate")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def isStalemate(ctx: GameContext): Boolean =
+    rules.isStalemate(ctx)
+
+  @POST
+  @Path("/is-insufficient-material")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def isInsufficientMaterial(ctx: GameContext): Boolean =
+    rules.isInsufficientMaterial(ctx)
+
+  @POST
+  @Path("/is-fifty-move-rule")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def isFiftyMoveRule(ctx: GameContext): Boolean =
+    rules.isFiftyMoveRule(ctx)
+
+  @POST
+  @Path("/is-threefold-repetition")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def isThreefoldRepetition(ctx: GameContext): Boolean =
+    rules.isThreefoldRepetition(ctx)
+
+  @POST
+  @Path("/apply-move")
+  @Consumes(Array(MediaType.APPLICATION_JSON))
+  @Produces(Array(MediaType.APPLICATION_JSON))
+  def applyMove(req: ContextMoveRequest): GameContext =
+    rules.applyMove(req.context)(req.move)

modules/rule/src/main/scala/de/nowchess/rules/sets/DefaultRules.scala

@@ -3,7 +3,7 @@ package de.nowchess.rules.sets
 import de.nowchess.api.board.*
 import de.nowchess.api.game.GameContext
 import de.nowchess.api.move.{Move, MoveType, PromotionPiece}
-import de.nowchess.rules.RuleSet
+import de.nowchess.api.rules.RuleSet
 
 import scala.annotation.tailrec
 

modules/rule/src/test/scala/de/nowchess/rules/config/JacksonConfigTest.scala

@@ -0,0 +1,30 @@
+package de.nowchess.rules.config
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import de.nowchess.api.board.{File, Rank, Square}
+import de.nowchess.api.move.MoveType
+import org.scalatest.funsuite.AnyFunSuite
+import org.scalatest.matchers.should.Matchers
+
+class JacksonConfigTest extends AnyFunSuite with Matchers:
+
+  private val mapper: ObjectMapper =
+    val m = new ObjectMapper()
+    new JacksonConfig().customize(m)
+    m
+
+  test("customize enables Option serialization via DefaultScalaModule"):
+    mapper.writeValueAsString(None) shouldBe "null"
+    mapper.writeValueAsString(Some("hello")) shouldBe """"hello""""
+
+  test("customize registers SquareSerializer"):
+    mapper.writeValueAsString(Square(File.E, Rank.R4)) shouldBe """"e4""""
+
+  test("customize registers MoveTypeSerializer"):
+    mapper.writeValueAsString(MoveType.CastleKingside) shouldBe """{"type":"castleKingside"}"""
+
+  test("customize registers SquareDeserializer"):
+    mapper.readValue(""""e4"""", classOf[Square]) shouldBe Square(File.E, Rank.R4)
+
+  test("customize registers MoveTypeDeserializer"):
+    mapper.readValue("""{"type":"enPassant"}""", classOf[MoveType]) shouldBe MoveType.EnPassant

modules/rule/src/test/scala/de/nowchess/rules/json/JsonSerializersTest.scala

@@ -0,0 +1,102 @@
+package de.nowchess.rules.json
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.fasterxml.jackson.databind.module.SimpleModule
+import com.fasterxml.jackson.module.scala.DefaultScalaModule
+import de.nowchess.api.board.{File, Rank, Square}
+import de.nowchess.api.move.{MoveType, PromotionPiece}
+import org.scalatest.funsuite.AnyFunSuite
+import org.scalatest.matchers.should.Matchers
+
+class JsonSerializersTest extends AnyFunSuite with Matchers:
+
+  private val mapper: ObjectMapper =
+    val m   = new ObjectMapper()
+    val mod = new SimpleModule()
+    m.registerModule(DefaultScalaModule)
+    mod.addKeySerializer(classOf[Square], new SquareKeySerializer())
+    mod.addKeyDeserializer(classOf[Square], new SquareKeyDeserializer())
+    mod.addSerializer(classOf[Square], new SquareSerializer())
+    mod.addDeserializer(classOf[Square], new SquareDeserializer())
+    mod.addSerializer(classOf[MoveType], new MoveTypeSerializer())
+    mod.addDeserializer(classOf[MoveType], new MoveTypeDeserializer())
+    m.registerModule(mod)
+    m
+
+  private val e4 = Square(File.E, Rank.R4)
+
+  // ── SquareKeySerializer ───────────────────────────────────────────
+
+  test("SquareKeySerializer writes square as map field name"):
+    mapper.writeValueAsString(Map(e4 -> "piece")) shouldBe """{"e4":"piece"}"""
+
+  // ── SquareKeyDeserializer ─────────────────────────────────────────
+
+  // scalafix:off DisableSyntax.null
+  test("SquareKeyDeserializer returns square for valid key"):
+    new SquareKeyDeserializer().deserializeKey("e4", null) shouldBe e4
+
+  test("SquareKeyDeserializer returns null for invalid key"):
+    new SquareKeyDeserializer().deserializeKey("z9", null) shouldBe null
+  // scalafix:on DisableSyntax.null
+
+  // ── SquareSerializer/Deserializer ─────────────────────────────────
+
+  test("SquareSerializer writes square as string"):
+    mapper.writeValueAsString(e4) shouldBe """"e4""""
+
+  test("SquareDeserializer reads valid square string"):
+    mapper.readValue(""""e4"""", classOf[Square]) shouldBe e4
+
+  // scalafix:off DisableSyntax.null
+  test("SquareDeserializer returns null for invalid square string"):
+    mapper.readValue(""""z9"""", classOf[Square]) shouldBe null
+  // scalafix:on DisableSyntax.null
+
+  // ── MoveTypeSerializer ────────────────────────────────────────────
+
+  test("MoveTypeSerializer serializes Normal non-capture"):
+    mapper.writeValueAsString(MoveType.Normal(false)) shouldBe """{"type":"normal","isCapture":false}"""
+
+  test("MoveTypeSerializer serializes Normal capture"):
+    mapper.writeValueAsString(MoveType.Normal(true)) shouldBe """{"type":"normal","isCapture":true}"""
+
+  test("MoveTypeSerializer serializes CastleKingside"):
+    mapper.writeValueAsString(MoveType.CastleKingside) shouldBe """{"type":"castleKingside"}"""
+
+  test("MoveTypeSerializer serializes CastleQueenside"):
+    mapper.writeValueAsString(MoveType.CastleQueenside) shouldBe """{"type":"castleQueenside"}"""
+
+  test("MoveTypeSerializer serializes EnPassant"):
+    mapper.writeValueAsString(MoveType.EnPassant) shouldBe """{"type":"enPassant"}"""
+
+  test("MoveTypeSerializer serializes Promotion"):
+    mapper.writeValueAsString(MoveType.Promotion(PromotionPiece.Queen)) shouldBe
+      """{"type":"promotion","piece":"Queen"}"""
+
+  // ── MoveTypeDeserializer ──────────────────────────────────────────
+
+  test("MoveTypeDeserializer deserializes normal non-capture"):
+    mapper.readValue("""{"type":"normal","isCapture":false}""", classOf[MoveType]) shouldBe
+      MoveType.Normal(false)
+
+  test("MoveTypeDeserializer deserializes normal capture"):
+    mapper.readValue("""{"type":"normal","isCapture":true}""", classOf[MoveType]) shouldBe
+      MoveType.Normal(true)
+
+  test("MoveTypeDeserializer deserializes castleKingside"):
+    mapper.readValue("""{"type":"castleKingside"}""", classOf[MoveType]) shouldBe MoveType.CastleKingside
+
+  test("MoveTypeDeserializer deserializes castleQueenside"):
+    mapper.readValue("""{"type":"castleQueenside"}""", classOf[MoveType]) shouldBe MoveType.CastleQueenside
+
+  test("MoveTypeDeserializer deserializes enPassant"):
+    mapper.readValue("""{"type":"enPassant"}""", classOf[MoveType]) shouldBe MoveType.EnPassant
+
+  test("MoveTypeDeserializer deserializes promotion"):
+    mapper.readValue("""{"type":"promotion","piece":"Rook"}""", classOf[MoveType]) shouldBe
+      MoveType.Promotion(PromotionPiece.Rook)
+
+  test("MoveTypeDeserializer throws for unknown type"):
+    an[Exception] should be thrownBy
+      mapper.readValue("""{"type":"unknown"}""", classOf[MoveType])

modules/rule/src/test/scala/de/nowchess/rules/resource/RuleSetResourceTest.scala

@@ -0,0 +1,301 @@
+package de.nowchess.rules.resource
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import de.nowchess.api.board.{Board, CastlingRights, Color, File, Piece, PieceType, Rank, Square}
+import de.nowchess.api.game.GameContext
+import de.nowchess.api.move.Move
+import de.nowchess.rules.config.JacksonConfig
+import de.nowchess.rules.dto.{ContextMoveRequest, ContextSquareRequest}
+import de.nowchess.rules.sets.DefaultRules
+import io.quarkus.test.junit.QuarkusTest
+import io.restassured.RestAssured
+import io.restassured.http.ContentType
+import org.hamcrest.Matchers.*
+import org.junit.jupiter.api.Test
+
+@QuarkusTest
+class RuleSetResourceTest:
+
+  private val mapper: ObjectMapper =
+    val m = new ObjectMapper()
+    new JacksonConfig().customize(m)
+    m
+
+  private val rules = DefaultRules
+
+  private def request() = RestAssured.`given`()
+
+  private def toJson(value: AnyRef): String = mapper.writeValueAsString(value)
+
+  private def contextSquareBody(ctx: GameContext, square: String): String =
+    toJson(ContextSquareRequest(ctx, square))
+
+  private def contextMoveBody(ctx: GameContext, move: Move): String =
+    toJson(ContextMoveRequest(ctx, move))
+
+  // ── all-legal-moves ───────────────────────────────────────────────
+
+  @Test
+  def allLegalMoves_initialPositionHas20Moves(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial))
+      .when()
+      .post("/api/rules/all-legal-moves")
+      .`then`()
+      .statusCode(200)
+      .body("size()", is(20))
+
+  // ── legal-moves ───────────────────────────────────────────────────
+
+  @Test
+  def legalMoves_e2PawnHas2Moves(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(contextSquareBody(GameContext.initial, "e2"))
+      .when()
+      .post("/api/rules/legal-moves")
+      .`then`()
+      .statusCode(200)
+      .body("size()", is(2))
+
+  // ── candidate-moves ───────────────────────────────────────────────
+
+  @Test
+  def candidateMoves_e2PawnHas2Candidates(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(contextSquareBody(GameContext.initial, "e2"))
+      .when()
+      .post("/api/rules/candidate-moves")
+      .`then`()
+      .statusCode(200)
+      .body("size()", is(2))
+
+  // ── is-check ──────────────────────────────────────────────────────
+
+  @Test
+  def isCheck_falseForInitialPosition(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial))
+      .when()
+      .post("/api/rules/is-check")
+      .`then`()
+      .statusCode(200)
+      .body(is("false"))
+
+  @Test
+  def isCheck_trueWhenKingAttacked(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(buildCheckContext()))
+      .when()
+      .post("/api/rules/is-check")
+      .`then`()
+      .statusCode(200)
+      .body(is("true"))
+
+  // ── is-checkmate ──────────────────────────────────────────────────
+
+  @Test
+  def isCheckmate_falseForInitialPosition(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial))
+      .when()
+      .post("/api/rules/is-checkmate")
+      .`then`()
+      .statusCode(200)
+      .body(is("false"))
+
+  @Test
+  def isCheckmate_trueForFoolsMate(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(buildFoolsMate()))
+      .when()
+      .post("/api/rules/is-checkmate")
+      .`then`()
+      .statusCode(200)
+      .body(is("true"))
+
+  // ── is-stalemate ──────────────────────────────────────────────────
+
+  @Test
+  def isStalemate_falseForInitialPosition(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial))
+      .when()
+      .post("/api/rules/is-stalemate")
+      .`then`()
+      .statusCode(200)
+      .body(is("false"))
+
+  @Test
+  def isStalemate_trueForStalematePosition(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(buildStalemateContext()))
+      .when()
+      .post("/api/rules/is-stalemate")
+      .`then`()
+      .statusCode(200)
+      .body(is("true"))
+
+  // ── is-insufficient-material ──────────────────────────────────────
+
+  @Test
+  def isInsufficientMaterial_falseForInitialPosition(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial))
+      .when()
+      .post("/api/rules/is-insufficient-material")
+      .`then`()
+      .statusCode(200)
+      .body(is("false"))
+
+  @Test
+  def isInsufficientMaterial_trueForKingsOnly(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(buildKingsOnlyContext()))
+      .when()
+      .post("/api/rules/is-insufficient-material")
+      .`then`()
+      .statusCode(200)
+      .body(is("true"))
+
+  // ── is-fifty-move-rule ────────────────────────────────────────────
+
+  @Test
+  def isFiftyMoveRule_falseForInitialPosition(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial))
+      .when()
+      .post("/api/rules/is-fifty-move-rule")
+      .`then`()
+      .statusCode(200)
+      .body(is("false"))
+
+  @Test
+  def isFiftyMoveRule_trueWhenClockAt100(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial.copy(halfMoveClock = 100)))
+      .when()
+      .post("/api/rules/is-fifty-move-rule")
+      .`then`()
+      .statusCode(200)
+      .body(is("true"))
+
+  // ── is-threefold-repetition ───────────────────────────────────────
+
+  @Test
+  def isThreefoldRepetition_falseForInitialPosition(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(GameContext.initial))
+      .when()
+      .post("/api/rules/is-threefold-repetition")
+      .`then`()
+      .statusCode(200)
+      .body(is("false"))
+
+  @Test
+  def isThreefoldRepetition_trueAfterRepeatedMoves(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(buildThreefoldContext()))
+      .when()
+      .post("/api/rules/is-threefold-repetition")
+      .`then`()
+      .statusCode(200)
+      .body(is("true"))
+
+  // ── apply-move ────────────────────────────────────────────────────
+
+  @Test
+  def applyMove_updatesContext(): Unit =
+    val move = rules
+      .legalMoves(GameContext.initial)(Square(File.E, Rank.R2))
+      .find(_.to == Square(File.E, Rank.R4))
+      .get
+    request()
+      .contentType(ContentType.JSON)
+      .body(contextMoveBody(GameContext.initial, move))
+      .when()
+      .post("/api/rules/apply-move")
+      .`then`()
+      .statusCode(200)
+      .body("turn", is("Black"))
+
+  // ── error handling ────────────────────────────────────────────────
+
+  @Test
+  def invalidSquare_returns400(): Unit =
+    request()
+      .contentType(ContentType.JSON)
+      .body(toJson(ContextSquareRequest(GameContext.initial, "z9")))
+      .when()
+      .post("/api/rules/legal-moves")
+      .`then`()
+      .statusCode(400)
+
+  // ── position builders ─────────────────────────────────────────────
+
+  private def buildCheckContext(): GameContext =
+    val board = Board(
+      Map(
+        Square(File.E, Rank.R1) -> Piece(Color.White, PieceType.King),
+        Square(File.E, Rank.R8) -> Piece(Color.Black, PieceType.King),
+        Square(File.E, Rank.R3) -> Piece(Color.Black, PieceType.Rook),
+      ),
+    )
+    GameContext(board, Color.White, CastlingRights.None, None, 0, List.empty, initialBoard = board)
+
+  private def buildFoolsMate(): GameContext =
+    val moves = List(("f2", "f3"), ("e7", "e5"), ("g2", "g4"), ("d8", "h4"))
+    moves.foldLeft(GameContext.initial) { (ctx, fromTo) =>
+      val from = Square.fromAlgebraic(fromTo._1).get
+      val to   = Square.fromAlgebraic(fromTo._2).get
+      rules.legalMoves(ctx)(from).find(_.to == to).fold(ctx)(rules.applyMove(ctx))
+    }
+
+  private def buildStalemateContext(): GameContext =
+    val board = Board(
+      Map(
+        Square(File.H, Rank.R8) -> Piece(Color.Black, PieceType.King),
+        Square(File.F, Rank.R7) -> Piece(Color.White, PieceType.Queen),
+        Square(File.G, Rank.R6) -> Piece(Color.White, PieceType.King),
+      ),
+    )
+    GameContext(board, Color.Black, CastlingRights.None, None, 0, List.empty, initialBoard = board)
+
+  private def buildKingsOnlyContext(): GameContext =
+    val board = Board(
+      Map(
+        Square(File.E, Rank.R1) -> Piece(Color.White, PieceType.King),
+        Square(File.E, Rank.R8) -> Piece(Color.Black, PieceType.King),
+      ),
+    )
+    GameContext(board, Color.White, CastlingRights.None, None, 0, List.empty, initialBoard = board)
+
+  private def buildThreefoldContext(): GameContext =
+    val g1 = Square(File.G, Rank.R1)
+    val f3 = Square(File.F, Rank.R3)
+    val g8 = Square(File.G, Rank.R8)
+    val f6 = Square(File.F, Rank.R6)
+    def mv(ctx: GameContext, from: Square, to: Square): GameContext =
+      rules.legalMoves(ctx)(from).find(_.to == to).fold(ctx)(rules.applyMove(ctx))
+    val ctx1 = mv(GameContext.initial, g1, f3)
+    val ctx2 = mv(ctx1, g8, f6)
+    val ctx3 = mv(ctx2, f3, g1)
+    val ctx4 = mv(ctx3, f6, g8)
+    val ctx5 = mv(ctx4, g1, f3)
+    val ctx6 = mv(ctx5, g8, f6)
+    val ctx7 = mv(ctx6, f3, g1)
+    mv(ctx7, f6, g8)

modules/rule/src/test/scala/de/nowchess/rules/resource/RuleSetResourceUnitTest.scala

@@ -0,0 +1,153 @@
+package de.nowchess.rules.resource
+
+import de.nowchess.api.board.{Board, CastlingRights, Color, File, Piece, PieceType, Rank, Square}
+import de.nowchess.api.game.GameContext
+import de.nowchess.api.move.Move
+import de.nowchess.rules.dto.{ContextMoveRequest, ContextSquareRequest}
+import de.nowchess.rules.sets.DefaultRules
+import jakarta.ws.rs.BadRequestException
+import org.scalatest.funsuite.AnyFunSuite
+import org.scalatest.matchers.should.Matchers
+
+class RuleSetResourceUnitTest extends AnyFunSuite with Matchers:
+
+  private val resource = new RuleSetResource()
+  private val rules    = DefaultRules
+
+  private def ctxSq(g: GameContext, sq: String) = ContextSquareRequest(g, sq)
+  private def ctxMv(g: GameContext, m: Move)    = ContextMoveRequest(g, m)
+
+  // ── position builders ─────────────────────────────────────────────
+
+  private def checkContext(): GameContext =
+    val board = Board(
+      Map(
+        Square(File.E, Rank.R1) -> Piece(Color.White, PieceType.King),
+        Square(File.E, Rank.R8) -> Piece(Color.Black, PieceType.King),
+        Square(File.E, Rank.R3) -> Piece(Color.Black, PieceType.Rook),
+      ),
+    )
+    GameContext(board, Color.White, CastlingRights.None, None, 0, List.empty, initialBoard = board)
+
+  private def foolsMate(): GameContext =
+    val moves = List(("f2", "f3"), ("e7", "e5"), ("g2", "g4"), ("d8", "h4"))
+    moves.foldLeft(GameContext.initial) { (c, ft) =>
+      val from = Square.fromAlgebraic(ft._1).get
+      val to   = Square.fromAlgebraic(ft._2).get
+      rules.legalMoves(c)(from).find(_.to == to).fold(c)(rules.applyMove(c))
+    }
+
+  private def stalemateContext(): GameContext =
+    val board = Board(
+      Map(
+        Square(File.H, Rank.R8) -> Piece(Color.Black, PieceType.King),
+        Square(File.F, Rank.R7) -> Piece(Color.White, PieceType.Queen),
+        Square(File.G, Rank.R6) -> Piece(Color.White, PieceType.King),
+      ),
+    )
+    GameContext(board, Color.Black, CastlingRights.None, None, 0, List.empty, initialBoard = board)
+
+  private def kingsOnlyContext(): GameContext =
+    val board = Board(
+      Map(
+        Square(File.E, Rank.R1) -> Piece(Color.White, PieceType.King),
+        Square(File.E, Rank.R8) -> Piece(Color.Black, PieceType.King),
+      ),
+    )
+    GameContext(board, Color.White, CastlingRights.None, None, 0, List.empty, initialBoard = board)
+
+  private def threefoldContext(): GameContext =
+    val g1 = Square(File.G, Rank.R1)
+    val f3 = Square(File.F, Rank.R3)
+    val g8 = Square(File.G, Rank.R8)
+    val f6 = Square(File.F, Rank.R6)
+    def mv(c: GameContext, from: Square, to: Square): GameContext =
+      rules.legalMoves(c)(from).find(_.to == to).fold(c)(rules.applyMove(c))
+    val c1 = mv(GameContext.initial, g1, f3)
+    val c2 = mv(c1, g8, f6)
+    val c3 = mv(c2, f3, g1)
+    val c4 = mv(c3, f6, g8)
+    val c5 = mv(c4, g1, f3)
+    val c6 = mv(c5, g8, f6)
+    val c7 = mv(c6, f3, g1)
+    mv(c7, f6, g8)
+
+  // ── allLegalMoves ─────────────────────────────────────────────────
+
+  test("allLegalMoves returns 20 moves for initial position"):
+    resource.allLegalMoves(GameContext.initial) should have size 20
+
+  // ── legalMoves ────────────────────────────────────────────────────
+
+  test("legalMoves returns 2 moves for e2 pawn"):
+    resource.legalMoves(ctxSq(GameContext.initial, "e2")) should have size 2
+
+  test("legalMoves throws BadRequestException for invalid square"):
+    an[BadRequestException] should be thrownBy
+      resource.legalMoves(ctxSq(GameContext.initial, "z9"))
+
+  // ── candidateMoves ────────────────────────────────────────────────
+
+  test("candidateMoves returns moves for e2 pawn"):
+    resource.candidateMoves(ctxSq(GameContext.initial, "e2")) should not be empty
+
+  test("candidateMoves throws BadRequestException for invalid square"):
+    an[BadRequestException] should be thrownBy
+      resource.candidateMoves(ctxSq(GameContext.initial, "z9"))
+
+  // ── isCheck ───────────────────────────────────────────────────────
+
+  test("isCheck returns false for initial position"):
+    resource.isCheck(GameContext.initial) shouldBe false
+
+  test("isCheck returns true when king is attacked"):
+    resource.isCheck(checkContext()) shouldBe true
+
+  // ── isCheckmate ───────────────────────────────────────────────────
+
+  test("isCheckmate returns false for initial position"):
+    resource.isCheckmate(GameContext.initial) shouldBe false
+
+  test("isCheckmate returns true for Fool's mate"):
+    resource.isCheckmate(foolsMate()) shouldBe true
+
+  // ── isStalemate ───────────────────────────────────────────────────
+
+  test("isStalemate returns false for initial position"):
+    resource.isStalemate(GameContext.initial) shouldBe false
+
+  test("isStalemate returns true for stalemate position"):
+    resource.isStalemate(stalemateContext()) shouldBe true
+
+  // ── isInsufficientMaterial ────────────────────────────────────────
+
+  test("isInsufficientMaterial returns false for initial position"):
+    resource.isInsufficientMaterial(GameContext.initial) shouldBe false
+
+  test("isInsufficientMaterial returns true for kings only"):
+    resource.isInsufficientMaterial(kingsOnlyContext()) shouldBe true
+
+  // ── isFiftyMoveRule ───────────────────────────────────────────────
+
+  test("isFiftyMoveRule returns false for initial position"):
+    resource.isFiftyMoveRule(GameContext.initial) shouldBe false
+
+  test("isFiftyMoveRule returns true when halfMoveClock is 100"):
+    resource.isFiftyMoveRule(GameContext.initial.copy(halfMoveClock = 100)) shouldBe true
+
+  // ── isThreefoldRepetition ─────────────────────────────────────────
+
+  test("isThreefoldRepetition returns false for initial position"):
+    resource.isThreefoldRepetition(GameContext.initial) shouldBe false
+
+  test("isThreefoldRepetition returns true after repeated moves"):
+    resource.isThreefoldRepetition(threefoldContext()) shouldBe true
+
+  // ── applyMove ─────────────────────────────────────────────────────
+
+  test("applyMove returns updated context with switched turn"):
+    val move = rules
+      .legalMoves(GameContext.initial)(Square(File.E, Rank.R2))
+      .find(_.to == Square(File.E, Rank.R4))
+      .get
+    resource.applyMove(ctxMv(GameContext.initial, move)).turn shouldBe Color.Black