@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -2,9 +2,13 @@ import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import type { TenantId } from "../../engine/types/identifiers";
+import { createSecret } from "../../secrets/types";
 import { createTestUser } from "../../stack";
+import { createRecordingProvider } from "../../testing";
 import { createDispatcher } from "../dispatcher";
 
+const streamCleanupState = { closed: false };
+
 const echoFeature = defineFeature("echo", (r) => {
   r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
 
@@ -25,6 +29,40 @@ const echoFeature = defineFeature("echo", (r) => {
     { access: { openToAll: true } },
   );
 
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.streamHandler(
+    "item:tail-leak",
+    z.object({}),
+    async function* () {
+      yield { apiKey: createSecret("leak-me") };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.streamHandler(
+    "item:tail-cleanup",
+    z.object({}),
+    async function* () {
+      try {
+        yield { i: 0 };
+        yield { i: 1 };
+      } finally {
+        streamCleanupState.closed = true;
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   r.hook("validation", "item:create", (data) => {
     if (data["name"] === "forbidden") return [{ field: "name", error: "forbidden_name" }];
     return null;
@@ -100,6 +138,35 @@ describe("dispatcher.write", () => {
     expect(result.isSuccess).toBe(true);
   });
 
+  test("user-bucketed handler without RateLimitResolver → internal_error", async () => {
+    // Misconfig: a handler opts into L3 rate-limit but the app never loaded the
+    // rate-limiting feature. User buckets cannot skip (unlike ip+no-IP), so we
+    // fail loud at first write instead of silently running uncapped.
+    const rlFeature = defineFeature("rl-user", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "item:create",
+        z.object({ name: z.string() }),
+        async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
+        {
+          access: { openToAll: true },
+          rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
+        },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([rlFeature]), {});
+    const result = await dispatcher.write(
+      "rl-user:write:item:create",
+      { name: "should-not-run" },
+      createTestUser(),
+    );
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("internal_error");
+      expect(result.error.message).toMatch(/RateLimitResolver is configured/);
+    }
+  });
+
   test("ctx.user ist Convenience-Alias auf event.user (gleicher Wert)", async () => {
     // Pinst dass der Handler auf ctx.user zugreifen kann ohne den
     // typo-resistenten event.user-Pfad zu nutzen. Identitätsprüfung
@@ -185,6 +252,231 @@ describe("dispatcher.query", () => {
   });
 });
 
+async function collect<T>(gen: AsyncGenerator<T>): Promise<T[]> {
+  const out: T[] = [];
+  for await (const chunk of gen) out.push(chunk);
+  return out;
+}
+
+describe("dispatcher.stream", () => {
+  test("validates and calls stream handler, yielding chunks in order", async () => {
+    const dispatcher = createTestDispatcher();
+    const chunks = await collect(
+      dispatcher.stream(
+        "echo:stream:item:tail",
+        { count: 3 },
+        createTestUser({ roles: ["Admin"] }),
+      ),
+    );
+
+    expect(chunks).toEqual([{ i: 0 }, { i: 1 }, { i: 2 }]);
+  });
+
+  test("gates fire on first pull, not on the stream() call itself", async () => {
+    const dispatcher = createTestDispatcher();
+    const gen = dispatcher.stream(
+      "echo:stream:item:tail",
+      { count: -1 },
+      createTestUser({ roles: ["Admin"] }),
+    );
+
+    await expect(collect(gen)).rejects.toMatchObject({ code: "validation_error", httpStatus: 400 });
+  });
+
+  test("rejects unauthorized user", async () => {
+    const dispatcher = createTestDispatcher();
+    const guest = createTestUser({ roles: ["Guest"] });
+
+    await expect(
+      collect(dispatcher.stream("echo:stream:item:tail", { count: 1 }, guest)),
+    ).rejects.toMatchObject({ code: "access_denied" });
+  });
+
+  test("throws for unknown stream handler", async () => {
+    const dispatcher = createTestDispatcher();
+
+    await expect(
+      collect(dispatcher.stream("nonexistent", {}, createTestUser({ roles: ["Admin"] }))),
+    ).rejects.toMatchObject({ code: "not_found", httpStatus: 404 });
+  });
+
+  test("a chunk containing a Secret<> value aborts the stream instead of leaking it", async () => {
+    const dispatcher = createTestDispatcher();
+
+    await expect(
+      collect(
+        dispatcher.stream("echo:stream:item:tail-leak", {}, createTestUser({ roles: ["Admin"] })),
+      ),
+    ).rejects.toMatchObject({ message: expect.stringContaining("Secret<> leaked") });
+  });
+
+  test("consumer breaking out of for-await runs the handler generator's finally block", async () => {
+    streamCleanupState.closed = false;
+    const dispatcher = createTestDispatcher();
+    const gen = dispatcher.stream(
+      "echo:stream:item:tail-cleanup",
+      {},
+      createTestUser({ roles: ["Admin"] }),
+    );
+
+    for await (const _chunk of gen) {
+      break;
+    }
+
+    expect(streamCleanupState.closed).toBe(true);
+  });
+
+  test("activates the dispatcher span in observabilityContext for every pull, not just the first", async () => {
+    // Regression for #1516: runStreamInstrumented used to start the span but
+    // never run the stream inside observabilityContext.run(...), so a
+    // handler-side startSpan() picked up whatever ALS context happened to be
+    // active at that pull (or none) instead of the stream's dispatcher span.
+    const provider = createRecordingProvider();
+    const nestedFeature = defineFeature("nested", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({ count: z.number().int().min(0) }),
+        async function* (query, handlerCtx) {
+          for (let i = 0; i < query.payload.count; i++) {
+            const child = handlerCtx.tracer.startSpan("nested.child");
+            child.end();
+            yield { i };
+          }
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([nestedFeature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    await collect(dispatcher.stream("nested:stream:tail", { count: 3 }, createTestUser()));
+
+    const dispatcherSpan = provider.spansByName("kumiko.dispatcher.handler")[0]!;
+    const childSpans = provider.spansByName("nested.child");
+    expect(childSpans).toHaveLength(3);
+    for (const child of childSpans) {
+      expect(child.parentSpanId).toBe(dispatcherSpan.spanId);
+    }
+  });
+
+  test("a close-time error on an otherwise-clean stream is reported, not swallowed", async () => {
+    // Regression for #1543: runStreamInstrumented's finally used to
+    // catch+discard any error from generator.return() unconditionally, even
+    // when nothing else had failed — an abandoned stream whose handler's
+    // own cleanup throws (closing a cursor/unsubscribing) was invisible to
+    // both the error-counter and the span status.
+    const provider = createRecordingProvider();
+    const closeFailFeature = defineFeature("closefail", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({}),
+        async function* () {
+          try {
+            yield { i: 0 };
+            yield { i: 1 };
+          } finally {
+            // biome-ignore lint/correctness/noUnsafeFinally: deliberately simulating a handler whose close-time cleanup fails
+            throw new Error("close-boom");
+          }
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([closeFailFeature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    const gen = dispatcher.stream("closefail:stream:tail", {}, createTestUser());
+    for await (const _chunk of gen) {
+      break;
+    }
+
+    const errorCounters = provider.metricEvents.filter(
+      (e) => e.type === "counter.inc" && e.name === "kumiko_dispatcher_handler_errors_total",
+    );
+    expect(errorCounters).toHaveLength(1);
+    const dispatcherSpan = provider.spansByName("kumiko.dispatcher.handler")[0]!;
+    expect(dispatcherSpan.status).toBe("error");
+  });
+
+  test("draining a stream to completion emits outcome:completed", async () => {
+    // completedNormally=true only when the inner generator finishes on its
+    // own — pins the success-path label so a refactor that drops the flag
+    // cannot silently reclassify clean streams as aborted (#1551).
+    const provider = createRecordingProvider();
+    const feature = defineFeature("complete", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({}),
+        async function* () {
+          yield { i: 0 };
+          yield { i: 1 };
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([feature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    await collect(dispatcher.stream("complete:stream:tail", {}, createTestUser()));
+
+    const duration = provider.metricEvents.find(
+      (e) =>
+        e.type === "histogram.observe" && e.name === "kumiko_dispatcher_handler_duration_seconds",
+    );
+    expect(duration).toBeDefined();
+    expect(duration?.labels).toMatchObject({
+      handler: "complete:stream:tail",
+      success: "true",
+      outcome: "completed",
+    });
+  });
+
+  test("generator.return() mid-stream emits outcome:aborted, not completed", async () => {
+    // Consumer walk-away (SSE tab-close) must not count as a clean
+    // completion — completedNormally stays false when return() interrupts
+    // the loop (#1551).
+    const provider = createRecordingProvider();
+    const feature = defineFeature("abort", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({}),
+        async function* () {
+          yield { i: 0 };
+          yield { i: 1 };
+          yield { i: 2 };
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    const dispatcher = createDispatcher(createRegistry([feature]), {
+      tracer: provider.tracer,
+      meter: provider.meter,
+    });
+
+    const gen = dispatcher.stream("abort:stream:tail", {}, createTestUser());
+    const first = await gen.next();
+    expect(first.value).toEqual({ i: 0 });
+    await gen.return(undefined);
+
+    const duration = provider.metricEvents.find(
+      (e) =>
+        e.type === "histogram.observe" && e.name === "kumiko_dispatcher_handler_duration_seconds",
+    );
+    expect(duration).toBeDefined();
+    expect(duration?.labels).toMatchObject({
+      handler: "abort:stream:tail",
+      success: "true",
+      outcome: "aborted",
+    });
+  });
+});
+
 // --- postQuery hooks on standalone (entity-less) queries ---
 
 describe("dispatcher.query postQuery hooks", () => {
@@ -333,6 +625,20 @@ describe("dispatcher feature-gate", () => {
         async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
         { access: { roles: ["Admin"] } },
       );
+      r.streamHandler(
+        "widget:tail",
+        z.object({}).passthrough(),
+        async function* () {
+          // Never completes on its own — the mid-stream toggle-off test
+          // relies on the generator staying open past the first yield.
+          let i = 0;
+          while (true) {
+            yield { i };
+            i++;
+          }
+        },
+        { access: { openToAll: true } },
+      );
     });
   }
 
@@ -368,6 +674,28 @@ describe("dispatcher feature-gate", () => {
     });
   });
 
+  test("disabling the feature mid-stream aborts an already-open stream", async () => {
+    const registry = createRegistry([toggled()]);
+    const disabled = new Set<string>();
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        effectiveFeatures: () => {
+          const all = new Set(registry.features.keys());
+          for (const d of disabled) all.delete(d);
+          return all;
+        },
+      },
+    );
+
+    const gen = dispatcher.stream("toggled:stream:widget:tail", {}, user);
+    expect((await gen.next()).value).toEqual({ i: 0 });
+
+    disabled.add("toggled");
+    await expect(gen.next()).rejects.toThrow(/feature toggled is disabled/);
+  });
+
   test("write of disabled feature returns WriteFailure with feature_disabled reason", async () => {
     const registry = createRegistry([toggled()]);
     const disabled = new Set<string>(["toggled"]);
@@ -480,7 +808,7 @@ describe("dispatcher feature-gate", () => {
       r.queryHandler(
         "check",
         z.object({}).passthrough(),
-        async (_event, ctx) => ({ enabled: ctx.hasFeature("toggled") }),
+        async (_event, ctx) => ({ enabled: await ctx.hasFeature("toggled") }),
         { access: { openToAll: true } },
       );
     });
@@ -504,6 +832,43 @@ describe("dispatcher feature-gate", () => {
       enabled: false,
     });
   });
+
+  test("issue #1233: ctx.hasFeature falls back to trialGate for a companion feature the tenant doesn't own", async () => {
+    // Regression for the trial-tenant bug: a handler owned by an always-on
+    // feature checks a DIFFERENT (trial-tier) feature via ctx.hasFeature.
+    // The sync resolver never carries trial features, so without the
+    // trialGate fallback this silently reads false for a trial tenant even
+    // though the tenant is genuinely in-trial for that companion feature —
+    // mirrors packages/bundled-features/src/managed-pages/handlers/branding.query.ts
+    // checking MANAGED_PAGES_CSS_FEATURE, which no handler owns.
+    const trialTenant = "00000000-0000-4000-8000-0000000000c5" as TenantId;
+    const plainTenant = "00000000-0000-4000-8000-0000000000d6" as TenantId;
+
+    const probe = defineFeature("probe", (r) => {
+      r.queryHandler(
+        "check",
+        z.object({}).passthrough(),
+        async (_event, ctx) => ({ enabled: await ctx.hasFeature("premium-companion") }),
+        { access: { openToAll: true } },
+      );
+    });
+    const registry = createRegistry([probe]);
+    const effectiveFeatures = Object.assign(() => new Set(["probe"]), {
+      trialGate: async (tenantId: TenantId, feature: string) =>
+        tenantId === trialTenant && feature === "premium-companion",
+    });
+    const dispatcher = createDispatcher(registry, {}, { effectiveFeatures });
+
+    const trialUser = createTestUser({ id: "u-c5", tenantId: trialTenant, roles: ["Admin"] });
+    const plainUser = createTestUser({ id: "u-d6", tenantId: plainTenant, roles: ["Admin"] });
+
+    await expect(dispatcher.query("probe:query:check", {}, trialUser)).resolves.toEqual({
+      enabled: true,
+    });
+    await expect(dispatcher.query("probe:query:check", {}, plainUser)).resolves.toEqual({
+      enabled: false,
+    });
+  });
 });
 
 describe("write-handler shape guard", () => {

package/src/pipeline/__tests__/event-consumer-state.integration.test.ts

@@ -0,0 +1,31 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createTestDb, type TestDb } from "../../stack";
+import { createEventConsumerStateTable } from "../event-consumer-state";
+
+// #1362: two dispatcher instances booting concurrently against the same DB
+// both see kumiko_event_consumers already present but rearm_count missing,
+// and both ALTER TABLE. Without IF NOT EXISTS the loser crashes on boot
+// with "column already exists" — a real TOCTOU since this table is
+// explicitly multi-instance.
+describe("createEventConsumerStateTable — concurrent boot", () => {
+  let testDb: TestDb;
+
+  beforeAll(async () => {
+    testDb = await createTestDb();
+  });
+
+  afterAll(async () => {
+    await testDb.cleanup();
+  });
+
+  test("running it twice concurrently does not throw", async () => {
+    await createEventConsumerStateTable(testDb.db);
+
+    await expect(
+      Promise.all([
+        createEventConsumerStateTable(testDb.db),
+        createEventConsumerStateTable(testDb.db),
+      ]),
+    ).resolves.toBeDefined();
+  });
+});

package/src/pipeline/__tests__/event-dispatcher-delivery-max-attempts.test.ts

@@ -0,0 +1,126 @@
+// EventConsumerErrorPolicy.maxAttempts lets a consumer override the
+// dispatcher-wide default (kumiko-framework#1349) — a consumer depending on
+// infra that may still be provisioning at boot (search adapter) needs more
+// retry headroom before it gets dead-lettered. deliverEvents is a pure
+// free function, so this is unit-level: no DB, no dispatcher lifecycle.
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import type { AppContext } from "../../engine/types";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import type { EventConsumer } from "../event-dispatcher";
+import {
+  type ConsumerStateRow,
+  deliverEvents,
+  type StoredEventRow,
+} from "../event-dispatcher-delivery";
+import { createSearchEventConsumer } from "../system-hooks";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+function stubContext(): AppContext {
+  return {
+    db: {} as unknown as AppContext["db"],
+    redis: {} as unknown as AppContext["redis"],
+    registry: {} as unknown as AppContext["registry"],
+  } as AppContext;
+}
+
+function stubEvent(id: bigint): StoredEventRow {
+  return {
+    id,
+    aggregateId: "agg-1",
+    aggregateType: "widget",
+    tenantId: "tenant-1",
+    version: 1,
+    type: "widget.created",
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: "system" },
+    createdAt: Temporal.Now.instant(),
+    createdBy: "system",
+  };
+}
+
+function stubState(): ConsumerStateRow {
+  return {
+    name: "consumer",
+    instanceId: "shared",
+    lastProcessedEventId: 0n,
+    status: "idle",
+    attempts: 0,
+    rearmCount: 0,
+    lastError: null,
+    updatedAt: Temporal.Now.instant(),
+  };
+}
+
+describe("deliverEvents — per-consumer maxAttempts override", () => {
+  test("stays alive past the dispatcher-wide default when errorPolicy.maxAttempts is higher", async () => {
+    const consumer: EventConsumer = {
+      name: "search",
+      errorPolicy: { maxAttempts: 20 },
+      handler: async () => {
+        throw new Error("meilisearch not provisioned yet");
+      },
+    };
+
+    const outcome = await deliverEvents(
+      consumer,
+      [stubEvent(1n)],
+      stubContext(),
+      /* dispatcher-wide default */ 10,
+      { ...stubState(), attempts: 10 },
+    );
+
+    expect(outcome.attempts).toBe(11);
+    expect(outcome.deadLettered).toBe(false);
+  });
+
+  test("dead-letters at the override once attempts reach it", async () => {
+    const consumer: EventConsumer = {
+      name: "search",
+      errorPolicy: { maxAttempts: 20 },
+      handler: async () => {
+        throw new Error("meilisearch not provisioned yet");
+      },
+    };
+
+    const outcome = await deliverEvents(consumer, [stubEvent(1n)], stubContext(), 10, {
+      ...stubState(),
+      attempts: 19,
+    });
+
+    expect(outcome.attempts).toBe(20);
+    expect(outcome.deadLettered).toBe(true);
+  });
+
+  test("a consumer without the override still dies at the dispatcher-wide default", async () => {
+    const consumer: EventConsumer = {
+      name: "plain",
+      handler: async () => {
+        throw new Error("boom");
+      },
+    };
+
+    const outcome = await deliverEvents(consumer, [stubEvent(1n)], stubContext(), 10, {
+      ...stubState(),
+      attempts: 9,
+    });
+
+    expect(outcome.attempts).toBe(10);
+    expect(outcome.deadLettered).toBe(true);
+  });
+});
+
+describe("createSearchEventConsumer — errorPolicy wiring", () => {
+  test("wires more retry headroom than the dispatcher-wide default", () => {
+    const consumer = createSearchEventConsumer(
+      {} as unknown as Parameters<typeof createSearchEventConsumer>[0],
+      {} as unknown as Parameters<typeof createSearchEventConsumer>[1],
+    );
+
+    expect(consumer.errorPolicy?.maxAttempts).toBeGreaterThan(10);
+  });
+});