feat: add ps-cache-kotlin sample for connection-affinity testing

ps-cache-kotlin/Dockerfile

@@ -0,0 +1,12 @@
+FROM maven:3.9-eclipse-temurin-21 AS builder
+WORKDIR /app
+COPY pom.xml .
+RUN mvn dependency:go-offline -q
+COPY src/ src/
+RUN mvn package -DskipTests -q
+
+FROM eclipse-temurin:21-jre-alpine
+WORKDIR /app
+COPY --from=builder /app/target/kotlin-app-1.0.0.jar app.jar
+EXPOSE 8080
+CMD ["java", "-jar", "app.jar"]

ps-cache-kotlin/docker-compose.yml

@@ -0,0 +1,34 @@
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: testdb
+    ports:
+      - "5433:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 2s
+      timeout: 5s
+      retries: 5
+
+  api:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      DB_HOST: db
+      DB_PORT: "5432"
+      DB_USER: postgres
+      DB_PASSWORD: postgres
+      DB_NAME: testdb
+    depends_on:
+      db:
+        condition: service_healthy
+
+volumes:
+  pgdata:

ps-cache-kotlin/init.sql

@@ -0,0 +1,15 @@
+CREATE SCHEMA IF NOT EXISTS travelcard;
+
+CREATE TABLE IF NOT EXISTS travelcard.travel_account (
+    id        SERIAL PRIMARY KEY,
+    member_id INT    NOT NULL UNIQUE,
+    name      TEXT   NOT NULL,
+    balance   INT    NOT NULL DEFAULT 0
+);
+
+INSERT INTO travelcard.travel_account (member_id, name, balance) VALUES
+    (19, 'Alice',   1000),
+    (23, 'Bob',     2500),
+    (31, 'Charlie', 500),
+    (42, 'Diana',   7500)
+ON CONFLICT (member_id) DO NOTHING;

ps-cache-kotlin/pom.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.4.4</version>
+    </parent>
+    <groupId>com.demo</groupId>
+    <artifactId>kotlin-app</artifactId>
+    <version>1.0.0</version>
+    <properties>
+        <java.version>21</java.version>
+        <kotlin.version>1.9.25</kotlin.version>
+    </properties>
+    <dependencies>
+        <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
+        <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-jdbc</artifactId></dependency>
+        <dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId></dependency>
+        <dependency><groupId>org.jetbrains.kotlin</groupId><artifactId>kotlin-reflect</artifactId></dependency>
+        <dependency><groupId>org.jetbrains.kotlin</groupId><artifactId>kotlin-stdlib</artifactId></dependency>
+    </dependencies>
+    <build>
+        <sourceDirectory>src/main/kotlin</sourceDirectory>
+        <plugins>
+            <plugin>
+                <groupId>org.jetbrains.kotlin</groupId>
+                <artifactId>kotlin-maven-plugin</artifactId>
+                <version>${kotlin.version}</version>
+                <configuration>
+                    <compilerPlugins><plugin>spring</plugin></compilerPlugins>
+                    <jvmTarget>${java.version}</jvmTarget>
+                </configuration>
+                <dependencies>
+                    <dependency><groupId>org.jetbrains.kotlin</groupId><artifactId>kotlin-maven-allopen</artifactId><version>${kotlin.version}</version></dependency>
+                </dependencies>
+                <executions><execution><id>compile</id><goals><goal>compile</goal></goals></execution></executions>
+            </plugin>
+            <plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin>
+        </plugins>
+    </build>
+</project>

ps-cache-kotlin/src/main/kotlin/com/demo/App.kt

@@ -0,0 +1,91 @@
+package com.demo
+
+import org.springframework.boot.autoconfigure.SpringBootApplication
+import org.springframework.boot.runApplication
+import org.springframework.jdbc.core.JdbcTemplate
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.RequestParam
+import org.springframework.web.bind.annotation.RestController
+import javax.sql.DataSource
+import com.zaxxer.hikari.HikariDataSource
+
+@SpringBootApplication
+class App
+
+fun main(args: Array<String>) {
+    runApplication<App>(*args)
+}
+
+data class Account(
+    val id: Int,
+    val memberId: Int,
+    val name: String,
+    val balance: Int
+)
+
+@RestController
+class AccountController(private val jdbc: JdbcTemplate, private val dataSource: DataSource) {
+
+    @GetMapping("/health")
+    fun health() = mapOf("status" to "ok")
+
+    /**
+     * /account?member=N queries the travel_account table.
+     *
+     * JDBC PS caching (prepareThreshold=1):
+     * - 1st call on a fresh connection: Parse(query="SELECT ...") + Bind + Describe + Execute
+     * - 2nd+ calls on same connection: Bind(ps="S_1") + Execute only (cached PS)
+     *
+     * The /evict endpoint forces HikariCP to evict all connections, so the
+     * NEXT /account call gets a fresh connection with cold PS cache.
+     */
+    @GetMapping("/account")
+    fun getAccount(@RequestParam("member") memberId: Int): Any {
+        return jdbc.execute { conn: java.sql.Connection ->
+            conn.autoCommit = false
+            try {
+                val ps = conn.prepareStatement(
+                    """SELECT id, member_id, name, balance
+                       FROM travelcard.travel_account
+                       WHERE member_id = ?"""
+                )
+                ps.setInt(1, memberId)
+                val rs = ps.executeQuery()
+
+                val result = if (rs.next()) {
+                    Account(
+                        id = rs.getInt("id"),
+                        memberId = rs.getInt("member_id"),
+                        name = rs.getString("name"),
+                        balance = rs.getInt("balance")
+                    )
+                } else {
+                    mapOf("error" to "not found", "member_id" to memberId)
+                }
+
+                rs.close()
+                ps.close()
+                conn.commit()
+                result
+            } catch (e: Exception) {
+                conn.rollback()
+                throw e
+            }
+        }!!
+    }
+
+    /**
+     * /evict forces HikariCP to evict all idle connections.
+     * Next request gets a FRESH PG connection → cold PS cache.
+     * This simulates what happens in production when connections cycle.
+     */
+    @GetMapping("/evict")
+    fun evict(): Map<String, Any> {
+        val hikari = dataSource as HikariDataSource
+        hikari.hikariPoolMXBean?.softEvictConnections()
+        // Also wait briefly for eviction
+        Thread.sleep(200)
+        return mapOf("evicted" to true, "active" to (hikari.hikariPoolMXBean?.activeConnections ?: 0),
+                      "idle" to (hikari.hikariPoolMXBean?.idleConnections ?: 0))
+    }
+}

ps-cache-kotlin/src/main/resources/application.properties

@@ -0,0 +1,7 @@
+server.port=8080
+spring.datasource.url=jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:testdb}?prepareThreshold=1&preparedStatementCacheQueries=256
+spring.datasource.username=${DB_USER:postgres}
+spring.datasource.password=${DB_PASSWORD:postgres}
+spring.datasource.hikari.maximum-pool-size=1
+spring.datasource.hikari.minimum-idle=1
+spring.sql.init.mode=never

ps-cache-kotlin/test.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="http://localhost:8080"
+
+echo "=== PS-Cache Mock Mismatch Test (Kotlin/JDBC) ==="
+
+echo "--- Window 1: Connection A ---"
+echo "  /account?member=19:"
+curl -s "$BASE_URL/account?member=19"
+echo ""
+sleep 0.3
+
+echo "  /account?member=23:"
+curl -s "$BASE_URL/account?member=23"
+echo ""
+sleep 0.3
+
+echo ""
+echo "--- Evict (force new connection) ---"
+echo "  /evict:"
+curl -s "$BASE_URL/evict"
+echo ""
+sleep 1
+
+echo ""
+echo "--- Window 2: Connection B ---"
+echo "  /account?member=31:"
+curl -s "$BASE_URL/account?member=31"
+echo ""
+sleep 0.3
+
+echo "  /account?member=42:"
+curl -s "$BASE_URL/account?member=42"
+echo ""
+
+echo ""
+echo "=== Done ==="