@cosmicdrift/kumiko-testing 0.413.1 → 0.415.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -87,7 +87,7 @@ if (typeof globalThis.Element !== "undefined") {
87
87
  // test files in one process, so without afterEach, React components from
88
88
  // file N stay mounted in file N+1's DOM.
89
89
  //
90
- // SIX leak sources (b is NOT cleaned here):
90
+ // SEVEN leak sources (b is NOT cleaned here):
91
91
  //
92
92
  // a) testing-library/react container: cleanup() unmounts and removes
93
93
  // every container node render() created.
@@ -105,6 +105,9 @@ if (typeof globalThis.Element !== "undefined") {
105
105
  // e) window.location / history.pushState.
106
106
  //
107
107
  // f) document.cookie.
108
+ //
109
+ // g) sessionStorage / localStorage: components persist UI state there on
110
+ // mount (e.g. nav collapse), which would leak into the next test file.
108
111
  afterEach(() => {
109
112
  // skip: this preload module runs its own afterEach unconditionally; plain
110
113
  // unit test files (no --dom) never get happy-dom registered, so document
@@ -149,6 +152,10 @@ afterEach(() => {
149
152
  }
150
153
  }
151
154
 
155
+ // (g) Web storage
156
+ globalThis.sessionStorage.clear();
157
+ globalThis.localStorage.clear();
158
+
152
159
  // (e) Reset window.location to happy-dom's initial url. replaceState
153
160
  // instead of pushState, otherwise a history stack of 3000+ entries
154
161
  // accumulates across all tests (memory leak, plus it breaks tests that
@@ -1,3 +1,4 @@
1
+ // @runtime dev
1
2
  export const SERVICE_ENV_DEFAULTS = {
2
3
  DATABASE_URL: "postgresql://kumiko:kumiko@localhost:15432/kumiko_dev",
3
4
  TEST_DATABASE_URL: "postgresql://kumiko:kumiko@localhost:15432/kumiko_test",
package/src/stack/db.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  // Test-DB Factory: CREATE DATABASE → connect → createEventsTable.
3
3
 
4
4
  import { DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX } from "@cosmicdrift/kumiko-framework/db";
5
+ import { requiredEnvFor } from "@cosmicdrift/kumiko-framework/env";
5
6
  import {
6
7
  acquireSessionAdvisoryLock,
7
8
  createApplicationRole,
@@ -15,18 +16,14 @@ import {
15
16
  transferPublicSchemaOwnership,
16
17
  } from "@cosmicdrift/kumiko-framework/internal/stack-support";
17
18
  import { ensureTemporalPolyfill } from "@cosmicdrift/kumiko-framework/time";
18
- import { generateId } from "@cosmicdrift/kumiko-framework/utils";
19
19
  import type { DbConnection, PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
20
+ import { testDatabaseName } from "./test-run.ts";
20
21
 
21
- function requireEnv(name: string): string {
22
- const value = process.env[name];
23
- if (!value) {
24
- throw new Error(
25
- `Missing required env var: ${name}. Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".`,
26
- );
27
- }
28
- return value;
29
- }
22
+ const requireEnv = requiredEnvFor(
23
+ "test stack",
24
+ process.env,
25
+ 'Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".',
26
+ );
30
27
 
31
28
  export const DEFAULT_TEST_DB_POOL_MAX = 10;
32
29
 
@@ -66,7 +63,7 @@ export function adminUrlOf(url: string): string {
66
63
  return url.replace(/\/[^/]+$/, "/postgres");
67
64
  }
68
65
 
69
- function databaseUrlOf(url: string, dbName: string): string {
66
+ export function databaseUrlOf(url: string, dbName: string): string {
70
67
  return url.replace(/\/[^/]+$/, `/${dbName}`);
71
68
  }
72
69
 
@@ -135,7 +132,7 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
135
132
  await ensureTemporalPolyfill();
136
133
  const opts: CreateTestDbOptions = typeof arg === "string" ? { baseUrl: arg } : (arg ?? {});
137
134
  const url = opts.baseUrl ?? requireEnv("TEST_DATABASE_URL");
138
- const dbName = opts.dbName ?? `kumiko_test_${generateId().slice(-8)}`;
135
+ const dbName = opts.dbName ?? testDatabaseName();
139
136
  const adminUrl = adminUrlOf(url);
140
137
 
141
138
  const applicationRole = opts.applicationRole === true;
@@ -200,7 +197,7 @@ export function ensureTestDbTemplate(
200
197
  options: { readonly applicationRole?: boolean } = {},
201
198
  ): Promise<void> {
202
199
  const known = testDbTemplates.get(templateDbName);
203
- if (known) return known;
200
+ if (known !== undefined) return known;
204
201
  const pending = buildTestDbTemplate(templateDbName, buildSchema, options);
205
202
  testDbTemplates.set(templateDbName, pending);
206
203
  pending.catch(() => testDbTemplates.delete(templateDbName));
@@ -29,4 +29,5 @@ export { pushEntityProjectionTables } from "./push-entity-projection-tables.ts";
29
29
  export { createTestRedis, type TestRedis } from "./redis.ts";
30
30
  export { createRequestHelper, type RequestHelper } from "./request-helper.ts";
31
31
  export { resetEventStore } from "./table-helpers.ts";
32
+ export { testRunQueueNamePrefix } from "./test-run.ts";
32
33
  export { setupTestStack, type TestStack, type TestStackOptions } from "./test-stack.ts";
@@ -1,6 +1,8 @@
1
1
  // @runtime dev
2
+ import { obliterateJobQueues } from "@cosmicdrift/kumiko-framework/jobs";
2
3
  import { generateId } from "@cosmicdrift/kumiko-framework/utils";
3
4
  import { requireEnv } from "./db.ts";
5
+ import { ensureCurrentTestRunAlive } from "./test-run.ts";
4
6
 
5
7
  export type TestRedis = {
6
8
  redis: import("ioredis").Redis;
@@ -12,8 +14,8 @@ export type TestRedis = {
12
14
  redisUrl: string;
13
15
  /** The per-test `keyPrefix` on `redis`, e.g. `kt:1a2b3c4d:`. */
14
16
  keyPrefix: string;
15
- /** Delete every key this test created (prefix-scoped). Replaces the old
16
- * `redis.flushdb()` — that wiped other parallel tests' BullMQ state. */
17
+ /** Delete every key this test created (prefix-scoped). Scans the whole Redis, so call it
18
+ * between tests that need a clean namespace, not as teardown — the run sweep does that. */
17
19
  flushNamespace: () => Promise<void>;
18
20
  cleanup: () => Promise<void>;
19
21
  };
@@ -27,17 +29,18 @@ export function queueNamePrefixForTestRedis(keyPrefix: string): string {
27
29
 
28
30
  export type CreateTestRedisOptions = {
29
31
  /** Reuse another stack's keyPrefix on a fresh connection. cleanup() then only
30
- * disconnects — the owning stack flushes the namespace and its queues. */
32
+ * disconnects — the owning stack removes the shared queues. */
31
33
  readonly borrowKeyPrefix?: string;
32
34
  };
33
35
 
34
36
  export async function createTestRedis(opts: CreateTestRedisOptions = {}): Promise<TestRedis> {
35
37
  const Redis = (await import("ioredis")).Redis;
36
38
  const redisUrl = requireEnv("REDIS_URL");
37
- // Every test gets a per-file key prefix on a shared DB (no DB-pool-of-15
38
- // round-robin). Collisions at birthday-paradox rates are gone — the
39
- // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
40
- const prefix = opts.borrowKeyPrefix ?? `kt:${generateId().slice(-8)}:`;
39
+ // Per-stack prefix inside the test run's namespace on a shared DB: the run sweep removes the
40
+ // namespace once per run instead of every cleanup scanning the whole Redis for it.
41
+ const prefix =
42
+ opts.borrowKeyPrefix ??
43
+ `kt:${await ensureCurrentTestRunAlive(redisUrl)}:${generateId().slice(-8)}:`;
41
44
  // Callers that check redis.status (rate-limit resolver) must not see "connect" on their first call.
42
45
  const redis = new Redis(redisUrl, { keyPrefix: prefix, lazyConnect: true });
43
46
  try {
@@ -73,12 +76,12 @@ export async function createTestRedis(opts: CreateTestRedisOptions = {}): Promis
73
76
  cleanup: async () => {
74
77
  if (opts.borrowKeyPrefix !== undefined) {
75
78
  redis.disconnect();
76
- // skip: the owning stack flushes the shared namespace and its queues
79
+ // skip: the owning stack removes the shared queues
77
80
  return;
78
81
  }
79
- await flushNamespace();
80
- // The derived per-stack JobRunner queues sit outside the keyPrefix.
81
- await deleteKeysMatching(`bull:${queueNamePrefixForTestRedis(prefix)}-*`);
82
+ // The namespace itself stays for the run sweep; only the derived JobRunner queues, which
83
+ // sit outside the keyPrefix, go now, by name.
84
+ await obliterateJobQueues({ redisUrl, queueNamePrefix: queueNamePrefixForTestRedis(prefix) });
82
85
  redis.disconnect();
83
86
  },
84
87
  };
@@ -0,0 +1,208 @@
1
+ // @runtime dev
2
+ import { randomBytes } from "node:crypto";
3
+ import {
4
+ createDbConnection,
5
+ dropDatabaseIfExists,
6
+ listDatabaseNamesWithPrefix,
7
+ } from "@cosmicdrift/kumiko-framework/internal/stack-support";
8
+ import { generateId } from "@cosmicdrift/kumiko-framework/utils";
9
+ import { SERVICE_ENV_DEFAULTS } from "../preload/service-env-defaults-values.ts";
10
+
11
+ // Set by the integration runner; every process of the run shares it, and the runner keeps it alive.
12
+ export const TEST_RUN_ID_ENV = "KUMIKO_TEST_RUN_ID";
13
+
14
+ const TEST_RUN_ALIVE_TTL_SECONDS = 15 * 60;
15
+ const TEST_RUN_ALIVE_REFRESH_MS = 60_000;
16
+ const SWEEP_SCAN_COUNT = 1000;
17
+ const TEST_DATABASE_PREFIX = "kumiko_test_";
18
+
19
+ // Anchored on the exact run-id width, so legacy `kt:<8 hex>:` keys and hand-named test DBs never match.
20
+ const RUN_SCOPED_REDIS_KEY = /^(?:kt:|bull:kt-)([0-9a-f]{12})[:-]/;
21
+ const RUN_SCOPED_DATABASE = /^kumiko_test_(?:tpl_)?([0-9a-f]{12})_/;
22
+
23
+ export function createTestRunId(): string {
24
+ return randomBytes(6).toString("hex");
25
+ }
26
+
27
+ export function runIdOfTestRedisKey(key: string): string | undefined {
28
+ return RUN_SCOPED_REDIS_KEY.exec(key)?.[1];
29
+ }
30
+
31
+ export function runIdOfTestDatabase(dbName: string): string | undefined {
32
+ return RUN_SCOPED_DATABASE.exec(dbName)?.[1];
33
+ }
34
+
35
+ export function testRunAliveKey(runId: string): string {
36
+ return `kt:${runId}:alive`;
37
+ }
38
+
39
+ async function markTestRunAlive(redisUrl: string, runId: string): Promise<void> {
40
+ const Redis = (await import("ioredis")).Redis;
41
+ const redis = new Redis(redisUrl, { lazyConnect: true });
42
+ try {
43
+ await redis.connect();
44
+ await redis.set(testRunAliveKey(runId), "1", "EX", TEST_RUN_ALIVE_TTL_SECONDS);
45
+ } finally {
46
+ redis.disconnect();
47
+ }
48
+ }
49
+
50
+ export type TestRunAliveKeeper = {
51
+ readonly stop: () => void;
52
+ // Set when the first mark failed; the refresh timer keeps retrying, so the run is not left unmarked.
53
+ readonly initialMarkError: unknown;
54
+ };
55
+
56
+ // A short connection per refresh: a held client would keep the test process from exiting.
57
+ export async function keepTestRunAlive(
58
+ redisUrl: string,
59
+ runId: string,
60
+ ): Promise<TestRunAliveKeeper> {
61
+ const timer = setInterval(() => {
62
+ markTestRunAlive(redisUrl, runId).catch(() => {
63
+ // skip: the next tick retries, and the TTL outlasts several missed refreshes
64
+ });
65
+ }, TEST_RUN_ALIVE_REFRESH_MS);
66
+ timer.unref();
67
+ const stop = () => clearInterval(timer);
68
+ try {
69
+ await markTestRunAlive(redisUrl, runId);
70
+ return { stop, initialMarkError: undefined };
71
+ } catch (error) {
72
+ return { stop, initialMarkError: error };
73
+ }
74
+ }
75
+
76
+ let processTestRunId: string | undefined;
77
+ let processTestRunAlive: Promise<TestRunAliveKeeper> | undefined;
78
+
79
+ // Outside the runner (a single `bun test`, dev and e2e servers) the process owns a run of its own.
80
+ export function currentTestRunId(): string {
81
+ const runnerRunId = process.env[TEST_RUN_ID_ENV];
82
+ if (runnerRunId !== undefined) return runnerRunId;
83
+ processTestRunId ??= createTestRunId();
84
+ return processTestRunId;
85
+ }
86
+
87
+ // A process-owned run keeps itself alive, so a runner's sweep can tell its keys from a dead run's.
88
+ export async function ensureCurrentTestRunAlive(redisUrl: string): Promise<string> {
89
+ const runId = currentTestRunId();
90
+ if (process.env[TEST_RUN_ID_ENV] !== undefined) return runId;
91
+ processTestRunAlive ??= keepTestRunAlive(redisUrl, runId);
92
+ const keeper = await processTestRunAlive;
93
+ if (keeper.initialMarkError !== undefined) {
94
+ keeper.stop();
95
+ processTestRunAlive = undefined;
96
+ throw keeper.initialMarkError;
97
+ }
98
+ return runId;
99
+ }
100
+
101
+ // Run-scoped only inside the runner: outside it no Redis key could prove the database is in use.
102
+ export function testDatabaseName(): string {
103
+ const runnerRunId = process.env[TEST_RUN_ID_ENV];
104
+ const suffix = generateId().slice(-8);
105
+ return runnerRunId === undefined
106
+ ? `${TEST_DATABASE_PREFIX}${suffix}`
107
+ : `${TEST_DATABASE_PREFIX}${runnerRunId}_${suffix}`;
108
+ }
109
+
110
+ /** Queue-name prefix for a JobRunner a test builds itself (`jobs.queueNamePrefix`,
111
+ * `createJobRunner`): it sits in the test run's namespace, so the run sweep removes its BullMQ
112
+ * keys even when the test never cleans them up. BullMQ rejects `:` in `label`. */
113
+ export function testRunQueueNamePrefix(label: string): string {
114
+ // A process-owned run must be marked alive too, or a runner's sweep takes these queues for a dead run's.
115
+ ensureCurrentTestRunAlive(process.env["REDIS_URL"] ?? SERVICE_ENV_DEFAULTS.REDIS_URL).catch(
116
+ () => {
117
+ // skip: no Redis means no BullMQ queues for the sweep to remove either
118
+ },
119
+ );
120
+ return `kt-${currentTestRunId()}-${label}-${generateId().slice(-8)}`;
121
+ }
122
+
123
+ export type FinishedTestRunSweep = {
124
+ readonly runId: string;
125
+ readonly redisUrl: string;
126
+ readonly adminDatabaseUrl: string;
127
+ };
128
+
129
+ export type FinishedTestRunSweepResult = {
130
+ readonly redisKeys: number;
131
+ readonly databases: number;
132
+ };
133
+
134
+ type IoRedis = import("ioredis").Redis;
135
+
136
+ function createRemovableRunCheck(
137
+ redis: IoRedis,
138
+ ownRunId: string,
139
+ ): (runId: string) => Promise<boolean> {
140
+ const verdicts = new Map<string, boolean>();
141
+ return async (runId) => {
142
+ if (runId === ownRunId) return true;
143
+ const known = verdicts.get(runId);
144
+ if (known !== undefined) return known;
145
+ const removable = (await redis.exists(testRunAliveKey(runId))) === 0;
146
+ verdicts.set(runId, removable);
147
+ return removable;
148
+ };
149
+ }
150
+
151
+ async function sweepTestRunRedisKeys(
152
+ redis: IoRedis,
153
+ isRemovableRun: (runId: string) => Promise<boolean>,
154
+ ): Promise<number> {
155
+ let removed = 0;
156
+ for (const match of ["kt:*", "bull:kt-*"]) {
157
+ for await (const batch of redis.scanStream({ match, count: SWEEP_SCAN_COUNT })) {
158
+ const keys: string[] = [];
159
+ for (const key of batch) {
160
+ const runId = runIdOfTestRedisKey(key);
161
+ if (runId !== undefined && (await isRemovableRun(runId))) keys.push(key);
162
+ }
163
+ if (keys.length > 0) removed += await redis.unlink(...keys);
164
+ }
165
+ }
166
+ return removed;
167
+ }
168
+
169
+ async function sweepTestRunDatabases(
170
+ adminUrl: string,
171
+ isRemovableRun: (runId: string) => Promise<boolean>,
172
+ ): Promise<number> {
173
+ const admin = createDbConnection({ url: adminUrl, maxConnections: 1, rowLevelSecurity: "off" });
174
+ let dropped = 0;
175
+ try {
176
+ for (const dbName of await listDatabaseNamesWithPrefix(admin.db, TEST_DATABASE_PREFIX)) {
177
+ const runId = runIdOfTestDatabase(dbName);
178
+ if (runId === undefined || !(await isRemovableRun(runId))) continue;
179
+ try {
180
+ await dropDatabaseIfExists(admin.db, dbName);
181
+ dropped += 1;
182
+ } catch {
183
+ // skip: a database with open connections is still in use; a later sweep retries it
184
+ }
185
+ }
186
+ } finally {
187
+ await admin.close();
188
+ }
189
+ return dropped;
190
+ }
191
+
192
+ // Once per run: removes what the run itself left behind, plus whatever runs without a live
193
+ // alive key (killed or crashed) left in Redis and Postgres.
194
+ export async function sweepFinishedTestRuns(
195
+ sweep: FinishedTestRunSweep,
196
+ ): Promise<FinishedTestRunSweepResult> {
197
+ const Redis = (await import("ioredis")).Redis;
198
+ const redis = new Redis(sweep.redisUrl, { lazyConnect: true });
199
+ try {
200
+ await redis.connect();
201
+ const isRemovableRun = createRemovableRunCheck(redis, sweep.runId);
202
+ const redisKeys = await sweepTestRunRedisKeys(redis, isRemovableRun);
203
+ const databases = await sweepTestRunDatabases(sweep.adminDatabaseUrl, isRemovableRun);
204
+ return { redisKeys, databases };
205
+ } finally {
206
+ redis.disconnect();
207
+ }
208
+ }
@@ -0,0 +1,289 @@
1
+ // @runtime dev
2
+ import { buildServer } from "@cosmicdrift/kumiko-framework/api";
3
+ import {
4
+ appHookScopedRunner,
5
+ DEFAULT_ROW_LEVEL_SECURITY_MODE,
6
+ systemScopedRunner,
7
+ } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
8
+ import { createRateLimitResolver } from "@cosmicdrift/kumiko-framework/internal/stack-support";
9
+ import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
10
+ import type { EventDispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
11
+ import {
12
+ createEventDedup,
13
+ createIdempotencyGuard,
14
+ dispatcherToWriteRef,
15
+ } from "@cosmicdrift/kumiko-framework/pipeline";
16
+ import type { ClosableCacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
17
+ import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
18
+ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
19
+ import { drainJobs } from "./drain-jobs.ts";
20
+ import type { TestRedis } from "./redis.ts";
21
+ import { createRequestHelper } from "./request-helper.ts";
22
+ import type { TestStack, TestStackOptions } from "./test-stack.ts";
23
+ import type { JobFailureTracker, StackServices } from "./test-stack-services.ts";
24
+ import { runCleanupsIgnoringErrors, type StackStorage } from "./test-stack-storage.ts";
25
+
26
+ function collectSearchableFields(features: TestStackOptions["features"]): string[] {
27
+ const searchableFields: string[] = [];
28
+ for (const feature of features) {
29
+ for (const [, entity] of Object.entries(feature.entities ?? {})) {
30
+ for (const [fieldName, field] of Object.entries(entity.fields)) {
31
+ if ((field.type === "text" || field.type === "longText") && field.searchable) {
32
+ searchableFields.push(fieldName);
33
+ }
34
+ if (field.type === "embedded") {
35
+ for (const [subName, subField] of Object.entries(field.schema)) {
36
+ if (subField.searchable) {
37
+ searchableFields.push(`${fieldName}_${subName}`);
38
+ }
39
+ }
40
+ }
41
+ }
42
+ }
43
+ }
44
+ return searchableFields;
45
+ }
46
+
47
+ // Auto-configure search for tenant 1 based on registry
48
+ async function configureStackSearch(
49
+ options: TestStackOptions,
50
+ enabledHooks: ReadonlyArray<string>,
51
+ searchAdapter: SearchAdapter,
52
+ ): Promise<void> {
53
+ if (enabledHooks.includes("search")) {
54
+ const searchableFields = collectSearchableFields(options.features);
55
+ if (options.searchConfig) {
56
+ await searchAdapter.configure(options.searchConfig.tenantId, {
57
+ searchableFields: options.searchConfig.searchableFields,
58
+ rankingFields: options.searchConfig.rankingFields,
59
+ });
60
+ } else if (searchableFields.length > 0) {
61
+ await searchAdapter.configure("00000000-0000-4000-8000-000000000001", {
62
+ searchableFields,
63
+ rankingFields: searchableFields,
64
+ });
65
+ }
66
+ }
67
+ }
68
+
69
+ // buildServer only auto-wires an L3 RateLimitResolver from
70
+ // `context.redis` — a degradation test that nulls `redis` via
71
+ // extraContext (to exercise a handler's own ctx.services.redis-down guard) also
72
+ // silently strips rate-limiting, even though every handler with a
73
+ // `rateLimit` declaration still requires a resolver at dispatch time.
74
+ // Since e7bf543ad, an IP-keyed bucket key is built unconditionally
75
+ // (falls back to a shared "unknown" IP rather than skipping), so the
76
+ // missing resolver now throws instead of merely skipping enforcement.
77
+ // Mirrors idempotency/eventDedup: built from the test-stack's own
78
+ // always-real `testRedis.redis`, independent of whatever extraContext
79
+ // did to `appContext.redis` — an explicit `context.rateLimit` from
80
+ // extraContext still wins (same precedence buildServer documents).
81
+ function resolveStackRateLimitFallback(
82
+ options: TestStackOptions,
83
+ appContext: StackServices["appContext"],
84
+ testRedis: TestRedis,
85
+ ): ReturnType<typeof createRateLimitResolver> | undefined {
86
+ const explicitRateLimit = propertyOf(appContext, "rateLimit");
87
+ const needsOwnRateLimitResolver =
88
+ explicitRateLimit === undefined &&
89
+ (appContext.redis === undefined || options.rateLimitNowMs !== undefined);
90
+ if (!needsOwnRateLimitResolver) return undefined;
91
+ return createRateLimitResolver({
92
+ // An app-supplied redis keeps buckets and app redis on the same instance.
93
+ redis: appContext.redis ?? testRedis.redis,
94
+ ...(options.rateLimitNowMs ? { nowMs: options.rateLimitNowMs } : {}),
95
+ });
96
+ }
97
+
98
+ function testCodeDb<T extends object>(options: TestStackOptions, db: T): T {
99
+ return (options.rowLevelSecurity ?? DEFAULT_ROW_LEVEL_SECURITY_MODE) === "on"
100
+ ? systemScopedRunner(db, "test stack seeds and reads rows across tenants")
101
+ : db;
102
+ }
103
+
104
+ async function resolveStackAnonymousAccess(
105
+ options: TestStackOptions,
106
+ testDb: StackStorage["testDb"],
107
+ testRedis: TestRedis,
108
+ services: StackServices,
109
+ ): Promise<Pick<ServerBuildOptions, "anonymousAccess">> {
110
+ const { registry, sseBroker } = services;
111
+ const hookDb = appHookScopedRunner(
112
+ testDb.db,
113
+ options.rowLevelSecurity ?? DEFAULT_ROW_LEVEL_SECURITY_MODE,
114
+ );
115
+ const baseAnon =
116
+ typeof options.anonymousAccess === "function"
117
+ ? options.anonymousAccess({ registry, db: hookDb, sseBroker, redis: testRedis.redis })
118
+ : options.anonymousAccess;
119
+ const resolvedAnon = options.enrichAnonymousAccess
120
+ ? await options.enrichAnonymousAccess(baseAnon, { registry, db: hookDb })
121
+ : baseAnon;
122
+ return resolvedAnon ? { anonymousAccess: resolvedAnon } : {};
123
+ }
124
+
125
+ type ServerBuildOptions = Parameters<typeof buildServer>[0];
126
+
127
+ // Default tests to no login rate-limiter so existing suites that loop
128
+ // over logins don't hit a 429 after 10 attempts. Suites specifically
129
+ // testing the limiter can override via authConfig.loginRateLimit.
130
+ function buildStackAuthConfig(
131
+ authConfig: TestStackOptions["authConfig"],
132
+ ): Pick<ServerBuildOptions, "auth"> {
133
+ if (!authConfig) return {};
134
+ return {
135
+ auth: {
136
+ ...authConfig,
137
+ ...(authConfig.loginRateLimit === undefined ? { loginRateLimit: null } : {}),
138
+ },
139
+ };
140
+ }
141
+
142
+ // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
143
+ // deterministic drains — no timer-induced flakiness. pollIntervalMs
144
+ // stays short anyway in case a test opts into `.start()`. pgClient
145
+ // plumbs through the LISTEN wake-up for tests that want to measure
146
+ // post-commit latency (Sprint E.4).
147
+ function stackEventDispatcherOptions(
148
+ options: TestStackOptions,
149
+ testDb: StackStorage["testDb"],
150
+ enabledHooks: ReadonlyArray<string>,
151
+ ): NonNullable<ServerBuildOptions["eventDispatcher"]> {
152
+ return {
153
+ pollIntervalMs: options.eventDispatcherPollIntervalMs ?? 50,
154
+ pgClient: testDb.client,
155
+ systemConsumers: {
156
+ sse: enabledHooks.includes("sse"),
157
+ search: enabledHooks.includes("search"),
158
+ accessInvalidation: enabledHooks.includes("sse"),
159
+ },
160
+ };
161
+ }
162
+
163
+ export type StackServerInput = {
164
+ readonly options: TestStackOptions;
165
+ readonly jwtSecret: string;
166
+ readonly enabledHooks: ReadonlyArray<string>;
167
+ readonly testDb: StackStorage["testDb"];
168
+ readonly testRedis: TestRedis;
169
+ readonly cacheSync: ClosableCacheSyncBus;
170
+ readonly services: StackServices;
171
+ readonly jobRunner: JobRunner | undefined;
172
+ readonly jobFailureTracker: JobFailureTracker;
173
+ };
174
+
175
+ type StackServer = ReturnType<typeof buildServer>;
176
+
177
+ function buildStackServerOptions(
178
+ input: StackServerInput,
179
+ anonymousAccess: Pick<ServerBuildOptions, "anonymousAccess">,
180
+ ): ServerBuildOptions {
181
+ const { options, jwtSecret, enabledHooks, testDb, testRedis, cacheSync, services, jobRunner } =
182
+ input;
183
+ const { registry, sseBroker, appContext } = services;
184
+ const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
185
+ const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
186
+ const rateLimitFallback = resolveStackRateLimitFallback(options, appContext, testRedis);
187
+ return {
188
+ registry,
189
+ context: rateLimitFallback ? { ...appContext, rateLimit: rateLimitFallback } : appContext,
190
+ jwtSecret,
191
+ ...(options.observability ? { observability: options.observability } : {}),
192
+ ...(options.lifecycleSystemHooks && { systemHooks: options.lifecycleSystemHooks }),
193
+ dispatcherOptions: {
194
+ idempotency,
195
+ cacheSync,
196
+ outsideTransactionDb: testDb.outsideTransactionDb,
197
+ ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
198
+ ...(jobRunner && { jobRunner }),
199
+ },
200
+ eventDedup,
201
+ sseBroker,
202
+ ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
203
+ ...(options.errorDocs && { errorDocs: options.errorDocs }),
204
+ ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
205
+ ...(options.metrics && { metrics: options.metrics }),
206
+ eventDispatcher: stackEventDispatcherOptions(options, testDb, enabledHooks),
207
+ ...buildStackAuthConfig(options.authConfig),
208
+ ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
209
+ ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
210
+ ...anonymousAccess,
211
+ };
212
+ }
213
+
214
+ function assembleTestStack(
215
+ input: StackServerInput,
216
+ server: StackServer,
217
+ eventDispatcher: EventDispatcher | undefined,
218
+ ): TestStack {
219
+ const { options, testDb, testRedis, cacheSync, services, jobRunner, jobFailureTracker } = input;
220
+ const http = createRequestHelper(server.app, server.jwt, {
221
+ ...(options.authConfig?.sessionCreator !== undefined && {
222
+ sessionCreator: options.authConfig.sessionCreator,
223
+ }),
224
+ });
225
+ // Test code and the drain see every tenant's rows; the services keep the enforced pool.
226
+ const crossTenantDb = testCodeDb(options, testDb.db);
227
+ return {
228
+ app: server.app,
229
+ jwt: server.jwt,
230
+ registry: services.registry,
231
+ db: crossTenantDb,
232
+ unscopedDb: testDb.db,
233
+ dbPoolMax: testDb.poolMax,
234
+ redis: testRedis,
235
+ cacheSync,
236
+ search: services.searchAdapter,
237
+ events: services.events,
238
+ http,
239
+ observability: server.observability,
240
+ sseBroker: services.sseBroker,
241
+ dispatcher: server.dispatcher,
242
+ context: server.context,
243
+ ...(services.clock !== undefined && { clock: services.clock }),
244
+ ...(eventDispatcher ? { eventDispatcher } : {}),
245
+ ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
246
+ ...(jobRunner ? { jobRunner } : {}),
247
+ drainJobs: () =>
248
+ drainJobs({ db: crossTenantDb, eventDispatcher, jobRunner }, jobFailureTracker),
249
+ cleanup: async () => {
250
+ if (jobRunner) await jobRunner.stop();
251
+ if (eventDispatcher) await eventDispatcher.stop();
252
+ await server.observability.shutdown();
253
+ await cacheSync.close();
254
+ await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
255
+ },
256
+ };
257
+ }
258
+
259
+ export async function startStackServer(input: StackServerInput): Promise<TestStack> {
260
+ const { options, enabledHooks, testDb, testRedis, services, jobRunner } = input;
261
+ await configureStackSearch(options, enabledHooks, services.searchAdapter);
262
+
263
+ const anonymousAccess = await resolveStackAnonymousAccess(options, testDb, testRedis, services);
264
+ const server = buildServer(buildStackServerOptions(input, anonymousAccess));
265
+
266
+ // Attach before start, as the prod entrypoints do: start() runs the worker and enqueues the
267
+ // runOnBoot jobs, and one that reaches JobContext.write before the attach fails its run.
268
+ if (jobRunner) {
269
+ jobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
270
+ try {
271
+ await jobRunner.start();
272
+ } catch (error) {
273
+ // setupTestStack's failure cleanup predates the server; a failed boot gate must not leak its observability.
274
+ await runCleanupsIgnoringErrors([() => server.observability.shutdown()]);
275
+ throw error;
276
+ }
277
+ }
278
+
279
+ const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
280
+
281
+ // Pre-register consumer state rows so tests can call runOnce() directly
282
+ // without a preceding explicit start(). Timer fires at pollIntervalMs=50
283
+ // but each consumer runs at most one turn at a time — tests that drain via
284
+ // runOnce() remain deterministic. Tests that specifically exercise the
285
+ // timer loop call start() again (idempotent) after setup.
286
+ if (eventDispatcher) await eventDispatcher.ensureRegistered();
287
+
288
+ return assembleTestStack(input, server, eventDispatcher);
289
+ }