@cosmicdrift/kumiko-framework 0.188.0 → 0.190.0

package/src/derivatives/__tests__/derivatives-context.integration.test.ts

@@ -0,0 +1,162 @@
+// Proves ctx.derivatives actually arrives on BOTH context-building paths
+// this cut wires it into: the HTTP write-handler path (dispatch-shared.ts
+// buildHandlerContext) and the job path (job-runner.ts handleJob). A unit
+// test on createDerivativesContext alone can't catch a forgotten wiring
+// point — this is that test.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { z } from "zod";
+import { defineFeature, EXT_DERIVATIVE_RENDERER } from "../../engine";
+import { InternalError, writeFailure } from "../../errors";
+import { createFilesFeature } from "../../files/feature";
+import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
+import { buildMultipartBody, patchFileInstanceofForBunTest, waitFor } from "../../testing";
+
+const fakeRender: DerivativeRendererPlugin["render"] = async () => new Uint8Array([9, 9, 9]);
+
+const jobResults: Array<{ storageKey: string; mimeType: string; rendered: boolean }> = [];
+
+const derivativesTestFeature = defineFeature("derivativestest", (r) => {
+  r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, { onRegister: () => {} });
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", { render: fakeRender });
+
+  r.writeHandler(
+    "make-variant",
+    z.object({ fileRefId: z.string() }),
+    async (event, ctx) => {
+      if (!ctx.derivatives) {
+        return writeFailure(
+          new InternalError({ message: "no ctx.derivatives on write-handler ctx" }),
+        );
+      }
+      const result = await ctx.derivatives.variant(
+        event.payload.fileRefId,
+        { maxEdge: 100 },
+        "thumb",
+      );
+      return { isSuccess: true as const, data: result };
+    },
+    { access: { openToAll: true } },
+  );
+
+  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload, ctx) => {
+    const fileRefId = (payload as { fileRefId: string }).fileRefId;
+    if (!ctx.derivatives) {
+      throw new Error("no ctx.derivatives on job ctx");
+    }
+    const result = await ctx.derivatives.variant(fileRefId, { maxEdge: 200 }, "card");
+    jobResults.push(result);
+  });
+});
+
+let stack: TestStack;
+const tenantId = testTenantId(1);
+const user = createTestUser({ id: 1, tenantId, roles: ["Admin"] });
+const otherTenantId = testTenantId(2);
+const otherTenantUser = createTestUser({ id: 10, tenantId: otherTenantId, roles: ["Admin"] });
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [createFilesFeature(), derivativesTestFeature],
+    files: { storageProvider: createInMemoryFileProvider() },
+    jobs: { consumerLane: "worker" },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function uploadFile(asUser = user): Promise<string> {
+  const token = await stack.jwt.sign(asUser);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from([1, 2, 3])], "photo.jpg", { type: "image/jpeg" }));
+  const { body, contentType } = await buildMultipartBody(fd);
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+    body,
+  });
+  expect(res.status).toBe(201);
+  const json = (await res.json()) as { id: string };
+  return json.id;
+}
+
+describe("ctx.derivatives wiring — HTTP write-handler path", () => {
+  test("a real write-handler sees ctx.derivatives and variant() returns a storage key", async () => {
+    const fileId = await uploadFile();
+
+    const result = await stack.http.writeOk<{
+      storageKey: string;
+      mimeType: string;
+      rendered: boolean;
+    }>("derivativestest:write:make-variant", { fileRefId: fileId }, user);
+
+    expect(result.storageKey).toContain("thumb-");
+    expect(result.mimeType).toBe("image/jpeg");
+    expect(result.rendered).toBe(true);
+  });
+});
+
+describe("ctx.derivatives wiring — job path", () => {
+  test("a job handler sees ctx.derivatives and variant() returns a storage key", async () => {
+    jobResults.length = 0;
+    const fileId = await uploadFile();
+
+    // handleJob resolves tenant scope from payload.tenantId (falls back to
+    // SYSTEM_TENANT_ID otherwise) — without it the derivatives lookup can't
+    // find the file uploaded under the test tenant.
+    await stack.jobRunner?.dispatch("derivativestest:job:record", { fileRefId: fileId, tenantId });
+
+    await waitFor(() => {
+      expect(jobResults.length).toBeGreaterThan(0);
+    });
+    expect(jobResults[0]?.storageKey).toContain("card-");
+    expect(jobResults[0]?.rendered).toBe(true);
+  });
+});
+
+// variant() filters on `id`, `tenantId`, and `isDeleted` — a unit test can't
+// tell a real Postgres query from a stub that ignores those filters, so
+// these three run against the real DB via setupTestStack.
+describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () => {
+  test("an unknown fileRefId throws", async () => {
+    const err = await stack.http.writeErr(
+      "derivativestest:write:make-variant",
+      { fileRefId: "00000000-0000-4000-8000-999999999999" },
+      user,
+    );
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  test("a soft-deleted fileRef throws", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+    const deleteRes = await stack.app.request(`/api/files/${fileId}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(deleteRes.status).toBe(200);
+
+    const err = await stack.http.writeErr(
+      "derivativestest:write:make-variant",
+      { fileRefId: fileId },
+      user,
+    );
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  test("a fileRef uploaded under a different tenant is not resolvable", async () => {
+    const foreignFileId = await uploadFile(otherTenantUser);
+
+    const err = await stack.http.writeErr(
+      "derivativestest:write:make-variant",
+      { fileRefId: foreignFileId },
+      user,
+    );
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+  });
+});

package/src/derivatives/__tests__/derivatives-context.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { Registry } from "../../engine/types";
+import { createFileContext } from "../../files/file-handle";
+import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { createDerivativesContext, resolveRenderer } from "../derivatives-context";
+
+const FILE_REF_ID = "11111111-1111-4111-8111-111111111111";
+const TENANT_ID = "22222222-2222-4222-8222-222222222222";
+
+// Minimal fake Registry — same pattern as provider-resolver.test.ts's
+// fakeRegistry: only getExtensionUsages is exercised by resolveRenderer.
+function fakeRegistry(usages: ReadonlyArray<{ entityName: string; options: unknown }>): Registry {
+  return {
+    getExtensionUsages: () => usages,
+  } as unknown as Registry;
+}
+
+function countingRenderer(): {
+  plugin: DerivativeRendererPlugin;
+  calls: () => number;
+} {
+  let calls = 0;
+  const plugin: DerivativeRendererPlugin = {
+    render: async () => {
+      calls++;
+      return new Uint8Array([calls]);
+    },
+  };
+  return { plugin, calls: () => calls };
+}
+
+// bun-db's fetchOne(db, table, where) duck-types `db` as a TenantDb via
+// tenantDbDelegate() and, when it matches, delegates straight to
+// db.selectMany(...) instead of building raw SQL — so a fake satisfying that
+// shape exercises variant()'s own logic without a live Postgres connection.
+// selectMany evaluates `where` against the canned row instead of ignoring
+// it: variant()'s two mandatory filters (tenantId, isDeleted) are real
+// integration-test territory, but a fake that returns the row unconditionally
+// would let those filters be deleted here without a single red test.
+function fakeDbWithFileRef(row: { storageKey: string; mimeType: string }): unknown {
+  const canned: Record<string, unknown> = {
+    ...row,
+    id: FILE_REF_ID,
+    tenantId: TENANT_ID,
+    isDeleted: false,
+  };
+  return {
+    raw: { unsafe: () => {} },
+    tenantId: TENANT_ID,
+    selectMany: async (_table: unknown, where?: Record<string, unknown>) => {
+      const matches = Object.entries(where ?? {}).every(([key, value]) => canned[key] === value);
+      return matches ? [canned] : [];
+    },
+    fetchOne: async () => canned,
+    insertOne: async () => undefined,
+    updateMany: async () => [],
+    deleteMany: async () => {},
+  };
+}
+
+describe("resolveRenderer", () => {
+  test("exact MIME match wins over a wildcard", () => {
+    const { plugin: exactPlugin } = countingRenderer();
+    const { plugin: wildcardPlugin } = countingRenderer();
+    const registry = fakeRegistry([
+      { entityName: "image/*", options: wildcardPlugin },
+      { entityName: "image/png", options: exactPlugin },
+    ]);
+    expect(resolveRenderer(registry, "image/png")).toBe(exactPlugin);
+  });
+
+  test("falls back to a `<type>/*` wildcard when no exact match exists", () => {
+    const { plugin: wildcardPlugin } = countingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/*", options: wildcardPlugin }]);
+    expect(resolveRenderer(registry, "image/jpeg")).toBe(wildcardPlugin);
+  });
+
+  test("no match returns undefined — caller throws with the known-list", () => {
+    const registry = fakeRegistry([]);
+    expect(resolveRenderer(registry, "application/pdf")).toBeUndefined();
+  });
+
+  test("a `; charset=` suffix on the source mimeType doesn't break resolution", () => {
+    const { plugin } = countingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/jpeg", options: plugin }]);
+    expect(resolveRenderer(registry, "image/jpeg; charset=binary")).toBe(plugin);
+  });
+
+  test("a registered usage without a render() throws instead of falling back to the wildcard", () => {
+    const { plugin: wildcardPlugin } = countingRenderer();
+    const registry = fakeRegistry([
+      { entityName: "image/*", options: wildcardPlugin },
+      { entityName: "image/png", options: { renderer: () => {} } },
+    ]);
+    expect(() => resolveRenderer(registry, "image/png")).toThrow(/image\/png/);
+  });
+});
+
+describe("createDerivativesContext — variant()", () => {
+  async function setup(mimeType = "image/jpeg") {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1, 2, 3]), mimeType);
+    const files = createFileContext(() => Promise.resolve(provider));
+    const { plugin, calls } = countingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/*", options: plugin }]);
+    const db = fakeDbWithFileRef({ storageKey: "tenant/photo.jpg", mimeType });
+    const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
+    return { ctx, calls, provider };
+  }
+
+  test("derive-on-first-use: first call renders, second call with the same spec hits the cache", async () => {
+    const { ctx, calls } = await setup();
+    const spec = { maxEdge: 320 } as const;
+
+    const first = await ctx.variant(FILE_REF_ID, spec, "thumb");
+    expect(first.rendered).toBe(true);
+    expect(calls()).toBe(1);
+
+    const second = await ctx.variant(FILE_REF_ID, spec, "thumb");
+    expect(second.rendered).toBe(false);
+    expect(calls()).toBe(1);
+    expect(second.storageKey).toBe(first.storageKey);
+  });
+
+  test("a changed spec renders again at a different key", async () => {
+    const { ctx, calls } = await setup();
+    const first = await ctx.variant(FILE_REF_ID, { maxEdge: 320 }, "thumb");
+    const second = await ctx.variant(FILE_REF_ID, { maxEdge: 640 }, "thumb");
+
+    expect(calls()).toBe(2);
+    expect(second.rendered).toBe(true);
+    expect(second.storageKey).not.toBe(first.storageKey);
+  });
+
+  test("no renderer registered for the mimeType throws, naming the known patterns", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/doc.pdf", new Uint8Array([1]));
+    const files = createFileContext(() => Promise.resolve(provider));
+    const registry = fakeRegistry([{ entityName: "image/*", options: countingRenderer().plugin }]);
+    const db = fakeDbWithFileRef({ storageKey: "tenant/doc.pdf", mimeType: "application/pdf" });
+    const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
+
+    await expect(ctx.variant(FILE_REF_ID, {}, "thumb")).rejects.toThrow(/image\/\*/);
+  });
+
+  test("mimeType is consistent across a fresh render and a cache hit for the same spec", async () => {
+    const { ctx } = await setup();
+    const spec = { format: "webp" } as const;
+
+    const first = await ctx.variant(FILE_REF_ID, spec, "thumb");
+    const second = await ctx.variant(FILE_REF_ID, spec, "thumb");
+
+    expect(first.mimeType).toBe("image/webp");
+    expect(second.mimeType).toBe("image/webp");
+  });
+
+  test("the mimeType written to storage matches the mimeType returned to the caller", async () => {
+    const { ctx, provider } = await setup();
+    const spec = { format: "webp" } as const;
+
+    const result = await ctx.variant(FILE_REF_ID, spec, "thumb");
+
+    expect(provider.mimeTypeOf(result.storageKey)).toBe(result.mimeType);
+    expect(result.mimeType).toBe("image/webp");
+  });
+});

package/src/derivatives/__tests__/variant-key.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { specHash, variantSuffix } from "../variant-key";
+
+describe("specHash — key stability", () => {
+  test("key order doesn't matter", () => {
+    expect(specHash({ fit: "cover", maxEdge: 512 })).toBe(specHash({ maxEdge: 512, fit: "cover" }));
+  });
+
+  test("an explicit undefined is neutral, same as omitting the key", () => {
+    expect(specHash({ fit: "cover" })).toBe(specHash({ fit: "cover", blur: undefined }));
+  });
+
+  test("nested object keys are sorted too", () => {
+    expect(specHash({ size: { width: 1, height: 2 } })).toBe(
+      specHash({ size: { height: 2, width: 1 } }),
+    );
+  });
+
+  test("a changed value produces a different hash — the whole point of hashing the spec", () => {
+    expect(specHash({ maxEdge: 512 })).not.toBe(specHash({ maxEdge: 640 }));
+  });
+});
+
+describe("variantSuffix", () => {
+  test("the name is part of the suffix — same spec, different name diverges", () => {
+    const spec = { maxEdge: 512 } as const;
+    expect(variantSuffix("thumb", spec)).not.toBe(variantSuffix("card", spec));
+  });
+
+  test("shape is `<name>-<8 hex chars>`", () => {
+    expect(variantSuffix("thumb", { maxEdge: 512 })).toMatch(/^thumb-[0-9a-f]{8}$/);
+  });
+
+  test("a path-traversal name is rejected — it would escape the tenant prefix in the derived key", () => {
+    expect(() => variantSuffix("../evil", {})).toThrow(/variant name/);
+  });
+
+  test("a name containing a slash is rejected", () => {
+    expect(() => variantSuffix("a/b", {})).toThrow(/variant name/);
+  });
+
+  test("an empty name is rejected", () => {
+    expect(() => variantSuffix("", {})).toThrow(/variant name/);
+  });
+
+  test("a name over 32 chars is rejected", () => {
+    expect(() => variantSuffix("a".repeat(40), {})).toThrow(/variant name/);
+  });
+
+  test("ordinary names pass through", () => {
+    expect(() => variantSuffix("thumb", {})).not.toThrow();
+    expect(() => variantSuffix("card-2x", {})).not.toThrow();
+    expect(() => variantSuffix("Hero", {})).not.toThrow();
+  });
+});

package/src/derivatives/derivatives-context.ts

@@ -0,0 +1,146 @@
+import type {
+  DerivativeRendererPlugin,
+  DerivativesContext,
+  VariantSpec,
+} from "@cosmicdrift/kumiko-types/derivatives-types";
+import { type AnyDb, fetchOne } from "../bun-db/query";
+import { EXT_DERIVATIVE_RENDERER } from "../engine/extension-names";
+import type { Registry, TenantId } from "../engine/types";
+import type { FileContext } from "../files/file-handle";
+import { fileRefsTable } from "../files/file-ref-table";
+import { assertSafeStorageKey } from "../files/types";
+import { variantSuffix } from "./variant-key";
+
+export type DerivativesContextDeps = {
+  readonly files: FileContext;
+  readonly registry: Registry;
+  readonly db: AnyDb;
+  readonly tenantId: TenantId;
+};
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind, same pattern as isFileProviderPlugin.
+function isDerivativeRendererPlugin(o: unknown): o is DerivativeRendererPlugin {
+  return typeof o === "object" && o !== null && "render" in o && typeof o.render === "function";
+}
+
+// Mirrors validateFile's mime-normalization: strip a `; charset=…` suffix,
+// trim, lowercase — so a provider-supplied `image/jpeg; charset=binary`
+// still resolves.
+function normalizeMimeType(mimeType: string): string {
+  return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+}
+
+export function resolveRenderer(
+  registry: Registry,
+  mimeType: string,
+): DerivativeRendererPlugin | undefined {
+  const normalized = normalizeMimeType(mimeType);
+  const usages = registry.getExtensionUsages(EXT_DERIVATIVE_RENDERER);
+
+  const exact = usages.find((u) => u.entityName === normalized);
+  if (exact) {
+    if (!isDerivativeRendererPlugin(exact.options))
+      throw new Error(
+        `derivatives.resolveRenderer: "${exact.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`,
+      );
+    return exact.options;
+  }
+
+  const wildcard = usages.find((u) => u.entityName === `${normalized.split("/")[0]}/*`);
+  if (wildcard) {
+    if (!isDerivativeRendererPlugin(wildcard.options))
+      throw new Error(
+        `derivatives.resolveRenderer: "${wildcard.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`,
+      );
+    return wildcard.options;
+  }
+
+  return undefined;
+}
+
+type FileRefRow = {
+  readonly storageKey: string;
+  readonly mimeType: string;
+};
+
+function isFileRefRow(row: Record<string, unknown>): row is FileRefRow {
+  return typeof row["storageKey"] === "string" && typeof row["mimeType"] === "string";
+}
+
+// The spec — not the renderer — determines the output mimeType, so it's the
+// single source of truth for both what gets written to storage and what the
+// caller receives; a cache hit never runs the renderer, so there's nothing
+// else to derive it from.
+function outputMimeType(spec: VariantSpec, sourceMimeType: string): string {
+  switch (spec.format) {
+    case "webp":
+      return "image/webp";
+    case "avif":
+      return "image/avif";
+    case "jpeg":
+      return "image/jpeg";
+    default:
+      return sourceMimeType;
+  }
+}
+
+export function createDerivativesContext(deps: DerivativesContextDeps): DerivativesContext {
+  return {
+    variant: async (fileRefId, spec, name) => {
+      const row = await fetchOne<Record<string, unknown>>(deps.db, fileRefsTable, {
+        id: fileRefId,
+        tenantId: deps.tenantId,
+        isDeleted: false,
+      });
+      if (!row) {
+        throw new Error(`derivatives.variant: no fileRef found for id "${fileRefId}"`);
+      }
+      if (!isFileRefRow(row)) {
+        throw new Error(
+          `derivatives.variant: fileRef "${fileRefId}" is missing storageKey/mimeType`,
+        );
+      }
+
+      const renderer = resolveRenderer(deps.registry, row.mimeType);
+      if (!renderer) {
+        const known =
+          deps.registry
+            .getExtensionUsages(EXT_DERIVATIVE_RENDERER)
+            .map((u) => u.entityName)
+            .join(", ") || "<none>";
+        throw new Error(
+          `derivatives.variant: no renderer registered for mimeType "${row.mimeType}". Known: ${known}.`,
+        );
+      }
+
+      const src = deps.files.ref(row.storageKey);
+      // ponytail: derived key keeps the source extension regardless of the
+      // spec's format — widen deriveKey if a storage backend ever routes on
+      // extension.
+      const target = src.derive(variantSuffix(name, spec));
+      // Belt-and-suspenders: variantSuffix already rejects an unsafe name,
+      // this catches a traversal segment reaching the key through any other
+      // path (e.g. a future deriveKey change).
+      assertSafeStorageKey(target.key);
+      const mimeType = outputMimeType(spec, row.mimeType);
+
+      if (await target.exists()) {
+        return {
+          storageKey: target.key,
+          mimeType,
+          rendered: false,
+        };
+      }
+
+      const original = await src.read();
+      const result = await renderer.render(original, spec, row.mimeType);
+      await target.write(result, mimeType);
+      return {
+        storageKey: target.key,
+        mimeType,
+        rendered: true,
+      };
+    },
+  };
+}

package/src/derivatives/index.ts

@@ -0,0 +1,3 @@
+export type { DerivativesContextDeps } from "./derivatives-context";
+export { createDerivativesContext, resolveRenderer } from "./derivatives-context";
+export { canonicalJson, specHash, variantSuffix } from "./variant-key";

package/src/derivatives/variant-key.ts

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+
+// Deterministic JSON: object keys sorted (recursively), `undefined` values
+// dropped, arrays keep their order. Two specs that are semantically equal
+// (same keys, different insertion order; explicit `undefined` vs. omitted)
+// serialize identically.
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+// A key built from the variant name alone would keep serving stale pixels
+// forever after a spec change; hashing the spec into the key means a
+// changed spec is automatically a new URL.
+export function specHash(spec: VariantSpec): string {
+  return createHash("sha256").update(canonicalJson(spec)).digest("hex").slice(0, 8);
+}
+
+const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;
+
+export function variantSuffix(name: string, spec: VariantSpec): string {
+  // `name` ends up in a storage key (see deriveKey) — an unvalidated value
+  // like "../../other-tenant/x" would escape the tenant prefix the key is
+  // built under.
+  if (!VARIANT_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `derivatives: variant name must match ${VARIANT_NAME_PATTERN.source} (letters, digits, hyphens; max 32 chars), got "${name}"`,
+    );
+  }
+  return `${name}-${specHash(spec)}`;
+}