@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/src/server/metadata-routes.ts

@@ -29,7 +29,6 @@ export type MetadataRouteType =
   | 'favicon'
   | 'icon'
   | 'opengraph-image'
-  | 'twitter-image'
   | 'apple-icon';
 
 // ─── Convention Table ────────────────────────────────────────────────────────
@@ -84,7 +83,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     contentType: 'image/x-icon',
     nestable: false,
     staticExtensions: ['ico'],
-    dynamicExtensions: [],
+    dynamicExtensions: ['ts', 'tsx'],
     servePath: 'favicon.ico',
   },
   'icon': {
@@ -103,14 +102,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     dynamicExtensions: ['ts', 'tsx'],
     servePath: 'opengraph-image',
   },
-  'twitter-image': {
-    type: 'twitter-image',
-    contentType: 'image/*',
-    nestable: true,
-    staticExtensions: ['png', 'jpg'],
-    dynamicExtensions: ['ts', 'tsx'],
-    servePath: 'twitter-image',
-  },
+
   'apple-icon': {
     type: 'apple-icon',
     contentType: 'image/*',
@@ -225,26 +217,59 @@ export function getMetadataRouteServePath(type: MetadataRouteType): string {
   throw new Error(`[timber] Unknown metadata route type: ${type}`);
 }
 
+const METADATA_SERVE_PATHS = new Set(
+  Object.values(METADATA_ROUTE_CONVENTIONS).map((c) => c.servePath)
+);
+
+export function isMetadataRouteServePath(pathname: string): boolean {
+  const lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);
+  return METADATA_SERVE_PATHS.has(lastSegment);
+}
+
+/** A <link> auto-link tag. */
+export interface AutoLinkLink {
+  tag: 'link';
+  rel: string;
+  href: string;
+  type?: string;
+}
+
+/** A <meta> auto-link tag. */
+export interface AutoLinkMeta {
+  tag: 'meta';
+  property?: string;
+  name?: string;
+  content: string;
+}
+
+export type AutoLinkTag = AutoLinkLink | AutoLinkMeta;
+
 /**
  * Get the auto-link tags to inject into <head> for metadata route files
  * discovered in a segment.
  *
+ * Returns link tags for icon/apple-icon/manifest, and meta tags for
+ * opengraph-image (emits both og:image and twitter:image). Returns null
+ * for types that don't auto-link (favicon, sitemap, robots).
+ *
  * @param type - The metadata route type
  * @param href - The resolved URL path to the metadata route
- * @returns An object with tag/attrs for the <head>, or null if no auto-link
+ * @returns Tag descriptor(s) for the <head>, or null if no auto-link
  */
-export function getMetadataRouteAutoLink(
-  type: MetadataRouteType,
-  href: string
-): { rel: string; href: string; type?: string } | null {
+export function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): AutoLinkTag[] {
   switch (type) {
     case 'icon':
-      return { rel: 'icon', href };
+      return [{ tag: 'link', rel: 'icon', href }];
     case 'apple-icon':
-      return { rel: 'apple-touch-icon', href };
+      return [{ tag: 'link', rel: 'apple-touch-icon', href }];
     case 'manifest':
-      return { rel: 'manifest', href };
+      return [{ tag: 'link', rel: 'manifest', href }];
+    case 'opengraph-image':
+      return [
+        { tag: 'meta', property: 'og:image', content: href },
+        { tag: 'meta', name: 'twitter:image', content: href },
+      ];
     default:
-      return null;
+      return [];
   }
 }

package/src/server/middleware-runner.ts

@@ -1,9 +1,9 @@
 /**
- * Middleware runner — executes a route's middleware.ts before rendering.
+ * Middleware runner — executes a route's middleware.ts chain before rendering.
  *
- * Only the leaf route's middleware runs. There is no middleware chain.
- * Middleware does NOT have next() — it either short-circuits with a Response
- * or returns void to continue to access checks + render.
+ * All middleware.ts files in the segment chain run, root to leaf (top-down).
+ * The first middleware that returns a Response short-circuits the chain.
+ * There is no next() — each middleware is independent.
  *
  * See design/07-routing.md §"middleware.ts"
  */
@@ -30,3 +30,74 @@ export async function runMiddleware(
   }
   return undefined;
 }
+
+/**
+ * Run all middleware functions in the segment chain, root to leaf.
+ *
+ * Execution is top-down: root middleware runs first, leaf middleware runs last.
+ * All middleware share the same MiddlewareContext — a parent that sets
+ * ctx.requestHeaders makes it visible to child middleware and downstream components.
+ *
+ * Short-circuits on the first middleware that returns a Response.
+ * Remaining middleware in the chain do not execute.
+ *
+ * @param chain - Middleware functions ordered root-to-leaf
+ * @param ctx - Shared middleware context
+ * @returns A Response if any middleware short-circuited, or undefined to continue
+ */
+export async function runMiddlewareChain(
+  chain: MiddlewareFn[],
+  ctx: MiddlewareContext
+): Promise<Response | undefined> {
+  for (const fn of chain) {
+    const result = await fn(ctx);
+    if (result instanceof Response) {
+      return result;
+    }
+  }
+  return undefined;
+}
+
+// ─── Per-Request Middleware Bypass ─────────────────────────────────────────
+
+/**
+ * Per-request marker for synthetic re-render requests that should NOT
+ * re-execute `middleware.ts`. The action-dispatch wrapper runs middleware
+ * once on the inbound action POST; when validation fails on the no-JS
+ * path, it builds a synthetic GET that flows through the normal pipeline
+ * to render the page with `getFormFlash()` data. Without this marker, the
+ * pipeline would run middleware a second time on that synthetic GET.
+ *
+ * The set is keyed by the synthetic Request object itself, so the entry
+ * lives exactly as long as the request and is garbage-collected with it.
+ * Cannot be set or detected by user code — there is no header, no URL
+ * parameter, nothing on the wire that an attacker could spoof.
+ *
+ * See TIM-871.
+ *
+ * @internal — framework use only.
+ */
+const middlewareBypassRequests = new WeakSet<Request>();
+
+/**
+ * Mark a request so the pipeline skips its middleware phase.
+ *
+ * Used by `wrap-action-dispatch.ts` for the no-JS form-rerender path.
+ *
+ * @internal
+ */
+export function markRequestBypassMiddleware(req: Request): void {
+  middlewareBypassRequests.add(req);
+}
+
+/**
+ * Check whether a request was marked to bypass middleware.
+ *
+ * Called by `handleRequest` in pipeline-phases.ts before invoking the
+ * middleware phase. Returns false for any request not explicitly marked.
+ *
+ * @internal
+ */
+export function shouldBypassMiddleware(req: Request): boolean {
+  return middlewareBypassRequests.has(req);
+}

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

@@ -0,0 +1,331 @@
+/**
+ * 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,
+  SUFFIX_BYTES,
+  createInjectorState,
+  createSuffixState,
+  injectorFlush,
+  processInjectorChunk,
+  processSuffixChunk,
+  suffixFlush,
+} from './html-injector-core.js';
+import { logStreamingError } from './logger.js';
+import { createTickCoalescer } from './coalesce-tick.js';
+import { isAbortError, NOINDEX_SCRIPT } from './render-utils.js';
+
+// ─── 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' || result.kind === 'noSuffix') {
+        this.push(chunk);
+        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 ────────────────────────────────────────────────────
+
+/**
+ * Options for the Node.js flight injector.
+ */
+export interface NodeFlightInjectorOptions {
+  /**
+   * Timeout in milliseconds for individual RSC stream reads. If a single
+   * `rscReader.read()` call does not resolve within this duration, the
+   * read is aborted and the stream errors with a `RenderTimeoutError`.
+   * Default: 30000 (30s).
+   */
+  renderTimeoutMs?: number;
+  /** Signal that fires when an unhandled RSC error is detected. */
+  errorSignal?: AbortSignal;
+}
+
+/**
+ * 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?: NodeFlightInjectorOptions
+): Transform {
+  if (!rscStream) {
+    return new Transform({
+      transform(chunk, _enc, cb) {
+        cb(null, chunk);
+      },
+    });
+  }
+
+  const core = new FlightInjectorCore(rscStream, options?.renderTimeoutMs, options?.errorSignal);
+
+  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
+): 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(NOINDEX_SCRIPT, 'utf-8'));
+  });
+
+  return output;
+}