@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.140

package/src/server/port-resolution.ts

@@ -0,0 +1,215 @@
+/**
+ * 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".
+ */
+
+/** 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 {
+  /**
+   * Port read from `vite.config.ts` `server.port` or the `--port` CLI
+   * flag (Vite merges `--port` into `userConfig.server.port` before
+   * plugins see it).
+   */
+  configPort?: number | undefined;
+  /** Raw value of `process.env.PORT`. */
+  envPort?: string | undefined;
+  /** Default port to use when neither `configPort` nor `envPort` is set. */
+  defaultPort?: number;
+}
+
+export interface ResolvedPortInput {
+  /** Port to start binding from. */
+  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.
+   */
+  explicit: boolean;
+}
+
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O — pair with {@link bindWithBump} to actually listen.
+ */
+export function resolveStartPort(input: ResolvePortInput): ResolvedPortInput {
+  const defaultPort = input.defaultPort ?? DEFAULT_PORT;
+
+  // `configPort` wins over `envPort`. This matches Vite's behavior:
+  // `vite --port 4000` overrides `PORT=5000` in the environment.
+  if (typeof input.configPort === 'number' && Number.isFinite(input.configPort)) {
+    return { port: input.configPort, explicit: true };
+  }
+
+  if (input.envPort != null && input.envPort !== '') {
+    const parsed = Number(input.envPort);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return { port: parsed, explicit: true };
+    }
+  }
+
+  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/primitives.ts

@@ -6,6 +6,9 @@
 import type { JsonSerializable } from './types.js';
 import { getWaitUntil as _getWaitUntil } from './waituntil-bridge.js';
 import { isDebug } from './debug.js';
+import { getRequestSearchString } from './request-context.js';
+import { mergePreservedSearchParams } from '../shared/merge-search-params.js';
+import { validateExternalRedirectUrl } from '../shared/href-validation.js';
 
 // ─── Dev-mode validation ────────────────────────────────────────────────────
 
@@ -143,37 +146,65 @@ export class DenySignal extends Error {
   }
 }
 
+/** Options for deny() when using the object form. */
+export interface DenyOptions {
+  /** HTTP status code (4xx or 5xx). Default: 403. */
+  status?: number;
+  /** Human-readable message (logged server-side, not sent to client). */
+  message?: string;
+  /** JSON-serializable data passed as `dangerouslyPassData` prop to status-code files. */
+  data?: JsonSerializable;
+}
+
 /**
- * Universal denial primitive. Throws a `DenySignal` that the framework catches.
+ * Universal denial/error primitive. Throws a `DenySignal` that the framework catches.
  *
  * - In segment context (outside Suspense): produces HTTP status code
  * - In slot context: graceful degradation → denied.tsx → default.tsx → null
  * - Inside Suspense (hold window): promoted to pre-flush behavior
  * - Inside Suspense (after flush): error boundary + noindex meta
  *
- * @param status - Any 4xx HTTP status code. Defaults to 403.
- * @param data - Optional JSON-serializable data passed as `dangerouslyPassData` prop to status-code files.
+ * Supports both positional and object signatures:
+ * ```ts
+ * deny()                                          // 403 (default)
+ * deny(404)                                       // 404
+ * deny(503, { retry: true })                      // 503 with data
+ * deny({ status: 503, message: 'Maintenance' })   // object form
+ * ```
+ *
+ * Accepts any 4xx or 5xx status code. This replaces the need for
+ * `throw new RenderError(...)` in user code — RenderError is now an
+ * internal pipeline detail.
+ *
+ * @param statusOrOptions - Status code (number) or options object. Default: 403.
+ * @param data - Optional JSON-serializable data (positional form only).
  */
-export function deny(status: number = 403, data?: JsonSerializable): never {
-  if (status < 400 || status > 499) {
-    throw new Error(
-      `deny() requires a 4xx status code, got ${status}. ` +
-        'For 5xx errors, throw a RenderError instead.'
-    );
+export function deny(statusOrOptions?: number | DenyOptions, data?: JsonSerializable): never {
+  let status: number;
+  let resolvedData: JsonSerializable | undefined;
+
+  if (typeof statusOrOptions === 'object' && statusOrOptions !== null) {
+    status = statusOrOptions.status ?? 403;
+    resolvedData = statusOrOptions.data;
+  } else {
+    status = statusOrOptions ?? 403;
+    resolvedData = data;
   }
-  warnIfNotSerializable(data, 'deny()');
-  throw new DenySignal(status, data);
+
+  if (status < 400 || status > 599) {
+    throw new Error(`deny() requires a 4xx or 5xx status code, got ${status}.`);
+  }
+  warnIfNotSerializable(resolvedData, 'deny()');
+  throw new DenySignal(status, resolvedData);
 }
 
 /**
- * Convenience alias for `deny(404)`.
- *
- * Provided for Next.js API compatibility — libraries and user code that
- * call `notFound()` from `next/navigation` get the same behavior as
- * `deny(404)` in timber.
+ * @deprecated Use `deny(404)` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
 export function notFound(): never {
-  throw new DenySignal(404);
+  deny(404);
 }
 
 /**
@@ -209,43 +240,109 @@ export class RedirectSignal extends Error {
 /** Pattern matching absolute URLs: http(s):// or protocol-relative // */
 const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
 
+// eslint-disable-next-line no-control-regex -- must match all C0 controls to prevent bypass
+const REDIRECT_CONTROL_CHARS_RE = /[\x00-\x1f]/g;
+
+/**
+ * Options for redirect() — alternative to passing a bare status code.
+ */
+export interface RedirectOptions {
+  /** HTTP redirect status code (3xx). Defaults to 302 (or 308 when `permanent: true`). */
+  status?: number;
+  /**
+   * When true, defaults the status to 308 (Permanent Redirect, preserves HTTP method).
+   * If `status` is also provided, `status` takes precedence.
+   *
+   * @example
+   * redirect('/new-path', { permanent: true });       // 308
+   * redirect('/new-path', { permanent: true, status: 301 }); // 301
+   */
+  permanent?: boolean;
+  /**
+   * Preserve search params from the current request URL on the redirect target.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Target path's own query params always take precedence over preserved ones.
+   */
+  preserveSearchParams?: true | string[];
+}
+
 /**
  * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
  * Use `redirectExternal()` for external redirects with an allow-list.
  *
  * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
- * @param status - HTTP redirect status code (3xx). Defaults to 302.
+ * @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
+ *
+ * @example
+ * // Simple redirect
+ * redirect('/login');
+ *
+ * // With status code
+ * redirect('/login', 301);
+ *
+ * // With preserved search params
+ * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
  */
-export function redirect(path: string, status: number = 302): never {
+export function redirect(path: string, statusOrOptions?: number | RedirectOptions): never {
+  let status: number;
+  let preserveSearchParams: true | string[] | undefined;
+
+  if (typeof statusOrOptions === 'number') {
+    status = statusOrOptions;
+  } else if (statusOrOptions) {
+    // Explicit status wins. Otherwise permanent: true → 308, default → 302.
+    status = statusOrOptions.status ?? (statusOrOptions.permanent ? 308 : 302);
+    preserveSearchParams = statusOrOptions.preserveSearchParams;
+  } else {
+    status = 302;
+  }
+
   if (status < 300 || status > 399) {
     throw new Error(`redirect() requires a 3xx status code, got ${status}.`);
   }
-  if (ABSOLUTE_URL_RE.test(path)) {
+  // Strip C0 control characters and trim whitespace before checking — browsers
+  // do this during URL resolution, so " \thttp://evil.com" resolves as absolute.
+  // Normalize for validation only: strip C0 controls, trim, then replace backslashes
+  // with forward slashes. Browsers normalize \ → / during URL resolution, so
+  // "/\evil.com" becomes "//evil.com" (protocol-relative open redirect).
+  const cleaned = path.replace(REDIRECT_CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (ABSOLUTE_URL_RE.test(cleaned)) {
     throw new Error(
       `redirect() only accepts relative URLs. Got absolute URL: "${path}". ` +
         'Use redirectExternal(url, allowList) for external redirects.'
     );
   }
-  throw new RedirectSignal(path, status);
+
+  let resolvedPath = path;
+  if (preserveSearchParams) {
+    const currentSearch = getRequestSearchString();
+    resolvedPath = mergePreservedSearchParams(path, currentSearch, preserveSearchParams);
+  }
+
+  throw new RedirectSignal(resolvedPath, status);
 }
 
 /**
- * Permanent redirect to a relative path. Shorthand for `redirect(path, 308)`.
- *
- * Uses 308 (Permanent Redirect) which preserves the HTTP method — the browser
- * will replay POST requests to the new location. This matches Next.js behavior.
- *
- * @param path - Relative path (e.g. '/new-page', '/dashboard')
+ * @deprecated Use `redirect(path, { permanent: true })` instead.
+ * Kept for internal use by the Next.js shim layer.
+ * @internal
  */
-export function permanentRedirect(path: string): never {
-  redirect(path, 308);
+export function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never {
+  redirect(path, { permanent: true, ...options });
 }
 
 /**
- * Redirect to an external URL. The hostname must be in the provided allow-list.
+ * Redirect to an external URL. The origin must be in the provided allow-list.
+ *
+ * Only http: and https: schemes are permitted. The allow-list is matched
+ * against full origins (scheme + host + port), not bare hostnames.
  *
  * @param url - Absolute URL to redirect to.
- * @param allowList - Array of allowed hostnames (e.g. ['example.com', 'auth.example.com']).
+ * @param allowList - Array of allowed origins (e.g. ['https://example.com', 'https://auth.example.com']).
  * @param status - HTTP redirect status code (3xx). Defaults to 302.
  */
 export function redirectExternal(url: string, allowList: string[], status: number = 302): never {
@@ -253,21 +350,8 @@ export function redirectExternal(url: string, allowList: string[], status: numbe
     throw new Error(`redirectExternal() requires a 3xx status code, got ${status}.`);
   }
 
-  let hostname: string;
-  try {
-    hostname = new URL(url).hostname;
-  } catch {
-    throw new Error(`redirectExternal() received an invalid URL: "${url}"`);
-  }
-
-  if (!allowList.includes(hostname)) {
-    throw new Error(
-      `redirectExternal() target "${hostname}" is not in the allow-list. ` +
-        `Allowed: [${allowList.join(', ')}]`
-    );
-  }
-
-  throw new RedirectSignal(url, status);
+  const canonicalUrl = validateExternalRedirectUrl(url, allowList);
+  throw new RedirectSignal(canonicalUrl, status);
 }
 
 // ─── RenderError ────────────────────────────────────────────────────────────

package/src/server/render-timeout.ts

@@ -0,0 +1,108 @@
+/**
+ * Render timeout utilities for SSR streaming pipeline.
+ *
+ * Provides a RenderTimeoutError class and a helper to create
+ * timeout-guarded AbortSignals. Used to defend against hung RSC
+ * streams and infinite SSR renders.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+ */
+
+/**
+ * Error thrown when an SSR render or RSC stream read exceeds the
+ * configured timeout. Callers can check `instanceof RenderTimeoutError`
+ * to distinguish timeout from other errors and return a 504 or close
+ * the connection cleanly.
+ */
+export class RenderTimeoutError extends Error {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number, context?: string) {
+    const message = context
+      ? `Render timeout after ${timeoutMs}ms: ${context}`
+      : `Render timeout after ${timeoutMs}ms`;
+    super(message);
+    this.name = 'RenderTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/**
+ * Result of createRenderTimeout — an AbortSignal that fires after
+ * the given duration, plus a cancel function to clear the timer
+ * when the render completes normally.
+ */
+export interface RenderTimeout {
+  /** AbortSignal that aborts after timeoutMs. */
+  signal: AbortSignal;
+  /** Cancel the timeout timer. Call this when the render completes. */
+  cancel: () => void;
+}
+
+/**
+ * Create a render timeout that aborts after the given duration.
+ *
+ * Returns an AbortSignal and a cancel function. The signal fires
+ * with a RenderTimeoutError as the abort reason after `timeoutMs`.
+ * Call `cancel()` when the render completes to prevent the timeout
+ * from firing.
+ *
+ * If an existing `parentSignal` is provided, the returned signal
+ * aborts when either the parent signal or the timeout fires —
+ * whichever comes first.
+ */
+export function createRenderTimeout(timeoutMs: number, parentSignal?: AbortSignal): RenderTimeout {
+  const controller = new AbortController();
+  const reason = new RenderTimeoutError(timeoutMs, 'RSC stream read timed out');
+
+  const timer = setTimeout(() => controller.abort(reason), timeoutMs);
+
+  let onParentAbort: (() => void) | null = null;
+
+  if (parentSignal) {
+    if (parentSignal.aborted) {
+      clearTimeout(timer);
+      controller.abort(parentSignal.reason);
+    } else {
+      onParentAbort = () => {
+        clearTimeout(timer);
+        controller.abort(parentSignal.reason);
+      };
+      parentSignal.addEventListener('abort', onParentAbort, { once: true });
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    cancel: () => {
+      clearTimeout(timer);
+      if (onParentAbort && parentSignal) {
+        parentSignal.removeEventListener('abort', onParentAbort);
+        onParentAbort = null;
+      }
+    },
+  };
+}
+
+/**
+ * Race a promise against a timeout. Rejects with RenderTimeoutError
+ * if the promise does not resolve within `timeoutMs`.
+ *
+ * Used to guard individual `rscReader.read()` calls inside pullLoop.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  context?: string
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new RenderTimeoutError(timeoutMs, context));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer!);
+  });
+}