@cosmicdrift/kumiko-server-runtime 0.329.0 → 0.330.0

package/src/boot/__tests__/job-run-logger.integration.test.ts

@@ -1,262 +0,0 @@
-// Regression guard for startDevJobRunners' lane default: a job registered
-// WITHOUT an explicit runIn used to get no consumer at all in the dev server
-// (the old `lanes` filter dropped `undefined` lanes), so it sat in the queue
-// forever. `runners.length` alone can't catch that — a lane with no consumer
-// still produces a runner object. This dispatches a real job and waits for
-// its side effect to prove the lane is actually being consumed.
-import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import {
-  createJobsFeature,
-  jobRunLogsTable,
-  jobRunsTable,
-} from "@cosmicdrift/kumiko-bundled-features/jobs";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import {
-  buildEntityTable,
-  createEventStoreExecutor,
-  selectMany,
-} from "@cosmicdrift/kumiko-framework/db";
-import {
-  createEntity,
-  createRegistry,
-  createTextField,
-  defineFeature,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { createDispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
-import {
-  createTestDb,
-  createTestRedis,
-  setupTestStack,
-  type TestDb,
-  type TestRedis,
-  TestUsers,
-  unsafeCreateEntityTable,
-  unsafePushTables,
-} from "@cosmicdrift/kumiko-framework/stack";
-import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
-import * as z from "zod";
-import { startDevJobRunners } from "../job-run-logger";
-
-let testDb: TestDb;
-let testRedis: TestRedis;
-let db: DbConnection;
-
-const jobRuns: Array<{ readonly note: string }> = [];
-
-// No `runIn` — the exact case the lane-default regression hits.
-const probeFeature = defineFeature("probe", (r) => {
-  r.job("noteIt", { trigger: { manual: true } }, async (payload) => {
-    jobRuns.push({ note: (payload as { note: string }).note });
-  });
-});
-
-beforeAll(async () => {
-  testDb = await createTestDb();
-  testRedis = await createTestRedis();
-  db = testDb.db;
-  await unsafePushTables(db, { jobRunsTable, jobRunLogsTable });
-});
-
-afterAll(async () => {
-  await testDb.cleanup();
-  await testRedis.cleanup();
-});
-
-describe("startDevJobRunners", () => {
-  test("job without explicit runIn gets a consumer and actually executes", async () => {
-    const registry = createRegistry([probeFeature, createJobsFeature()]);
-
-    const { runners, stop } = await startDevJobRunners({
-      registry,
-      db,
-      context: {},
-      redisUrl: testRedis.redisUrl,
-      queueNamePrefix: `test-lane-default-${crypto.randomUUID()}`,
-      // Construction-only — this job never calls ctx.write/ctx.queryAs, so a
-      // dispatcher built against a bare `{}` context is enough to satisfy
-      // the (now required) opts.dispatcher without wiring a full stack.
-      dispatcher: createDispatcher(registry, {}),
-    });
-
-    try {
-      expect(runners.length).toBe(1);
-      const runner = runners[0];
-      if (runner === undefined) throw new Error("expected a runner");
-
-      await runner.dispatch("probe:job:note-it", { note: "hello-from-dev-runner" });
-
-      await waitFor(() => {
-        expect(jobRuns.some((r) => r.note === "hello-from-dev-runner")).toBe(true);
-      });
-    } finally {
-      await stop();
-    }
-  });
-});
-
-// kumiko-framework#2553: startDevJobRunners built its per-lane JobRunners but
-// never called attachDispatcher() on them (unlike createApiEntrypoint /
-// createWorkerEntrypoint / createAllInOneEntrypoint, which all do this
-// automatically) — so ctx.write/ctx.queryAs inside a dev-run job always hit
-// the "dispatcher attached — call attachDispatcher() first" stub. This
-// mirrors create-kumiko-server.ts's real wiring (setupTestStack + a separate
-// startDevJobRunners as the lane consumer) and drives a job that calls both
-// ctx.write and ctx.queryAs end-to-end.
-const attachNoteEntity = createEntity({
-  table: "job_attach_notes",
-  fields: { text: createTextField({ personal: false, reason: "test_fixture", required: true }) },
-});
-const attachNoteTable = buildEntityTable("note", attachNoteEntity);
-
-const attachResults: Array<{ writeOk: boolean; rowCount: number }> = [];
-const attachFailures: string[] = [];
-
-const attachDispatcherFeature = defineFeature("jobattach", (r) => {
-  r.entity("note", attachNoteEntity);
-
-  r.writeHandler(
-    "create",
-    z.object({ text: z.string() }),
-    async (event, ctx) => {
-      const crud = createEventStoreExecutor(attachNoteTable, attachNoteEntity, {
-        entityName: "note",
-      });
-      return crud.create(event.payload, event.user, ctx.db);
-    },
-    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
-  );
-
-  r.queryHandler("list", z.object({}), async (_query, ctx) => selectMany(ctx.db, attachNoteTable), {
-    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
-  });
-
-  r.job("record", { trigger: { manual: true }, retries: 0 }, async (payload, ctx) => {
-    try {
-      const text = (payload as { text: string }).text;
-      const writeResult = await ctx.write("jobattach:write:create", { text });
-      const rows = await ctx.queryAs(TestUsers.admin, "jobattach:query:list", {});
-      attachResults.push({
-        writeOk: writeResult.isSuccess,
-        rowCount: (rows as unknown[]).length,
-      });
-    } catch (error) {
-      attachFailures.push(error instanceof Error ? error.message : String(error));
-      throw error;
-    }
-  });
-});
-
-describe("startDevJobRunners attaches the dispatcher (kumiko-framework#2553)", () => {
-  afterEach(() => {
-    attachResults.length = 0;
-    attachFailures.length = 0;
-  });
-
-  test("a dev-run job's ctx.write and ctx.queryAs both succeed", async () => {
-    const attachQueueNamePrefix = `test-attach-dispatcher-${crypto.randomUUID()}`;
-    const stack = await setupTestStack({
-      features: [attachDispatcherFeature, createJobsFeature()],
-      // Enqueuer-only — startDevJobRunners below is the sole consumer,
-      // mirroring create-kumiko-server.ts.
-      jobs: { queueNamePrefix: attachQueueNamePrefix },
-    });
-    await unsafeCreateEntityTable(stack.db, attachNoteEntity);
-
-    try {
-      const { runners, stop } = await startDevJobRunners({
-        registry: stack.registry,
-        db: stack.db,
-        context: stack.context,
-        redisUrl: stack.redis.redisUrl,
-        dispatcher: stack.dispatcher,
-        queueNamePrefix: attachQueueNamePrefix,
-      });
-
-      try {
-        const runner = runners[0];
-        if (runner === undefined) throw new Error("expected a runner");
-
-        await runner.dispatch("jobattach:job:record", { text: "hello-from-dev-runner" });
-
-        await waitFor(() => {
-          expect(attachResults.length + attachFailures.length).toBeGreaterThan(0);
-        });
-        if (attachFailures.length > 0) {
-          throw new Error(`job failed: ${attachFailures.join(", ")}`);
-        }
-        expect(attachResults[0]).toEqual({ writeOk: true, rowCount: 1 });
-      } finally {
-        await stop();
-      }
-    } finally {
-      await stack.cleanup();
-    }
-  }, 15000);
-});
-
-// Regression guard for the shared-Redis job-queue-collision bug: two boots
-// (e.g. two parallel dev/e2e servers) that don't set distinct
-// queueNamePrefix values consume from the same BullMQ queue names and steal
-// each other's jobs ("Unknown job: ..."). Both registries below register the
-// SAME feature/job name on purpose — if the queues were shared, runner B
-// would recognize and execute jobs meant for runner A (proving the
-// collision), not just fail to run them. Distinct prefixes must keep every
-// dispatched job on runner A's side.
-describe("startDevJobRunners isolates queues by queueNamePrefix", () => {
-  test("two runners with distinct prefixes on the same Redis don't cross-consume", async () => {
-    const runsA: string[] = [];
-    const runsB: string[] = [];
-
-    const isoFeatureA = defineFeature("iso", (r) => {
-      r.job("mark", { trigger: { manual: true } }, async (payload) => {
-        runsA.push((payload as { note: string }).note);
-      });
-    });
-    const isoFeatureB = defineFeature("iso", (r) => {
-      r.job("mark", { trigger: { manual: true } }, async (payload) => {
-        runsB.push((payload as { note: string }).note);
-      });
-    });
-
-    const registryA = createRegistry([isoFeatureA, createJobsFeature()]);
-    const registryB = createRegistry([isoFeatureB, createJobsFeature()]);
-
-    const runnerA = await startDevJobRunners({
-      registry: registryA,
-      db,
-      context: {},
-      redisUrl: testRedis.redisUrl,
-      queueNamePrefix: `test-iso-a-${crypto.randomUUID()}`,
-      dispatcher: createDispatcher(registryA, {}),
-    });
-    const runnerB = await startDevJobRunners({
-      registry: registryB,
-      db,
-      context: {},
-      redisUrl: testRedis.redisUrl,
-      queueNamePrefix: `test-iso-b-${crypto.randomUUID()}`,
-      dispatcher: createDispatcher(registryB, {}),
-    });
-
-    try {
-      const dispatchA = runnerA.runners[0];
-      if (dispatchA === undefined) throw new Error("expected a runner for registry A");
-
-      const notes = Array.from({ length: 10 }, (_, i) => `from-a-${i}`);
-      for (const note of notes) {
-        await dispatchA.dispatch("iso:job:mark", { note });
-      }
-
-      // If the queues were shared, some of these 10 jobs would land on
-      // runner B instead — runsA would never reach length 10 and this
-      // would time out rather than pass.
-      await waitFor(() => {
-        expect(runsA).toHaveLength(10);
-      });
-      expect(runsB).toEqual([]);
-    } finally {
-      await runnerA.stop();
-      await runnerB.stop();
-    }
-  });
-});

package/src/boot/__tests__/job-run-logger.test.ts

@@ -1,26 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { createJobsFeature } from "@cosmicdrift/kumiko-bundled-features/jobs";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { createRegistry, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { jobRunLoggerCallbacks } from "../job-run-logger";
-
-// ponytail: callbacks shape only — no DB I/O; createTestDb needs TEST_DATABASE_URL (CI unit job has none).
-const mockDb = {} as DbConnection;
-
-describe("jobRunLoggerCallbacks", () => {
-  test("returns undefined when jobs feature is not registered", () => {
-    const registry = createRegistry([
-      defineFeature("empty", () => ({ handlers: {}, queries: {} })),
-    ]);
-    expect(jobRunLoggerCallbacks(registry, mockDb)).toBeUndefined();
-  });
-
-  test("returns logger callbacks when jobs feature is registered", () => {
-    const registry = createRegistry([createJobsFeature()]);
-    const callbacks = jobRunLoggerCallbacks(registry, mockDb);
-    expect(callbacks).toBeDefined();
-    expect(typeof callbacks?.onJobStart).toBe("function");
-    expect(typeof callbacks?.onJobComplete).toBe("function");
-    expect(typeof callbacks?.onJobFailed).toBe("function");
-  });
-});

package/src/boot/boot-crypto.ts

@@ -1,67 +0,0 @@
-// One place that turns env/options into the app-wide crypto objects:
-// the MasterKeyProvider (KUMIKO_SECRETS_MASTER_KEY_V<n> keyring) and the
-// EnvelopeCipher for `encrypted: true` config keys. runProdApp and
-// runDevApp both resolve this once and thread it into
-// buildBootExtraContext + applyBootSeeds so resolver, set-handler and
-// seeds share the same cipher instance (and DEK cache).
-
-import {
-  createDekCache,
-  createEnvelopeCipher,
-  createEnvMasterKeyProvider,
-  type DekCache,
-  type EnvelopeCipher,
-  type MasterKeyProvider,
-} from "@cosmicdrift/kumiko-framework/secrets";
-
-// Keyring detection without throwing: only build the env provider when at
-// least one versioned KEK is actually set. Covers (a) apps without any
-// encryption — no KEK requirement, and (b) dev with an app-supplied
-// provider in options.masterKey — env stays irrelevant.
-const MASTER_KEK_VAR = /^KUMIKO_SECRETS_MASTER_KEY_V\d+$/;
-export function envHasMasterKek(env: Record<string, string | undefined>): boolean {
-  return Object.entries(env).some(([k, v]) => MASTER_KEK_VAR.test(k) && !!v);
-}
-
-export type BootCrypto = {
-  readonly masterKeyProvider?: MasterKeyProvider;
-  // Cipher for encrypted config keys. Present exactly when a master key is
-  // available.
-  readonly configCipher?: EnvelopeCipher;
-  // Cipher for `encrypted: true` entity fields — same master key and
-  // instance as configCipher (kept as a separate field for API stability).
-  readonly entityFieldCipher?: EnvelopeCipher;
-  readonly dekCache: DekCache;
-};
-
-export function resolveBootCrypto(
-  envSource: Record<string, string | undefined>,
-  masterKeyOverride?: MasterKeyProvider,
-): BootCrypto {
-  const masterKeyProvider =
-    masterKeyOverride ??
-    (envHasMasterKek(envSource)
-      ? createEnvMasterKeyProvider({
-          // CURRENT_VERSION default "1" spiegelt secretsEnvSchema — ohne
-          // ihn wirft der raw-env-Provider, obwohl V1 gesetzt ist.
-          env: {
-            ...envSource,
-            KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION:
-              envSource["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
-          },
-        })
-      : undefined);
-
-  const dekCache = createDekCache();
-  const configCipher = masterKeyProvider
-    ? createEnvelopeCipher(masterKeyProvider, { dekCache })
-    : undefined;
-  const entityFieldCipher = configCipher;
-
-  return {
-    ...(masterKeyProvider && { masterKeyProvider }),
-    ...(configCipher && { configCipher }),
-    ...(entityFieldCipher && { entityFieldCipher }),
-    dekCache,
-  };
-}

package/src/boot/job-run-logger.ts

@@ -1,63 +0,0 @@
-import { createJobRunLogger } from "@cosmicdrift/kumiko-bundled-features/jobs";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
-import type { AppContext, JobRunIn } from "@cosmicdrift/kumiko-framework/engine/types";
-import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
-import { type Dispatcher, dispatcherToWriteRef } from "@cosmicdrift/kumiko-framework/pipeline";
-
-export function jobRunLoggerCallbacks(
-  registry: Registry,
-  db: DbConnection,
-): ReturnType<typeof createJobRunLogger> | undefined {
-  if (registry.getFeature("jobs") === undefined) return undefined;
-  return createJobRunLogger({ db, registry });
-}
-
-/** Dev-server parity: consume api + worker lanes when jobs are registered. */
-export async function startDevJobRunners(opts: {
-  readonly registry: Registry;
-  readonly db: DbConnection;
-  readonly context: AppContext;
-  readonly redisUrl: string;
-  readonly dispatcher: Dispatcher;
-  // Redis is shared across boots and apps (unlike the ephemeral per-boot
-  // test DB); no silent default here so every caller is forced to pick a
-  // prefix that isolates its own queues.
-  readonly queueNamePrefix: string;
-}): Promise<{ readonly runners: readonly JobRunner[]; readonly stop: () => Promise<void> }> {
-  const jobs = [...opts.registry.getAllJobs().values()];
-  if (opts.registry.getFeature("jobs") === undefined || jobs.length === 0) {
-    return { runners: [], stop: async () => {} };
-  }
-
-  const logger = createJobRunLogger({ db: opts.db, registry: opts.registry });
-  const runners: JobRunner[] = [];
-  // `?? "worker"` mirrors job-runner's laneForJob: a job without an explicit
-  // runIn is enqueued onto the worker lane, so filtering those out would leave
-  // its queue without a consumer whenever no other job named the lane.
-  const lanes = new Set<JobRunIn>(jobs.map((j) => j.runIn ?? "worker"));
-
-  for (const lane of lanes) {
-    const jr = createJobRunner({
-      registry: opts.registry,
-      context: { ...opts.context, db: opts.db },
-      redisUrl: opts.redisUrl,
-      queueNamePrefix: opts.queueNamePrefix,
-      consumerLane: lane,
-      ...logger,
-    });
-    // Without this, ctx.write/ctx.queryAs inside a dev-run job throw
-    // "dispatcher attached — call attachDispatcher() first" on their first
-    // call — the prod entrypoints attach automatically, dev boot must too.
-    jr.attachDispatcher(dispatcherToWriteRef(opts.dispatcher));
-    await jr.start();
-    runners.push(jr);
-  }
-
-  return {
-    runners,
-    stop: async () => {
-      for (const runner of runners) await runner.stop();
-    },
-  };
-}

package/src/boot/pii-event-backfill-on-boot.ts

@@ -1,43 +0,0 @@
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
-import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { runPiiEventBackfill } from "@cosmicdrift/kumiko-framework/migrations";
-
-export const SKIP_PII_BACKFILL_ENV = "KUMIKO_SKIP_PII_BACKFILL";
-
-type ShutdownRegistry = {
-  registerShutdownHook(name: string, fn: () => Promise<void>): void;
-};
-
-// Runs in the background instead of blocking boot: the first run after a bump
-// scans the whole store and would delay readiness in proportion to its size.
-// Every batch is its own transaction, so an abort at any point is safe.
-export function startPiiEventBackfillOnBoot(opts: {
-  readonly db: DbConnection;
-  readonly registry: Registry;
-  readonly lifecycle: ShutdownRegistry;
-  readonly envSource: Readonly<Record<string, string | undefined>>;
-}): void {
-  if (opts.envSource[SKIP_PII_BACKFILL_ENV] === "1") {
-    // skip: operator opted out via KUMIKO_SKIP_PII_BACKFILL
-    return;
-  }
-
-  const log = createFallbackLogger("pii-event-backfill");
-  const abortController = new AbortController();
-  const run = runPiiEventBackfill(opts.db, opts.registry, {
-    signal: abortController.signal,
-  }).then(
-    () => undefined,
-    (e: unknown) => {
-      log.error("PII event backfill crashed; it will be retried on the next boot", {
-        error: e instanceof Error ? e.message : String(e),
-      });
-    },
-  );
-
-  opts.lifecycle.registerShutdownHook("piiEventBackfill", async () => {
-    abortController.abort();
-    await run;
-  });
-}