@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/port-resolution.ts

@@ -0,0 +1,53 @@
+/** 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;
+
+// ── 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). Preview uses this to default to strict port binding.
+   */
+  explicit: boolean;
+}
+
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O.
+ */
+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 };
+}

package/src/server/prebuilt/cache-key.ts

@@ -0,0 +1,299 @@
+/**
+ * Component cache-key hashing for prebuilt (cache.component) entries.
+ *
+ * Key: `sha256(canonicalJson({ props, params })).slice(0, 16)` — see
+ * design/44-render-at-build-time.md §Cache Key. Both the request-time
+ * lookup (prebuilt-runtime.ts) and the post-build capture pass (TIM-1119)
+ * MUST use this exact function, or build artifacts become unaddressable.
+ *
+ * THE IDENTITY CONTRACT (design/44 §Cache Key): cache identity is **JSON
+ * value semantics** — two inputs are the same entry iff they are the same
+ * JSON value. This is an ALLOWLIST, not a denylist: a value participates
+ * in caching iff it is plain JSON data — null, boolean, finite number,
+ * string, dense array, or a plain `Object.prototype` object with only
+ * enumerable string-keyed data properties — plus `undefined` and `-0`,
+ * which hash as distinct sentinels because flight preserves them. Every
+ * value outside that domain (functions, symbols, bigints, accessors,
+ * hidden or symbol-keyed properties, non-`Object.prototype` prototypes
+ * including null, aliased references, sparse arrays, cycles, non-finite
+ * numbers) is UNKEYABLE by definition: `computeComponentCacheKey` returns
+ * null and the caller renders live — slower, never wrong.
+ *
+ * The line between rejected and declared-out-of-domain: values are
+ * REJECTED when the JSON projection itself would be ambiguous or lossy
+ * (hidden/symbol/non-enumerable properties, accessors, exotic
+ * prototypes). Observable state that leaves the projection intact — key
+ * order, reference identity, descriptor metadata (writable/configurable,
+ * frozen/sealed/extensible), proxy behavior — is DECLARED outside
+ * cache.component's supported input domain rather than rejected:
+ * key-order insensitivity is required for determinism, and rejecting
+ * frozen objects would unkey ubiquitous legitimate inputs
+ * (Object.freeze'd config props) to defend against components that
+ * render differently based on property attributes.
+ *
+ * Two hard rules for this walk itself: it must be TOTAL (never throw
+ * anything but UnkeyableValueError) and SIDE-EFFECT-FREE (descriptor
+ * reads only; never invoke user code such as getters).
+ *
+ * Object keys sort recursively so `{a, b}` and `{b, a}` hash identically
+ * (design/13-security.md checklist #14 — cache key determinism; key order
+ * is deliberately NOT part of identity).
+ */
+
+import { createHash } from 'node:crypto';
+import type { CoercedParams } from '../../shared/param-value.ts';
+
+class UnkeyableValueError extends Error {}
+
+function canonicalize(value: unknown, seen: Set<object>): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      if (!Number.isFinite(value)) throw new UnkeyableValueError('non-finite number');
+      // -0 is distinct: flight preserves it ("$-0"), and String(-0) would
+      // collapse it to "0" (codex review round 4 on PR #835).
+      return Object.is(value, -0) ? '-0' : String(value);
+    case 'object':
+      break;
+    case 'undefined':
+      // Distinct sentinel, NOT collapsed to null or omitted: flight
+      // serialization preserves `undefined` ("$undefined"), so a component
+      // can render [undefined] differently from [null] and {a: undefined}
+      // differently from {}. Bare `undefined` cannot collide with any
+      // other canonical output (strings are always quoted). Codex review
+      // round 3 on PR #835.
+      return 'undefined';
+    default:
+      // function, symbol, bigint
+      throw new UnkeyableValueError(`unsupported type: ${typeof value}`);
+  }
+  const obj = value as object;
+  // Any REPEATED reference — cycle or alias — is unkeyable. Flight
+  // preserves reference identity (the second occurrence serializes as a
+  // row reference), so a component can observe `props.a === props.b`;
+  // hashing an aliased shape identically to a structurally-equal
+  // non-aliased one could splice the wrong subtree (codex review round 5
+  // on PR #835). Objects are never removed from `seen`: revisiting one
+  // anywhere in the walk throws.
+  if (seen.has(obj)) throw new UnkeyableValueError('repeated object reference (cycle or alias)');
+  seen.add(obj);
+  // Hidden own properties — symbol keys and non-enumerable props — are
+  // readable by a live-rendered component but invisible to this walk, so
+  // two observably different inputs would collide on one key (codex
+  // review on PR #835). Unkeyable.
+  if (Object.getOwnPropertySymbols(obj).length > 0) {
+    throw new UnkeyableValueError('symbol-keyed property');
+  }
+  {
+    if (Array.isArray(obj)) {
+      // Dense-array own names are exactly ['0'..'n-1', 'length'] — anything
+      // else is a custom expando property this walk would silently drop.
+      if (Object.getOwnPropertyNames(obj).length !== obj.length + 1) {
+        throw new UnkeyableValueError('non-index array property');
+      }
+      const parts: string[] = [];
+      for (let i = 0; i < obj.length; i++) {
+        // Sparse holes are unkeyable: a server component receiving the
+        // original array can observe `i in arr`, which no canonical form
+        // survives faithfully. (An explicit undefined element is fine —
+        // handled by the sentinel above.)
+        const desc = Object.getOwnPropertyDescriptor(obj, i);
+        if (desc === undefined) throw new UnkeyableValueError('sparse array hole');
+        // Accessors are rejected WITHOUT invoking them — a getter may
+        // throw or side-effect, and the key walk must never alter a
+        // render (codex review on PR #835).
+        if (desc.get !== undefined || desc.set !== undefined) {
+          throw new UnkeyableValueError('accessor property');
+        }
+        // Non-enumerable elements are invisible to Object.keys/spread/
+        // JSON.stringify — the JSON projection would be ambiguous, same
+        // rule as the object branch's keys-vs-names check.
+        if (!desc.enumerable) throw new UnkeyableValueError('non-enumerable array element');
+        parts.push(canonicalize(desc.value, seen));
+      }
+      return '[' + parts.join(',') + ']';
+    }
+    // Allowlist: exactly Object.prototype. Dates, Maps, class instances —
+    // and null-prototype objects, which a component can distinguish from
+    // literals via Object.getPrototypeOf — are all outside the JSON
+    // domain.
+    if (Object.getPrototypeOf(obj) !== Object.prototype) {
+      throw new UnkeyableValueError('non-plain object');
+    }
+    const keys = Object.keys(obj).sort();
+    if (keys.length !== Object.getOwnPropertyNames(obj).length) {
+      throw new UnkeyableValueError('non-enumerable property');
+    }
+    const parts: string[] = [];
+    for (const key of keys) {
+      // Descriptor read, not property read: accessors are rejected WITHOUT
+      // invoking them — a getter may throw or side-effect, and the key
+      // walk must never alter a render (codex review on PR #835).
+      const desc = Object.getOwnPropertyDescriptor(obj, key)!;
+      if (desc.get !== undefined || desc.set !== undefined) {
+        throw new UnkeyableValueError('accessor property');
+      }
+      parts.push(JSON.stringify(key) + ':' + canonicalize(desc.value, seen));
+    }
+    return '{' + parts.join(',') + '}';
+  }
+}
+
+/**
+ * Canonicalize a single value, or null if it is unkeyable. The ONE
+ * definition of "faithfully comparable" — every prebuilt code path that
+ * needs value equality (cache keys, slot-param divergence) goes through
+ * this, so the unkeyable rules (accessors, hidden props, aliases,
+ * bigints, …) live in exactly one place.
+ */
+export function tryCanonicalize(value: unknown): string | null {
+  try {
+    return canonicalize(value, new Set());
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+}
+
+/**
+ * Totality by construction: ANY throw from the walk means the input is
+ * outside the keyable domain. The walk touches only user-controlled
+ * values through reflection ops — and a Proxy trap can throw arbitrary
+ * errors from any of them (codex review on PR #835) — so converting only
+ * UnkeyableValueError would let hostile/exotic inputs abort a render
+ * that plain live rendering would have served fine. Unexpected error
+ * types are logged for visibility (they would indicate either a proxy
+ * trap or a canonicalizer bug) but still degrade to unkeyable.
+ */
+function toUnkeyable(error: unknown): null {
+  if (!(error instanceof UnkeyableValueError)) {
+    console.error(
+      '[timber] cache key canonicalization threw — treating input as unkeyable:',
+      error
+    );
+  }
+  return null;
+}
+
+/**
+ * Split a props record into data props (participate in the cache key) and
+ * slot values (React-element holes, excluded from the key) per the
+ * component's declared `slots` option (TIM-1173).
+ *
+ * Every DECLARED slot lands in `slotValues` — present or not — because the
+ * capture render always injects a SlotOutlet placeholder for each declared
+ * slot: the cached shell is identical whether the caller passed the slot
+ * or omitted it, so slot presence must not vary the key. `dataProps` is
+ * everything else and is what gets hashed.
+ *
+ * Returns null when the props OBJECT itself is outside the identity
+ * contract at the top level — accessors, symbol-keyed or non-enumerable
+ * properties, or a non-`Object.prototype` prototype. Splitting such an
+ * object would normalize away observable state (and reading an accessor
+ * would invoke user code, which this walk must never do) BEFORE
+ * `computeComponentCacheKey` gets the chance to reject it — a cached
+ * shell could then be served for inputs a live render distinguishes.
+ * Null means unkeyable: the caller renders live with the original props.
+ * The walk is descriptor-reads only; getters are never invoked. Nested
+ * data-prop values still face the full allowlist when hashed.
+ */
+/** Create an own enumerable data property — safe for keys like `__proto__`. */
+function defineOwn(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  });
+}
+
+export function splitSlotProps(
+  props: Record<string, unknown>,
+  slots: readonly string[]
+): { dataProps: Record<string, unknown>; slotValues: Record<string, unknown> } | null {
+  // TOTAL, like tryCanonicalize: the reflection ops below run against a
+  // user-controlled object, and a Proxy trap (getPrototypeOf, ownKeys,
+  // getOwnPropertyDescriptor) can throw arbitrarily — that must degrade
+  // to unkeyable (live render), not abort the request. toUnkeyable logs
+  // the unexpected throw for visibility. Codex P2 on PR #890.
+  try {
+    if (Object.getPrototypeOf(props) !== Object.prototype) return null;
+    if (Object.getOwnPropertySymbols(props).length > 0) return null;
+    const slotSet = new Set(slots);
+    const dataProps: Record<string, unknown> = {};
+    const slotValues: Record<string, unknown> = {};
+    // Own-property defines + Object.hasOwn, never assignment or `in`: a
+    // prop/slot legitimately named `__proto__` must land as an own data
+    // property (assignment would mutate the map's prototype), and an absent
+    // slot named `toString`/`constructor` must not read as present through
+    // the prototype chain (the provider would then expose the inherited
+    // function instead of undefined). Codex P2 on PR #890.
+    for (const key of Object.getOwnPropertyNames(props)) {
+      const desc = Object.getOwnPropertyDescriptor(props, key);
+      if (
+        desc === undefined ||
+        desc.get !== undefined ||
+        desc.set !== undefined ||
+        !desc.enumerable
+      ) {
+        return null;
+      }
+      defineOwn(slotSet.has(key) ? slotValues : dataProps, key, desc.value);
+    }
+    for (const slot of slotSet) {
+      if (!Object.hasOwn(slotValues, slot)) defineOwn(slotValues, slot, undefined);
+    }
+    return { dataProps, slotValues };
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+}
+
+/**
+ * Compute the cache-entry hash for a component render:
+ * `sha256({props, params}).slice(0, 16)` over canonical JSON.
+ *
+ * Returns null when props (or params) contain unkeyable values — the
+ * caller must fall back to dynamic rendering.
+ */
+export function computeComponentCacheKey(
+  props: Record<string, unknown>,
+  params: CoercedParams
+): string | null {
+  let canonical: string;
+  try {
+    // One shared `seen` set: an object aliased between params and props is
+    // just as observable as one aliased within either.
+    const seen = new Set<object>();
+    // The params RECORD is framework-produced: coerceSegmentParams builds
+    // it with Object.create(null) as a prototype-pollution defense
+    // (design/13 checklist #36b), uniformly on every request — its
+    // prototype is an implementation detail, not user-observable input
+    // variation, so the record is normalized to a plain object before the
+    // walk (codex P1 on PR #835: rejecting it made every real request
+    // unkeyable). Nested VALUES still face the full allowlist, and user
+    // props stay strict — a null-prototype prop object remains unkeyable.
+    canonical =
+      '{"params":' +
+      canonicalize({ ...params }, seen) +
+      ',"props":' +
+      canonicalize(props, seen) +
+      '}';
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+  // NOTE(hash choice — DECIDED, TIM-1119): 64 bits of truncated sha256 is
+  // the SHIPPED artifact format; the capture pass writes .flight files and
+  // manifest entries named by this hash, so changing the width is now a
+  // build-artifact format break. The width is adequate: entries are
+  // namespaced per component AND per deploy, so birthday odds need ~2^32
+  // entries under ONE component to matter, and design/13 #24 already
+  // accepts 64-bit non-crypto FNV-1a for data-cache keys on the same
+  // namespacing argument. Only revisit (with a format migration) if the
+  // phase-3 runtime tier ever stores attacker-influenced keys more
+  // aggressively.
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}

package/src/server/prebuilt/capture-render.ts

@@ -0,0 +1,118 @@
+/**
+ * One build-time capture entry (server/prebuilt-builder.ts): render a
+ * registered component in isolation under the synthetic build store and
+ * drain its flight payload under a deadline.
+ */
+
+import { createElement } from 'react';
+
+import { SlotOutlet } from '../../client/slot-outlet.tsx';
+import type { CoercedParams } from '../../shared/param-value.ts';
+import { renderToReadableStream } from '../../rsc-runtime/rsc.ts';
+import { requestContextAls } from '../als-registry.ts';
+import { readAllBytesWithDeadline } from '../stream-utils.ts';
+import type { PrebuiltRegistration } from '../prebuilt-runtime.ts';
+import { createCaptureScope, type NestedWrapperRender } from './capture-state.ts';
+import { resolveTags } from './lifetime.ts';
+import { LAYOUT_CHILDREN_SLOT } from './slots.ts';
+import { createBuildTimeStore } from './synthetic-store.ts';
+
+/** Wrap payload bytes as a single-chunk stream for the smoke revival. */
+export function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(c) {
+      c.enqueue(bytes);
+      c.close();
+    },
+  });
+}
+
+/**
+ * View of a registered component that satisfies createElement — same
+ * narrowing rationale as prebuilt-runtime.ts.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RenderableComponent = (props: any) => React.ReactNode;
+
+export interface EntryOutcome {
+  bytes: Uint8Array | null;
+  failure: unknown;
+  nested: NestedWrapperRender[];
+  resolvedTags: string[] | undefined;
+  segmentParamsRead: boolean;
+}
+
+/**
+ * Render one (component, props, coerced-params) entry in isolation and drain
+ * its flight payload. Any `onError` during serialization fails the entry —
+ * a payload with an embedded error row would replay that error on every
+ * future request, so only fully clean renders are captured.
+ */
+export async function renderEntry(
+  registration: PrebuiltRegistration,
+  props: Record<string, unknown>,
+  coercedParams: CoercedParams,
+  timeoutMs: number,
+  isLayout: boolean
+): Promise<EntryOutcome> {
+  const storeHandle = createBuildTimeStore(registration.id, coercedParams);
+  const { store, violations } = storeHandle;
+  let failure: unknown = null;
+
+  const capture = createCaptureScope(registration.id, registration.options, props);
+  let bytes: Uint8Array | null = null;
+  let resolvedTags: string[] | undefined;
+  try {
+    // Render AND drain inside one ALS scope. Flight renders in the context
+    // it was started from (and pinged from), not the one that pulls the
+    // stream, so the render itself only needs the scope at creation; the
+    // drain sits inside it too so everything in this capture reads the
+    // synthetic store (segmentParams.get() inside the component).
+    // Tag resolution also runs inside this scope so function-form tags
+    // that read segment params see the synthetic store (codex P2 on PR #858).
+    // Layout captures get <SlotOutlet slot="children" /> as children so
+    // the cached payload has a context-driven hole (design/45, TIM-1181).
+    const renderProps =
+      isLayout && !('children' in props)
+        ? { ...props, children: createElement(SlotOutlet, { slot: LAYOUT_CHILDREN_SLOT }) }
+        : props;
+    // The capture scope wraps the render the same way, so every wrapper
+    // inside it reports to this entry (cycle + nesting clamp).
+    bytes = await capture.run(() =>
+      requestContextAls.run(store, async () => {
+        const stream = renderToReadableStream(
+          createElement(registration.component as RenderableComponent, renderProps),
+          {
+            onError(error: unknown) {
+              failure ??= error ?? new Error('unknown render error');
+              // Digest string keeps flight from warning about a missing
+              // digest; the payload is discarded because `failure` is set.
+              return 'timber-prebuilt-capture-error';
+            },
+          }
+        );
+        // On timeout the reader is cancelled, never abandoned mid-read
+        // (design/13 A2/A3), and the entry fails.
+        const drained = await readAllBytesWithDeadline(stream, timeoutMs, 'render');
+        const tags = resolveTags(registration.options, props);
+        resolvedTags = tags.length > 0 ? tags : undefined;
+        return drained;
+      })
+    );
+  } catch (error) {
+    // Sync component throw (renderToReadableStream creation), drain
+    // timeout, or stream error.
+    failure ??= error;
+  }
+  const nested = capture.nestedRenders();
+
+  // Side-channel check FIRST: a component that touched per-request context
+  // is a hard error even when it caught the throw and rendered a fallback —
+  // accepting that payload would bake the request-dependent branch for
+  // every future request (codex P1 on PR #836).
+  const { segmentParamsRead } = storeHandle;
+  if (violations.length > 0)
+    return { bytes: null, failure: violations[0], nested, resolvedTags, segmentParamsRead };
+  if (failure !== null) return { bytes: null, failure, nested, resolvedTags, segmentParamsRead };
+  return { bytes, failure: null, nested, resolvedTags, segmentParamsRead };
+}

package/src/server/prebuilt/capture-routes.ts

@@ -0,0 +1,104 @@
+/**
+ * Candidate routes for the post-build capture pass
+ * (server/prebuilt-builder.ts, design/44-render-at-build-time.md §Build
+ * Phase): which pages carry prebuilt components, and which param combos
+ * to capture them for.
+ */
+
+import type { CoercedParams } from '../../shared/param-value.ts';
+import type { ManifestFile, ManifestSegmentNode } from '../route-matcher.ts';
+import { hasDynamicSegments } from '../sitemap-generator.ts';
+
+// ─── Route collection ─────────────────────────────────────────────────────
+
+export interface CandidateRoute {
+  urlPath: string;
+  page: ManifestFile;
+  /** Layout files along the chain that declare prebuilt components. */
+  layoutsToLoad: ManifestFile[];
+  /** Component IDs attributed to this route's page + layout chain. */
+  componentIds: string[];
+  /** Component IDs from layout files (receive SlotOutlet as children). */
+  layoutComponentIds: Set<string>;
+}
+
+/**
+ * Walk the manifest tree and collect pages whose file chain (page +
+ * layouts above it) has prebuilt components attributed to it. Slots and
+ * intercepting/private segments are not walked — slot-scoped prebuilt is
+ * already unkeyable at request time when slot params diverge (see
+ * resolveKeyParams in prebuilt-runtime.ts), so the build doesn't model
+ * slots either.
+ */
+export function collectCandidateRoutes(
+  root: ManifestSegmentNode,
+  fileComponentMap: Record<string, string[]>
+): CandidateRoute[] {
+  const routes: CandidateRoute[] = [];
+
+  const walk = (node: ManifestSegmentNode, layoutChain: ManifestFile[]) => {
+    if (node.segmentType === 'intercepting' || node.segmentType === 'private') return;
+    const chain = node.layout ? [...layoutChain, node.layout] : layoutChain;
+
+    if (node.page) {
+      const componentIds = new Set<string>();
+      const layoutIds = new Set<string>();
+      for (const f of chain)
+        for (const id of fileComponentMap[f.filePath] ?? []) {
+          componentIds.add(id);
+          layoutIds.add(id);
+        }
+      for (const id of fileComponentMap[node.page.filePath] ?? []) componentIds.add(id);
+      if (componentIds.size > 0) {
+        routes.push({
+          urlPath: node.urlPath,
+          page: node.page,
+          layoutsToLoad: chain.filter((l) => (fileComponentMap[l.filePath] ?? []).length > 0),
+          componentIds: Array.from(componentIds),
+          layoutComponentIds: layoutIds,
+        });
+      }
+    }
+
+    for (const child of node.children) walk(child, chain);
+  };
+
+  walk(root, []);
+  return routes;
+}
+
+// ─── Param enumeration ────────────────────────────────────────────────────
+
+export type ParamCombo = CoercedParams;
+
+/**
+ * Resolve the param combos to capture for a route. Static routes have
+ * exactly one combo (the empty record) — `export const prerender`-style
+ * components on static pages need no enumerator. Dynamic routes require
+ * `generateStaticSegmentParams` (design/44 §generateStaticSegmentParams);
+ * without it every request renders live and the wrapper is a no-op.
+ */
+export async function enumerateCombos(
+  route: CandidateRoute,
+  pageModule: Record<string, unknown>,
+  log: (message: string) => void
+): Promise<ParamCombo[] | null> {
+  if (!hasDynamicSegments(route.urlPath)) return [{}];
+
+  const generateFn = pageModule.generateStaticSegmentParams;
+  if (typeof generateFn !== 'function') {
+    log(
+      `[timber] cache.component: route ${route.urlPath} has prebuilt components but no ` +
+        `generateStaticSegmentParams export — all its entries will render dynamically ` +
+        `until the page declares its param combos`
+    );
+    return null;
+  }
+  const combos: unknown = await (generateFn as () => unknown)();
+  if (!Array.isArray(combos)) {
+    throw new Error(
+      `generateStaticSegmentParams must return an array of param records, got ${typeof combos}`
+    );
+  }
+  return combos as ParamCombo[];
+}