@cosmicdrift/kumiko-framework 0.192.0 → 0.193.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.192.0",
+  "version": "0.193.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -186,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.192.0",
+    "@cosmicdrift/kumiko-types": "0.193.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.192.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.193.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/request-id-middleware.ts

@@ -1,5 +1,5 @@
 import type { Context, Next } from "hono";
-import { requestContext } from "./request-context";
+import { type RequestContextData, requestContext } from "./request-context";
 
 const REQUEST_ID_HEADER = "X-Request-ID";
 const CORRELATION_ID_HEADER = "X-Correlation-ID";
@@ -14,6 +14,47 @@ function sanitizeClientId(value: string | undefined): string | undefined {
   return value !== undefined && SAFE_ID_RE.test(value) ? value : undefined;
 }
 
+/**
+ * Builds the RequestContextData record for a Hono request — requestId
+ * (client-supplied + sanitized, or generated), correlationId (mirrors
+ * requestId unless the client set its own), the underlying abort signal,
+ * and the client IP/User-Agent. Extracted out of `requestIdMiddleware` so
+ * call-sites that invoke a handler outside that middleware's `next()`
+ * chain (e.g. server.ts's httpRoute→systemQuery mount) can still populate
+ * the same AsyncLocalStorage record via `requestContext.run(...)`.
+ */
+export function buildRequestContextData(c: Context): RequestContextData {
+  const requestId =
+    sanitizeClientId(c.req.header(REQUEST_ID_HEADER)) ?? requestContext.generateId();
+  const correlationId = sanitizeClientId(c.req.header(CORRELATION_ID_HEADER)) ?? requestId;
+
+  // Hono exposes the underlying Fetch Request — its `signal` aborts
+  // when the client disconnects (mobile back-press, tab close). We
+  // propagate it through requestContext so framework internals can
+  // honour cancellation at long-running checkpoints. Older Hono /
+  // adapter combos may not populate `c.req.raw.signal`; conditional
+  // spread keeps `signal: undefined` out of the stored record so
+  // downstream `signal?` checks behave as if no signal exists.
+  const signal = c.req.raw?.signal;
+  // Client IP for per-IP rate limiting. Trust `x-forwarded-for` when
+  // present (proxy/CDN) — first hop is the originating client. Adapter-
+  // specific socket-address fallback (bun, node) is not standardized
+  // in Hono; deployments behind a proxy should always set xff. Without
+  // either we leave `ip` undefined and skip ip-bucketed checks rather
+  // than fabricate one.
+  const xff = c.req.header("x-forwarded-for");
+  const ip = xff?.split(",")[0]?.trim();
+  const userAgent = c.req.header("user-agent");
+
+  return {
+    requestId,
+    correlationId,
+    ...(signal ? { signal } : {}),
+    ...(ip && ip.length > 0 ? { ip } : {}),
+    ...(userAgent !== undefined ? { userAgent } : {}),
+  };
+}
+
 /**
  * Assigns a requestId + correlationId to every request and wraps execution
  * in AsyncLocalStorage. Runs BEFORE auth — both ids are available even for
@@ -25,39 +66,11 @@ function sanitizeClientId(value: string | undefined): string | undefined {
  */
 export function requestIdMiddleware() {
   return async (c: Context, next: Next) => {
-    const requestId =
-      sanitizeClientId(c.req.header(REQUEST_ID_HEADER)) ?? requestContext.generateId();
-    const correlationId = sanitizeClientId(c.req.header(CORRELATION_ID_HEADER)) ?? requestId;
-    c.header(REQUEST_ID_HEADER, requestId);
-    c.header(CORRELATION_ID_HEADER, correlationId);
-    c.set("requestId", requestId);
-
-    // Hono exposes the underlying Fetch Request — its `signal` aborts
-    // when the client disconnects (mobile back-press, tab close). We
-    // propagate it through requestContext so framework internals can
-    // honour cancellation at long-running checkpoints. Older Hono /
-    // adapter combos may not populate `c.req.raw.signal`; conditional
-    // spread keeps `signal: undefined` out of the stored record so
-    // downstream `signal?` checks behave as if no signal exists.
-    const signal = c.req.raw?.signal;
-    // Client IP for per-IP rate limiting. Trust `x-forwarded-for` when
-    // present (proxy/CDN) — first hop is the originating client. Adapter-
-    // specific socket-address fallback (bun, node) is not standardized
-    // in Hono; deployments behind a proxy should always set xff. Without
-    // either we leave `ip` undefined and skip ip-bucketed checks rather
-    // than fabricate one.
-    const xff = c.req.header("x-forwarded-for");
-    const ip = xff?.split(",")[0]?.trim();
-    const userAgent = c.req.header("user-agent");
-    await requestContext.run(
-      {
-        requestId,
-        correlationId,
-        ...(signal ? { signal } : {}),
-        ...(ip && ip.length > 0 ? { ip } : {}),
-        ...(userAgent !== undefined ? { userAgent } : {}),
-      },
-      () => next(),
-    );
+    const data = buildRequestContextData(c);
+    c.header(REQUEST_ID_HEADER, data.requestId);
+    c.header(CORRELATION_ID_HEADER, data.correlationId);
+    c.set("requestId", data.requestId);
+
+    await requestContext.run(data, () => next());
   };
 }

package/src/api/server.ts

@@ -57,7 +57,8 @@ import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
-import { requestIdMiddleware } from "./request-id-middleware";
+import { requestContext } from "./request-context";
+import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware";
 import {
   DEFAULT_MAX_REQUEST_BYTES,
   registerBodyLimit,
@@ -769,7 +770,17 @@ export function buildServer(options: ServerOptions): KumikoServer {
             // it into a public response. The forced tenant already comes
             // from bypassing the HTTP layer entirely; no elevated role
             // is needed or wanted on top of that.
-            dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+            //
+            // httpRoute handlers run OUTSIDE /api/* — requestIdMiddleware
+            // (which wraps requestContext.run with ip/requestId/
+            // correlationId) never sees this request. Without this wrap,
+            // `rateLimit: {per: "ip", ...}` on a handler invoked via
+            // systemQuery is silent dead-code: enforceRateLimit reads
+            // requestContext.get()?.ip, which is undefined here, so
+            // buildBucketKey always returns {kind: "skip"}.
+            requestContext.run(buildRequestContextData(c), () =>
+              dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+            ),
         });
       switch (route.method) {
         case "GET":

package/src/engine/__tests__/engine.test.ts

@@ -814,6 +814,28 @@ describe("createApp", () => {
     );
   });
 
+  // hasMoneyField used to only look at top-level fields, so an entity whose
+  // only money lives inside an embedded-list sub-schema (e.g. invoice lines
+  // with no top-level money field) slipped past this check — its cells and
+  // totals would then silently render in entity.defaultCurrency ?? "EUR"
+  // regardless of the app's actual currency.
+  test("rejects an entity whose only money field is nested in an embedded list", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          fields: {
+            lines: createEmbeddedListField({ amount: { type: "money", required: true } }),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      "has money fields but no defaultCurrency",
+    );
+  });
+
   test("rejects unknown defaultCurrency", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
@@ -955,6 +977,9 @@ describe("createApp", () => {
               qty: { type: "decimal", scale: 3 },
             }),
           },
+          // meta.amount is money nested in an embedded field — needs a
+          // defaultCurrency the same as a top-level money field would.
+          defaultCurrency: "EUR",
         }),
       );
     });
@@ -1073,6 +1098,7 @@ describe("createApp", () => {
               { totalsMatch: { amount: "title" } },
             ),
           },
+          defaultCurrency: "EUR",
         }),
       );
     });
@@ -1093,6 +1119,7 @@ describe("createApp", () => {
               { totalsMatch: { amount: "ghostTotal" } },
             ),
           },
+          defaultCurrency: "EUR",
         }),
       );
     });

package/src/engine/create-app.ts

@@ -85,7 +85,17 @@ export function createApp(config: AppConfig): App {
   // Validate defaultCurrency on entities that have money fields
   for (const feature of config.features) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-      const hasMoneyField = Object.values(entity.fields).some((f) => f.type === "money");
+      // A top-level money field isn't the only way an entity can hold money —
+      // an embedded-list's sub-schema (e.g. invoice lines) can carry a money
+      // cell with no top-level money field at all. Without this, that entity
+      // slips past the defaultCurrency check and its cells/totals render in
+      // the entity.defaultCurrency ?? "EUR" fallback regardless of the app's
+      // actual currency.
+      const hasMoneyField = Object.values(entity.fields).some(
+        (f) =>
+          f.type === "money" ||
+          (f.type === "embedded" && Object.values(f.schema).some((s) => s.type === "money")),
+      );
       if (entity.defaultCurrency && !currencies.includes(entity.defaultCurrency)) {
         throw new Error(
           `Entity "${entityName}" in feature "${feature.name}" has defaultCurrency "${entity.defaultCurrency}" which is not in the currencies list. Available: ${currencies.join(", ")}`,

package/src/engine/extension-names.ts

@@ -104,6 +104,22 @@ export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider" as con
  */
 export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer" as const;
 
+/**
+ * `derivativePublicPredicate` — per-entityType "is this FileRef's derivative
+ * publicly readable?" gate for the anonymous variant route (file-derivatives).
+ *
+ * Apps register via
+ * `r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "<entityType>", { isPublic:
+ * (args, ctx) => boolean | Promise<boolean> })`, where `<entityType>` is the
+ * `entityType` string a FileRef carries from upload (e.g. "vehicle", "event").
+ * No registration for a given entityType is default-deny — the public route
+ * serves nothing for that entityType, not even a 403 (404, so existence isn't
+ * confirmed to an unauthorised caller).
+ *
+ * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ */
+export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate" as const;
+
 /**
  * `searchAdapter` — Search-Adapter-Forget-Hooks (Meilisearch-Index-Cleanup
  * bei User-Forget oder Tenant-Destroy).

package/src/engine/index.ts

@@ -77,6 +77,7 @@ export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
 export type { KumikoExtensionName } from "./extension-names";
 export {
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
   EXT_DERIVATIVE_RENDERER,
   EXT_EXTERNAL_RESOURCE,
   EXT_FILE_PROVIDER,

package/src/jobs/__tests__/job-runner-boot-timeout.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// Simulates an unreachable Redis: waitUntilReady() never resolves. Everything
+// else start() touches (Queue.on/close/add/upsertJobScheduler) is a no-op —
+// with an empty registry those code paths aren't exercised anyway.
+mock.module("bullmq", () => {
+  class FakeQueue {
+    on() {}
+    close() {
+      return Promise.resolve();
+    }
+    getJobCounts() {
+      return Promise.resolve({});
+    }
+    removeJobScheduler() {
+      return Promise.resolve();
+    }
+    upsertJobScheduler() {
+      return Promise.resolve();
+    }
+    add() {
+      return Promise.resolve();
+    }
+  }
+  class FakeWorker {
+    on() {}
+    waitUntilReady() {
+      return new Promise(() => {});
+    }
+    close() {
+      return Promise.resolve();
+    }
+  }
+  return { Queue: FakeQueue, Worker: FakeWorker };
+});
+
+import { createRegistry } from "../../engine";
+import type { AppContext } from "../../engine/types";
+import { createJobRunner } from "../job-runner";
+
+describe("createJobRunner start() boot timeout", () => {
+  test("rejects instead of hanging forever when the worker's Redis connection never becomes ready", async () => {
+    const registry = createRegistry([]);
+    const context: AppContext = {};
+    const runner = createJobRunner({
+      registry,
+      context,
+      redisUrl: "redis://localhost:6379",
+      consumerLane: "worker",
+      bootRedisTimeoutMs: 50,
+    });
+
+    await expect(runner.start()).rejects.toThrow(/Redis not reachable within 50ms \(lane=worker\)/);
+  });
+});

package/src/jobs/job-runner.ts

@@ -132,6 +132,10 @@ export type JobRunnerOptions = {
   // Tests set a unique prefix (e.g. `"test-${Date.now()}"`) for isolation —
   // two parallel test-runners never see each other's jobs.
   queueNamePrefix?: string | undefined;
+  // Override how long start() waits for the worker's Redis connection
+  // before failing boot. Defaults to BOOT_REDIS_TIMEOUT_MS; tests shrink it
+  // to keep an unreachable-Redis assertion fast.
+  bootRedisTimeoutMs?: number | undefined;
   getActiveTenantIds?: () => Promise<TenantId[]>;
   onJobStart?: (jobName: string, jobId: string, meta: JobMeta) => void;
   onJobComplete?: (jobName: string, jobId: string, duration: number, logs: JobLogEntry[]) => void;
@@ -192,9 +196,20 @@ function parseRedisOpts(url: string): { host: string; port: number; db?: number
   return result;
 }
 
+// redisOpts carries no connectTimeout/retry cap, so an unreachable Redis
+// would otherwise hang start() forever with no health endpoint to notice.
+const BOOT_REDIS_TIMEOUT_MS = 10_000;
+
+function timeoutReject(ms: number, message: string): Promise<never> {
+  return new Promise((_, reject) => {
+    setTimeout(() => reject(new Error(message)), ms);
+  });
+}
+
 export function createJobRunner(options: JobRunnerOptions): JobRunner {
   const { registry, context, redisUrl, consumerLane } = options;
   const queueNamePrefix = options.queueNamePrefix ?? DEFAULT_QUEUE_NAME_PREFIX;
+  const bootRedisTimeoutMs = options.bootRedisTimeoutMs ?? BOOT_REDIS_TIMEOUT_MS;
   const redisOpts = parseRedisOpts(redisUrl);
   // Use the context's tracer when present (observability-provider injected at
   // boot); otherwise noop so dispatch/handleJob stay zero-cost without config.
@@ -531,7 +546,15 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       // worker's connections (main + blocking) are ready (fw#1805). This
       // mirrors the wait BullMQ already does internally for
       // upsertJobScheduler()/add() below when the lane has a cron/boot job.
-      await worker.waitUntilReady();
+      // Racing a timeout against it keeps an unreachable Redis from hanging
+      // start() forever — there's no worker health endpoint to notice.
+      await Promise.race([
+        worker.waitUntilReady(),
+        timeoutReject(
+          bootRedisTimeoutMs,
+          `job-runner: Redis not reachable within ${bootRedisTimeoutMs}ms (lane=${consumerLane})`,
+        ),
+      ]);
 
       // Only schedule cron + boot for jobs that belong to this lane. Jobs
       // assigned to the other lane get their cron/boot wiring from the