@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

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 ────────────────────────────────────────────────────
 
@@ -107,6 +113,31 @@ export class DenySignal extends Error {
   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.
+   *
+   * 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.
+   *
+   * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+   */
+  ownerKey?: string;
+
+  /**
+   * When true, the pipeline must respond with `rscErrorEnvelope` so the
+   * client hard-navigates instead of attempting to render a deny page
+   * from the RSC payload. Set by AccessGate when a skipped segment
+   * denies — rendering the deny page in-tree would appear inside the
+   * client's cached layout chrome (TIM-1074). See TIM-1363.
+   */
+  _hardNavigate?: boolean;
+
   constructor(status: number, data?: JsonSerializable) {
     super(`Access denied with status ${status}`);
     this.name = 'DenySignal';
@@ -143,50 +174,61 @@ 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);
-}
 
-/**
- * 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.
- */
-export function notFound(): never {
-  throw new DenySignal(404);
+  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);
 }
 
-/**
- * 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 +248,116 @@ 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 ───────────────────────────────────────────────────────
 
 /**
- * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
- * Use `redirectExternal()` for external redirects with an allow-list.
+ * 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).
  *
- * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
- * @param status - HTTP redirect status code (3xx). Defaults to 302.
+ * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
  */
-export function redirect(path: string, status: number = 302): never {
-  if (status < 300 || status > 399) {
-    throw new Error(`redirect() requires a 3xx status code, got ${status}.`);
+export function isControlFlowSignal(error: unknown): boolean {
+  if (error instanceof DenySignal || error instanceof RedirectSignal) {
+    return true;
   }
-  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.'
-    );
+  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
+      }
+    }
   }
-  throw new RedirectSignal(path, status);
+  return false;
 }
 
 /**
- * Permanent redirect to a relative path. Shorthand for `redirect(path, 308)`.
+ * 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.
  *
- * 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. '/login', 'settings', '/login?returnTo=/dash')
+ * @param statusOrOptions - HTTP status code (3xx, default 302) or options object.
+ *
+ * @example
+ * // Simple redirect
+ * redirect('/login');
+ *
+ * // With status code
+ * redirect('/login', 301);
  *
- * @param path - Relative path (e.g. '/new-page', '/dashboard')
+ * // With preserved search params
+ * redirect(`/docs/${version}/${slug}`, { preserveSearchParams: ['foo'] });
  */
-export function permanentRedirect(path: string): never {
-  redirect(path, 308);
+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}.`);
+  }
+  // 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(resolvedPath, status);
 }
 
 /**
- * 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 +365,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 +423,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 +431,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/publish-params.ts

@@ -0,0 +1,42 @@
+/**
+ * Publishing the request's params onto the RSC payload.
+ *
+ * Every tree the server sends the browser goes through here: the ordinary
+ * route payload (`route-element-builder.ts`), both deny renderers
+ * (`deny-renderer.ts`) and the error renderer. One helper rather than a wrap
+ * at each site, because these previously *were* separate sites — a response
+ * header, an inline script, and a second copy of each on the deny path — and
+ * the deny path shipping empty params was the bug that came of it (TIM-1285).
+ *
+ * Reads the request store rather than taking params as an argument, so a
+ * caller cannot pass a different record than the one the request rendered
+ * with. See design/41-global-params.md §"Transport".
+ */
+
+import { toPlainRecord } from '../shared/param-value.js';
+import type { RscPayloadRoot } from '../shared/payload-root.js';
+import { getSegmentParamsForClient, getSlotParamsForClient } from './request-context.js';
+
+/**
+ * Build the payload root: the tree, and the params it rendered with beside it.
+ *
+ * The params are a *sibling* of the tree, not a provider around it. A provider
+ * inside the payload is shadowed by the retained tree's own provider on a
+ * partial navigation, and its props are not readable at the instant the root
+ * row resolves — see `shared/payload-root.ts` for both, and TIM-1297. The
+ * client renders the one provider readers see, above the merge point.
+ *
+ * The records are flattened to plain objects on the way out. Every param
+ * record the framework builds is `Object.create(null)` (design/13-security.md
+ * #36b/#36c), and React Flight rejects a null prototype — "Classes or null
+ * prototypes are not supported". `ParamsProvider` restores the prototype on
+ * the other side, so what the app reads is unchanged; only the wire
+ * representation differs.
+ */
+export function withPublishedParams(element: React.ReactElement): RscPayloadRoot {
+  return {
+    tree: element,
+    params: toPlainRecord(getSegmentParamsForClient()),
+    slotParams: toPlainRecord(getSlotParamsForClient() ?? null),
+  };
+}

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>';