npm - @cosmicdrift/kumiko-server-runtime - Versions diffs - 0.285.1 → 0.286.0 - Mend

@cosmicdrift/kumiko-server-runtime 0.285.1 → 0.286.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/package.json +4 -3
package/src/__tests__/render-head-tags.test.ts +27 -0
package/src/__tests__/run-prod-app-static-files.test.ts +107 -0
package/src/changes.json +8 -0
package/src/render-head-tags.ts +14 -0
package/src/run-prod-app-static-files.ts +107 -3
package/src/run-prod-app.ts +42 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.285.1",
+  "version": "0.286.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -80,8 +80,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.285.1",
-    "@cosmicdrift/kumiko-framework": "0.285.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.286.0",
+    "@cosmicdrift/kumiko-framework": "0.286.0",
+    "@cosmicdrift/kumiko-headless": "0.286.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/render-head-tags.test.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { injectPageHead } from "../render-head-tags";
+describe("injectPageHead", () => {
+  const TAGS = '<title>New Title</title>\n<meta name="description" content="d">';
+  test("replaces an existing <title> instead of duplicating it", () => {
+    const html = "<html><head><title>Old</title></head><body></body></html>";
+    const out = injectPageHead(html, TAGS);
+    expect(out).not.toContain("<title>Old</title>");
+    expect((out.match(/<title>/g) ?? []).length).toBe(1);
+    expect(out).toContain("<title>New Title</title>");
+  });
+  test("applying twice does not duplicate the head-tags block", () => {
+    const html = "<html><head><title>Old</title></head><body></body></html>";
+    const once = injectPageHead(html, TAGS);
+    const twice = injectPageHead(once, TAGS);
+    expect(twice).toBe(once);
+    expect((twice.match(/kumiko-page-head/g) ?? []).length).toBe(1);
+  });
+  test("HTML without </head> is returned unchanged", () => {
+    const html = "<html><body><title>Old</title></body></html>";
+    expect(injectPageHead(html, TAGS)).toBe(html);
+  });
+});

package/src/__tests__/run-prod-app-static-files.test.ts CHANGED Viewed

@@ -203,3 +203,110 @@ describe("buildStaticFallback hostDispatch", () => {
     expect(await res.text()).toContain("spa-shell");
   });
 });
+describe("buildStaticFallback resolvePageHead", () => {
+  let tmp = "";
+  const HTML = "<!doctype html><html><head><title>Offlot</title></head><body>shell</body></html>";
+  function stubDispatcher(): { query: () => Promise<unknown> } {
+    return { query: async () => ({}) };
+  }
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "kumiko-pagehead-"));
+    await writeFile(join(tmp, "tenant.html"), HTML);
+    await writeFile(join(tmp, "index.html"), HTML);
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+  // Exercised through hostDispatch's "html" branch — that's the path
+  // offlot actually uses in production (createOfflotHostDispatch returns
+  // {kind:"html", ...} for every host), not the default single-app path.
+  test("resolver meta → og-tags appear in the hostDispatch HTML response", async () => {
+    const handler = buildStaticFallback(
+      () => noRouteMatchedResponse(),
+      tmp,
+      "{}",
+      () => ({ kind: "html", file: "tenant.html" }),
+      {
+        resolvePageHead: async () => ({
+          title: "Vehicle X",
+          description: "A car",
+          ogImage: "https://x/i.png",
+        }),
+        dispatcher: stubDispatcher(),
+      },
+    );
+    const res = await handler(new Request("http://t/"));
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).toContain("<title>Vehicle X</title>");
+    expect(text).toContain('<meta property="og:image" content="https://x/i.png" />');
+  });
+  test("resolver throws → 200 with the unchanged shell", async () => {
+    const handler = buildStaticFallback(
+      () => noRouteMatchedResponse(),
+      tmp,
+      "{}",
+      () => ({ kind: "html", file: "tenant.html" }),
+      {
+        resolvePageHead: async () => {
+          throw new Error("boom");
+        },
+        dispatcher: stubDispatcher(),
+      },
+    );
+    const res = await handler(new Request("http://t/"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe(HTML);
+  });
+  test("resolver never resolves → 200 with the unchanged shell after the timeout", async () => {
+    const handler = buildStaticFallback(
+      () => noRouteMatchedResponse(),
+      tmp,
+      "{}",
+      () => ({ kind: "html", file: "tenant.html" }),
+      {
+        resolvePageHead: () => new Promise(() => {}),
+        dispatcher: stubDispatcher(),
+      },
+    );
+    const res = await handler(new Request("http://t/"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe(HTML);
+  }, 2000);
+  test("two paths with different resolved titles get different ETags", async () => {
+    const handler = buildStaticFallback(
+      () => noRouteMatchedResponse(),
+      tmp,
+      "{}",
+      () => ({ kind: "html", file: "tenant.html" }),
+      {
+        resolvePageHead: async ({ path }) => ({ title: `Title for ${path}` }),
+        dispatcher: stubDispatcher(),
+      },
+    );
+    const resA = await handler(new Request("http://t/a"));
+    const resB = await handler(new Request("http://t/b"));
+    expect(resA.headers.get("etag")).not.toBe(resB.headers.get("etag"));
+  });
+  test("no resolvePageHead configured → response is byte-identical to the no-resolver call", async () => {
+    const withoutPageHead = buildStaticFallback(
+      () => noRouteMatchedResponse(),
+      tmp,
+      "{}",
+      () => ({ kind: "html", file: "tenant.html" }),
+    );
+    const res = await withoutPageHead(new Request("http://t/"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe(HTML);
+  });
+});

package/src/changes.json ADDED Viewed

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "runProdApp gains resolvePageHead for per-request Open-Graph/title/description metadata",
+    "detail": "New PageHeadResolver/PageHeadMeta types and a resolvePageHead option on RunProdAppOptions. buildStaticFallback's static-files module resolves the metadata on both HTML-serving paths (hostDispatch and the default index.html), timing the resolver out at 300ms via Promise.race and always falling back to the unchanged 200 shell on error/null/timeout. Head tags render via renderApexHeadTags from the new @cosmicdrift/kumiko-headless dependency (ApexHead built from PageHeadMeta, lang derived from meta.locale's language subtag, default \"en\"; og:type is hardcoded \"website\" by the renderer, so PageHeadMeta has no ogType field), injected idempotently via a marker comment in render-head-tags.ts's injectPageHead, same pattern as inject-schema.ts. A strong ETag is recomputed over the final bytes whenever head tags are actually injected, so two requests with different resolved metadata never collide on one ETag. systemQuery inside the resolver dispatches as createAnonymousUser (not createSystemUser) wrapped in requestContext.run, using the new buildRequestContextDataFromRequest(req: Request) extracted from @cosmicdrift/kumiko-framework/api's existing buildRequestContextData(c: Context) — needed because this resolver runs outside Hono's router and only has a raw Request. No behavior change for apps that don't set resolvePageHead."
+  }
+]

package/src/render-head-tags.ts ADDED Viewed

@@ -0,0 +1,14 @@
+const HEAD_TAGS_MARKER = "<!-- kumiko-page-head -->";
+const TITLE_TAG_RE = /<title\b[^>]*>[\s\S]*?<\/title>/i;
+// Idempotent by marker (repeated calls, e.g. hostDispatch + default path
+// both hitting the same request, never double-inject) and safe on a
+// head-less document (nothing to splice into). `tagsHtml` is pre-rendered
+// HTML from a caller (renderApexHeadTags) — this function only owns
+// placement + the original <title> removal, not escaping.
+export function injectPageHead(html: string, tagsHtml: string): string {
+  if (html.includes(HEAD_TAGS_MARKER)) return html;
+  if (!html.includes("</head>")) return html;
+  const withoutTitle = html.replace(TITLE_TAG_RE, "");
+  return withoutTitle.replace("</head>", () => `${HEAD_TAGS_MARKER}\n${tagsHtml}\n</head>`);
+}

package/src/run-prod-app-static-files.ts CHANGED Viewed

@@ -1,12 +1,22 @@
 import {
+  buildRequestContextDataFromRequest,
   type CachePolicy,
   cachedResponse,
   computeStrongEtag,
   computeWeakEtag,
+  requestContext,
 } from "@cosmicdrift/kumiko-framework/api";
+import { createAnonymousUser, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { type ApexHead, renderApexHeadTags } from "@cosmicdrift/kumiko-headless/apex";
 import { ASSETS_DIR } from "./build-prod-bundle";
 import { injectSchema } from "./inject-schema";
-import type { HostDispatchFn } from "./run-prod-app";
+import { injectPageHead } from "./render-head-tags";
+import type {
+  HostDispatchFn,
+  PageHeadMeta,
+  PageHeadResolver,
+  PageHeadSystemQuery,
+} from "./run-prod-app";
 import { stripNoRouteMatchHeader, tryHonoFirst } from "./try-hono-first";
 // Static-asset + SPA-fallback serving for runProdApp's HTTP handler. Split
@@ -110,11 +120,28 @@ export function mimeTypeFor(filePath: string): string {
   }
 }
+// Minimal structural shape of the dispatcher buildStaticFallback needs —
+// not the full Dispatcher type, so this file doesn't have to import the
+// pipeline package just to type one param.
+type QueryDispatcher = {
+  readonly query: (type: string, payload: unknown, user: SessionUser) => Promise<unknown>;
+};
+export type PageHeadOptions = {
+  readonly resolvePageHead: PageHeadResolver;
+  readonly dispatcher: QueryDispatcher;
+};
+// Resolver runs alongside the request, never gates it: a slow, throwing, or
+// null-returning resolver must never turn a 200 shell into a 500 or a stall.
+const PAGE_HEAD_TIMEOUT_MS = 300;
 export function buildStaticFallback(
   apiHandler: (req: Request) => Response | Promise<Response>,
   staticDir: string,
   appSchemaJson: string,
   hostDispatch?: HostDispatchFn,
+  pageHead?: PageHeadOptions,
 ): (req: Request) => Promise<Response> {
   const indexHtml = `${staticDir}/index.html`;
@@ -166,6 +193,81 @@ export function buildStaticFallback(
     });
   }
+  // ApexHead.lang is required (html lang="..."); PageHeadMeta only carries
+  // og:locale-shaped strings ("de_DE", "en-US") since that's all og:locale
+  // needs. Take the language subtag before the region separator; default to
+  // "en" when there's no locale to derive one from.
+  function apexLangFromLocale(locale: string | undefined): string {
+    return locale?.split(/[_-]/)[0]?.toLowerCase() || "en";
+  }
+  function toApexHead(meta: PageHeadMeta): ApexHead {
+    return {
+      lang: apexLangFromLocale(meta.locale),
+      title: meta.title,
+      description: meta.description ?? "",
+      ...(meta.canonicalUrl !== undefined ? { canonicalUrl: meta.canonicalUrl } : {}),
+      ...(meta.ogImage !== undefined ? { ogImage: meta.ogImage } : {}),
+      ...(meta.siteName !== undefined ? { siteName: meta.siteName } : {}),
+      ...(meta.locale !== undefined ? { locale: meta.locale } : {}),
+    };
+  }
+  // Resolves per-request head metadata, capped at PAGE_HEAD_TIMEOUT_MS.
+  // Never throws — a failing/slow/absent resolver just means "no head
+  // metadata this request", not a broken response.
+  async function resolvePageHeadMeta(req: Request): Promise<PageHeadMeta | null> {
+    if (!pageHead) return null;
+    const url = new URL(req.url);
+    const host = req.headers.get("host") ?? url.host;
+    const systemQuery: PageHeadSystemQuery = (type, payload, tenantId) =>
+      requestContext.run(requestContext.get() ?? buildRequestContextDataFromRequest(req), () =>
+        pageHead.dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+      );
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const timedOut = new Promise<null>((resolve) => {
+        timer = setTimeout(() => resolve(null), PAGE_HEAD_TIMEOUT_MS);
+      });
+      // .catch on the resolver's own promise (not just the outer try/catch)
+      // so a rejection arriving AFTER the timeout already won the race
+      // doesn't surface as an unhandled rejection.
+      const resolved = pageHead
+        .resolvePageHead({ path: url.pathname, host, systemQuery })
+        .catch(() => null);
+      return await Promise.race([resolved, timedOut]);
+    } catch {
+      return null;
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+  // Injects resolved head metadata into an already-read HTML payload, right
+  // before it's served. Recomputes a strong etag over the final bytes so
+  // two requests with different head metadata never collide on one etag
+  // (see computeStrongEtag usage in readHtmlFile above for the same
+  // requirement on schema-injection). No resolvePageHead configured, no
+  // meta resolved, or nothing actually changed (e.g. no `</head>` to
+  // inject into) → the original html object is returned untouched.
+  async function applyPageHead(
+    req: Request,
+    html: { bytes: ArrayBuffer; mime: string; etag: string; mtimeMs: number },
+  ): Promise<{ bytes: ArrayBuffer; mime: string; etag: string; mtimeMs: number }> {
+    const meta = await resolvePageHeadMeta(req);
+    if (!meta) return html;
+    const text = new TextDecoder().decode(html.bytes);
+    const injected = injectPageHead(text, renderApexHeadTags(toApexHead(meta)));
+    if (injected === text) return html;
+    const encoded = new TextEncoder().encode(injected);
+    return {
+      bytes: encoded.buffer as ArrayBuffer,
+      mime: html.mime,
+      etag: computeStrongEtag(encoded),
+      mtimeMs: html.mtimeMs,
+    };
+  }
   // hostDispatch konsultieren wenn gesetzt UND der Request auf den
   // HTML-Fallback fällt (Root oder SPA-Route). Returnt entweder die
   // resolved Response (redirect/404/html) oder null wenn der Default-
@@ -196,7 +298,8 @@ export function buildStaticFallback(
     // sonst darf ein Shared-Cache Tenant-As Schema an Tenant B liefern.
     const extraHeaders: Record<string, string> = { vary: "Host" };
     if (result.csp) extraHeaders["content-security-policy"] = result.csp;
-    return serveHtmlFile(req, "/index.html", html, extraHeaders);
+    const withHead = await applyPageHead(req, html);
+    return serveHtmlFile(req, "/index.html", withHead, extraHeaders);
   }
   return async (req: Request): Promise<Response> => {
@@ -249,7 +352,8 @@ export function buildStaticFallback(
     // Default Single-App-Pfad: index.html, schema injected.
     const index = await readHtmlFile(indexHtml, true);
     if (index) {
-      return serveHtmlFile(req, "/index.html", index);
+      const withHead = await applyPageHead(req, index);
+      return serveHtmlFile(req, "/index.html", withHead);
     }
     // Kein Hono-Match, keine Disk-Datei, kein index.html → liefer den

package/src/run-prod-app.ts CHANGED Viewed

@@ -98,6 +98,7 @@ import {
   type EffectiveFeaturesResolver,
   type FeatureDefinition,
   findTierResolverUsage,
+  type TenantId,
   type TierResolverPlugin,
   validateAppCustomScreenWriteQns,
   validateBoot,
@@ -430,6 +431,34 @@ export type HostDispatchFn = (req: {
   readonly search: string;
 }) => HostDispatchResult;
+/** Per-request head metadata (Open-Graph/title/description) for the
+ *  static-fallback HTML shell. Only `title` is required; everything else
+ *  falls back to no tag rather than a placeholder. */
+export type PageHeadMeta = {
+  readonly title: string;
+  readonly description?: string;
+  readonly ogImage?: string;
+  readonly canonicalUrl?: string;
+  readonly siteName?: string;
+  readonly locale?: string;
+};
+// Matches bundled-features' shared/system-query.ts SystemQueryFn shape
+// (non-generic, Promise<unknown>) rather than a generic <T> signature —
+// that's the convention every other systemQuery caller in the framework
+// already follows (r.httpRoute handlers, seo/managed-pages features).
+export type PageHeadSystemQuery = (
+  type: string,
+  payload: unknown,
+  tenantId: TenantId,
+) => Promise<unknown>;
+export type PageHeadResolver = (input: {
+  readonly path: string;
+  readonly host: string;
+  readonly systemQuery: PageHeadSystemQuery;
+}) => Promise<PageHeadMeta | null>;
 export type RunProdAppOptions = {
   /** App-specific features. config/user/tenant/auth-email-password are
    *  auto-mixed when `auth:` is set — don't add them yourself. */
@@ -475,6 +504,16 @@ export type RunProdAppOptions = {
    *  werden. CSP-Header pro Host können zusätzlich Asset-Pfade
    *  einschränken. */
   readonly hostDispatch?: HostDispatchFn;
+  /** Per-request head-metadata resolver (Open-Graph/title/description) for
+   *  the static-fallback HTML shell — see `PageHeadResolver`. Consulted on
+   *  the same two HTML-serving paths as `hostDispatch` (host-dispatched
+   *  HTML + the default single-app index.html), right before the response
+   *  is sent. On error, `null`, or a resolve time over 300ms, the shell
+   *  ships unchanged with status 200 — this must never turn into a 500 or
+   *  a blank page. `systemQuery` inside the resolver runs as the
+   *  anonymous role (not system) — the resolver is reachable by any
+   *  public visitor, same access gate as a real anonymous request. */
+  readonly resolvePageHead?: PageHeadResolver;
   /** Pfad zu kumiko/migrations für den Boot-Gate. Default "./kumiko/
    *  migrations" relativ zum process-cwd (wo die App gestartet wird —
    *  bei Container-Deploys typischerweise der App-Workspace-Root, weil
@@ -1271,6 +1310,9 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
           options.staticDir,
           appSchemaJson,
           options.hostDispatch,
+          options.resolvePageHead
+            ? { resolvePageHead: options.resolvePageHead, dispatcher: entrypoint.dispatcher }
+            : undefined,
         )
       : // No staticDir (split-deploy / API-only container) → app.fetch's
         // response goes straight to the client, bypassing buildStaticFallback