@cosmicdrift/kumiko-server-runtime 0.328.1 → 0.330.0

package/dist/run-worker-app.d.ts

@@ -0,0 +1,92 @@
+import { type ServerOptions } from "@cosmicdrift/kumiko-framework/api";
+import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type EffectiveFeaturesResolver, type FeatureDefinition, type Registry, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
+import { type WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
+import type { ObservabilityOptions, ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
+import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import { Redis } from "ioredis";
+import { type SystemWireDeps } from "./extra-routes-deps.js";
+export type WorkerContextOption = Record<string, unknown> | ((deps: WorkerDeps) => Record<string, unknown>);
+export type WorkerDeps = {
+    readonly db: DbConnection;
+    readonly redis: Redis;
+    readonly registry: Registry;
+};
+/** Deps for the `wireComponents` hook — app-wired co-running components
+ *  (an analysis runner, an IMAP supervisor, ...) that need the system-
+ *  write dispatcher and register their own shutdown hooks on the worker
+ *  lifecycle. Same shape as the `wire` hook's SystemWireDeps, plus
+ *  `lifecycle` for `registerShutdownHook`. */
+export type WorkerWireDeps = SystemWireDeps & {
+    readonly lifecycle: WorkerEntrypoint["lifecycle"];
+};
+export type RunWorkerAppOptions = {
+    /** App-specific features — same array as in the API/all-in-one process,
+     *  so the registry + schema stay identical across processes. */
+    readonly features: readonly FeatureDefinition[];
+    /** Opt-in boot-validator warnings — see ValidateBootOptions. */
+    readonly validateBootOptions?: ValidateBootOptions;
+    /** Mount the auto-mixed config/user/tenant/auth-email-password features —
+     *  MUST match the API process's `includeBundled` value, otherwise API
+     *  and worker run with a diverging registry topology. Also controls
+     *  whether buildBootExtraContext auto-wires `configResolver` (same
+     *  auth-mode gate as runProdApp). */
+    readonly includeBundled?: boolean;
+    /** Path to kumiko/migrations for the boot gate. See RunProdAppOptions
+     *  ["migrations"] — identical semantics. */
+    readonly migrations?: {
+        readonly dir: string;
+    } | false;
+    /** Extra AppContext keys — same factory-union pattern as
+     *  RunProdAppOptions["extraContext"], without sseBroker (the worker
+     *  has none — see entrypoint/index.ts's documented SSE limitation). */
+    readonly extraContext?: WorkerContextOption;
+    /** MasterKeyProvider for ctx.secrets. Default: env-KEK (see
+     *  RunProdAppOptions["masterKey"]). */
+    readonly masterKey?: MasterKeyProvider;
+    /** Subject-key adapter for crypto-shredding — boot checks health()
+     *  before any connection (see RunProdAppOptions["kms"]). */
+    readonly kms?: KmsAdapter;
+    /** Blind-index key for lookupable fields (see
+     *  RunProdAppOptions["blindIndexKey"]). */
+    readonly blindIndexKey?: string;
+    /** Explicit opt-out from the PII boot gate (see
+     *  RunProdAppOptions["allowPlaintextPii"]). */
+    readonly allowPlaintextPii?: string;
+    readonly jobs?: {
+        readonly queueNamePrefix?: string;
+        /** Source of active tenant ids for `perTenant: true` jobs (see
+         *  RunProdAppOptions["jobs"]["getActiveTenantIds"]) — identical
+         *  semantics, framework falls back to the tenant feature's own
+         *  active-tenant-ids query when omitted. */
+        readonly getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
+    };
+    /** Tuning knobs for the event-dispatcher loop (pollIntervalMs, pgClient
+     *  for LISTEN/NOTIFY). */
+    readonly eventDispatcher?: ServerOptions["eventDispatcher"];
+    /** Hook for app-wired co-running components that need the system-write
+     *  dispatcher (e.g. an analysis runner, an IMAP supervisor). Runs AFTER
+     *  `entrypoint.start()` — the hook itself is responsible for starting
+     *  its component and registering a shutdown hook on `lifecycle`. */
+    readonly wireComponents?: (deps: WorkerWireDeps) => Promise<void> | void;
+    /** Feature-toggle resolver (see RunProdAppOptions["effectiveFeatures"]). */
+    readonly effectiveFeatures?: EffectiveFeaturesResolver;
+    /** Override `process.env` for env-validation (see
+     *  RunProdAppOptions["envSource"]). */
+    readonly envSource?: Record<string, string | undefined>;
+    /** Env names to decrypt from their `_CIPHERTEXT` twin at boot, typically
+     *  `kmsSlotsOf(composedEnv.schema)`. The worker parses no env schema, so it
+     *  cannot derive them; without this it reads the env as is. */
+    readonly kmsSlots?: readonly string[];
+    readonly observability?: ObservabilityProvider;
+    readonly observabilityOptions?: ObservabilityOptions;
+};
+export type WorkerAppHandle = {
+    /** In KUMIKO_DRY_RUN_ENV=boot mode with an injected envSource (test
+     *  path), no boot ran — this slot is an undefined-cast, do not access. */
+    readonly entrypoint: WorkerEntrypoint;
+    readonly stop: () => Promise<void>;
+};
+export declare function runWorkerApp(options: RunWorkerAppOptions): Promise<WorkerAppHandle>;

package/dist/run-worker-app.js

@@ -0,0 +1,220 @@
+// runWorkerApp — production-grade bootstrap wrapper for a dedicated
+// Kumiko worker process. Symmetric to runProdApp, but without HTTP: no
+// Hono app, no auth routes, no SSE broker, no seeds. Shares the boot core
+// with runProdApp (env fail-fast, Temporal polyfill, composeFeatures/
+// registry, PII invariants, KMS health gate, connections, schema-drift
+// gate, boot-crypto, extraContext) — see fw#1725: before this function,
+// every app deploying a worker rebuilt this boot by hand (solon#42), and
+// every deviation was silent: without `ensureTemporalPolyfill`, every job
+// in the worker fails with "Temporal is not defined" in a retry loop,
+// with no boot-time signal that anything is wrong.
+//
+// App-author writes:
+//   await runWorkerApp({ features, wireComponents: async (deps) => {...} });
+//
+// Container/Coolify sets the same env vars as runProdApp:
+//   DATABASE_URL, REDIS_URL, JWT_SECRET — PORT is not needed.
+import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
+import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configureEntityFieldEncryption, createDbConnection, } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, findTierResolverUsage, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { createWorkerEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
+import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
+import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
+import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import { Redis } from "ioredis";
+import { resolveBootCrypto } from "./boot/boot-crypto.js";
+import { jobRunLoggerCallbacks } from "./boot/job-run-logger.js";
+import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
+import { composeFeatures } from "./compose-features.js";
+import { makeDispatchSystemWrite } from "./extra-routes-deps.js";
+import { assertPiiBootInvariants } from "./pii-boot-gate.js";
+import { requireEnv } from "./run-prod-app.js";
+import { addConfigAccessorFactory, buildBootExtraContext } from "./run-prod-app-boot-context.js";
+function makeBootModeHandle() {
+    return {
+        // @cast-boundary boot-mode: no entrypoint exists because no boot ran —
+        // callers on this path never read this slot.
+        entrypoint: undefined,
+        stop: async () => { },
+    };
+}
+export async function runWorkerApp(options) {
+    const rawEnvSource = options.envSource ?? process.env;
+    const envSource = options.kmsSlots
+        ? await resolvePlatformKeks(rawEnvSource, {
+            slots: options.kmsSlots,
+            logPrefix: "[runWorkerApp]",
+        })
+        : rawEnvSource;
+    // 1. Polyfill before anything else — exactly the bug fw#1725 reports:
+    //    without it, every job in the worker fails with "Temporal is not
+    //    defined" in a retry loop, with no boot-time signal.
+    const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
+    await ensureTemporalPolyfill();
+    // 2. Env vars: fail-fast, same requireEnv as runProdApp. JWT_SECRET is
+    //    validated by loadJwtSecretOrKeyring itself (throws when neither
+    //    JWT_SECRET nor JWT_SECRET_V<n> is set).
+    const databaseUrl = requireEnv("DATABASE_URL", envSource, "runWorkerApp");
+    const redisUrl = requireEnv("REDIS_URL", envSource, "runWorkerApp");
+    const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+    console.log("[runWorkerApp] booting Kumiko worker…");
+    // 3. Feature registry — identical to runProdApp, MUST be built with the
+    //    same `includeBundled` as the API process.
+    const features = composeFeatures(options.features, {
+        includeBundled: !!options.includeBundled,
+    });
+    validateBoot(features, { env: envSource, ...options.validateBootOptions });
+    warnIfNonUtcServerTimeZone();
+    assertPiiBootInvariants(features, {
+        kms: options.kms,
+        blindIndexKey: options.blindIndexKey,
+        allowPlaintextPii: options.allowPlaintextPii,
+        mode: "prod",
+    });
+    const registry = createRegistry(features);
+    // Boot-mode exit (parity with runProdApp's C1): validators ran and the
+    // registry is built, no DB/Redis client was constructed. Makes the boot
+    // testable without real Postgres/Redis infra.
+    if (envSource["KUMIKO_DRY_RUN_ENV"] === "boot") {
+        // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+        console.log(`[runWorkerApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`);
+        if (options.envSource === undefined) {
+            process.exit(0);
+        }
+        return makeBootModeHandle();
+    }
+    // 4. KMS health gate — runs BEFORE the connections, so an abort leaks
+    //    nothing (identical to runProdApp).
+    if (options.kms) {
+        const kmsHealth = await options.kms.health();
+        if (!kmsHealth.ok) {
+            throw new Error(`[runWorkerApp] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
+        }
+    }
+    const { db, close: closeDb } = createDbConnection(databaseUrl);
+    const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    let resolvedEffectiveFeatures = options.effectiveFeatures;
+    if (resolvedEffectiveFeatures === undefined) {
+        const tierResolverUsage = findTierResolverUsage(features);
+        if (tierResolverUsage) {
+            const plugin = tierResolverUsage.options;
+            resolvedEffectiveFeatures = await plugin.build({ db, registry });
+        }
+    }
+    // 5. Schema-drift gate — identical to runProdApp.
+    if (options.migrations !== false) {
+        const migrationsDir = options.migrations?.dir ?? "./kumiko/migrations";
+        // biome-ignore lint/suspicious/noConsole: boot-time progress hint
+        console.log(`[runWorkerApp] checking schema drift (${migrationsDir})…`);
+        try {
+            await assertKumikoSchemaCurrent(db, migrationsDir);
+        }
+        catch (err) {
+            if (err instanceof SchemaDriftError) {
+                // biome-ignore lint/suspicious/noConsole: terminal error message
+                console.error(`\n[runWorkerApp] BOOT ABORTED — ${err.message}\n`);
+            }
+            throw err;
+        }
+    }
+    // 6. Pipeline pieces — same defaults as runProdApp.
+    const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
+    const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
+    const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
+    // 7. Boot-crypto + extraContext — the core of fw#1725: KMS wiring,
+    //    blind-index, config-encryption must be wired in the worker exactly
+    //    like in the API, otherwise the worker writes rows the API can no
+    //    longer read (different cipher, missing blind index).
+    const deps = { db, redis, registry };
+    const resolvedExtraContext = typeof options.extraContext === "function"
+        ? options.extraContext(deps)
+        : (options.extraContext ?? {});
+    const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
+    configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+    configurePiiSubjectKms(options.kms);
+    configureBlindIndexKey(options.blindIndexKey);
+    const autoExtraContext = buildBootExtraContext({
+        db,
+        features,
+        envSource,
+        registry,
+        hasAuth: !!options.includeBundled,
+        crypto: bootCrypto,
+        ...(options.kms && { kms: options.kms }),
+    });
+    const extraContext = addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry);
+    const jobLogger = jobRunLoggerCallbacks(registry, db);
+    const entrypoint = createWorkerEntrypoint({
+        registry,
+        context: { db, redis, entityCache, registry, ...extraContext },
+        jwtSecret: jwtSecretOrKeyring,
+        dispatcherOptions: {
+            idempotency,
+            ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
+        },
+        eventDedup,
+        ...(options.observability && { observability: options.observability }),
+        ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
+        redisUrl,
+        ...jobLogger,
+        ...(options.jobs?.queueNamePrefix !== undefined && {
+            queueNamePrefix: options.jobs.queueNamePrefix,
+        }),
+        ...(options.jobs?.getActiveTenantIds !== undefined && {
+            getActiveTenantIds: options.jobs.getActiveTenantIds,
+        }),
+        ...(options.eventDispatcher && { eventDispatcher: options.eventDispatcher }),
+    });
+    const handle = {
+        entrypoint,
+        stop: async () => {
+            await entrypoint.stop();
+            await closeDb();
+            redis.disconnect();
+        },
+    };
+    await entrypoint.start();
+    startPiiEventBackfillOnBoot({
+        db,
+        registry,
+        lifecycle: entrypoint.lifecycle,
+        envSource,
+    });
+    if (options.wireComponents) {
+        await options.wireComponents({
+            db,
+            redis,
+            registry,
+            dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
+            lifecycle: entrypoint.lifecycle,
+        });
+    }
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        // skip: shutdown already in progress, avoid double-drain
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+        console.log(`[runWorkerApp] ${signal} received — draining…`);
+        try {
+            await handle.stop();
+            // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+            console.log("[runWorkerApp] graceful shutdown complete.");
+        }
+        catch (e) {
+            // biome-ignore lint/suspicious/noConsole: shutdown-time error, only path is stderr
+            console.error("[runWorkerApp] error during shutdown:", e);
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+    console.log("[runWorkerApp] ready — worker running.");
+    return handle;
+}

package/dist/security-headers.d.ts

@@ -0,0 +1,20 @@
+export type SecurityHeadersOption = false | {
+    /** `Strict-Transport-Security` value, or `false` to omit.
+     *  Default: `max-age=31536000; includeSubDomains`. */
+    readonly hsts?: string | false;
+    /** `X-Frame-Options` value, or `false` to omit. Default: `DENY`.
+     *  Apps that must be embeddable (iframe widgets) set `false` and
+     *  scope framing via a `csp` frame-ancestors directive instead. */
+    readonly frameOptions?: string | false;
+    /** `false` omits `X-Content-Type-Options: nosniff`. */
+    readonly contentTypeOptions?: false;
+    /** `Referrer-Policy` value, or `false` to omit.
+     *  Default: `strict-origin-when-cross-origin`. */
+    readonly referrerPolicy?: string | false;
+    /** `Content-Security-Policy` default for ALL responses. No built-in
+     *  default — a wrong CSP breaks app assets, so it stays opt-in.
+     *  A per-host CSP from `hostDispatch` wins over this value. */
+    readonly csp?: string;
+};
+export declare function resolveSecurityHeaders(option: SecurityHeadersOption | undefined): ReadonlyArray<readonly [string, string]>;
+export declare function withSecurityHeaders<TServeArg = string>(handler: (req: Request, serveArg?: TServeArg) => Response | Promise<Response>, option: SecurityHeadersOption | undefined): (req: Request, serveArg?: TServeArg) => Response | Promise<Response>;

package/dist/security-headers.js

@@ -0,0 +1,49 @@
+const DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
+const DEFAULT_FRAME_OPTIONS = "DENY";
+const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
+export function resolveSecurityHeaders(option) {
+    if (option === false)
+        return [];
+    const opt = option ?? {};
+    const headers = [];
+    const hsts = opt.hsts ?? DEFAULT_HSTS;
+    if (hsts !== false)
+        headers.push(["strict-transport-security", hsts]);
+    const frameOptions = opt.frameOptions ?? DEFAULT_FRAME_OPTIONS;
+    if (frameOptions !== false)
+        headers.push(["x-frame-options", frameOptions]);
+    if (opt.contentTypeOptions !== false)
+        headers.push(["x-content-type-options", "nosniff"]);
+    const referrerPolicy = opt.referrerPolicy ?? DEFAULT_REFERRER_POLICY;
+    if (referrerPolicy !== false)
+        headers.push(["referrer-policy", referrerPolicy]);
+    if (opt.csp)
+        headers.push(["content-security-policy", opt.csp]);
+    return headers;
+}
+// Sets each header only when absent so per-response values (e.g. the
+// per-host CSP from hostDispatch) always win over the runtime default.
+export function withSecurityHeaders(handler, option) {
+    const defaults = resolveSecurityHeaders(option);
+    if (defaults.length === 0)
+        return handler;
+    return async (req, serveArg) => {
+        const res = await handler(req, serveArg);
+        try {
+            for (const [name, value] of defaults) {
+                if (!res.headers.has(name))
+                    res.headers.set(name, value);
+            }
+            return res;
+        }
+        catch {
+            // Immutable-headers Response (e.g. proxied fetch) — re-wrap.
+            const headers = new Headers(res.headers);
+            for (const [name, value] of defaults) {
+                if (!headers.has(name))
+                    headers.set(name, value);
+            }
+            return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+        }
+    };
+}

package/dist/session-boot-gate.d.ts

@@ -0,0 +1,11 @@
+export type SessionBootGateOptions = {
+    readonly hasAuth: boolean;
+    readonly sessionStoreProviderMounted: boolean;
+    /** prod fails hard on a missing sessionStore provider (stateless JWTs would
+     *  silently skip server-side revocation and any session-list UI stays
+     *  empty); dev only warns — a forgotten sessions mount in a local sample
+     *  app shouldn't crash the dev-server boot, but it must not stay silent
+     *  either (#2027 — dev previously had no gate here at all). */
+    readonly mode: "prod" | "dev";
+};
+export declare function assertSessionBootInvariants(opts: SessionBootGateOptions): void;

package/dist/session-boot-gate.js

@@ -0,0 +1,22 @@
+// Catch a forgotten sessions mount at boot instead of silently degrading
+// into stateless JWTs (#1372). Mount createSessionsFeature() for revocable
+// sessions; there is no auth.sessions opt-out anymore.
+export function assertSessionBootInvariants(opts) {
+    // skip: no auth mounted — nothing to gate.
+    if (!opts.hasAuth)
+        return;
+    // skip: sessionStore provider is wired (sessions feature).
+    if (opts.sessionStoreProviderMounted)
+        return;
+    const tag = opts.mode === "prod" ? "runProdApp" : "runDevApp";
+    const message = "auth is mounted but no sessionStore provider is registered. JWTs would be stateless " +
+        "(no server-side revocation) and any session-list screen stays empty. Mount " +
+        "createSessionsFeature() (@cosmicdrift/kumiko-bundled-features/sessions) alongside auth-foundation.";
+    if (opts.mode === "dev") {
+        // biome-ignore lint/suspicious/noConsole: boot-time ops warning, no logger configured this early
+        console.warn(`[${tag}] ${message}`);
+        // skip: dev mode, warning already logged above — never abort dev boot.
+        return;
+    }
+    throw new Error(`[${tag}] BOOT ABORTED — ${message}`);
+}

package/dist/session-wiring.d.ts

@@ -0,0 +1,11 @@
+/**
+ * runProdApp session-wiring decision (extracted pure so it is testable without a
+ * full prod boot).
+ *
+ * Secure-by-default (#1372): mounting a sessionStore provider (sessions feature)
+ * turns server-side session revocation ON automatically. There is no
+ * `auth.sessions` opt-in/opt-out — mount sessions for revocable JWTs, omit it
+ * for intentional stateless JWTs (boot-gate warns / aborts unless acknowledged
+ * via a future flag if needed; today auth without sessions fails the gate).
+ */
+export declare function shouldWireProdSessions(hasAuth: boolean, sessionStoreProviderMounted: boolean): boolean;

package/{src/session-wiring.ts → dist/session-wiring.js}

@@ -8,10 +8,6 @@
  * for intentional stateless JWTs (boot-gate warns / aborts unless acknowledged
  * via a future flag if needed; today auth without sessions fails the gate).
  */
-
-export function shouldWireProdSessions(
-  hasAuth: boolean,
-  sessionStoreProviderMounted: boolean,
-): boolean {
-  return hasAuth && sessionStoreProviderMounted;
+export function shouldWireProdSessions(hasAuth, sessionStoreProviderMounted) {
+    return hasAuth && sessionStoreProviderMounted;
 }

package/dist/try-hono-first.d.ts

@@ -0,0 +1,24 @@
+export type HonoLikeApp = {
+    readonly fetch: (req: Request, socketAddress?: string) => Response | Promise<Response>;
+};
+export type HonoFirstResult = {
+    /** True when Hono has a matching route (no router-miss).
+     *  Caller returns the response directly.
+     *  False when no route matches (router-miss, detected via 404 +
+     *  NO_ROUTE_MATCH_HEADER_NAME). Caller does the SPA/static fallback;
+     *  the response still carries the 404 as a final fallback in case the
+     *  SPA path doesn't deliver anything either. */
+    readonly matched: boolean;
+    readonly response: Response;
+};
+export declare function stripNoRouteMatchHeader(response: Response): Response;
+/**
+ * Hono-first try: app.fetch FIRST. If matched (no router-miss), the caller
+ * returns the response directly. If not matched, the caller falls back to
+ * its own SPA/static fallback — the response (404) stays available as a
+ * last-resort safety net.
+ *
+ * req.clone() because downstream needs to read the request body again
+ * (future-proofing for POST/PUT/PATCH — only GET routes today).
+ */
+export declare function tryHonoFirst(app: HonoLikeApp, req: Request, socketAddress?: string): Promise<HonoFirstResult>;

package/{src/try-hono-first.ts → dist/try-hono-first.js}

@@ -27,41 +27,17 @@
 //
 // req.clone() because downstream needs to read the request body again
 // (future-proofing for POST/PUT/PATCH — only GET routes today).
-
 import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
-
-export type HonoLikeApp = {
-  // Hono.app.fetch is `(req, env?) => Response | Promise<Response>` (sync if
-  // all handlers are sync, otherwise a Promise). createApiEntrypoint's
-  // apiHandler matches the same shape. The union accepts both — we await
-  // below, which works for either case. `socketAddress` rides in as `env`
-  // so requestIdMiddleware/rate-limit can read it via `c.env` without Hono
-  // ever seeing a raw Bun `Server`.
-  readonly fetch: (req: Request, socketAddress?: string) => Response | Promise<Response>;
-};
-
-export type HonoFirstResult = {
-  /** True when Hono has a matching route (no router-miss).
-   *  Caller returns the response directly.
-   *  False when no route matches (router-miss, detected via 404 +
-   *  NO_ROUTE_MATCH_HEADER_NAME). Caller does the SPA/static fallback;
-   *  the response still carries the 404 as a final fallback in case the
-   *  SPA path doesn't deliver anything either. */
-  readonly matched: boolean;
-  readonly response: Response;
-};
-
 // Removes the internal router-miss marker from a response before it leaves
 // the process. Needed at EVERY site that potentially passes app.fetch()'s
 // response through to a real client — including the passthrough paths that
 // never call tryHonoFirst at all (e.g. /api/* in runProdApp, dotted-paths/
 // non-GET in the dev server). No no-op check needed: Headers.delete() on a
 // missing key is harmless.
-export function stripNoRouteMatchHeader(response: Response): Response {
-  response.headers.delete(NO_ROUTE_MATCH_HEADER_NAME);
-  return response;
+export function stripNoRouteMatchHeader(response) {
+    response.headers.delete(NO_ROUTE_MATCH_HEADER_NAME);
+    return response;
 }
-
 /**
  * Hono-first try: app.fetch FIRST. If matched (no router-miss), the caller
  * returns the response directly. If not matched, the caller falls back to
@@ -71,13 +47,9 @@ export function stripNoRouteMatchHeader(response: Response): Response {
  * req.clone() because downstream needs to read the request body again
  * (future-proofing for POST/PUT/PATCH — only GET routes today).
  */
-export async function tryHonoFirst(
-  app: HonoLikeApp,
-  req: Request,
-  socketAddress?: string,
-): Promise<HonoFirstResult> {
-  const response = await app.fetch(req.clone(), socketAddress);
-  const isRouterMiss = response.status === 404 && response.headers.has(NO_ROUTE_MATCH_HEADER_NAME);
-  stripNoRouteMatchHeader(response);
-  return { matched: !isRouterMiss, response };
+export async function tryHonoFirst(app, req, socketAddress) {
+    const response = await app.fetch(req.clone(), socketAddress);
+    const isRouterMiss = response.status === 404 && response.headers.has(NO_ROUTE_MATCH_HEADER_NAME);
+    stripNoRouteMatchHeader(response);
+    return { matched: !isRouterMiss, response };
 }