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

package/src/server/node-stream-transforms.ts

@@ -0,0 +1,323 @@
+/**
+ * Node.js native stream transforms for SSR HTML post-processing.
+ *
+ * Node.js `Transform` wrappers around the pure helpers in
+ * `html-injector-core.ts`. Used on Node.js / Bun where C++-backed
+ * native streams are significantly faster than the JS-implemented
+ * Web Streams. The Web `TransformStream` equivalents live in
+ * `html-injectors.ts` and wrap the same core — keep the two files
+ * byte-for-byte equivalent in behavior. If you fix a streaming bug
+ * here, it almost certainly belongs in the core (`html-injector-core.ts`),
+ * not in this wrapper.
+ *
+ * Architecture:
+ *   renderToPipeableStream → pipe(errorHandler) → pipe(headInjector)
+ *     → pipe(flightInjector) → Readable.toWeb() → Response
+ *
+ * All chunks stay in C++ Node.js stream buffers until the final
+ * Readable.toWeb() conversion for the Response body.
+ */
+
+import { PassThrough, Transform, type Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import {
+  BufferAggregator,
+  FlightInjectorCore,
+  type FlightInjectorOptions,
+  SUFFIX_BYTES,
+  createInjectorState,
+  createSuffixState,
+  injectorFlush,
+  processInjectorChunk,
+  processSuffixChunk,
+  suffixFlush,
+} from './html-injector-core.ts';
+import { logStreamingError } from './logger.ts';
+import { createTickCoalescer } from './coalesce-tick.ts';
+import { isAbortError, noindexScript } from './render-utils.ts';
+
+// ─── Buffered Transform ──────────────────────────────────────────────────────
+
+export interface NodeBufferedTransformOptions {
+  /**
+   * Flush synchronously once the buffer reaches this many bytes.
+   * Prevents unbounded memory growth for very large Fizz flushes.
+   * Default: Infinity (no byte limit — flush only on tick boundary).
+   */
+  readonly maxBufferByteLength?: number;
+}
+
+/**
+ * Node.js `Transform` that buffers incoming chunks and coalesces them
+ * within a single event loop tick.
+ *
+ * Equivalent to `createBufferedTransformStream` in `html-injectors.ts` —
+ * the actual buffer math lives in `BufferAggregator`. This wrapper only
+ * owns the `setImmediate` scheduling and the push to the Node `Transform`.
+ *
+ * **Not a polling loop.** Single-shot `setImmediate` per flush cycle —
+ * no recursive scheduling. See design/02 §"No Polling".
+ */
+export function createNodeBufferedTransform(options: NodeBufferedTransformOptions = {}): Transform {
+  const buffer = new BufferAggregator(options.maxBufferByteLength ?? Infinity);
+
+  const flushBuffer = () => {
+    const merged = buffer.drain();
+    if (merged) transform.push(merged);
+  };
+
+  const coalescer = createTickCoalescer(flushBuffer);
+
+  const transform = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      const overCap = buffer.append(chunk);
+      if (overCap) {
+        flushBuffer();
+      } else {
+        coalescer.schedule();
+      }
+      callback();
+    },
+    flush(callback) {
+      coalescer.flushSync();
+      callback();
+    },
+  });
+
+  return transform;
+}
+
+// ─── Move Suffix Transform ───────────────────────────────────────────────────
+
+/**
+ * Node.js `Transform` that moves `</body></html>` to the end of the stream.
+ *
+ * Equivalent to `createMoveSuffixStream` in `html-injectors.ts`. Strips
+ * the suffix on first sight and re-emits it from `flush()`. If the
+ * suffix never appeared in the input, it is appended anyway so output
+ * is well-formed.
+ */
+export function createNodeMoveSuffixTransform(): Transform {
+  const state = createSuffixState();
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      const result = processSuffixChunk(state, chunk);
+      if (result.kind === 'passthrough') {
+        this.push(chunk);
+        callback();
+        return;
+      }
+      if (result.kind === 'noSuffix') {
+        if (result.emitSafe) this.push(Buffer.from(result.emitSafe));
+        callback();
+        return;
+      }
+      if (result.before) this.push(Buffer.from(result.before));
+      if (result.after) this.push(Buffer.from(result.after));
+      callback();
+    },
+    flush(callback) {
+      this.push(Buffer.from(suffixFlush(state)));
+      callback();
+    },
+  });
+}
+
+// Re-export for tests / consumers that need the suffix bytes constant.
+export { SUFFIX_BYTES };
+
+// ─── Head Injection ──────────────────────────────────────────────────────────
+
+/**
+ * Node.js `Transform` that injects HTML content before `</head>`.
+ *
+ * Equivalent to `injectHead` in `html-injectors.ts`. Streams chunks
+ * through immediately, keeping only a small trailing buffer to handle
+ * `</head>` split across chunk boundaries.
+ */
+export function createNodeHeadInjector(headHtml: string): Transform {
+  if (!headHtml) {
+    return new Transform({
+      transform(chunk, _enc, cb) {
+        cb(null, chunk);
+      },
+    });
+  }
+
+  const state = createInjectorState({ content: headHtml, targetTag: '</head>' });
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      const result = processInjectorChunk(state, chunk);
+      if (result.kind === 'passthrough') {
+        callback(null, chunk);
+        return;
+      }
+      if (result.bytes) this.push(Buffer.from(result.bytes));
+      callback();
+    },
+    flush(callback) {
+      const leftover = injectorFlush(state);
+      if (leftover) this.push(Buffer.from(leftover));
+      callback();
+    },
+  });
+}
+
+// ─── RSC Flight Injection ────────────────────────────────────────────────────
+
+/**
+ * Node.js `Transform` that merges RSC script tags into the HTML stream.
+ *
+ * Equivalent to `createFlightInjectionTransform` in `html-injectors.ts`.
+ * The state machine, pending queue, and pull loop all live in
+ * `FlightInjectorCore` — this wrapper only shuffles bytes between the
+ * core and the Node `Transform.push()` API.
+ *
+ * Suffix stripping (`</body></html>`) is handled upstream by
+ * `createNodeMoveSuffixTransform`. RSC scripts are buffered in
+ * `core.pending[]` and only drained from `transform()` (after a complete
+ * HTML chunk) or `flush()` — never mid-tag. See design/02
+ * §"Scripts at Chunk Boundaries Only".
+ *
+ * The RSC stream is a Web `ReadableStream` (from the tee'd RSC Flight
+ * stream). The core reads from it using the Web API — this is the one
+ * bridge point between Web Streams and Node.js streams in the pipeline.
+ */
+export function createNodeFlightInjector(
+  rscStream: ReadableStream<Uint8Array> | undefined,
+  options?: FlightInjectorOptions
+): Transform {
+  if (!rscStream) {
+    return new Transform({
+      transform(chunk, _enc, cb) {
+        cb(null, chunk);
+      },
+    });
+  }
+
+  const core = new FlightInjectorCore(rscStream, options);
+
+  const drain = (): void => {
+    while (core.pending.length > 0) transform.push(Buffer.from(core.pending.shift()!));
+  };
+
+  const transform = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      const wasInit = core.isInit;
+      if (wasInit) core.notifyFirstChunk();
+
+      // Emit the HTML chunk, then drain any buffered RSC scripts.
+      // Scripts always come AFTER a complete HTML chunk — never mid-tag.
+      // The buffered transform upstream (TIM-528) ensures coherent chunks.
+      // Suffix stripping is upstream via createNodeMoveSuffixTransform (TIM-530).
+      transform.push(chunk);
+      drain();
+
+      // Start the pull loop on the first HTML chunk.
+      if (wasInit) core.ensurePullLoop(drain);
+      callback();
+    },
+    destroy(err, callback) {
+      core.abort(err ?? 'pipeline destroyed');
+      callback(err);
+    },
+    flush(callback) {
+      // All HTML chunks have been emitted. Pull loop stops yielding.
+      core.notifyHtmlDone();
+
+      const finish = () => {
+        drain();
+        const err = core.terminalError;
+        if (err !== null) {
+          transform.destroy(err instanceof Error ? err : new Error(String(err)));
+          return;
+        }
+        callback();
+      };
+
+      if (core.isPullDone) {
+        finish();
+        return;
+      }
+      // Wait on the pull-loop promise instead of polling. Zero CPU cost
+      // while waiting. See design/02 §"No Polling".
+      core.ensurePullLoop(drain).then(finish, (err) => {
+        // ensurePullLoop's underlying loop catches its own errors and
+        // sends PULL_ERROR — this catch is defence-in-depth for any
+        // synchronous throws inside the .then() chain itself.
+        transform.destroy(err instanceof Error ? err : new Error(String(err)));
+      });
+    },
+  });
+
+  return transform;
+}
+
+// ─── Error Handling ──────────────────────────────────────────────────────────
+
+/**
+ * Run the Node SSR post-processing pipeline with post-shell error handling.
+ *
+ * Equivalent to wrapStreamWithErrorHandling() in ssr-render.ts: when the
+ * stream errors after the shell has flushed (deny/throw inside Suspense,
+ * an RSC read timeout in the flight injector, or an upstream Fizz error),
+ * the response closes cleanly with a trailing noindex script instead of
+ * aborting the connection mid-body. Abort errors (client disconnect,
+ * render-timeout abort) close the output silently — no noindex, no log.
+ *
+ * Why this is a pump function and not a Transform stage (TIM-1019):
+ * stream.promises.pipeline() destroys every stage in the chain when any
+ * stage errors, so a Transform *inside* the pipeline can never append
+ * bytes after a failure — by the time its 'error' listener fires, the
+ * transform and everything downstream are already destroyed and push()/
+ * end() are no-ops. The output PassThrough therefore lives OUTSIDE the
+ * pipeline() call: the last stage pipes into it (pipe() ends the output
+ * on upstream success but leaves it open on upstream error), and the
+ * pipeline's rejection handler appends the noindex script.
+ *
+ * Consumer cancellation (e.g. Readable.toWeb() cancel on client
+ * disconnect) is wired back into the pipeline via an AbortSignal so the
+ * source and all stages are torn down — the teardown that membership in
+ * pipeline() used to provide.
+ */
+export function runNodePipelineWithErrorHandling(
+  source: Readable,
+  transforms: readonly [Transform, ...Transform[]],
+  signal?: AbortSignal,
+  nonce?: string
+): PassThrough {
+  const output = new PassThrough();
+  const last = transforms[transforms.length - 1]!;
+  last.pipe(output);
+
+  // If the consumer destroys the output (client disconnect), abort the
+  // pipeline so the Fizz source and flight injector release their
+  // resources. On normal completion the pipeline has already settled and
+  // the abort is a no-op.
+  const consumerGone = new AbortController();
+  output.once('close', () => consumerGone.abort());
+
+  // The cast satisfies pipeline()'s [source, ...transforms, destination]
+  // tuple overload — TS can't prove the shape across a spread, but the
+  // signature above guarantees a non-empty transform list at compile time.
+  const stages = [source, ...transforms] as unknown as readonly [
+    Readable,
+    ...Transform[],
+    Transform,
+  ];
+
+  pipeline(stages, { signal: consumerGone.signal }).catch((error: unknown) => {
+    if (output.writableEnded || output.destroyed) return;
+    if (isAbortError(error) || signal?.aborted || consumerGone.signal.aborted) {
+      output.end();
+      return;
+    }
+    logStreamingError({ error });
+    output.end(Buffer.from(noindexScript(nonce), 'utf-8'));
+  });
+
+  return output;
+}

package/src/server/nuqs-ssr-provider.tsx

@@ -45,17 +45,18 @@ function makeNuqsSsrAdapter(searchParams: URLSearchParams) {
  * Wrap the SSR element tree with a nuqs adapter context.
  *
  * Called by ssr-entry.ts before passing the element to renderSsrStream.
- * Takes the NavContext search params and provides them to nuqs hooks
+ * Takes the NavContext raw query string and provides it to nuqs hooks
  * running during SSR so they render with the correct initial values.
  *
- * @param searchParamsRecord - The request's search params as a plain record
+ * The raw string — not a collapsed record — is what preserves repeated
+ * query keys (`?tag=a&tag=b`) for nuqs multi parsers, matching the raw
+ * `location.search` the client adapter reads after hydration (TIM-1428).
+ *
+ * @param search - The request's raw app-visible query string (`''` or `?…`)
  * @param children - The React element tree to wrap
  */
-export function withNuqsSsrAdapter(
-  searchParamsRecord: Record<string, string>,
-  children: ReactNode
-): ReactNode {
-  const searchParams = new URLSearchParams(searchParamsRecord);
+export function withNuqsSsrAdapter(search: string, children: ReactNode): ReactNode {
+  const searchParams = new URLSearchParams(search);
   const Provider = makeNuqsSsrAdapter(searchParams);
   // AdapterProvider types require children in the props object (not as 3rd arg)
   // eslint-disable-next-line react/no-children-prop

package/src/server/param-coercion.ts

@@ -0,0 +1,201 @@
+/**
+ * Segment param coercion — runs the app/schema.ts codecs over the raw
+ * matcher output before middleware and rendering.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the coercer can be
+ * imported directly by other entry points (the action-dispatch wrapper,
+ * the revalidation renderer in `rsc-entry/index.ts`) without pulling
+ * the entire pipeline phase module along with it.
+ *
+ * The function throws `ParamCoercionError` (defined below) on any codec
+ * failure; the pipeline catches that and dispatches to the 404 page.
+ * See design/07-routing.md §"Where Coercion Runs".
+ */
+
+import type { Codec } from '../codec.ts';
+import type { SegmentType } from '../routing/types.ts';
+import { effectiveUrlSegment } from '../routing/segment-classify.ts';
+import { toBracketKey } from '../params/resolve-schema.ts';
+import type { RouteMatch } from './pipeline.ts';
+import { normalizeParamValue, type CoercedParams } from '../shared/param-value.ts';
+/**
+ * Thrown when an app/schema.ts segment-param codec's parse() fails.
+ * The pipeline catches this and responds with 404.
+ */
+export class ParamCoercionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ParamCoercionError';
+  }
+}
+import { isDebug } from './debug.ts';
+
+// ---------------------------------------------------------------------------
+// Module-level global codec store (TIM-931)
+// ---------------------------------------------------------------------------
+
+/** Global schema codecs, set once at startup from virtual:timber-schema. */
+let _globalCodecs: Record<string, Codec<unknown>> | null = null;
+
+/**
+ * Register the global schema codecs. Called once from the RSC entry
+ * at server startup when app/schema.ts provides segment param codecs.
+ * @internal
+ */
+export function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | null): void {
+  _globalCodecs = codecs;
+}
+
+/**
+ * Coerce raw slot params through global schema codecs.
+ *
+ * Each slot segment that has a paramName is looked up in the global codec
+ * map by its bracket key (e.g. '[...year]' for catch-all). If a codec
+ * exists, the raw value is parsed through it. If no codec exists or no
+ * global codecs are registered, the raw value passes through unchanged.
+ *
+ * Segments are read through `effectiveUrlSegment` because an intercepting
+ * node's own `segmentType` is `'intercepting'` and its `paramName` is unset
+ * — the param it binds lives in the intercepted name (`(.)[id]` → `[id]`).
+ * The slot resolver matches through the same helper, so the key a param is
+ * coerced under is always the key it was matched under (TIM-1281).
+ *
+ * Unlike main route coercion, this does NOT throw ParamCoercionError on
+ * failure — slots degrade gracefully. A failed coercion logs a warning
+ * in dev mode and keeps the raw value.
+ *
+ * @internal — framework use only
+ */
+export function coerceSlotParams(
+  slotChain: Array<{
+    segmentName: string;
+    segmentType: SegmentType;
+    paramName?: string;
+    interceptedSegmentName?: string;
+  }>,
+  rawParams: Record<string, string | string[]>
+): CoercedParams {
+  const globalCodecs = _globalCodecs;
+  if (!globalCodecs) return rawParams;
+
+  const result: CoercedParams = Object.create(null);
+  for (const key of Object.keys(rawParams)) {
+    result[key] = rawParams[key];
+  }
+
+  for (const node of slotChain) {
+    const segment = effectiveUrlSegment(node);
+    if (!segment.paramName) continue;
+    const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
+    const codec = globalCodecs[bracketKey];
+    if (!codec) continue;
+
+    const key = segment.paramName;
+    if (!(key in result)) continue;
+
+    let parsed: unknown;
+    try {
+      parsed = codec.parse(result[key] as string | string[]);
+    } catch (err) {
+      // Slot param coercion failures are non-fatal — keep the raw value.
+      // The main route already validated the URL; the slot just interprets
+      // the same parts differently.
+      if (isDebug()) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `[timber] Slot param coercion failed for "${key}" (codec: ${bracketKey})\n` +
+            `  Error: ${message}\n` +
+            `  Raw value: ${JSON.stringify(result[key])}\n` +
+            `  Keeping raw value.`
+        );
+      }
+      continue;
+    }
+    result[key] = normalizeParamValue(parsed, key);
+  }
+
+  return result;
+}
+
+/**
+ * Coerce the matched route's raw segment params and return the result.
+ *
+ * Reads `match.rawSegmentParams` and never writes to `match`: the caller
+ * decides where the coerced params go. Reading the raw record makes the call
+ * repeatable — coercing a match twice runs every codec on the URL value both
+ * times, never on its own output.
+ *
+ * Codecs come from `app/schema.ts` and nowhere else (TIM-1342 completed
+ * design/41-global-params.md migration step 9). A route with no schema, or
+ * a param the schema does not declare, keeps its raw string — which is the
+ * honest type for an uninterpreted URL segment.
+ *
+ * Throws ParamCoercionError if any codec fails (→ 404).
+ *
+ * This runs BEFORE middleware, so ctx.segmentParams is already typed.
+ * See design/07-routing.md §"Where Coercion Runs"
+ * See design/41-global-params.md §"Pipeline Integration"
+ *
+ * Stays `async` with nothing to await: it is injected as a
+ * `CoerceSegmentParamsFn` into the revalidation renderer, which awaits
+ * it. Making it synchronous would
+ * change that contract and remove a microtask boundary the pipeline's
+ * ordering has always had, for no gain.
+ */
+// eslint-disable-next-line @typescript-eslint/require-await -- see above
+export async function coerceSegmentParams(match: RouteMatch): Promise<CoercedParams> {
+  const globalCodecs = _globalCodecs;
+  // Always a null-prototype record, whether or not any segment has a codec.
+  const mergeTarget: CoercedParams = Object.create(null);
+  for (const key of Object.keys(match.rawSegmentParams)) {
+    if (key !== '__proto__') {
+      mergeTarget[key] = match.rawSegmentParams[key];
+    }
+  }
+
+  // TIM-931/TIM-936: When a global schema is available, use it for coercion
+  // instead of per-segment params.ts files. The global codec map is keyed
+  // by bracket name (e.g. '[id]', '[...slug]') to avoid collisions between
+  // distinct segment types that share a param name.
+  if (globalCodecs) {
+    for (const node of match.segments) {
+      // Read through `effectiveUrlSegment` for the same reason
+      // `coerceSlotParams` does: an intercepting node's own `segmentType` is
+      // 'intercepting' and its `paramName` is unset — the param it binds lives
+      // in the intercepted name (`(.)[id]` → `[id]`). Until TIM-1280 an
+      // intercepting node could only appear in a *slot* chain, so only that
+      // path needed it; a children-path interception puts one in the main
+      // chain, and reading the node directly would silently skip coercion for
+      // exactly the param the intercepting directory declares — so the swapped
+      // route and the canonical one would disagree about the param's type.
+      const segment = effectiveUrlSegment(node);
+      if (!segment.paramName) continue;
+      const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
+      const codec = globalCodecs[bracketKey];
+      if (!codec) continue; // no codec in schema → keep raw string
+
+      const key = segment.paramName;
+      if (!(key in mergeTarget)) continue;
+      let parsed: unknown;
+      try {
+        parsed = codec.parse(mergeTarget[key] as string | string[]);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isDebug()) {
+          console.warn(
+            `[timber] Global schema codec rejected value for param "${key}"\n` +
+              `  Error: ${message}\n` +
+              `  Raw value: ${JSON.stringify(mergeTarget[key])}\n` +
+              `  Hint: check the codec in app/schema.ts for key '${bracketKey}'.`
+          );
+        }
+        throw new ParamCoercionError(message);
+      }
+      // Outside the catch: a codec that rejects a URL value is a 404, a codec
+      // that returns an unrepresentable one is a bug in the app. Normalizing
+      // inside would report the second as the first.
+      mergeTarget[key] = normalizeParamValue(parsed, key);
+    }
+  }
+  return mergeTarget;
+}