rivetkit 2.1.5 → 2.1.6-rc.1

package/src/driver-test-suite/tests/actor-db-kv-stats.ts

@@ -0,0 +1,282 @@
+import { describe, expect, test } from "vitest";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest, waitFor } from "../utils";
+
+export function runActorDbKvStatsTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor Database KV Stats Tests", () => {
+		// -- Warm path tests --
+		// These call warmUp first to prime the pager cache and reset
+		// stats, then measure the exact KV behavior of subsequent ops.
+		// This is the steady-state path for a live actor.
+
+		test(
+			"warm UPDATE uses BATCH_ATOMIC: exactly 1 putBatch, 0 reads, no journal",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-ba-${crypto.randomUUID()}`,
+				]);
+
+				await actor.warmUp();
+
+				await actor.increment();
+				const stats = await actor.getStats();
+				const log = await actor.getLog();
+
+				expect(stats.putBatchCalls).toBe(1);
+				expect(stats.getBatchCalls).toBe(0);
+
+				const allKeys = log.flatMap((e: { keys: string[] }) => e.keys);
+				const journalKeys = allKeys.filter((k: string) => k.includes("journal"));
+				expect(journalKeys.length).toBe(0);
+			},
+			30_000,
+		);
+
+		test(
+			"warm SELECT uses 0 KV round trips",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-2-${crypto.randomUUID()}`,
+				]);
+
+				await actor.warmUp();
+
+				await actor.getCount();
+				const stats = await actor.getStats();
+
+				expect(stats.getBatchCalls).toBe(0);
+				expect(stats.putBatchCalls).toBe(0);
+			},
+			30_000,
+		);
+
+		test(
+			"warm SELECT after UPDATE adds no KV round trips",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-3-${crypto.randomUUID()}`,
+				]);
+
+				await actor.warmUp();
+
+				await actor.increment();
+				const updateStats = await actor.getStats();
+
+				await actor.resetStats();
+				await actor.incrementAndRead();
+				const combinedStats = await actor.getStats();
+
+				expect(combinedStats.putBatchCalls).toBe(updateStats.putBatchCalls);
+				expect(combinedStats.getBatchCalls).toBe(updateStats.getBatchCalls);
+			},
+			30_000,
+		);
+
+		test(
+			"warm multi-page INSERT writes multiple chunk keys",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-4-${crypto.randomUUID()}`,
+				]);
+
+				// First call creates table/index and primes cache
+				await actor.insertWithIndex();
+				await actor.resetStats();
+
+				await actor.insertWithIndex();
+				const stats = await actor.getStats();
+				const log = await actor.getLog();
+
+				expect(stats.putBatchCalls).toBeGreaterThanOrEqual(1);
+				expect(stats.putBatchEntries).toBeGreaterThan(1);
+
+				const putOps = log.filter(
+					(e: { op: string }) => e.op === "putBatch" || e.op === "put",
+				);
+				const allKeys = putOps.flatMap((e: { keys: string[] }) => e.keys);
+				const mainChunkKeys = allKeys.filter((k: string) =>
+					k.startsWith("chunk:main["),
+				);
+				expect(mainChunkKeys.length).toBeGreaterThanOrEqual(1);
+			},
+			30_000,
+		);
+
+		test(
+			"warm ROLLBACK produces no data page writes",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-5-${crypto.randomUUID()}`,
+				]);
+
+				await actor.rollbackTest();
+				await actor.resetStats();
+
+				await actor.rollbackTest();
+				const log = await actor.getLog();
+
+				const putOps = log.filter(
+					(e: { op: string }) => e.op === "putBatch" || e.op === "put",
+				);
+				const mainChunkKeys = putOps
+					.flatMap((e: { keys: string[] }) => e.keys)
+					.filter((k: string) => k.startsWith("chunk:main["));
+				expect(mainChunkKeys.length).toBe(0);
+			},
+			30_000,
+		);
+
+		test(
+			"warm multi-statement transaction produces writes",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-6-${crypto.randomUUID()}`,
+				]);
+
+				await actor.multiStmtTx();
+				await actor.resetStats();
+
+				await actor.multiStmtTx();
+				const stats = await actor.getStats();
+
+				expect(stats.putBatchCalls).toBeGreaterThanOrEqual(1);
+			},
+			30_000,
+		);
+
+		// -- Structural property tests --
+		// These assert invariants that hold regardless of cache state.
+
+		test(
+			"no WAL or SHM operations occur",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-7-${crypto.randomUUID()}`,
+				]);
+
+				await actor.warmUp();
+
+				await actor.increment();
+				const log = await actor.getLog();
+
+				const allKeys = log.flatMap((e: { keys: string[] }) => e.keys);
+				const walOrShmKeys = allKeys.filter(
+					(k: string) => k.includes("wal") || k.includes("shm"),
+				);
+				expect(walOrShmKeys.length).toBe(0);
+			},
+			30_000,
+		);
+
+		test(
+			"every putBatch has at most 128 keys",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-8-${crypto.randomUUID()}`,
+				]);
+
+				await actor.warmUp();
+
+				await actor.increment();
+				const log = await actor.getLog();
+
+				const putBatchOps = log.filter(
+					(e: { op: string }) => e.op === "putBatch",
+				);
+				for (const entry of putBatchOps) {
+					expect(
+						(entry as { keys: string[] }).keys.length,
+					).toBeLessThanOrEqual(128);
+				}
+			},
+			30_000,
+		);
+
+		// -- Large transaction tests --
+
+		test(
+			"large transaction falls back to journal when exceeding 127 dirty pages",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-9-${crypto.randomUUID()}`,
+				]);
+
+				await actor.warmUp();
+
+				await actor.bulkInsertLarge();
+				const stats = await actor.getStats();
+				const log = await actor.getLog();
+
+				expect(stats.putBatchCalls).toBeGreaterThan(1);
+
+				const allKeys = log.flatMap((e: { keys: string[] }) => e.keys);
+				const journalKeys = allKeys.filter((k: string) =>
+					k.includes("journal"),
+				);
+				expect(journalKeys.length).toBeGreaterThan(0);
+
+				const putBatchOps = log.filter(
+					(e: { op: string }) => e.op === "putBatch",
+				);
+				for (const entry of putBatchOps) {
+					expect(
+						(entry as { keys: string[] }).keys.length,
+					).toBeLessThanOrEqual(128);
+				}
+			},
+			60_000,
+		);
+
+		test(
+			"large transaction data integrity: 200 rows and integrity check pass",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-10-${crypto.randomUUID()}`,
+				]);
+
+				await actor.bulkInsertLarge();
+
+				const count = await actor.getRowCount();
+				expect(count).toBe(200);
+
+				const integrity = await actor.runIntegrityCheck();
+				expect(integrity).toBe("ok");
+			},
+			60_000,
+		);
+
+		test(
+			"large transaction survives actor sleep and wake",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.dbKvStatsActor.getOrCreate([
+					`kv-stats-11-${crypto.randomUUID()}`,
+				]);
+
+				await actor.bulkInsertLarge();
+				const countBefore = await actor.getRowCount();
+				expect(countBefore).toBe(200);
+
+				await actor.triggerSleep();
+				await waitFor(driverTestConfig, 250);
+
+				const countAfter = await actor.getRowCount();
+				expect(countAfter).toBe(200);
+
+				const integrity = await actor.runIntegrityCheck();
+				expect(integrity).toBe("ok");
+			},
+			60_000,
+		);
+	});
+}

package/src/driver-test-suite/tests/actor-db-raw.ts

@@ -25,12 +25,16 @@ export function runActorDbRawTests(driverTestConfig: DriverTestConfig) {
 				const { client } = await setupDriverTest(c, driverTestConfig);
 
 				// First instance adds items
-				const instance1 = client.dbActorRaw.getOrCreate(["test-persistence"]);
+				const instance1 = client.dbActorRaw.getOrCreate([
+					"test-persistence",
+				]);
 				await instance1.insertValue("Item 1");
 				await instance1.insertValue("Item 2");
 
 				// Second instance (same actor) should see persisted data
-				const instance2 = client.dbActorRaw.getOrCreate(["test-persistence"]);
+				const instance2 = client.dbActorRaw.getOrCreate([
+					"test-persistence",
+				]);
 				const count = await instance2.getCount();
 				expect(count).toBe(2);
 			});

package/src/driver-test-suite/tests/actor-db.ts

@@ -52,7 +52,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"bootstraps schema on startup",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-bootstrap-${crypto.randomUUID()}`,
 					]);
@@ -66,7 +69,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"supports CRUD, raw SQL, and multi-statement exec",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-crud-${crypto.randomUUID()}`,
 					]);
@@ -78,8 +84,12 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 
 					const values = await actor.getValues();
 					expect(values.length).toBeGreaterThanOrEqual(2);
-					expect(values.some((row) => row.value === "alpha")).toBeTruthy();
-					expect(values.some((row) => row.value === "beta")).toBeTruthy();
+					expect(
+						values.some((row) => row.value === "alpha"),
+					).toBeTruthy();
+					expect(
+						values.some((row) => row.value === "beta"),
+					).toBeTruthy();
 
 					await actor.updateValue(first.id, "alpha-updated");
 					const updated = await actor.getValue(first.id);
@@ -100,7 +110,8 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 						expect(rawCount).toBe(1);
 					}
 
-					const multiValue = await actor.multiStatementInsert("gamma");
+					const multiValue =
+						await actor.multiStatementInsert("gamma");
 					expect(multiValue).toBe("gamma-updated");
 				},
 				dbTestTimeout,
@@ -109,7 +120,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"handles transactions",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-tx-${crypto.randomUUID()}`,
 					]);
@@ -127,7 +141,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"persists across sleep and wake cycles",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-sleep-${crypto.randomUUID()}`,
 					]);
@@ -149,10 +166,15 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"completes onDisconnect DB writes before sleeping",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const key = `db-${variant}-disconnect-${crypto.randomUUID()}`;
 
-					const actor = getDbActor(client, variant).getOrCreate([key]);
+					const actor = getDbActor(client, variant).getOrCreate([
+						key,
+					]);
 					await actor.reset();
 					await actor.configureDisconnectInsert(true, 250);
 
@@ -167,7 +189,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"handles high-volume inserts",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-high-volume-${crypto.randomUUID()}`,
 					]);
@@ -187,7 +212,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"handles payloads across chunk boundaries",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-chunk-${crypto.randomUUID()}`,
 					]);
@@ -205,13 +233,17 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"handles large payloads",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-large-${crypto.randomUUID()}`,
 					]);
 
 					await actor.reset();
-					const { id } = await actor.insertPayloadOfSize(LARGE_PAYLOAD_SIZE);
+					const { id } =
+						await actor.insertPayloadOfSize(LARGE_PAYLOAD_SIZE);
 					const storedSize = await actor.getPayloadSize(id);
 					expect(storedSize).toBe(LARGE_PAYLOAD_SIZE);
 				},
@@ -221,7 +253,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"supports shrink and regrow workloads with vacuum",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-shrink-regrow-${crypto.randomUUID()}`,
 					]);
@@ -256,7 +291,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"handles repeated updates to the same row",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-updates-${crypto.randomUUID()}`,
 					]);
@@ -289,7 +327,10 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			test(
 				"passes integrity checks after mixed workload and sleep",
 				async (c) => {
-					const { client } = await setupDriverTest(c, driverTestConfig);
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
 					const actor = getDbActor(client, variant).getOrCreate([
 						`db-${variant}-integrity-${crypto.randomUUID()}`,
 					]);
@@ -299,11 +340,15 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 						INTEGRITY_SEED_COUNT,
 						INTEGRITY_CHURN_COUNT,
 					);
-					expect((await actor.integrityCheck()).toLowerCase()).toBe("ok");
+					expect((await actor.integrityCheck()).toLowerCase()).toBe(
+						"ok",
+					);
 
 					await actor.triggerSleep();
 					await waitFor(driverTestConfig, SLEEP_WAIT_MS + 100);
-					expect((await actor.integrityCheck()).toLowerCase()).toBe("ok");
+					expect((await actor.integrityCheck()).toLowerCase()).toBe(
+						"ok",
+					);
 				},
 				dbTestTimeout,
 			);
@@ -315,7 +360,9 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			"runs db provider cleanup on sleep",
 			async (c) => {
 				const { client } = await setupDriverTest(c, driverTestConfig);
-				const observer = client.dbLifecycleObserver.getOrCreate(["observer"]);
+				const observer = client.dbLifecycleObserver.getOrCreate([
+					"observer",
+				]);
 
 				const lifecycle = client.dbLifecycle.getOrCreate([
 					`db-lifecycle-sleep-${crypto.randomUUID()}`,
@@ -340,7 +387,9 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 
 				expect(after.create).toBeGreaterThanOrEqual(before.create);
 				expect(after.migrate).toBeGreaterThanOrEqual(before.migrate);
-				expect(after.cleanup).toBeGreaterThanOrEqual(before.cleanup + 1);
+				expect(after.cleanup).toBeGreaterThanOrEqual(
+					before.cleanup + 1,
+				);
 			},
 			lifecycleTestTimeout,
 		);
@@ -349,7 +398,9 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			"runs db provider cleanup on destroy",
 			async (c) => {
 				const { client } = await setupDriverTest(c, driverTestConfig);
-				const observer = client.dbLifecycleObserver.getOrCreate(["observer"]);
+				const observer = client.dbLifecycleObserver.getOrCreate([
+					"observer",
+				]);
 
 				const lifecycle = client.dbLifecycle.getOrCreate([
 					`db-lifecycle-destroy-${crypto.randomUUID()}`,
@@ -380,8 +431,11 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			"runs db provider cleanup when migration fails",
 			async (c) => {
 				const { client } = await setupDriverTest(c, driverTestConfig);
-				const observer = client.dbLifecycleObserver.getOrCreate(["observer"]);
-				const beforeTotalCleanup = await observer.getTotalCleanupCount();
+				const observer = client.dbLifecycleObserver.getOrCreate([
+					"observer",
+				]);
+				const beforeTotalCleanup =
+					await observer.getTotalCleanupCount();
 				const key = `db-lifecycle-migrate-failure-${crypto.randomUUID()}`;
 				const lifecycle = client.dbLifecycleFailing.getOrCreate([key]);
 
@@ -402,7 +456,9 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 					await waitFor(driverTestConfig, LIFECYCLE_POLL_INTERVAL_MS);
 				}
 
-				expect(cleanupCount).toBeGreaterThanOrEqual(beforeTotalCleanup + 1);
+				expect(cleanupCount).toBeGreaterThanOrEqual(
+					beforeTotalCleanup + 1,
+				);
 			},
 			lifecycleTestTimeout,
 		);
@@ -411,7 +467,9 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 			"handles parallel actor lifecycle churn",
 			async (c) => {
 				const { client } = await setupDriverTest(c, driverTestConfig);
-				const observer = client.dbLifecycleObserver.getOrCreate(["observer"]);
+				const observer = client.dbLifecycleObserver.getOrCreate([
+					"observer",
+				]);
 
 				const actorHandles = Array.from({ length: 12 }, (_, i) =>
 					client.dbLifecycle.getOrCreate([
@@ -423,19 +481,29 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 				);
 
 				await Promise.all(
-					actorHandles.map((handle, i) => handle.insertValue(`phase-1-${i}`)),
+					actorHandles.map((handle, i) =>
+						handle.insertValue(`phase-1-${i}`),
+					),
+				);
+				await Promise.all(
+					actorHandles.map((handle) => handle.triggerSleep()),
 				);
-				await Promise.all(actorHandles.map((handle) => handle.triggerSleep()));
 				await waitFor(driverTestConfig, SLEEP_WAIT_MS + 100);
 				await Promise.all(
-					actorHandles.map((handle, i) => handle.insertValue(`phase-2-${i}`)),
+					actorHandles.map((handle, i) =>
+						handle.insertValue(`phase-2-${i}`),
+					),
 				);
 
 				const survivors = actorHandles.slice(0, 6);
 				const destroyed = actorHandles.slice(6);
 
-				await Promise.all(destroyed.map((handle) => handle.triggerDestroy()));
-				await Promise.all(survivors.map((handle) => handle.triggerSleep()));
+				await Promise.all(
+					destroyed.map((handle) => handle.triggerDestroy()),
+				);
+				await Promise.all(
+					survivors.map((handle) => handle.triggerSleep()),
+				);
 				await waitFor(driverTestConfig, SLEEP_WAIT_MS + 100);
 				await Promise.all(survivors.map((handle) => handle.ping()));
 
@@ -468,7 +536,9 @@ export function runActorDbTests(driverTestConfig: DriverTestConfig) {
 				}
 
 				for (const actorId of actorIds) {
-					expect(lifecycleCleanup.get(actorId) ?? 0).toBeGreaterThanOrEqual(1);
+					expect(
+						lifecycleCleanup.get(actorId) ?? 0,
+					).toBeGreaterThanOrEqual(1);
 				}
 			},
 			lifecycleTestTimeout,