feat: add simulation engine

Author: pvlugter

.scalafix.conf

@@ -0,0 +1,7 @@
+OrganizeImports {
+  groups = [
+    "re:javax?\\."
+    "scala."
+    "*"
+  ]
+}

README.md

@@ -5,7 +5,7 @@ This project tests event sourced actors events that are then read by a projectio
 It is currently support the following alternative Akka Persistence and Akka Projection setup:
 
 * R2DBC (Postgres) as the event sourcing event store and the projection using R2DBC (Postgres)
-* Cassandra as the event sourcing event store and the projection using JDBC (Postgres) 
+* Cassandra as the event sourcing event store and the projection using JDBC (Postgres)
 * JDBC (Postgres) as the event sourcing event store and the projection using JDBC (Postgres)
 
 ## Running a test locally
@@ -48,12 +48,16 @@ Start the application:
 sbt "run 2551"
 ```
 
+### Run simulations
+
+See [simulation/README.md] for more detail on running simulations. Or for simple test runs, see below.
+
 ### Start test run
 
 Start a test run:
 
 ```shell
-curl -X POST --data '{"name":"","nrActors":1000, "messagesPerActor": 100, "concurrentActors": 100, "bytesPerEvent": 100, "timeout": 60000}' --header "content-type: application/json" http://127.0.0.1:8051/test
+curl -X POST --data '{"nrActors":1000, "messagesPerActor": 100, "concurrentActors": 100, "bytesPerEvent": 100, "timeout": 60000}' --header "content-type: application/json" http://127.0.0.1:8051/test
 ```
 
 the params are:
@@ -73,7 +77,7 @@ the expected event total is the `nrActors` * `messagesPeractor` * `${event-proce
 Multiple projections can be run to increase the load on the tagging infrastructure while not overloading the normal event log.
 Each projection gets its own tag for the same reason. A real production application would have different projections use the same tag.
 
-The test checks that every message makes it into the projection. these are stored in the `events` table. Duplicated 
+The test checks that every message makes it into the projection. these are stored in the `events` table. Duplicated
 are detected with a primary key.
 
 To inspect the database:
@@ -137,15 +141,15 @@ Typically, multiple nodes are required to re-create issues as while one node is
 
 ### cinnamon
 
-the application exposes persistence metrics via cinnamon and prometheus. the cinnamon prometheus sandbox can be used to 
+the application exposes persistence metrics via cinnamon and prometheus. the cinnamon prometheus sandbox can be used to
 view the metrics in grafana.
 
 ## failure scenarios
 
 ### projection restart
 
 A known edge case is that a projection is restarted and delayed events from before the offset are then missed.
-This should only happen in when multiple nodes are writing events as delayed event should still be written in offset 
+This should only happen in when multiple nodes are writing events as delayed event should still be written in offset
 order.
 
 ## Deployment to eks/gke
@@ -176,7 +180,7 @@ this will create:
 - install the metrics server into the eks cluster (requried by the operator)
 - configure security groups to allow communication
 
-the outputs printed at the end of `terraform apply` give all the information needed to configure the `kubernetes/deployment.yaml` 
+the outputs printed at the end of `terraform apply` give all the information needed to configure the `kubernetes/deployment.yaml`
 
 ```
 db_endpoint = "projection-testing.cgrtpi2lqrw8.us-east-2.rds.amazonaws.com:5432"

build.sbt

@@ -1,11 +1,11 @@
-val AkkaVersion = "2.10.0"
-val AkkaHttpVersion = "10.7.0"
-val AkkaProjectionVersion = "1.6.7"
-val AkkaManagementVersion = "1.6.0"
-val AkkaPersistenceR2dbcVersion = "1.3.1"
-val AkkaPersistenceDynamoDBVersion = "2.0.5"
-val AkkaPersistenceJdbcVersion = "5.5.0"
-val AkkaPersistenceCassandraVersion = "1.3.0"
+val AkkaVersion = "2.10.5"
+val AkkaHttpVersion = "10.7.1"
+val AkkaProjectionVersion = "1.6.13"
+val AkkaManagementVersion = "1.6.2"
+val AkkaPersistenceR2dbcVersion = "1.3.7"
+val AkkaPersistenceDynamoDBVersion = "2.0.6"
+val AkkaPersistenceJdbcVersion = "5.5.2"
+val AkkaPersistenceCassandraVersion = "1.3.2"
 
 ThisBuild / dynverSeparator := "-"
 
@@ -59,6 +59,8 @@ lazy val `akka-projection-testing` = project
       "ch.qos.logback" % "logback-classic" % "1.5.12",
       "org.postgresql" % "postgresql" % "42.7.4",
       "org.hdrhistogram" % "HdrHistogram" % "2.2.2",
+      "org.apache.commons" % "commons-rng-simple" % "1.6",
+      "org.apache.commons" % "commons-statistics-distribution" % "1.1",
       "com.typesafe.akka" %% "akka-actor-testkit-typed" % AkkaVersion % Test,
       "com.typesafe.akka" %% "akka-persistence-testkit" % AkkaVersion % Test,
       "com.typesafe.akka" %% "akka-stream-testkit" % AkkaVersion % Test,

project/plugins.sbt

@@ -1,4 +1,4 @@
-addSbtPlugin("com.lightbend.cinnamon" % "sbt-cinnamon" % "2.21.2")
+addSbtPlugin("com.lightbend.cinnamon" % "sbt-cinnamon" % "2.21.3-20250408-0269a7e")
 addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.2")
 addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.10.0")
 addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.10.4")

simulation/README.md

@@ -0,0 +1,17 @@
+# Simulation
+
+A simulation engine can be used to generate more randomised projection tests.
+
+See [../README.md] for more detail on running the projection testing application generally.
+
+Examples for simulation definitions can be found in [examples].
+
+A JSON schema is available in [schema/run-simulation.json].
+
+With the projection testing application running locally with a database, a simple simulation can be run with:
+
+```sh
+curl -X POST http://localhost:8051/simulation/run \
+     -H "Content-Type: application/json" \
+     -d @simulation/examples/simple.json
+```

simulation/examples/multi.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "../schema/run-simulation.json",
+  "simulation": {
+    "name": "Multi-stage test",
+    "description": "Simulates a warm-up, peak load, and cool-down phase.",
+    "stages": [
+      {
+        "name": "Warm-up",
+        "duration": "3m",
+        "generators": [
+          {
+            "entityId": {
+              "entity": {
+                "count": "10k"
+              }
+            },
+            "activity": {
+              "frequency": "5/s",
+              "duration": {
+                "distribution": "exponential",
+                "mean": "5s",
+                "min": "1s",
+                "max": "15s"
+              },
+              "event": {
+                "frequency": "2/s",
+                "dataSize": "256B"
+              }
+            },
+            "random": {
+              "seed": 1001
+            }
+          }
+        ]
+      },
+      {
+        "name": "Peak load",
+        "duration": "5m",
+        "generators": [
+          {
+            "entityId": {
+              "entity": {
+                "count": "10k"
+              },
+              "sliceDistribution": {
+                "type": "zipf",
+                "exponent": 1.1,
+                "shuffled": true
+              }
+            },
+            "activity": {
+              "frequency": {
+                "rate": {
+                  "function": "sinusoidal",
+                  "base": "20/s",
+                  "amplitude": "10/s",
+                  "period": "30s"
+                }
+              },
+              "duration": {
+                "distribution": "log-normal",
+                "median": "8s",
+                "p95": "20s",
+                "min": "2s",
+                "max": "30s"
+              },
+              "event": {
+                "frequency": "5/s",
+                "dataSize": {
+                  "distribution": "weibull",
+                  "shape": 1.5,
+                  "scale": "1kB",
+                  "min": "100B",
+                  "max": "5kB"
+                }
+              }
+            },
+            "random": {
+              "seed": 2002
+            }
+          }
+        ]
+      },
+      {
+        "name": "Cool-down",
+        "duration": "2m",
+        "delay": "10s",
+        "generators": [
+          {
+            "entityId": {
+              "entity": {
+                "count": "10k"
+              }
+            },
+            "activity": {
+              "frequency": {
+                "rate": {
+                  "function": "linear",
+                  "initial": "10/s",
+                  "target": "1/s"
+                }
+              },
+              "duration": "3s",
+              "event": {
+                "frequency": "1/s",
+                "dataSize": "128B"
+              }
+            },
+            "random": {
+              "seed": 3003
+            }
+          }
+        ]
+      }
+    ],
+    "engine": {
+      "tick": "100ms",
+      "parallelism": 8,
+      "ackPersists": false
+    }
+  }
+}

simulation/examples/simple.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../schema/run-simulation.json",
+  "simulation": {
+    "name": "Simple",
+    "description": "Simple simulation with uniform distribution over entities.",
+    "stages": [
+      {
+        "duration": "1 minute",
+        "generators": [
+          {
+            "entityId": {
+              "entity": {
+                "count": "10k"
+              }
+            },
+            "activity": {
+              "frequency": "10 / second",
+              "duration": "10 seconds",
+              "event": {
+                "frequency": "1 / second",
+                "dataSize": "100 B"
+              }
+            }
+          }
+        ]
+      }
+    ]
+  }
+}