docs(keycloak-session-store): import the session-storage lab as a new project

The keycloak project ended with four open questions that design could not settle. A two-VM lab was built to answer them by measurement, and this is that material: 26 experiments, 125 raw command outputs, 22 browser captures. Follows the import procedure in README.md. source/ the originating repository verbatim — 78 documents, 28 SVGs, 8 manifests, plus .source-revision recording the commit final/ the SSOT document.md 729 lines written from the 29 experiment documents, not concatenated: what was predicted, what was measured, and where the measurement itself was wrong evidence/raw 125 outputs, flattened to <experiment>__<file> because the originals collided (01-baseline.txt appeared three times) and the audit only globs the top level evidence/meta one per raw file; command and exitCode are null and the README says why rather than inventing them evidence/browser 22 captures assets/ three diagrams through techviz .techviz/ their VizSpecs A separate project rather than an addition to keycloak: the B-layer answers that project's four questions, but the A, C and D layers are about cluster failure, SSO and operations, and one document.md should hold one subject. The four question records there can point here through 관계. Recorded rather than papered over: only three of the 28 diagrams were remade. The repository forbids hand-drawn SVG and forbids titles inside the canvas; all 28 originals carry both, so converting them is redrawing, not reformatting. They stay in source/ and the gap is written into the document. verify-pipeline.py passes. audit-records.py reports no issues. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-04 22:51:59 +09:00
parent 43bccd08a8
commit b2963105a8
5017 changed files with 372751 additions and 4943 deletions
@@ -0,0 +1,124 @@
+package dev.caskeleton.adapter.outbound.persistence.platform.pool;
+
+import com.zaxxer.hikari.HikariConfig;
+import com.zaxxer.hikari.HikariDataSource;
+import dev.caskeleton.adapter.outbound.persistence.testkit.pool.PoolMeasurement;
+import dev.caskeleton.adapter.outbound.persistence.testkit.postgresql.PostgreSqlContainerFactory;
+import dev.caskeleton.adapter.outbound.persistence.testkit.postgresql.PostgreSqlVersion;
+import java.sql.Connection;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.testcontainers.postgresql.PostgreSQLContainer;
+
+/** Analysis-only probe: what a real saturated Hikari pool reports, and how long acquisition waits. */
+class AnalysisPoolSaturationProbe {
+
+  private static PostgreSQLContainer container;
+
+  @BeforeAll
+  static void startServer() {
+    container = PostgreSqlContainerFactory.create(PostgreSqlVersion.PG_16);
+    container.start();
+  }
+
+  @AfterAll
+  static void stopServer() {
+    if (container != null) {
+      container.stop();
+    }
+  }
+
+  @Test
+  void realSaturatedPoolPendingCount() throws Exception {
+    try (HikariDataSource pool = pool(2, 3000L)) {
+      Connection first = pool.getConnection();
+      Connection second = pool.getConnection();
+      CountDownLatch waiterStarted = new CountDownLatch(1);
+      AtomicReference<String> waiterOutcome = new AtomicReference<>("none");
+      Thread waiter =
+          new Thread(
+              () -> {
+                waiterStarted.countDown();
+                try (Connection blocked = pool.getConnection()) {
+                  waiterOutcome.set("acquired");
+                } catch (Exception refused) {
+                  waiterOutcome.set(refused.getClass().getSimpleName());
+                }
+              });
+      waiter.start();
+      waiterStarted.await(5, TimeUnit.SECONDS);
+      Thread.sleep(500L);
+
+      var bean = pool.getHikariPoolMXBean();
+      PoolMeasurement measurement =
+          new PoolMeasurement(
+              bean.getActiveConnections(),
+              bean.getIdleConnections(),
+              bean.getThreadsAwaitingConnection(),
+              Duration.ZERO);
+      System.out.println("realPool.active=" + measurement.active());
+      System.out.println("realPool.idle=" + measurement.idle());
+      System.out.println("realPool.pending=" + measurement.pending());
+      System.out.println("realPool.saturated=" + measurement.saturated());
+
+      first.close();
+      waiter.join(10_000L);
+      System.out.println("realPool.waiterOutcome=" + waiterOutcome.get());
+      second.close();
+    }
+  }
+
+  @Test
+  void acquireWaitAgainstTheConfiguredTimeout() throws Exception {
+    long configuredTimeoutMillis = 500L;
+    try (HikariDataSource pool = pool(2, configuredTimeoutMillis)) {
+      Connection first = pool.getConnection();
+      Connection second = pool.getConnection();
+      Instant startedAt = Instant.now();
+      String outcome;
+      try (Connection refused = pool.getConnection()) {
+        outcome = "acquired";
+      } catch (Exception failure) {
+        outcome = failure.getClass().getSimpleName();
+      }
+      Duration waited = Duration.between(startedAt, Instant.now());
+      System.out.println("acquire.configuredTimeoutMillis=" + configuredTimeoutMillis);
+      System.out.println("acquire.observedWaitMillis=" + waited.toMillis());
+      System.out.println("acquire.outcome=" + outcome);
+      System.out.println(
+          "acquire.assertedUpperBoundMillis=" + (configuredTimeoutMillis + 2000L));
+      first.close();
+      second.close();
+    }
+  }
+
+  @Test
+  void handBuiltFixtureStateVersusRealPoolState() {
+    PoolMeasurement fixture = new PoolMeasurement(4, 2, 3, Duration.ofMillis(80));
+    System.out.println("fixture.active=" + fixture.active());
+    System.out.println("fixture.idle=" + fixture.idle());
+    System.out.println("fixture.pending=" + fixture.pending());
+    System.out.println("fixture.saturated=" + fixture.saturated());
+    System.out.println("fixture.total=" + fixture.total());
+    int concurrentThreads = 8;
+    int maxRequiresNewDepth = 1;
+    System.out.println(
+        "formula.required=" + (concurrentThreads * (1 + maxRequiresNewDepth) + 1));
+  }
+
+  private static HikariDataSource pool(int size, long connectionTimeoutMillis) {
+    HikariConfig config = new HikariConfig();
+    config.setJdbcUrl(container.getJdbcUrl());
+    config.setUsername(container.getUsername());
+    config.setPassword(container.getPassword());
+    config.setMaximumPoolSize(size);
+    config.setConnectionTimeout(connectionTimeoutMillis);
+    return new HikariDataSource(config);
+  }
+}