@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/src/server/primitives.ts

@@ -6,6 +6,12 @@
 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 {
+  assertRelativeRedirectPath,
+  validateExternalRedirectUrl,
+} from '../shared/href-validation.js';
 
 // ─── Dev-mode validation ────────────────────────────────────────────────────
 
@@ -143,50 +149,70 @@ 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);
 }
 
-/**
- * Next.js redirect type discriminator.
- *
- * Provided for API compatibility with libraries that import `RedirectType`
- * from `next/navigation`. In timber, `redirect()` always uses `replace`
- * semantics (no history entry for the redirect itself).
- */
-export const RedirectType = {
-  push: 'push',
-  replace: 'replace',
-} as const;
+// Single source of truth shared with the client next/navigation shim —
+// see shared/redirect-type.ts.
+export { RedirectType } from '../shared/redirect-type.js';
 
 // ─── RedirectSignal ─────────────────────────────────────────────────────────
 
@@ -206,46 +232,125 @@ 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+\-.]*:|\/\/)/;
+// ─── Signal Detection ───────────────────────────────────────────────────────
+
+/**
+ * Returns true if the error is a framework control-flow signal (RedirectSignal
+ * or DenySignal) rather than a genuine application error. Works both for direct
+ * instances (RSC-side) and deserialized digest errors (SSR cross-boundary).
+ *
+ * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
+ */
+export function isControlFlowSignal(error: unknown): boolean {
+  if (error instanceof DenySignal || error instanceof RedirectSignal) {
+    return true;
+  }
+  if (error && typeof error === 'object') {
+    const digest = (error as { digest?: unknown }).digest;
+    if (typeof digest === 'string') {
+      try {
+        const parsed = JSON.parse(digest) as { type?: unknown } | null;
+        if (parsed && typeof parsed === 'object') {
+          return parsed.type === 'redirect' || parsed.type === 'deny';
+        }
+      } catch {
+        // Not valid digest JSON
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * 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)) {
-    throw new Error(
-      `redirect() only accepts relative URLs. Got absolute URL: "${path}". ` +
-        'Use redirectExternal(url, allowList) for external redirects.'
-    );
+  // Relative-only validation shared with the client next/navigation shim —
+  // strips C0 controls and normalizes backslashes before the scheme check.
+  assertRelativeRedirectPath(path);
+
+  let resolvedPath = path;
+  if (preserveSearchParams) {
+    const currentSearch = getRequestSearchString();
+    resolvedPath = mergePreservedSearchParams(path, currentSearch, preserveSearchParams);
   }
-  throw new RedirectSignal(path, status);
+
+  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 +358,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 ────────────────────────────────────────────────────────────
@@ -324,11 +416,6 @@ export class RenderError<
 
 // ─── waitUntil ──────────────────────────────────────────────────────────────
 
-/** Minimal interface for adapters that support background work. */
-export interface WaitUntilAdapter {
-  waitUntil?(promise: Promise<unknown>): void;
-}
-
 // Intentional per-app singleton — warn-once flag that persists for the
 // lifetime of the process/isolate. Not per-request; do not migrate to ALS.
 let _waitUntilWarned = false;
@@ -337,30 +424,20 @@ let _waitUntilWarned = false;
  * Register a promise to be kept alive after the response is sent.
  * Maps to `ctx.waitUntil()` on Cloudflare Workers and similar platforms.
  *
- * In production, the platform adapter installs a per-request waitUntil
- * function via ALS (see waituntil-bridge.ts). This function checks the
- * ALS bridge first, then falls back to the legacy adapter argument.
- *
- * If neither is available, a warning is logged once and the promise is
- * left to resolve (or reject) without being tracked.
+ * The platform adapter installs a per-request waitUntil function via ALS
+ * (see waituntil-bridge.ts). If no ALS handler is available, a warning
+ * is logged once and the promise is left to resolve (or reject) without
+ * being tracked.
  *
  * @param promise - The background work to keep alive.
- * @param adapter - Optional legacy adapter (prefer ALS bridge in production).
  */
-export function waitUntil(promise: Promise<unknown>, adapter?: WaitUntilAdapter): void {
-  // Check ALS bridge first (installed by generated entry points)
+export function waitUntil(promise: Promise<unknown>): void {
   const alsFn = _getWaitUntil();
   if (alsFn) {
     alsFn(promise);
     return;
   }
 
-  // Fall back to legacy adapter argument
-  if (adapter && typeof adapter.waitUntil === 'function') {
-    adapter.waitUntil(promise);
-    return;
-  }
-
   if (!_waitUntilWarned) {
     _waitUntilWarned = true;
     console.warn(

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!);
+  });
+}

package/src/server/render-utils.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared render-phase utilities — used by both the Node.js and Web
+ * stream wrappers. Pure functions only; no stream-shape dependencies.
+ *
+ * Consolidated from duplicated copies in node-stream-transforms.ts,
+ * ssr-render.ts, and rsc-entry/helpers.ts. See TIM-1071 item 1.
+ */
+
+/**
+ * Check if an error is an abort error (connection closed by client).
+ *
+ * When the browser aborts a request (page refresh, navigation away),
+ * the AbortSignal fires and React/streams throw an AbortError. This
+ * is not an application error — suppress it from error boundaries and logs.
+ */
+export function isAbortError(error: unknown): boolean {
+  if (error instanceof DOMException && error.name === 'AbortError') return true;
+  if (error instanceof Error && error.name === 'AbortError') return true;
+  return false;
+}
+
+/**
+ * Inline script that adds `<meta name="robots" content="noindex">` to the
+ * document head. Injected when a render-phase error replaces the shell so
+ * search engines don't index error pages.
+ *
+ * MUST be byte-identical across all stream wrappers (Node and Web) to
+ * ensure consistent Content-Length headers.
+ */
+export const NOINDEX_SCRIPT =
+  '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';