@cosmicdrift/kumiko-server-runtime 0.288.0 → 0.289.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.288.0",
+  "version": "0.289.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,9 +80,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.288.0",
-    "@cosmicdrift/kumiko-framework": "0.288.0",
-    "@cosmicdrift/kumiko-headless": "0.288.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.289.0",
+    "@cosmicdrift/kumiko-framework": "0.289.0",
+    "@cosmicdrift/kumiko-headless": "0.289.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/boot-probe-fixture.ts

@@ -34,6 +34,7 @@ export function makeProbeFeature(opts: {
       name: "ping",
       schema: z.object({}),
       access: { roles: ["anonymous"] },
+      rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
       handler: async () => ({ pong: true }),
     });
   });

package/src/__tests__/run-prod-app.integration.test.ts

@@ -87,12 +87,14 @@ const widgetFeature = defineFeature("prod-probe", (r) => {
     name: "ping",
     schema: z.object({}),
     access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
     handler: async () => ({ pong: true }),
   });
   r.queryHandler({
     name: "kms-probe",
     schema: z.object({}),
     access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
     handler: async (_event, ctx) => ({ hasKms: ctx.kms !== undefined }),
   });
   // SystemAdmin-gated write — Ziel des extraRoutes.dispatchSystemWrite-

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "PageHeadMeta/PageHeadResolver/PageHeadSystemQuery now importable from the server-runtime barrel",
+    "detail": "The three resolvePageHead types moved to @cosmicdrift/kumiko-headless/apex (kumiko-framework#3026) and are re-exported unchanged from run-prod-app.ts, so the existing @cosmicdrift/kumiko-server-runtime/run-prod-app subpath import keeps working. New: the main @cosmicdrift/kumiko-server-runtime barrel now also exports all three, closing the gap where a consumer had to use the subpath just to type a resolver. render-head-tags.ts (internal-only, not a public subpath) is removed; injectPageHead now lives in headless."
+  },
   {
     "version": "0.286.0",
     "type": "improvement",

package/src/index.ts

@@ -7,6 +7,9 @@ export type {
   AccountUnlockSetup,
   EmailVerificationSetup,
   InviteSetup,
+  PageHeadMeta,
+  PageHeadResolver,
+  PageHeadSystemQuery,
   PasswordResetSetup,
   ProdAppHandle,
   ProdSeedFn,

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

@@ -7,16 +7,10 @@ import {
   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 { resolveAndInjectPageHead } from "@cosmicdrift/kumiko-headless/apex";
 import { ASSETS_DIR } from "./build-prod-bundle";
 import { injectSchema } from "./inject-schema";
-import { injectPageHead } from "./render-head-tags";
-import type {
-  HostDispatchFn,
-  PageHeadMeta,
-  PageHeadResolver,
-  PageHeadSystemQuery,
-} from "./run-prod-app";
+import type { HostDispatchFn, PageHeadResolver, PageHeadSystemQuery } from "./run-prod-app";
 import { stripNoRouteMatchHeader, tryHonoFirst } from "./try-hono-first";
 
 // Static-asset + SPA-fallback serving for runProdApp's HTTP handler. Split
@@ -132,10 +126,6 @@ export type PageHeadOptions = {
   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,
@@ -193,56 +183,6 @@ 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
@@ -250,14 +190,28 @@ export function buildStaticFallback(
   // 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.
+  //
+  // The resolve+timeout+inject itself runs through headless's
+  // resolveAndInjectPageHead — the single call site runDevApp also uses
+  // (kumiko-framework#3026), so only the systemQuery/dispatcher wiring
+  // below (Request-bound, prod-specific) and the etag recompute are local.
   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;
+    if (!pageHead) return html;
+    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)),
+      );
     const text = new TextDecoder().decode(html.bytes);
-    const injected = injectPageHead(text, renderApexHeadTags(toApexHead(meta)));
+    const injected = await resolveAndInjectPageHead(text, pageHead.resolvePageHead, {
+      path: url.pathname,
+      host,
+      systemQuery,
+    });
     if (injected === text) return html;
     const encoded = new TextEncoder().encode(injected);
     return {

package/src/run-prod-app.ts

@@ -98,7 +98,6 @@ import {
   type EffectiveFeaturesResolver,
   type FeatureDefinition,
   findTierResolverUsage,
-  type TenantId,
   type TierResolverPlugin,
   validateAppCustomScreenWriteQns,
   validateBoot,
@@ -137,6 +136,11 @@ import {
 } from "@cosmicdrift/kumiko-framework/pipeline";
 import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import type {
+  PageHeadMeta,
+  PageHeadResolver,
+  PageHeadSystemQuery,
+} from "@cosmicdrift/kumiko-headless/apex";
 import Redis from "ioredis";
 import { applyBootSeeds } from "./boot/apply-boot-seeds";
 import { resolveBootCrypto } from "./boot/boot-crypto";
@@ -431,33 +435,13 @@ 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>;
+// PageHeadMeta/PageHeadResolver/PageHeadSystemQuery moved to
+// @cosmicdrift/kumiko-headless/apex (kumiko-framework#3026) — runDevApp needs
+// the same types and the same resolve+inject function runProdApp uses, and
+// headless is where renderApexHeadTags already lives. Re-exported here so
+// existing subpath-imports (`@cosmicdrift/kumiko-server-runtime/run-prod-app`)
+// keep working unchanged.
+export type { PageHeadMeta, PageHeadResolver, PageHeadSystemQuery };
 
 export type RunProdAppOptions = {
   /** App-specific features. config/user/tenant/auth-email-password are

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

@@ -1,27 +0,0 @@
-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/render-head-tags.ts

@@ -1,14 +0,0 @@
-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>`);
-}