@zerotal/core 1.6.3 → 1.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.6.3",
+  "version": "1.7.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -11,6 +11,7 @@
     ".": "./src/index.ts",
     "./routes": "./src/router/routes.ts",
     "./contracts": "./src/contracts/index.ts",
+    "./errors": "./src/errors/index.ts",
     "./lock": "./src/lock/index.ts",
     "./logger": "./src/logger/index.ts",
     "./commands": "./src/command/builtin/index.ts",
@@ -34,6 +35,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",

package/src/application/Application.ts

@@ -14,6 +14,7 @@ import type { HttpContext } from "../pipeline/HttpContext.ts";
 import { Pipeline } from "../pipeline/Pipeline.ts";
 import { ExceptionHandler } from "./ExceptionHandler.ts";
 import { Router, RouterState } from "../router/Router.ts";
+import { defineRouteMethods, defineRoutes } from "../router/routes.ts";
 import type { StaticOptions } from "../router/Router.ts";
 import { Health, resolveHealthConfig, checkHealthAccess } from "../health/Health.ts";
 import type { HealthConfigShape } from "../health/Health.ts";
@@ -27,7 +28,10 @@ import {
 import { builtinConcerns } from "../conventions/builtinConcerns.ts";
 import { ConfigManager } from "../config/ConfigManager.ts";
 import { DEFAULT_MAX_REQUEST_BODY_SIZE } from "../config/AppConfig.ts";
-import { SecureHeadersMiddleware } from "../middleware/SecureHeadersMiddleware.ts";
+import {
+  SecureHeadersMiddleware,
+  staticSecurityHeaders,
+} from "../middleware/SecureHeadersMiddleware.ts";
 import { isAllowedOrigin, allowedOriginsFrom } from "../http/originGuard.ts";
 import { rescueSync } from "../helpers/index.ts";
 import { configureAssets, setAssetVersion, assetVersion } from "../assets/assets.ts";
@@ -39,7 +43,7 @@ import { NotFoundError } from "../errors/HttpError.ts";
 import type { ContainerBindings } from "../container/types.ts";
 import { dispatchRequest } from "../router/RouteHandler.ts";
 import type { ProviderHooks } from "../router/RouteHandler.ts";
-import { isProdLike, deployEnv } from "../support/env.ts";
+import { isProdLike, deployEnv, runtimeMode } from "../support/env.ts";
 import { appKeyStrengthWarning } from "../support/appKey.ts";
 import { runBootDoctor } from "./BootDoctor.ts";
 import { runConfigValidators } from "../config/validation.ts";
@@ -237,10 +241,13 @@ export async function _lazyStaticResponse(
     const relative = pathname.slice(trimmedPrefix.length).replace(/^\//, "");
     const file = Bun.file(`${rootDir}/${relative}`);
     if (await file.exists()) {
-      return new Response(
-        file as unknown as BodyInit,
-        options?.headers ? { headers: options.headers } : undefined,
-      );
+      // The same headers Bun's native static routes carry (see Router.compile).
+      // This path returns before the pipeline runs, so without it a file served
+      // lazily — every file under the dev worker — would be the one response in
+      // the app with no security headers on it.
+      return new Response(file as unknown as BodyInit, {
+        headers: { ...staticSecurityHeaders(), ...options?.headers },
+      });
     }
   }
   return undefined;
@@ -248,6 +255,8 @@ export async function _lazyStaticResponse(
 
 /** Minimal WebSocket handler shape accepted by Bun.serve(). */
 export interface WebSocketHandlers {
+  /** Seconds a connection may go quiet before Bun closes it. Bun's default is 10. */
+  idleTimeout?: number;
   open?(ws: unknown): void;
   message(ws: unknown, message: string | Uint8Array): void;
   close?(ws: unknown, code: number, reason: string): void;
@@ -260,6 +269,39 @@ export interface WebSocketHandlers {
  */
 export type AppScopeInstaller = () => () => void;
 
+/**
+ * What one provider cost to boot, and what it contributed.
+ *
+ * @see Application.providerReport
+ */
+export interface ProviderReport {
+  /** Provider class name. The array is in boot order. */
+  name: string;
+  /**
+   * Wall-clock milliseconds across all three lifecycle hooks.
+   *
+   * `onBooted` runs concurrently across providers, so these do not sum to the
+   * application's boot time — they overlap, and the report reports that rather
+   * than serialising the boot to produce a tidier number.
+   */
+  durationMs: number;
+  /** Container tokens this provider bound, as names. */
+  bindings: string[];
+}
+
+/**
+ * A container token as a readable name.
+ *
+ * Tokens are class constructors or plain strings; the map keys are neither
+ * sorted nor serialisable as they stand, and a reader wants `CacheManager`, not
+ * `[class CacheManager]`.
+ */
+function _tokenName(token: unknown): string {
+  if (typeof token === "string") return token;
+  if (typeof token === "function") return token.name || "‹anonymous›";
+  return String(token);
+}
+
 const _appScopeInstallers: AppScopeInstaller[] = [];
 
 /**
@@ -318,6 +360,8 @@ export class Application {
   _env: Environment = "web";
   private _booted = false;
   private _bootDurationMs: number | undefined = undefined;
+  /** Per-provider boot cost and container provenance; see {@link providerReport}. */
+  private _providerReport: ProviderReport[] = [];
   private _static?: ReturnType<typeof Bun.serve>;
   private _configMap: Record<string, Record<string, unknown>> | undefined = undefined;
   /** Tracks where config came from, to reject conflicting overrides via useConfig(). */
@@ -460,8 +504,12 @@ export class Application {
       );
     }
 
-    // eslint-disable-next-line no-restricted-syntax -- runtime mode is exactly what Application.create() wants; _normaliseEnv maps deployment names onto it
-    const rawEnv = options.env ?? Bun.env["APP_ENV"] ?? "web";
+    // The runtime mode, which is what provider filtering is keyed on. Reading
+    // `APP_ENV` here used to be right only because `setAppEnv()` had overwritten
+    // it with the mode; now the mode has its own variable and this asks for it
+    // directly. `_normaliseEnv` still maps a deployment name onto a mode, for an
+    // explicit `options.env`.
+    const rawEnv = options.env ?? runtimeMode("web");
     const resolvedEnv: Environment = _normaliseEnv(rawEnv);
 
     const app = new Application();
@@ -609,6 +657,60 @@ export class Application {
     return this._bootDurationMs;
   }
 
+  /**
+   * What each provider cost to boot, and what it put in the container.
+   *
+   * `bootDurationMs` says the app took 240ms and nothing said which provider
+   * spent it; the container lists a hundred bindings and nothing said who bound
+   * them. Both are answered here, in boot order — which is itself the answer to
+   * a third question, since provider order decides who wins a contested binding.
+   *
+   * Empty until `boot()` runs. Populated in every environment: it costs one
+   * `performance.now()` pair and one registry diff per provider at boot, and a
+   * report that only exists in development is one you cannot ask for when a
+   * staging boot is the slow one.
+   *
+   * @category Lifecycle
+   */
+  get providerReport(): readonly ProviderReport[] {
+    return this._providerReport;
+  }
+
+  /**
+   * Time one provider lifecycle hook and attribute anything it bound.
+   *
+   * Accumulates across the three phases, so a provider that binds in
+   * `onRegister` and spends its time in `onBooting` reads as one row.
+   */
+  private _recordProviderWork<T>(provider: ServiceProvider, work: () => T): T {
+    const name = provider.constructor.name;
+    let row = this._providerReport.find((entry) => entry.name === name);
+    if (!row) {
+      row = { name, durationMs: 0, bindings: [] };
+      this._providerReport.push(row);
+    }
+    const before = new Set(this.container.registry.keys());
+    const started = performance.now();
+    const finish = (): T => {
+      row!.durationMs = Math.round((row!.durationMs + performance.now() - started) * 100) / 100;
+      for (const token of this.container.registry.keys()) {
+        if (!before.has(token)) row!.bindings.push(_tokenName(token));
+      }
+      return undefined as T;
+    };
+    const result = work();
+    // An async hook is only finished when its promise is — timing it
+    // synchronously would report every `await` in it as free.
+    if (result instanceof Promise) {
+      return result.then((value: unknown) => {
+        finish();
+        return value;
+      }) as T;
+    }
+    finish();
+    return result;
+  }
+
   /**
    * The runtime environment this application is running in.
    *
@@ -973,6 +1075,17 @@ export class Application {
     };
 
     return {
+      // Bun closes an idle WebSocket after 10 seconds by default, and the client
+      // pings every 30 — so a connection that is merely *quiet* was being cut
+      // before it ever had reason to speak, taking its channel subscriptions
+      // with it. Nothing surfaced: the page stayed rendered, the client kept its
+      // channel objects, and broadcasts simply stopped arriving for anyone who
+      // had been reading for more than ten seconds.
+      //
+      // 120s leaves room for four missed pings before a genuinely dead socket is
+      // reaped, which is the direction to err: a stale connection costs memory,
+      // a reaped live one costs the feature.
+      idleTimeout: 120,
       open: (ws: unknown) => {
         if ((ws as AnyWS).data._dev) {
           DevWsServer.open(ws as AnyWS);
@@ -1056,7 +1169,15 @@ export class Application {
     for (const callback of this._bindCallbacks) callback(this.container);
 
     // Phase 1 — synchronous, binds into container.
-    for (const provider of this._activeProviders) provider.onRegister();
+    //
+    // Timed, and the container is diffed around each provider, so the inspector
+    // can answer "who bound `cache`, and what did booting it cost". Provenance
+    // by diff rather than by having the container record a registrar: it keeps
+    // the cost at boot instead of on every binding, and adds no mutable state to
+    // the container for a question only a debugging tool asks.
+    for (const provider of this._activeProviders) {
+      this._recordProviderWork(provider, () => provider.onRegister());
+    }
 
     // Config validation — providers have registered their namespace validators
     // in onRegister; run them before anything boots. In a production-like
@@ -1069,10 +1190,20 @@ export class Application {
     }
 
     // Phase 2 — sequential in registration order.
-    for (const provider of this._activeProviders) await provider.onBooting();
+    for (const provider of this._activeProviders) {
+      await this._recordProviderWork(provider, () => provider.onBooting());
+    }
 
     // Phase 3 — async, all providers have finished booting.
-    await Promise.all(this._activeProviders.map((provider) => provider.onBooted()));
+    //
+    // These run concurrently, so the recorded durations overlap and do not sum
+    // to the phase. That is the truth about this phase and the report says so
+    // rather than serialising the boot to make a tidier number.
+    await Promise.all(
+      this._activeProviders.map((provider) =>
+        this._recordProviderWork(provider, () => provider.onBooted()),
+      ),
+    );
 
     // Ensure config and events are resolved so makeSync() works below.
     await this.container.make("config");
@@ -1100,6 +1231,21 @@ export class Application {
       await this._loadFileRoutes();
     }
 
+    // Install the route table for `zerotal/routes`, now that every route is
+    // registered.
+    //
+    // That module is the standalone URL builder a browser bundle imports, so it
+    // cannot reach for `Router` itself — importing the router would drag the
+    // server into every client bundle. The dependency therefore points this way:
+    // the server, which already has both, pushes the table in.
+    //
+    // Without this, `route()` threw on the server for any app that renders its
+    // own markup — a `view` build produces every href and form action there —
+    // and the fix was a `defineRoutes()` call each app had to know to write.
+    // A browser entry still calls it; that is a different process with no router
+    // to read. See T24.
+    this._installRouteTable();
+
     // A routes/ directory nobody routed is a silent 404 for every path in it — the file
     // imports cleanly and registers nothing, which looks identical to a typo'd URL.
     this._warnUnroutedRoutesDir(process.cwd());
@@ -1153,6 +1299,23 @@ export class Application {
     if (warning) frameworkLog("app").warn(warning);
   }
 
+  /**
+   * Hand the registered routes to the standalone `route()` builder.
+   *
+   * Name → pattern for the URLs, and name → verb for `action()`. `RouteDefinition`
+   * carries its own `name` beside `method`, so the pair comes from one record —
+   * a path join would be wrong, since `GET /login` and `POST /login` share a path.
+   */
+  private _installRouteTable(): void {
+    const methods = new Map<string, string>();
+    for (const definition of Router.routes.values()) {
+      if (definition.name) methods.set(definition.name, definition.method);
+    }
+
+    defineRoutes(Router.namedRoutes);
+    defineRouteMethods(Object.fromEntries(methods));
+  }
+
   private async _loadFileRoutes(): Promise<void> {
     for (const { dir, prefix, middleware } of this._fileRouteGroups) {
       await Router.groupAsync({ prefix, middleware }, () => scanFileRoutes(dir).then(() => {}));

package/src/command/builtin/DoctorCommand.ts

@@ -2,15 +2,18 @@
  * `bun zt doctor` — run every static sanity check against this app and print
  * the findings with their fixes. Exits 1 when anything is broken outright.
  *
- * With `--url`, it also probes the deployed app's WebSocket transport from the outside,
- * through whatever proxy is in front of it. That is the only way to see the failures that
- * leave the app healthy from the inside and inert in the browser.
+ * With `--url`, it also reads the deployed app from the outside, through whatever proxy is
+ * in front of it — the only way to see two classes of failure. The WebSocket transport,
+ * which a proxy can gate or drop while leaving the app healthy from the inside and inert in
+ * the browser. And security headers sent twice, because a header the app sets and the proxy
+ * also sets is invisible from in here: the app's own view is the value it wrote.
  */
 import { Command } from "../Command.ts";
 import type { Application } from "../../application/Application.ts";
 import { runDoctor } from "../../doctor/AppDoctor.ts";
 import type { DoctorReportEntry } from "../../doctor/AppDoctor.ts";
 import { probeTransport } from "../../doctor/TransportProbe.ts";
+import { probeHeaders } from "../../doctor/HeaderProbe.ts";
 
 export class DoctorCommand extends Command {
   static override commandName = "doctor";
@@ -21,7 +24,8 @@ export class DoctorCommand extends Command {
       name: "url",
       type: "string" as const,
       description:
-        "Also probe the deployed app's WebSocket transport at this public URL, as a browser would",
+        "Also read the deployed app at this public URL: handshake its WebSocket transport " +
+        "as a browser would, and report security headers the response carries twice",
     },
   ];
 
@@ -34,9 +38,13 @@ export class DoctorCommand extends Command {
     for (const entry of report) this._print(entry);
 
     const probeFailures = await this._probeTransport(app);
+    const headerFindings = await this._probeHeaders();
 
-    const warns = report.filter((e) => e.result.status === "warn").length;
-    const fails = report.filter((e) => e.result.status === "fail").length + probeFailures;
+    const warns = report.filter((e) => e.result.status === "warn").length + headerFindings.warnings;
+    const fails =
+      report.filter((e) => e.result.status === "fail").length +
+      probeFailures +
+      headerFindings.failures;
     this.newLine();
     // Throw rather than `process.exit(1)` — same exit code from the CLI (the runner
     // converts it), but composable. Exiting here killed any caller running the
@@ -86,6 +94,45 @@ export class DoctorCommand extends Command {
     return failures;
   }
 
+  /**
+   * Report security headers the deployed response carries more than once.
+   *
+   * Only reachable from outside: the app's own view of a header is the value it
+   * wrote, which is correct as far as it goes — the proxy's copy is invisible
+   * from in here. Conflicting values count as failures because a control that
+   * different browsers apply differently is not a control; identical duplicates
+   * are a warning, because they are a conflict waiting for someone to edit one
+   * side.
+   */
+  private async _probeHeaders(): Promise<{ failures: number; warnings: number }> {
+    const url = this.flags["url"] as string | undefined;
+    if (!url) return { failures: 0, warnings: 0 };
+
+    const findings = await probeHeaders(url);
+    this.newLine();
+    this.section("Response headers");
+
+    if (findings.length === 0) {
+      this.line("✓ No duplicated security headers.");
+      return { failures: 0, warnings: 0 };
+    }
+
+    let failures = 0;
+    let warnings = 0;
+    for (const finding of findings) {
+      const line = `${finding.conflicting ? "✗" : "!"} ${finding.header} — ${finding.message}`;
+      if (finding.conflicting) {
+        this.error(line);
+        failures++;
+      } else {
+        this.warn(line);
+        warnings++;
+      }
+      if (finding.fix) this.line(`    fix: ${finding.fix}`);
+    }
+    return { failures, warnings };
+  }
+
   private _print({ check, result }: DoctorReportEntry): void {
     const mark = result.status === "ok" ? "✓" : result.status === "warn" ? "!" : "✗";
     const line = `${mark} ${check.label} — ${result.message}`;

package/src/command/builtin/RouteTypesCommand.ts

@@ -34,6 +34,7 @@ export class RouteTypesCommand extends Command {
 
   async run(): Promise<void> {
     const check = this.flags["check"] as boolean;
+
     const result = await writeRouteTypes(Router.namedRoutes, { check });
 
     if (check) {