@cosmicdrift/kumiko-framework 0.85.0 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.85.0",
+  "version": "0.87.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.85.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.87.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/http-cache.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from "bun:test";
+import {
+  cacheControlHeader,
+  cachedResponse,
+  computeRevisionEtag,
+  computeStrongEtag,
+  computeWeakEtag,
+  etagMatches,
+  parseIfNoneMatch,
+} from "../http-cache";
+
+describe("computeWeakEtag", () => {
+  test("formats mtime-size weak tag", () => {
+    expect(computeWeakEtag(1_700_000_000_000, 4096)).toBe('W/"1700000000000-4096"');
+  });
+});
+
+describe("computeStrongEtag", () => {
+  test("same seed → same tag", () => {
+    expect(computeStrongEtag("hello")).toBe(computeStrongEtag("hello"));
+  });
+
+  test("different seed → different tag", () => {
+    expect(computeStrongEtag("hello")).not.toBe(computeStrongEtag("world"));
+  });
+});
+
+describe("computeRevisionEtag", () => {
+  test("stable for same parts", () => {
+    const parts = ["tenant-a", "about", "de", "3", "2026-01-01T00:00:00.000Z"];
+    expect(computeRevisionEtag(parts)).toBe(computeRevisionEtag(parts));
+  });
+});
+
+describe("cacheControlHeader", () => {
+  test("immutable default", () => {
+    expect(cacheControlHeader({ kind: "immutable" })).toBe("public, max-age=31536000, immutable");
+  });
+
+  test("revalidate default", () => {
+    expect(cacheControlHeader({ kind: "revalidate" })).toBe("public, max-age=0, must-revalidate");
+  });
+
+  test("no-cache", () => {
+    expect(cacheControlHeader({ kind: "no-cache" })).toBe("no-cache");
+  });
+
+  test("none → undefined", () => {
+    expect(cacheControlHeader({ kind: "none" })).toBeUndefined();
+  });
+});
+
+describe("parseIfNoneMatch", () => {
+  test("empty / null", () => {
+    expect(parseIfNoneMatch(null)).toEqual([]);
+    expect(parseIfNoneMatch("")).toEqual([]);
+  });
+
+  test("single tag", () => {
+    expect(parseIfNoneMatch('"abc"')).toEqual(['"abc"']);
+  });
+
+  test("multiple tags", () => {
+    expect(parseIfNoneMatch(' "a" , W/"b" ')).toEqual(['"a"', 'W/"b"']);
+  });
+
+  test("wildcard", () => {
+    expect(parseIfNoneMatch("*")).toEqual(["*"]);
+  });
+});
+
+describe("etagMatches", () => {
+  const etag = '"deadbeef"';
+
+  test("no header → false", () => {
+    expect(etagMatches(null, etag)).toBe(false);
+  });
+
+  test("exact match", () => {
+    expect(etagMatches('"deadbeef"', etag)).toBe(true);
+  });
+
+  test("weak matches strong value", () => {
+    expect(etagMatches('W/"deadbeef"', etag)).toBe(true);
+    expect(etagMatches('"deadbeef"', 'W/"deadbeef"')).toBe(true);
+  });
+
+  test("wildcard", () => {
+    expect(etagMatches("*", etag)).toBe(true);
+  });
+
+  test("mismatch", () => {
+    expect(etagMatches('"other"', etag)).toBe(false);
+  });
+});
+
+describe("cachedResponse", () => {
+  const etag = computeStrongEtag("body");
+
+  test("200 with body and headers", () => {
+    const res = cachedResponse(new Request("https://example.test/"), {
+      body: "hello",
+      etag,
+      cache: { kind: "revalidate" },
+      headers: { "content-type": "text/plain" },
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("etag")).toBe(etag);
+    expect(res.headers.get("cache-control")).toBe("public, max-age=0, must-revalidate");
+    expect(res.headers.get("content-type")).toBe("text/plain");
+  });
+
+  test("304 when If-None-Match matches", async () => {
+    const req = new Request("https://example.test/", {
+      headers: { "if-none-match": etag },
+    });
+    const res = cachedResponse(req, {
+      body: "hello",
+      etag,
+      cache: { kind: "revalidate" },
+    });
+    expect(res.status).toBe(304);
+    expect(res.headers.get("etag")).toBe(etag);
+    expect(await res.text()).toBe("");
+  });
+
+  test("HEAD returns no body", async () => {
+    const res = cachedResponse(new Request("https://example.test/", { method: "HEAD" }), {
+      body: "hello",
+      etag,
+      cache: { kind: "revalidate" },
+    });
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("");
+  });
+
+  test("304 via If-Modified-Since", () => {
+    const lastModified = new Date("2026-06-01T12:00:00.000Z");
+    const req = new Request("https://example.test/", {
+      headers: { "if-modified-since": lastModified.toUTCString() },
+    });
+    const res = cachedResponse(req, {
+      body: "hello",
+      etag,
+      cache: { kind: "revalidate" },
+      lastModified,
+    });
+    expect(res.status).toBe(304);
+  });
+});

package/src/api/http-cache.ts

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+
+export type CachePolicy =
+  | { readonly kind: "immutable"; readonly maxAgeSeconds?: number }
+  | { readonly kind: "revalidate"; readonly maxAgeSeconds?: number }
+  | { readonly kind: "no-cache" }
+  | { readonly kind: "none" };
+
+export type CachedResponseInit = {
+  readonly body: BodyInit | null;
+  readonly status?: number;
+  readonly headers?: Record<string, string>;
+  readonly etag: string;
+  readonly cache: CachePolicy;
+  readonly lastModified?: Date;
+};
+
+const DEFAULT_IMMUTABLE_MAX_AGE = 31_536_000;
+const DEFAULT_REVALIDATE_MAX_AGE = 0;
+
+function digestEtag(seed: string | Uint8Array): string {
+  const hash = createHash("sha256").update(seed).digest("base64url").slice(0, 22);
+  return `"${hash}"`;
+}
+
+/** Weak ETag for disk files — cheap, good enough for static assets. */
+export function computeWeakEtag(mtimeMs: number, size: number): string {
+  return `W/"${mtimeMs}-${size}"`;
+}
+
+/** Strong ETag from final response bytes (e.g. index.html after schema inject). */
+export function computeStrongEtag(seed: string | Uint8Array): string {
+  return digestEtag(seed);
+}
+
+/** Strong ETag from revision parts — avoids rendering before a 304 check. */
+export function computeRevisionEtag(parts: readonly string[]): string {
+  return digestEtag(parts.join("\0"));
+}
+
+export function cacheControlHeader(policy: CachePolicy): string | undefined {
+  switch (policy.kind) {
+    case "immutable":
+      return `public, max-age=${policy.maxAgeSeconds ?? DEFAULT_IMMUTABLE_MAX_AGE}, immutable`;
+    case "revalidate": {
+      const maxAge = policy.maxAgeSeconds ?? DEFAULT_REVALIDATE_MAX_AGE;
+      return `public, max-age=${maxAge}, must-revalidate`;
+    }
+    case "no-cache":
+      return "no-cache";
+    case "none":
+      return undefined;
+  }
+}
+
+function normalizeEtag(value: string): string {
+  return value.trim();
+}
+
+function weakEtagMatches(stored: string, candidate: string): boolean {
+  const storedNorm = normalizeEtag(stored);
+  const candidateNorm = normalizeEtag(candidate);
+  if (storedNorm === candidateNorm) return true;
+  const storedWeak = storedNorm.startsWith("W/") ? storedNorm.slice(2) : storedNorm;
+  const candidateWeak = candidateNorm.startsWith("W/") ? candidateNorm.slice(2) : candidateNorm;
+  return storedWeak === candidateWeak;
+}
+
+/** Parse `If-None-Match` into individual tag values (order preserved). */
+export function parseIfNoneMatch(header: string | null): readonly string[] {
+  if (header === null || header.trim() === "") return [];
+  if (header.trim() === "*") return ["*"];
+  return header
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+export function etagMatches(ifNoneMatch: string | null, etag: string): boolean {
+  const tags = parseIfNoneMatch(ifNoneMatch);
+  if (tags.length === 0) return false;
+  if (tags.includes("*")) return true;
+  return tags.some((tag) => weakEtagMatches(etag, tag));
+}
+
+function isNotModifiedSince(ifModifiedSince: string, lastModified: Date): boolean {
+  const parsed = Date.parse(ifModifiedSince);
+  if (Number.isNaN(parsed)) return false;
+  // HTTP dates have second precision — floor the stored mtime.
+  return Math.floor(lastModified.getTime() / 1000) * 1000 <= parsed;
+}
+
+function buildResponseHeaders(init: CachedResponseInit): Record<string, string> {
+  const headers: Record<string, string> = { ...(init.headers ?? {}), etag: init.etag };
+  const cacheControl = cacheControlHeader(init.cache);
+  if (cacheControl !== undefined) headers["cache-control"] = cacheControl;
+  if (init.lastModified !== undefined) {
+    headers["last-modified"] = init.lastModified.toUTCString();
+  }
+  return headers;
+}
+
+/** Conditional GET/HEAD helper — returns 304 when the client already has the revision. */
+export function cachedResponse(req: Request, init: CachedResponseInit): Response {
+  const headers = buildResponseHeaders(init);
+  const ifNoneMatch = req.headers.get("if-none-match");
+  if (etagMatches(ifNoneMatch, init.etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  if (init.lastModified !== undefined) {
+    const ifModifiedSince = req.headers.get("if-modified-since");
+    if (ifModifiedSince !== null && isNotModifiedSince(ifModifiedSince, init.lastModified)) {
+      return new Response(null, { status: 304, headers });
+    }
+  }
+  if (req.method === "HEAD") {
+    return new Response(null, { status: init.status ?? 200, headers });
+  }
+  return new Response(init.body, { status: init.status ?? 200, headers });
+}

package/src/api/index.ts

@@ -18,6 +18,16 @@ export type {
   SessionRevoker,
 } from "./auth-routes";
 export { createAuthRoutes, createInMemoryLoginRateLimiter } from "./auth-routes";
+export type { CachedResponseInit, CachePolicy } from "./http-cache";
+export {
+  cacheControlHeader,
+  cachedResponse,
+  computeRevisionEtag,
+  computeStrongEtag,
+  computeWeakEtag,
+  etagMatches,
+  parseIfNoneMatch,
+} from "./http-cache";
 export type { JwtHelper, JwtPayload } from "./jwt";
 export { createJwtHelper } from "./jwt";
 export { type RequestContextData, requestContext } from "./request-context";

package/src/engine/__tests__/build-app-schema-settings-hub.test.ts

@@ -206,19 +206,14 @@ describe("buildAppSchema — dangling audience-ref dev-warning (#408/3)", () =>
   // (the boot-validator exempts the audience QNs), but the entry renders
   // invisibly — the dev must see a warning, not silently nothing.
   function warnsFor(scopes: string[]): string[] {
-    const prevEnv = process.env.NODE_ENV;
-    process.env.NODE_ENV = "development";
     const warn = spyOn(console, "warn").mockImplementation(() => {});
     try {
-      buildAppSchema(createRegistry([placingShell(...scopes), billing]));
+      buildAppSchema(createRegistry([placingShell(...scopes), billing]), {
+        authoringWarnings: true,
+      });
       return warn.mock.calls.map((c) => String(c[0]));
     } finally {
       warn.mockRestore();
-      if (prevEnv === undefined) {
-        delete process.env.NODE_ENV;
-      } else {
-        process.env.NODE_ENV = prevEnv;
-      }
     }
   }
 
@@ -235,9 +230,7 @@ describe("buildAppSchema — dangling audience-ref dev-warning (#408/3)", () =>
     expect(messages.some((m) => m.includes("nie generiert"))).toBe(false);
   });
 
-  test("authoring warnings are suppressed under NODE_ENV=test — no CI-log noise (#408/1)", () => {
-    // bun:test sets NODE_ENV=test; an unplaced audience (tenant left over by
-    // placingShell("system")) must NOT emit a console.warn into CI logs.
+  test("authoring warnings are off by default — tests/prod boot stay silent", () => {
     const warn = spyOn(console, "warn").mockImplementation(() => {});
     try {
       buildAppSchema(createRegistry([placingShell("system"), billing]));

package/src/engine/build-app-schema.ts

@@ -34,7 +34,13 @@ import {
 import type { Registry } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
 
-export function buildAppSchema(registry: Registry): AppSchema {
+export type BuildAppSchemaOptions = {
+  /** Dev-server authoring hints (Settings-Hub placement). Default off — only
+   *  `createKumikoServer` opts in; prod boot + unit tests stay silent. */
+  readonly authoringWarnings?: boolean;
+};
+
+export function buildAppSchema(registry: Registry, options: BuildAppSchemaOptions = {}): AppSchema {
   const features: FeatureSchema[] = [];
   for (const [featureName, feature] of registry.features) {
     const navs = Object.values(feature.navs);
@@ -78,8 +84,10 @@ export function buildAppSchema(registry: Registry): AppSchema {
       const placed = placeSettingsHub(workspaces, generated);
       workspaces = placed.workspaces;
       if (placed.standalone !== undefined) workspaces.push(placed.standalone);
-      warnUnplacedAudiences(placed.unplaced);
-      warnDanglingAudienceRefs(placed.danglingRefs);
+      if (options.authoringWarnings === true) {
+        warnUnplacedAudiences(placed.unplaced);
+        warnDanglingAudienceRefs(placed.danglingRefs);
+      }
     }
   }
 
@@ -200,10 +208,6 @@ function placeSettingsHub(
 function warnUnplacedAudiences(unplaced: readonly string[]): void {
   // skip: every audience placed — nothing to warn about
   if (unplaced.length === 0) return;
-  const env = typeof process !== "undefined" ? process.env.NODE_ENV : undefined;
-  // skip: dev-only authoring hint — silent in production and in tests
-  // (bun:test sets NODE_ENV=test) where it would only noise up CI logs.
-  if (env === "production" || env === "test") return;
   // biome-ignore lint/suspicious/noConsole: dev-only authoring hint
   console.warn(
     `[kumiko] Settings-Hub: ${unplaced.join(", ")} nicht in einer App-Workspace platziert — ` +
@@ -216,9 +220,6 @@ function warnUnplacedAudiences(unplaced: readonly string[]): void {
 function warnDanglingAudienceRefs(dangling: readonly string[]): void {
   // skip: no dangling refs — nothing to warn about
   if (dangling.length === 0) return;
-  const env = typeof process !== "undefined" ? process.env.NODE_ENV : undefined;
-  // skip: dev-only authoring hint — silent in production and in tests
-  if (env === "production" || env === "test") return;
   // biome-ignore lint/suspicious/noConsole: dev-only authoring hint
   console.warn(
     `[kumiko] Settings-Hub: ${dangling

package/src/engine/index.ts

@@ -7,7 +7,7 @@ export {
   validateBoot,
 } from "./boot-validator";
 export { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler";
-export { buildAppSchema } from "./build-app-schema";
+export { type BuildAppSchemaOptions, buildAppSchema } from "./build-app-schema";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema";
 export {
   buildConfigFeatureSchema,