@timber-js/app 0.2.0-alpha.5 → 0.2.0-alpha.51

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

@@ -0,0 +1,504 @@
+/**
+ * Node.js native stream transforms for SSR HTML post-processing.
+ *
+ * These are Node.js Transform stream equivalents of the Web Stream
+ * transforms in html-injectors.ts. Used on Node.js/Bun where native
+ * streams (C++ backed) are faster than Web Streams (JS reimplementation).
+ *
+ * The transforms are pure string operations on HTML chunks — the same
+ * logic as the Web Stream versions, just wrapped in Node.js Transform
+ * instead of Web TransformStream.
+ *
+ * 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 { Transform } from 'node:stream';
+import { createGzip, constants } from 'node:zlib';
+
+// ─── Buffered Transform ──────────────────────────────────────────────────────
+
+/**
+ * Options for the Node.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.
+ * React Fizz may emit multiple micro-chunks within a single flush.
+ * Without buffering, downstream transforms (especially flight injection)
+ * could see chunk boundaries in the middle of HTML tags or attributes.
+ *
+ * This transform collects all chunks that arrive in the same tick and
+ * emits them as a single concatenated Buffer on the next `setImmediate`.
+ *
+ * **Not a polling loop.** Uses a single-shot `setImmediate` per flush
+ * cycle — no recursive scheduling, no busy-wait. See design/02 §"No Polling".
+ *
+ * Inspired by Next.js `createBufferedTransformStream`.
+ */
+export function createNodeBufferedTransform(options: NodeBufferedTransformOptions = {}): Transform {
+  const { maxBufferByteLength = Infinity } = options;
+
+  let bufferedChunks: Buffer[] = [];
+  let bufferByteLength = 0;
+  let pendingImmediate: ReturnType<typeof setImmediate> | null = null;
+
+  const transform = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      bufferedChunks.push(chunk);
+      bufferByteLength += chunk.byteLength;
+
+      if (bufferByteLength >= maxBufferByteLength) {
+        // Synchronous flush — buffer is too large to hold
+        flushBuffer();
+      } else if (!pendingImmediate) {
+        // Schedule a deferred flush for end of this tick.
+        // Single-shot setImmediate — NOT a recursive loop.
+        // See design/02 §"No Polling".
+        pendingImmediate = setImmediate(() => {
+          pendingImmediate = null;
+          flushBuffer();
+        });
+      }
+
+      callback();
+    },
+    flush(callback) {
+      // Cancel any pending deferred flush and flush synchronously
+      if (pendingImmediate) {
+        clearImmediate(pendingImmediate);
+        pendingImmediate = null;
+      }
+      flushBuffer();
+      callback();
+    },
+  });
+
+  function flushBuffer() {
+    if (bufferedChunks.length === 0) return;
+
+    const merged = Buffer.concat(bufferedChunks, bufferByteLength);
+    bufferedChunks = [];
+    bufferByteLength = 0;
+    transform.push(merged);
+  }
+
+  return transform;
+}
+
+// ─── Injection Transforms ────────────────────────────────────────────────────
+
+import { createMachine } from '../utils/state-machine.js';
+import { flightChunkScript } from './flight-scripts.js';
+import {
+  flightInjectionTransitions,
+  isHtmlDone,
+  isPullDone,
+  type FlightInjectionState,
+  type FlightInjectionEvent,
+} from './flight-injection-state.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
+import { logStreamingError } from './logger.js';
+
+// ─── Move Suffix Transform ───────────────────────────────────────────────────
+
+const SUFFIX = '</body></html>';
+const SUFFIX_BUF = Buffer.from(SUFFIX, 'utf-8');
+
+/**
+ * Node.js Transform that moves `</body></html>` to the end of the stream.
+ *
+ * Equivalent to createMoveSuffixStream() in html-injectors.ts.
+ * Strips the suffix when first encountered and re-emits it in flush().
+ * If no suffix is found, it's appended anyway for well-formed HTML.
+ */
+export function createNodeMoveSuffixTransform(): Transform {
+  let foundSuffix = false;
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      if (foundSuffix) {
+        this.push(chunk);
+        callback();
+        return;
+      }
+
+      const text = chunk.toString('utf-8');
+      const idx = text.indexOf(SUFFIX);
+      if (idx === -1) {
+        this.push(chunk);
+        callback();
+        return;
+      }
+
+      foundSuffix = true;
+
+      // If the entire chunk is exactly the suffix, skip it
+      if (chunk.byteLength === SUFFIX_BUF.byteLength) {
+        callback();
+        return;
+      }
+
+      // Emit content before the suffix
+      const before = text.slice(0, idx);
+      const after = text.slice(idx + SUFFIX.length);
+      if (before) this.push(Buffer.from(before, 'utf-8'));
+      if (after) this.push(Buffer.from(after, 'utf-8'));
+      callback();
+    },
+    flush(callback) {
+      // Always emit the suffix at the very end
+      this.push(SUFFIX_BUF);
+      callback();
+    },
+  });
+}
+
+// ─── 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 target = '</head>';
+  const tailLen = target.length - 1;
+  let injected = false;
+  let tail = '';
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      if (injected) {
+        callback(null, chunk);
+        return;
+      }
+
+      const text = tail + chunk.toString('utf-8');
+      const tagIndex = text.indexOf(target);
+
+      if (tagIndex !== -1) {
+        const before = text.slice(0, tagIndex);
+        const after = text.slice(tagIndex);
+        this.push(Buffer.from(before + headHtml + after, 'utf-8'));
+        injected = true;
+        tail = '';
+        callback();
+      } else {
+        const safeEnd = Math.max(0, text.length - tailLen);
+        if (safeEnd > 0) {
+          this.push(Buffer.from(text.slice(0, safeEnd), 'utf-8'));
+        }
+        tail = text.slice(safeEnd);
+        callback();
+      }
+    },
+    flush(callback) {
+      if (!injected && tail) {
+        this.push(Buffer.from(tail, 'utf-8'));
+      }
+      callback();
+    },
+  });
+}
+
+// ─── RSC Flight Injection ────────────────────────────────────────────────────
+
+/**
+ * Node.js Transform that merges RSC script tags into the HTML stream.
+ *
+ * Reads RSC chunks from the provided ReadableStream and injects them
+ * as `<script>` tags between HTML chunks. Scripts are buffered in
+ * pending[] and only drained from transform() (after a complete HTML
+ * chunk) or flush() — never pushed directly from the pull loop.
+ *
+ * Suffix stripping (</body></html>) is handled upstream by
+ * createNodeMoveSuffixTransform. This transform only interleaves
+ * RSC scripts at safe chunk boundaries.
+ *
+ * The RSC stream is a Web ReadableStream (from the tee'd RSC Flight
+ * stream). We read from it using the Web API — this is the one bridge
+ * point between Web Streams and Node.js streams in the pipeline.
+ */
+/**
+ * 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;
+}
+
+export function createNodeFlightInjector(
+  rscStream: ReadableStream<Uint8Array> | undefined,
+  options?: NodeFlightInjectorOptions
+): Transform {
+  if (!rscStream) {
+    return new Transform({
+      transform(chunk, _enc, cb) {
+        cb(null, chunk);
+      },
+    });
+  }
+
+  const timeoutMs = options?.renderTimeoutMs ?? 30_000;
+  const rscReader = rscStream.getReader();
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+
+  const machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
+    initial: { phase: 'init' },
+    transitions: flightInjectionTransitions,
+  });
+
+  // Stored promise from pullLoop — awaited in flush() via .then()
+  // instead of polling. See design/02 §"No Polling".
+  let pullPromise: Promise<void> | null = null;
+
+  // RSC script chunks waiting to be drained at a safe boundary.
+  // pullLoop buffers here; transform() and flush() drain.
+  // Scripts are NEVER pushed directly from pullLoop — they are only
+  // emitted from transform() (after a complete HTML chunk) or flush().
+  // This guarantees scripts never land mid-tag. See TIM-527/TIM-529.
+  const pending: Buffer[] = [];
+
+  // pullLoop reads RSC chunks and buffers them as <script> tags in
+  // pending[]. It does NOT push directly to the transform output —
+  // that would cause scripts to interleave at arbitrary byte
+  // boundaries within HTML chunks (TIM-527). Pending scripts are
+  // drained only from transform() or flush().
+  async function pullLoop(): Promise<void> {
+    // Yield once so the first transform() call can process the shell
+    // HTML chunk before we start reading RSC data.
+    await new Promise<void>((r) => setImmediate(r));
+    try {
+      for (;;) {
+        // Guard each RSC read with a timeout so a permanently hung
+        // RSC stream eventually aborts instead of blocking forever.
+        // See design/02-rendering-pipeline.md §"Streaming Constraints".
+        const readPromise = rscReader.read();
+        const { done, value } =
+          timeoutMs > 0
+            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
+        if (done) {
+          machine.send({ type: 'PULL_DONE' });
+          return;
+        }
+        const decoded = decoder.decode(value, { stream: true });
+        const scriptBuf = Buffer.from(flightChunkScript(decoded), 'utf-8');
+        // Buffer the script — drained by the next transform() or flush().
+        pending.push(scriptBuf);
+        // Yield between reads so HTML chunks get a chance to flow
+        // through transform() first — but only while HTML is still
+        // streaming. Once flush() fires, drain without yielding.
+        if (!isHtmlDone(machine.state)) {
+          await new Promise<void>((r) => setImmediate(r));
+        }
+      }
+    } catch (err) {
+      // On timeout, cancel the RSC reader to release resources.
+      if (err instanceof RenderTimeoutError) {
+        rscReader.cancel(err).catch(() => {});
+      }
+      machine.send({ type: 'PULL_ERROR', error: err });
+    }
+  }
+
+  /** Drain all buffered RSC script chunks to the transform output. */
+  function drainPending(): void {
+    while (pending.length > 0) {
+      transform.push(pending.shift()!);
+    }
+  }
+
+  // No bootstrap script here — the init script is in <head> via
+  // flightInitScript() (see flight-scripts.ts). This ensures __timber_f
+  // exists before any chunk scripts execute.
+
+  const transform = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      const isFirst = machine.state.phase === 'init';
+      if (isFirst) {
+        machine.send({ type: 'FIRST_CHUNK' });
+      }
+
+      // 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 each chunk is
+      // a coherent HTML fragment. Suffix stripping is handled upstream
+      // by createNodeMoveSuffixTransform (TIM-530).
+      transform.push(chunk);
+      drainPending();
+
+      // Start the pull loop on the first HTML chunk.
+      if (isFirst) {
+        pullPromise = pullLoop();
+      }
+      callback();
+    },
+    flush(callback) {
+      // All HTML chunks have been emitted. Transition to flushing —
+      // the pull loop will stop yielding between RSC reads since
+      // isHtmlDone() now returns true.
+      machine.send({ type: 'HTML_DONE' });
+
+      const finish = () => {
+        // Drain any remaining buffered RSC scripts
+        drainPending();
+        if (machine.state.phase === 'error') {
+          const err = machine.state.error;
+          transform.destroy(err instanceof Error ? err : new Error(String(err)));
+          return;
+        }
+        callback();
+      };
+
+      if (isPullDone(machine.state)) {
+        finish();
+        return;
+      }
+      // Wait for the RSC pull loop promise to resolve instead of
+      // polling with setImmediate. No CPU spin, no busy-poll —
+      // just a Promise chain. See design/02 §"No Polling".
+      if (!pullPromise) {
+        pullPromise = pullLoop();
+      }
+      pullPromise.then(finish, (err) => {
+        machine.send({ type: 'PULL_ERROR', error: err });
+        finish();
+      });
+    },
+  });
+
+  return transform;
+}
+
+// ─── Error Handling ──────────────────────────────────────────────────────────
+
+const NOINDEX_SCRIPT =
+  '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';
+
+/**
+ * Node.js Transform that catches post-shell streaming errors.
+ *
+ * Equivalent to wrapStreamWithErrorHandling() in ssr-render.ts.
+ * Catches errors from React's streaming phase (deny/throw inside Suspense
+ * after the shell has flushed) and closes the stream cleanly.
+ */
+export function createNodeErrorHandler(signal?: AbortSignal): Transform {
+  const transform = new Transform({
+    transform(chunk, _encoding, callback) {
+      callback(null, chunk);
+    },
+  });
+
+  transform.on('error', (error) => {
+    const isAbort =
+      (error instanceof DOMException && error.name === 'AbortError') ||
+      (error instanceof Error && error.name === 'AbortError') ||
+      signal?.aborted;
+
+    if (isAbort) {
+      transform.end();
+      return;
+    }
+
+    logStreamingError({ error });
+    transform.push(Buffer.from(NOINDEX_SCRIPT, 'utf-8'));
+    transform.end();
+  });
+
+  return transform;
+}
+
+// ─── Compression ─────────────────────────────────────────────────────────────
+
+const COMPRESSIBLE_TYPES = new Set([
+  'text/html',
+  'text/css',
+  'text/plain',
+  'text/xml',
+  'text/javascript',
+  'text/x-component',
+  'application/json',
+  'application/javascript',
+  'application/xml',
+  'application/xhtml+xml',
+  'application/rss+xml',
+  'application/atom+xml',
+  'image/svg+xml',
+]);
+
+/**
+ * Create a Node.js gzip Transform using native node:zlib.
+ *
+ * Uses `createGzip()` which is backed by C++ zlib — significantly faster
+ * than the Web Streams `CompressionStream` API (which is a JS wrapper
+ * around the same zlib but with per-chunk Promise overhead).
+ *
+ * Returns null if the response shouldn't be compressed (wrong content type,
+ * client doesn't accept gzip, already encoded, etc.).
+ */
+export function createNodeGzipCompressor(
+  requestHeaders: Headers,
+  responseHeaders: Headers
+): Transform | null {
+  // Check Accept-Encoding
+  const acceptEncoding = requestHeaders.get('accept-encoding') || '';
+  if (!acceptEncoding.includes('gzip')) return null;
+
+  // Check content type is compressible
+  const contentType = responseHeaders.get('content-type') || '';
+  const mimeType = contentType.split(';')[0].trim().toLowerCase();
+  if (!COMPRESSIBLE_TYPES.has(mimeType)) return null;
+
+  // Don't double-compress
+  if (responseHeaders.has('content-encoding')) return null;
+
+  // Set response headers for gzip
+  responseHeaders.set('content-encoding', 'gzip');
+  responseHeaders.delete('content-length');
+  const existingVary = responseHeaders.get('vary');
+  if (existingVary) {
+    if (!existingVary.toLowerCase().includes('accept-encoding')) {
+      responseHeaders.set('vary', existingVary + ', Accept-Encoding');
+    }
+  } else {
+    responseHeaders.set('vary', 'Accept-Encoding');
+  }
+
+  // Z_SYNC_FLUSH ensures each chunk is flushed to the output immediately.
+  // Without it, gzip buffers internally and the browser doesn't receive
+  // the HTML shell until the gzip stream closes — breaking streaming.
+  // ~2–5% size overhead vs Z_NO_FLUSH but preserves correct streaming.
+  return createGzip({ flush: constants.Z_SYNC_FLUSH });
+}