@timber-js/app 0.2.0-alpha.34 → 0.2.0-alpha.35

package/src/server/flight-injection-state.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared state machine types and transitions for RSC Flight injection.
+ *
+ * Both html-injectors.ts (Web Streams) and node-stream-transforms.ts
+ * (Node.js streams) implement identical state transitions — only the
+ * I/O primitives differ. This module defines the discriminated union
+ * states and the transition map once.
+ *
+ * Valid state flow:
+ *   init → streaming → body-level → flushing → done
+ *                  └──────────────→ flushing → done
+ *   (any) → error
+ *
+ * Design doc: 02-rendering-pipeline.md
+ */
+
+import type { TransitionMap } from '../utils/state-machine.js';
+
+// ─── States ──────────────────────────────────────────────────────────────────
+
+/** Waiting for first HTML chunk. Pull loop not started. */
+export interface InitState {
+  phase: 'init';
+}
+
+/** HTML chunks flowing, pull loop running, suffix not yet stripped. */
+export interface StreamingState {
+  phase: 'streaming';
+}
+
+/**
+ * Suffix (</body></html>) stripped. RSC scripts injected at body level.
+ * HTML may still be streaming (Suspense chunks after suffix).
+ */
+export interface BodyLevelState {
+  phase: 'body-level';
+}
+
+/** HTML stream done (flush fired). Draining remaining RSC chunks. */
+export interface FlushingState {
+  phase: 'flushing';
+  /** When true, suffix was found before flushing. */
+  hadSuffix: boolean;
+}
+
+/** All streams consumed. Terminal state. */
+export interface DoneState {
+  phase: 'done';
+  hadSuffix: boolean;
+}
+
+/** Pull loop failed. Terminal state with captured error. */
+export interface ErrorState {
+  phase: 'error';
+  error: unknown;
+}
+
+export type FlightInjectionState =
+  | InitState
+  | StreamingState
+  | BodyLevelState
+  | FlushingState
+  | DoneState
+  | ErrorState;
+
+// ─── Events ──────────────────────────────────────────────────────────────────
+
+/** First HTML chunk arrived — start the pull loop. */
+export interface FirstChunkEvent {
+  type: 'FIRST_CHUNK';
+}
+
+/** The </body></html> suffix was found and stripped. */
+export interface SuffixFoundEvent {
+  type: 'SUFFIX_FOUND';
+}
+
+/** HTML stream finished (flush/end). */
+export interface HtmlDoneEvent {
+  type: 'HTML_DONE';
+}
+
+/** RSC pull loop completed (all chunks read or stream closed). */
+export interface PullDoneEvent {
+  type: 'PULL_DONE';
+}
+
+/** RSC pull loop encountered an error. */
+export interface PullErrorEvent {
+  type: 'PULL_ERROR';
+  error: unknown;
+}
+
+export type FlightInjectionEvent =
+  | FirstChunkEvent
+  | SuffixFoundEvent
+  | HtmlDoneEvent
+  | PullDoneEvent
+  | PullErrorEvent;
+
+// ─── Transitions ─────────────────────────────────────────────────────────────
+
+export const flightInjectionTransitions: TransitionMap<FlightInjectionState, FlightInjectionEvent> =
+  {
+    'init': {
+      FIRST_CHUNK: (): StreamingState => ({ phase: 'streaming' }),
+      // Edge case: HTML stream ends immediately (empty body)
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing', hadSuffix: false }),
+    },
+    'streaming': {
+      SUFFIX_FOUND: (): BodyLevelState => ({ phase: 'body-level' }),
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing', hadSuffix: false }),
+      PULL_DONE: (): StreamingState => ({ phase: 'streaming' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+    'body-level': {
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing', hadSuffix: true }),
+      PULL_DONE: (): BodyLevelState => ({ phase: 'body-level' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+    'flushing': {
+      PULL_DONE: (s): DoneState => ({ phase: 'done', hadSuffix: s.hadSuffix }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+      // Suffix can be found during flushing if flush() processes remaining text
+      SUFFIX_FOUND: (_s): FlushingState => ({ phase: 'flushing', hadSuffix: true }),
+    },
+  };
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Whether the machine is in a state where the suffix has been stripped. */
+export function isSuffixStripped(state: FlightInjectionState): boolean {
+  switch (state.phase) {
+    case 'body-level':
+      return true;
+    case 'flushing':
+    case 'done':
+      return state.hadSuffix;
+    default:
+      return false;
+  }
+}
+
+/** Whether the HTML stream has finished (flush/end fired). */
+export function isHtmlDone(state: FlightInjectionState): boolean {
+  return state.phase === 'flushing' || state.phase === 'done';
+}
+
+/** Whether the RSC pull loop has completed. */
+export function isPullDone(state: FlightInjectionState): boolean {
+  return state.phase === 'done' || state.phase === 'error';
+}

package/src/server/form-data.ts

@@ -173,4 +173,80 @@ export const coerce = {
       return undefined;
     }
   },
+
+  /**
+   * Coerce a date string to a Date object.
+   * Handles `<input type="date">` (`"2024-01-15"`), `<input type="datetime-local">`
+   * (`"2024-01-15T10:30"`), and full ISO 8601 strings.
+   * - Valid date string → `Date`
+   * - `""` / `undefined` / `null` → `undefined`
+   * - Invalid date strings → `undefined` (schema validation will catch this)
+   * - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`
+   */
+  date(value: unknown): Date | undefined {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (value instanceof Date) return value;
+    if (typeof value !== 'string') return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) return undefined;
+
+    // Overflow detection: extract Y/M/D from the input string and verify
+    // they match the parsed Date components. new Date('2024-02-31') silently
+    // normalizes to March 2nd — we reject such inputs.
+    const ymdMatch = value.match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (ymdMatch) {
+      const inputYear = Number(ymdMatch[1]);
+      const inputMonth = Number(ymdMatch[2]);
+      const inputDay = Number(ymdMatch[3]);
+
+      // Use UTC methods for date-only and Z-suffixed strings to avoid
+      // timezone offset shifting the day. For datetime-local (no Z suffix),
+      // the Date constructor parses in local time, so use local methods.
+      const isUTC = value.length === 10 || value.endsWith('Z');
+      const parsedYear = isUTC ? date.getUTCFullYear() : date.getFullYear();
+      const parsedMonth = isUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1;
+      const parsedDay = isUTC ? date.getUTCDate() : date.getDate();
+
+      if (inputYear !== parsedYear || inputMonth !== parsedMonth || inputDay !== parsedDay) {
+        return undefined;
+      }
+    }
+
+    return date;
+  },
+
+  /**
+   * Create a File coercion function with optional size and mime type validation.
+   * Returns the File if valid, `undefined` otherwise.
+   *
+   * ```ts
+   * // Basic — just checks it's a real File
+   * z.preprocess(coerce.file(), z.instanceof(File))
+   *
+   * // With constraints
+   * z.preprocess(
+   *   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
+   *   z.instanceof(File)
+   * )
+   * ```
+   */
+  file(options?: { maxSize?: number; accept?: string[] }): (value: unknown) => File | undefined {
+    return (value: unknown): File | undefined => {
+      if (value === undefined || value === null || value === '') return undefined;
+      if (!(value instanceof File)) return undefined;
+
+      // Empty file input (no selection): browsers submit File with name="" and size=0
+      if (value.size === 0 && value.name === '') return undefined;
+
+      if (options?.maxSize !== undefined && value.size > options.maxSize) {
+        return undefined;
+      }
+
+      if (options?.accept !== undefined && !options.accept.includes(value.type)) {
+        return undefined;
+      }
+
+      return value;
+    };
+  },
 };

package/src/server/html-injectors.ts

@@ -7,6 +7,16 @@
  * Design docs: 02-rendering-pipeline.md, 18-build-system.md §"Entry Files"
  */
 
+import { createMachine } from '../utils/state-machine.js';
+import {
+  flightInjectionTransitions,
+  isSuffixStripped,
+  isHtmlDone,
+  isPullDone,
+  type FlightInjectionState,
+  type FlightInjectionEvent,
+} from './flight-injection-state.js';
+
 /**
  * Inject HTML content before a closing tag in the stream.
  *
@@ -179,6 +189,11 @@ export function createInlinedRscStream(
  * scanning or depth tracking needed — the suffix removal is the
  * structural guarantee.
  *
+ * State machine phases:
+ *   init → streaming → body-level → flushing → done
+ *                  └──────────────→ flushing → done
+ *   (any) → error
+ *
  * Inspired by Next.js createFlightDataInjectionTransformStream.
  */
 function createFlightInjectionTransform(
@@ -190,17 +205,13 @@ function createFlightInjectionTransform(
   const suffixBytes = encoder.encode(suffix);
 
   const rscReader = rscScriptStream.getReader();
+
+  const machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
+    initial: { phase: 'init' },
+    transitions: flightInjectionTransitions,
+  });
+
   let pullPromise: Promise<void> | null = null;
-  let donePulling = false;
-  let pullError: unknown = null;
-  // Once the suffix is stripped, all content is body-level and
-  // scripts can safely be drained after any HTML chunk.
-  let foundSuffix = false;
-  // Set to true in flush() — once all HTML chunks have been emitted,
-  // there's no need to yield between RSC reads. This eliminates
-  // ~36 macrotask yields per request (18 chunks × 2 yields each)
-  // that were the primary source of SSR overhead vs Next.js.
-  let htmlStreamFinished = false;
 
   // RSC script chunks waiting to be injected at the body level.
   const pending: Uint8Array[] = [];
@@ -220,7 +231,7 @@ function createFlightInjectionTransform(
       for (;;) {
         const { done, value } = await rscReader.read();
         if (done) {
-          donePulling = true;
+          machine.send({ type: 'PULL_DONE' });
           return;
         }
         pending.push(value);
@@ -228,13 +239,12 @@ function createFlightInjectionTransform(
         // through transform() first — but only while HTML is still
         // streaming. Once flush() fires (all HTML emitted), drain
         // remaining RSC chunks without yielding.
-        if (!htmlStreamFinished) {
+        if (!isHtmlDone(machine.state)) {
           await new Promise<void>((r) => setImmediate(r));
         }
       }
     } catch (err) {
-      pullError = err;
-      donePulling = true;
+      machine.send({ type: 'PULL_ERROR', error: err });
     }
   }
 
@@ -243,10 +253,8 @@ function createFlightInjectionTransform(
     while (pending.length > 0) {
       controller.enqueue(pending.shift()!);
     }
-    if (pullError) {
-      const err = pullError;
-      pullError = null;
-      controller.error(err);
+    if (machine.state.phase === 'error') {
+      controller.error(machine.state.error);
     }
   }
 
@@ -257,11 +265,12 @@ function createFlightInjectionTransform(
       // and ensures the shell HTML is enqueued before any RSC
       // script tags. Without this, the pull loop starts eagerly
       // and may read RSC data before the browser has any HTML.
-      if (!pullPromise) {
+      if (machine.state.phase === 'init') {
+        machine.send({ type: 'FIRST_CHUNK' });
         pullPromise = pullLoop();
       }
 
-      if (foundSuffix) {
+      if (isSuffixStripped(machine.state)) {
         // Post-suffix: everything is body-level (Suspense chunks).
         // Emit HTML, then drain any buffered scripts.
         controller.enqueue(chunk);
@@ -273,7 +282,7 @@ function createFlightInjectionTransform(
       const text = decoder.decode(chunk, { stream: true });
       const idx = text.indexOf(suffix);
       if (idx !== -1) {
-        foundSuffix = true;
+        machine.send({ type: 'SUFFIX_FOUND' });
         // Emit everything before the suffix (still inside <body>'s
         // child elements — don't inject scripts here).
         const before = text.slice(0, idx);
@@ -290,20 +299,27 @@ function createFlightInjectionTransform(
       }
     },
     flush(controller) {
-      // All HTML chunks have been emitted. Signal the pull loop to
-      // stop yielding between RSC reads — no more HTML to interleave.
-      htmlStreamFinished = true;
+      // All HTML chunks have been emitted. Transition to flushing —
+      // the pull loop will stop yielding between RSC reads since
+      // isHtmlDone() now returns true. This eliminates ~36 macrotask
+      // yields per request (18 chunks × 2 yields each) that were the
+      // primary source of SSR overhead vs Next.js.
+      machine.send({ type: 'HTML_DONE' });
 
       // Drain remaining RSC chunks at body level
       const finish = () => {
         drainPending(controller);
         // Re-emit the suffix at the very end so HTML is well-formed
-        if (foundSuffix) {
+        if (machine.state.phase === 'done' && machine.state.hadSuffix) {
+          controller.enqueue(suffixBytes);
+        } else if (machine.state.phase === 'flushing' && machine.state.hadSuffix) {
+          // Pull was already done before flush — drainPending didn't
+          // transition, but we still need the suffix
           controller.enqueue(suffixBytes);
         }
       };
 
-      if (donePulling) {
+      if (isPullDone(machine.state)) {
         finish();
         return;
       }

package/src/server/index.ts

@@ -6,19 +6,17 @@ export type { MiddlewareContext } from './types';
 export type { RouteContext } from './types';
 export type { Metadata, MetadataRoute } from './types';
 
-// Request Context — ALS-backed headers(), cookies(), and searchParams()
+// Request Context — ALS-backed headers(), cookies(), and rawSearchParams()
 // Design doc: design/04-authorization.md §"AccessContext does not include cookies or headers"
 // Design doc: design/23-search-params.md §"Server Integration"
 export {
   headers,
   cookies,
-  searchParams,
-  setParsedSearchParams,
+  rawSearchParams,
   runWithRequestContext,
   setMutableCookieContext,
   markResponseFlushed,
   getSetCookieHeaders,
-  setCookieSecrets,
 } from './request-context';
 export type { ReadonlyHeaders, RequestCookies, CookieOptions } from './request-context';
 

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

@@ -20,6 +20,16 @@
 import { Transform } from 'node:stream';
 import { createGzip, constants } from 'node:zlib';
 
+import { createMachine } from '../utils/state-machine.js';
+import {
+  flightInjectionTransitions,
+  isSuffixStripped,
+  isHtmlDone,
+  isPullDone,
+  type FlightInjectionState,
+  type FlightInjectionEvent,
+} from './flight-injection-state.js';
+
 // ─── Head Injection ──────────────────────────────────────────────────────────
 
 /**
@@ -124,29 +134,26 @@ export function createNodeFlightInjector(
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
 
-  let donePulling = false;
-  let pullError: unknown = null;
-  let foundSuffix = false;
-  let htmlStreamFinished = false;
-  // Reference to the transform instance, set on first transform() call.
-  // Used by pullLoop to push RSC chunks directly to the output without
-  // waiting for HTML chunks to trigger drainPending.
-  let transformRef: Transform | null = null;
+  const machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
+    initial: { phase: 'init' },
+    transitions: flightInjectionTransitions,
+  });
 
   // pullLoop reads RSC chunks and pushes them directly to the transform
   // output as <script> tags. This ensures RSC data is delivered to the
   // browser as soon as it's available — not deferred until the next HTML
   // chunk. Critical for streaming: the shell RSC payload must arrive
   // with the shell HTML so hydration can start before Suspense resolves.
-  async function pullLoop(): Promise<void> {
-    // Yield once so the first transform() call can set transformRef and
-    // emit the bootstrap signal before we start pushing data chunks.
+
+  async function pullLoop(stream: Transform): Promise<void> {
+    // Yield once so the first transform() call can emit the bootstrap
+    // signal before we start pushing data chunks.
     await new Promise<void>((r) => setImmediate(r));
     try {
       for (;;) {
         const { done, value } = await rscReader.read();
         if (done) {
-          donePulling = true;
+          machine.send({ type: 'PULL_DONE' });
           return;
         }
         const decoded = decoder.decode(value, { stream: true });
@@ -154,34 +161,37 @@ export function createNodeFlightInjector(
         const scriptBuf = Buffer.from(`<script>self.__timber_f.push(${escaped})</script>`, 'utf-8');
         // Push directly to the transform output — don't wait for an
         // HTML chunk to trigger drainPending.
-        if (transformRef) {
-          transformRef.push(scriptBuf);
-        }
-        if (!htmlStreamFinished) {
+        stream.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 (all HTML emitted), drain
+        // remaining RSC chunks without yielding.
+        if (!isHtmlDone(machine.state)) {
           await new Promise<void>((r) => setImmediate(r));
         }
       }
     } catch (err) {
-      pullError = err;
-      donePulling = true;
+      machine.send({ type: 'PULL_ERROR', error: err });
     }
   }
 
-  return new Transform({
+  // Bootstrap script to emit after the first HTML chunk (but before
+  // any RSC data chunks). Must come AFTER the doctype + <html> so
+  // browsers don't enter Quirks Mode.
+  const bootstrapBuf = Buffer.from(
+    `<script>(self.__timber_f=self.__timber_f||[]).push(${htmlEscapeJsonString(JSON.stringify([0]))})</script>`,
+    'utf-8'
+  );
+
+  const transform = new Transform({
     transform(chunk: Buffer, _encoding, callback) {
-      if (!transformRef) {
-        transformRef = this;
-        // Emit bootstrap signal with the first HTML chunk (the shell).
-        // This must arrive before any data chunks.
-        const bootstrap = `<script>(self.__timber_f=self.__timber_f||[]).push(${htmlEscapeJsonString(JSON.stringify([0]))})</script>`;
-        this.push(Buffer.from(bootstrap, 'utf-8'));
-        // Start the pull loop — it will push RSC data chunks directly
-        // to the transform output as they arrive from the RSC stream.
-        pullLoop();
+      const isFirst = machine.state.phase === 'init';
+      if (isFirst) {
+        machine.send({ type: 'FIRST_CHUNK' });
       }
 
-      if (foundSuffix) {
-        this.push(chunk);
+      if (isSuffixStripped(machine.state)) {
+        transform.push(chunk);
         callback();
         return;
       }
@@ -189,38 +199,53 @@ export function createNodeFlightInjector(
       const text = chunk.toString('utf-8');
       const idx = text.indexOf(suffix);
       if (idx !== -1) {
-        foundSuffix = true;
+        machine.send({ type: 'SUFFIX_FOUND' });
         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'));
+        if (before) transform.push(Buffer.from(before, 'utf-8'));
+        if (after) transform.push(Buffer.from(after, 'utf-8'));
       } else {
-        this.push(chunk);
+        transform.push(chunk);
+      }
+
+      // Emit bootstrap AFTER the first HTML chunk so the doctype and
+      // <html> tag are the first bytes the browser sees. Then start
+      // the pull loop to stream RSC data chunks.
+      if (isFirst) {
+        transform.push(bootstrapBuf);
+        pullLoop(transform);
       }
       callback();
     },
     flush(callback) {
-      htmlStreamFinished = true;
+      // 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 = () => {
-        if (pullError) {
-          this.destroy(pullError instanceof Error ? pullError : new Error(String(pullError)));
+        if (machine.state.phase === 'error') {
+          const err = machine.state.error;
+          transform.destroy(err instanceof Error ? err : new Error(String(err)));
           return;
         }
-        if (foundSuffix) {
-          this.push(suffixBuf);
+        const hadSuffix =
+          (machine.state.phase === 'done' && machine.state.hadSuffix) ||
+          (machine.state.phase === 'flushing' && machine.state.hadSuffix);
+        if (hadSuffix) {
+          transform.push(suffixBuf);
         }
         callback();
       };
 
-      if (donePulling) {
+      if (isPullDone(machine.state)) {
         finish();
         return;
       }
       // Wait for the RSC stream to finish before closing.
       // pullLoop is already running and pushing directly.
       const waitForPull = () => {
-        if (donePulling || pullError) {
+        if (isPullDone(machine.state)) {
           finish();
         } else {
           setImmediate(waitForPull);
@@ -229,6 +254,8 @@ export function createNodeFlightInjector(
       waitForPull();
     },
   });
+
+  return transform;
 }
 
 // ─── Error Handling ──────────────────────────────────────────────────────────