@timber-js/app 0.2.0-alpha.197 → 0.2.0-alpha.199

package/src/server/port-resolution.ts

@@ -1,34 +1,8 @@
-/**
- * Port resolution for the dev server, Vite preview, and the Node
- * production preview server.
- *
- * Behavior (see TIM-842):
- *
- *   1. Default port is **3000** for both dev and prod.
- *   2. If the user did NOT set an explicit port, auto-bump from 3000
- *      until a free port is found (3000 → 3001 → 3002 → …).
- *   3. If the user DID set an explicit port (via `--port`, `PORT` env
- *      var, or `vite.config.ts` `server.port`), use it as-is and let
- *      the bind fail loudly on conflict (`strictPort: true`).
- *
- * The port-bump probe is performed by binding the **actual** server
- * (e.g. the dev holding server) — not a throwaway probe — so there is
- * no time-of-check / time-of-use race between probing and listening.
- *
- * Design doc: 21-dev-server.md §"Default Port and Auto-Bump".
- */
+/** Port input precedence for dev and preview. Vite owns binding and restart reuse. */
 
 /** Default port used by `timber dev` and `timber preview`. */
 export const DEFAULT_PORT = 3000;
 
-/**
- * A function that attempts to bind to a given port.
- *
- * Resolves with the bound port on success. Rejects with an error
- * (typically with `code === 'EADDRINUSE'`) on failure.
- */
-export type ListenFn = (port: number) => Promise<number>;
-
 // ── Pure resolution ────────────────────────────────────────────────────
 
 export interface ResolvePortInput {
@@ -49,8 +23,7 @@ export interface ResolvedPortInput {
   port: number;
   /**
    * `true` if the port came from an explicit user override (config or
-   * env). When `true`, callers must NOT auto-bump and must surface
-   * `EADDRINUSE` to the user.
+   * env). Preview uses this to default to strict port binding.
    */
   explicit: boolean;
 }
@@ -58,7 +31,7 @@ export interface ResolvedPortInput {
 /**
  * Pure: compute the starting port from config / env / defaults.
  *
- * Performs no I/O — pair with {@link bindWithBump} to actually listen.
+ * Performs no I/O.
  */
 export function resolveStartPort(input: ResolvePortInput): ResolvedPortInput {
   const defaultPort = input.defaultPort ?? DEFAULT_PORT;
@@ -78,138 +51,3 @@ export function resolveStartPort(input: ResolvePortInput): ResolvedPortInput {
 
   return { port: defaultPort, explicit: false };
 }
-
-// ── Bind with auto-bump ────────────────────────────────────────────────
-
-export interface BindWithBumpOptions {
-  /** First port to attempt. */
-  startPort: number;
-  /**
-   * If `true`, increment the port and retry on `EADDRINUSE`. If
-   * `false`, attempt once and let the error propagate.
-   */
-  autoBump: boolean;
-  /** Maximum number of port attempts when `autoBump` is `true`. */
-  maxAttempts?: number;
-}
-
-export interface BindWithBumpResult {
-  /** Port that was actually bound. */
-  port: number;
-  /** `true` if the bound port differs from `startPort`. */
-  bumped: boolean;
-}
-
-/**
- * Bind a server starting at `startPort`, optionally bumping the port
- * on `EADDRINUSE` until a free one is found.
- *
- * Use this with the actual server you intend to keep listening (e.g.
- * the dev holding server). Pairing the probe with the real listen
- * eliminates the TOCTOU race that a throwaway probe would introduce.
- */
-export async function bindWithBump(
-  listen: ListenFn,
-  options: BindWithBumpOptions
-): Promise<BindWithBumpResult> {
-  const maxAttempts = options.autoBump ? (options.maxAttempts ?? 100) : 1;
-  let lastErr: unknown = null;
-
-  for (let i = 0; i < maxAttempts; i++) {
-    const port = options.startPort + i;
-    try {
-      const bound = await listen(port);
-      return { port: bound, bumped: i > 0 };
-    } catch (err) {
-      lastErr = err;
-      // Only retry on EADDRINUSE — other errors (EACCES, etc.) are
-      // permanent and must surface immediately.
-      if (!isAddrInUse(err)) throw err;
-    }
-  }
-
-  throw lastErr ?? new Error(`Could not bind to a free port starting at ${options.startPort}`);
-}
-
-/** True if `err` is a Node `EADDRINUSE` error from `server.listen()`. */
-export function isAddrInUse(err: unknown): boolean {
-  return (
-    typeof err === 'object' && err !== null && (err as { code?: string }).code === 'EADDRINUSE'
-  );
-}
-
-// ── High-level helper used by the rootSync plugin ────────────────────
-
-export interface StartDevServerPortInput {
-  /** Resolved port from `userConfig.server?.port` (or `--port`), or undefined. */
-  configPort: number | undefined;
-  /** Raw `process.env.PORT` value. */
-  envPort: string | undefined;
-  /** ListenFn for the holding server (or any pre-bind probe target). */
-  listen: ListenFn;
-  /** Logger — defaults to `console`. Injected for tests. */
-  log?: (msg: string) => void;
-  warn?: (msg: string) => void;
-}
-
-export interface StartDevServerPortResult {
-  /** Port chosen for both the holding server and Vite's dev server. */
-  port: number;
-  /** True if the user explicitly set the port (=> Vite must `strictPort: true`). */
-  explicit: boolean;
-  /** True if the holding server actually bound the port. */
-  bound: boolean;
-}
-
-/**
- * Run the full dev-server port resolution + holding-server bind sequence.
- *
- * Resolves the port from config / env / default, attempts to bind the
- * holding server (auto-bumping when the port came from the default),
- * and logs the chosen URL. On a clean failure for an explicit port, it
- * warns and falls back to the requested port so Vite can surface the
- * conflict via `strictPort: true`.
- *
- * Extracted from `index.ts` so the rootSync `config()` hook stays
- * focused on plugin assembly.
- */
-export async function startDevServerPort(
-  input: StartDevServerPortInput
-): Promise<StartDevServerPortResult> {
-  const log = input.log ?? ((msg: string) => console.log(msg));
-  const warn = input.warn ?? ((msg: string) => console.warn(msg));
-
-  const start = resolveStartPort({
-    configPort: input.configPort,
-    envPort: input.envPort,
-    defaultPort: DEFAULT_PORT,
-  });
-
-  try {
-    const result = await bindWithBump(input.listen, {
-      startPort: start.port,
-      autoBump: !start.explicit,
-    });
-    if (result.bumped) {
-      log(`\n  \x1b[33m[timber]\x1b[0m Port ${start.port} in use, using ${result.port}\n`);
-    }
-    log(
-      `\n  \x1b[2m\u{1FAB5} timber.js dev server starting at\x1b[0m ` +
-        `\x1b[36mhttp://localhost:${result.port}\x1b[0m\n`
-    );
-    return { port: result.port, explicit: start.explicit, bound: true };
-  } catch (err) {
-    // Holding server failed to bind. For explicit ports we leave the
-    // bound state false and let Vite fail loudly via strictPort: true.
-    // For implicit ports this is essentially unreachable (auto-bump
-    // tries 100 ports), but if we hit it we still want Vite to surface
-    // the error.
-    if (start.explicit && isAddrInUse(err)) {
-      warn(
-        `\n  \x1b[33m[timber]\x1b[0m Port ${start.port} is already in use. ` +
-          `Set PORT (or remove the override) to pick another port.\n`
-      );
-    }
-    return { port: start.port, explicit: start.explicit, bound: false };
-  }
-}

package/src/server/prebuilt-builder.ts

@@ -46,10 +46,10 @@ import { createElement } from 'react';
 
 import { requestContextAls } from './als-registry.ts';
 import type { CoercedParams } from '../shared/param-value.ts';
-import { ParamCoercionError } from './route-element-builder.ts';
+import { ParamCoercionError } from './param-coercion.ts';
 import { SlotOutlet } from '../client/slot-outlet.tsx';
 import { coerceSegmentParams } from './param-coercion.ts';
-import { DenySignal, RedirectSignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './primitives.ts';
 import {
   beginCapture,
   endCapture,
@@ -395,8 +395,8 @@ async function renderEntry(
 
 /** Human-readable classification for a failed entry. */
 function describeFailure(error: unknown): string {
-  if (error instanceof DenySignal) return `component called deny(${error.status})`;
-  if (error instanceof RedirectSignal) return `component called redirect("${error.location}")`;
+  if (isDenySignal(error)) return `component called deny(${error.status})`;
+  if (isRedirectSignal(error)) return `component called redirect("${error.location}")`;
   if (error instanceof Error) return error.message;
   return String(error);
 }

package/src/server/primitives.ts

@@ -103,31 +103,85 @@ function warnIfNotSerializable(data: unknown, callerName: string): void {
   }
 }
 
+// ─── Signal branding ────────────────────────────────────────────────────────
+//
+// Catch sites must NOT use `instanceof` on these classes. In dev, an HMR
+// program reload clears the RSC module cache; a request that is mid-render
+// still holds the catch sites from the old evaluation of this module while
+// user code loaded after the reload throws from the new one. The two
+// evaluations are distinct classes, so `instanceof` fails and a correct
+// deny() falls through every catch site as an unhandled 500 (TIM-1499).
+//
+// Each class stamps a `Symbol.for` brand on its instances in the constructor.
+// `Symbol.for` keys live in the realm-wide symbol registry, so every
+// evaluation of this module — and every module graph in the same process —
+// agrees on the key. The `is*` predicates below check the brand and are the
+// only supported way to detect a signal. The classes themselves are NOT
+// anchored on globalThis: a re-evaluated module must hand out its own
+// (possibly updated) class, not a stale one.
+//
+// See design/18-build-system.md §"Dev Mode: Signal Identity Across Program Reloads".
+
+const DENY_BRAND: unique symbol = Symbol.for('timber:signal.deny');
+const REDIRECT_BRAND: unique symbol = Symbol.for('timber:signal.redirect');
+const RENDER_ERROR_BRAND: unique symbol = Symbol.for('timber:signal.render-error');
+const SSR_STREAM_ERROR_BRAND: unique symbol = Symbol.for('timber:signal.ssr-stream-error');
+
+function hasBrand(value: unknown, brand: symbol): boolean {
+  return typeof value === 'object' && value !== null && brand in value;
+}
+
+/** True for any `DenySignal`, regardless of which module evaluation created it. */
+export function isDenySignal(error: unknown): error is DenySignal {
+  return hasBrand(error, DENY_BRAND);
+}
+
+/** True for any `RedirectSignal`, regardless of which module evaluation created it. */
+export function isRedirectSignal(error: unknown): error is RedirectSignal {
+  return hasBrand(error, REDIRECT_BRAND);
+}
+
+/** True for any `RenderError`, regardless of which module evaluation created it. */
+export function isRenderError(error: unknown): error is RenderError {
+  return hasBrand(error, RENDER_ERROR_BRAND);
+}
+
+/**
+ * True for any `SsrStreamError`. This one also crosses Vite environments:
+ * it is thrown in SSR and caught in RSC, which are separate module graphs in
+ * the same process — the brand is the only identity the two share.
+ */
+export function isSsrStreamError(error: unknown): error is SsrStreamError {
+  return hasBrand(error, SSR_STREAM_ERROR_BRAND);
+}
+
 // ─── DenySignal ─────────────────────────────────────────────────────────────
 
 /**
  * Render-phase signal thrown by `deny()`. Caught by the framework to produce
  * the correct HTTP status code (segment context) or graceful degradation (slot context).
+ *
+ * Detect with `isDenySignal()`, never `instanceof` — see "Signal branding" above.
  */
 export class DenySignal extends Error {
+  readonly [DENY_BRAND] = true;
   readonly status: number;
   readonly data: JsonSerializable | undefined;
 
   /**
-   * Segment key of the segment that owns the deny page matched for this
-   * signal — set by a framework catch site that matched an entry it may not
-   * render at its own position, and re-threw so the boundary at the owning
-   * segment renders it instead.
+   * Ordered list of segment keys that own matching deny pages for this
+   * signal, best match first. Present = addressed (a boundary should
+   * render it); absent = unplaced (the re-render fallback serves it).
    *
-   * Written only by the three in-tree catch sites (`PageDenyBoundary`,
-   * `TracedLayout`, `AccessGate`), never by user code. Two readers depend on
-   * it: `TimberErrorBoundary`, which declines any deny whose `ownerKey` is
-   * not its own `segmentKey`, and `buildRscPayloadResponse`, which keeps
-   * streaming instead of re-rendering when it is set.
+   * In-tree hoists stamp a single-element list (`[entry.ownerKey]`) —
+   * identical to the pre-TIM-1450 `ownerKey`. Late addressing (TIM-1450)
+   * stamps the full candidate list so the client can find the first
+   * *reachable* owner via its ancestry context, eliminating the
+   * owner-below-throw-site escape.
    *
    * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
    */
-  ownerKey?: string;
+  owners?: string[];
 
   /**
    * When true, the pipeline must respond with `rscErrorEnvelope` so the
@@ -235,8 +289,11 @@ export { RedirectType } from '../shared/redirect-type.ts';
 /**
  * Render-phase signal thrown by `redirect()` and `redirectExternal()`.
  * Caught by the framework to produce a 3xx response or client-side navigation.
+ *
+ * Detect with `isRedirectSignal()`, never `instanceof` — see "Signal branding" above.
  */
 export class RedirectSignal extends Error {
+  readonly [REDIRECT_BRAND] = true;
   readonly location: string;
   readonly status: number;
 
@@ -258,7 +315,7 @@ export class RedirectSignal extends Error {
  * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
  */
 export function isControlFlowSignal(error: unknown): boolean {
-  if (error instanceof DenySignal || error instanceof RedirectSignal) {
+  if (isDenySignal(error) || isRedirectSignal(error)) {
     return true;
   }
   if (error && typeof error === 'object') {
@@ -396,11 +453,14 @@ export interface RenderErrorDigest<
  *   resourceId: params.id,
  * })
  * ```
+ *
+ * Detect with `isRenderError()`, never `instanceof` — see "Signal branding" above.
  */
 export class RenderError<
   TCode extends string = string,
   TData extends JsonSerializable = JsonSerializable,
 > extends Error {
+  readonly [RENDER_ERROR_BRAND] = true;
   readonly code: TCode;
   readonly digest: RenderErrorDigest<TCode, TData>;
   readonly status: number;
@@ -474,8 +534,12 @@ export function _resetWaitUntilWarning(): void {
  *
  * Defined in primitives.ts (not ssr-entry.ts) because ssr-entry.ts imports
  * react-dom/server which cannot be loaded in the RSC environment.
+ *
+ * Detect with `isSsrStreamError()` — it is thrown in the SSR environment and
+ * caught in RSC, so `instanceof` never matches. See "Signal branding" above.
  */
 export class SsrStreamError extends Error {
+  readonly [SSR_STREAM_ERROR_BRAND] = true;
   override readonly cause: unknown;
 
   constructor(message: string, cause: unknown) {

package/src/server/response-cache-policy.ts

@@ -0,0 +1,45 @@
+/**
+ * Legacy shared-cache control fields that predate RFC 9213 and so do not
+ * follow the `<target>-Cache-Control` naming pattern — the one part of this
+ * rule that cannot be matched by shape. `X-Accel-Expires` is nginx
+ * `proxy_cache`, which gives it precedence over `Cache-Control`.
+ *
+ * A closed historical set, unlike the vendor `*-Cache-Control` names, which
+ * keep being minted and are handled by pattern below.
+ */
+const LEGACY_CDN_CACHE_HEADERS = ['Surrogate-Control', 'Edge-Control', 'X-Accel-Expires'];
+
+/**
+ * Whether a response header overrides `Cache-Control` at a shared cache.
+ *
+ * Matched by *shape*, not by vendor name. RFC 9213 defines targeted fields
+ * as `<target>-Cache-Control`, and every CDN spells its own: `CDN-`,
+ * `Cloudflare-CDN-`, `Netlify-CDN-`, `Vercel-CDN-`, and whichever ships
+ * next. A vendor list here is a denylist with an unbounded tail — it was
+ * extended twice during review, each time by one name, which is the signal
+ * that enumeration is the wrong shape. The suffix rule is total.
+ *
+ * `Cache-Control` itself does not match (no `-` prefix) and is replaced
+ * separately.
+ */
+function isSharedCacheOverride(name: string): boolean {
+  const lowered = name.toLowerCase();
+  return (
+    lowered.endsWith('-cache-control') ||
+    LEGACY_CDN_CACHE_HEADERS.some((legacy) => legacy.toLowerCase() === lowered)
+  );
+}
+
+/** Disable caching, including CDN overrides that take precedence over Cache-Control. */
+export function preventResponseCaching(headers: Headers): void {
+  // Collected before deleting — mutating Headers while iterating its live
+  // key iterator can skip entries.
+  const overrides: string[] = [];
+  for (const name of headers.keys()) {
+    if (isSharedCacheOverride(name)) overrides.push(name);
+  }
+  for (const name of overrides) {
+    headers.delete(name);
+  }
+  headers.set('Cache-Control', 'private, no-store');
+}