@timber-js/app 0.1.1 → 0.1.2

package/src/server/action-handler.ts

@@ -0,0 +1,325 @@
+/**
+ * Server Action Request Handler — dispatches incoming action POST requests.
+ *
+ * Handles both JS-enabled (RSC) and no-JS (HTML form POST) action submissions.
+ * Wired into the RSC entry to intercept action requests before the render pipeline.
+ *
+ * Flow:
+ * 1. Detect action request (POST with `x-rsc-action` header or form action fields)
+ * 2. CSRF validation
+ * 3. Load and execute the server action
+ * 4. Return RSC stream (with-JS) or 302 redirect (no-JS)
+ *
+ * See design/08-forms-and-actions.md
+ */
+
+import {
+  loadServerAction,
+  decodeReply,
+  decodeAction,
+  renderToReadableStream,
+} from '@vitejs/plugin-rsc/rsc';
+
+import { validateCsrf, type CsrfConfig } from './csrf.js';
+import { executeAction, type RevalidateRenderer } from './actions.js';
+import {
+  runWithRequestContext,
+  setMutableCookieContext,
+  getSetCookieHeaders,
+} from './request-context.js';
+import { handleActionError } from './action-client.js';
+import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './body-limits.js';
+import { parseFormData } from './form-data.js';
+import type { FormFlashData } from './form-flash.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** Configuration for the action handler. */
+export interface ActionDispatchConfig {
+  /** CSRF configuration. */
+  csrf: CsrfConfig;
+  /** Renderer for revalidatePath — produces RSC flight payloads. */
+  revalidateRenderer?: RevalidateRenderer;
+  /** Body size limits (from timber.config.ts). */
+  bodyLimits?: BodyLimitsConfig;
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────
+
+const RSC_CONTENT_TYPE = 'text/x-component';
+
+// ─── Detection ────────────────────────────────────────────────────────────
+
+/**
+ * Check if a request is a server action invocation.
+ *
+ * Two cases:
+ * - With JS: POST with `x-rsc-action` header (client callServer dispatch)
+ * - Without JS: POST with form data containing `$ACTION_REF` or `$ACTION_KEY`
+ *   (React's progressive enhancement hidden fields)
+ */
+export function isActionRequest(req: Request): boolean {
+  if (req.method !== 'POST') return false;
+
+  // With-JS case: explicit action header
+  if (req.headers.get('x-rsc-action')) return true;
+
+  // No-JS case: check Content-Type for form data
+  const ct = req.headers.get('Content-Type') ?? '';
+  if (ct.includes('application/x-www-form-urlencoded') || ct.includes('multipart/form-data')) {
+    return true;
+  }
+
+  return false;
+}
+
+// ─── Handler ──────────────────────────────────────────────────────────────
+
+/** Signal from handleFormAction to re-render the page with flash data instead of redirecting. */
+export interface FormRerender {
+  rerender: FormFlashData;
+}
+
+/**
+ * Handle a server action request.
+ *
+ * Returns a Response, a FormRerender signal (for no-JS validation failure re-render),
+ * or null if this isn't actually an action request (e.g., a regular form POST to an API route).
+ */
+export async function handleActionRequest(
+  req: Request,
+  config: ActionDispatchConfig
+): Promise<Response | FormRerender | null> {
+  // CSRF validation — reject cross-origin mutation requests.
+  const csrfResult = validateCsrf(req, config.csrf);
+  if (!csrfResult.ok) {
+    return new Response(null, { status: csrfResult.status });
+  }
+
+  // Body size limits — reject oversized requests before parsing.
+  // Multipart requests (file uploads) get a higher limit than regular actions.
+  const bodyKind = (req.headers.get('Content-Type') ?? '').includes('multipart/form-data')
+    ? 'upload'
+    : 'action';
+  const limitsResult = enforceBodyLimits(req, bodyKind, config.bodyLimits ?? {});
+  if (!limitsResult.ok) {
+    return new Response(null, { status: limitsResult.status });
+  }
+
+  // Run inside request context so headers(), cookies() work in actions.
+  // Actions are a mutable context — they can set cookies (design/29-cookies.md).
+  return runWithRequestContext(req, async () => {
+    setMutableCookieContext(true);
+    const actionId = req.headers.get('x-rsc-action');
+
+    let result: Response | FormRerender | null;
+    if (actionId) {
+      // With-JS path: client sent action ID in header, args in body
+      result = await handleRscAction(req, actionId, config);
+    } else {
+      // No-JS path: form POST with React's hidden action fields
+      result = await handleFormAction(req, config);
+    }
+
+    // Apply cookie jar to action responses
+    if (result instanceof Response) {
+      for (const value of getSetCookieHeaders()) {
+        result.headers.append('Set-Cookie', value);
+      }
+    }
+    return result;
+  });
+}
+
+// ─── With-JS Action ───────────────────────────────────────────────────────
+
+/**
+ * Handle an RSC action request (JavaScript enabled).
+ *
+ * The client serialized the action args via `encodeReply` and sent them
+ * as the request body. The action ID is in the `x-rsc-action` header.
+ */
+async function handleRscAction(
+  req: Request,
+  actionId: string,
+  config: ActionDispatchConfig
+): Promise<Response> {
+  // Load the server action function by reference ID
+  const actionFn = (await loadServerAction(actionId)) as (...args: unknown[]) => Promise<unknown>;
+
+  // Decode the args from the request body (RSC wire format)
+  const contentType = req.headers.get('Content-Type') ?? '';
+  let args: unknown[];
+
+  if (contentType.includes('multipart/form-data')) {
+    // FormData-based args (file uploads, etc.)
+    const formData = await req.formData();
+    // Enforce field count limit after parsing FormData.
+    const fieldResult = enforceFieldLimit(formData, config.bodyLimits ?? {});
+    if (!fieldResult.ok) {
+      return new Response(null, { status: fieldResult.status });
+    }
+    args = (await decodeReply(formData)) as unknown[];
+  } else {
+    // Text-based args
+    const body = await req.text();
+    args = (await decodeReply(body)) as unknown[];
+  }
+
+  // Execute the action with revalidation tracking.
+  // Errors are caught here so raw 'use server' functions (not using
+  // createActionClient) still return structured error responses instead
+  // of leaking stack traces as 500s.
+  let result;
+  try {
+    result = await executeAction(actionFn, args, {
+      renderer: config.revalidateRenderer,
+    });
+  } catch (error) {
+    // Log full error server-side for debugging
+    console.error('[timber] server action error:', error);
+
+    // Return structured error response — ActionError gets its code/data,
+    // unexpected errors get sanitized { code: 'INTERNAL_ERROR' }
+    const errorResult = handleActionError(error);
+    const rscStream = renderToReadableStream(errorResult);
+    return new Response(rscStream, {
+      status: 200,
+      headers: { 'Content-Type': RSC_CONTENT_TYPE },
+    });
+  }
+
+  // Handle redirect — encode in RSC stream for client-side SPA navigation.
+  // The client detects X-Timber-Redirect and calls router.navigate() instead
+  // of following an HTTP 302 (which would cause a full page reload).
+  if (result.redirectTo) {
+    const redirectPayload = {
+      _redirect: result.redirectTo,
+      _status: result.redirectStatus ?? 302,
+    };
+    const rscStream = renderToReadableStream(redirectPayload);
+    return new Response(rscStream, {
+      status: 200,
+      headers: {
+        'Content-Type': RSC_CONTENT_TYPE,
+        'X-Timber-Redirect': result.redirectTo,
+      },
+    });
+  }
+
+  // Render the action result as an RSC stream.
+  // When revalidatePath was called, piggyback the revalidated element tree
+  // alongside the action result in a single renderToReadableStream call.
+  // The client detects the X-Timber-Revalidation header and unpacks both.
+  const headers: Record<string, string> = {
+    'Content-Type': RSC_CONTENT_TYPE,
+  };
+
+  let payload: unknown;
+  if (result.revalidation) {
+    // Wrapper object — Next.js-style pattern: action result + element tree
+    // serialized together so React Flight handles both in one stream.
+    payload = {
+      _action: result.actionResult,
+      _tree: result.revalidation.element,
+    };
+    headers['X-Timber-Revalidation'] = '1';
+    // Forward head elements as JSON so the client can update <head>.
+    if (result.revalidation.headElements.length > 0) {
+      headers['X-Timber-Head'] = JSON.stringify(result.revalidation.headElements);
+    }
+  } else {
+    payload = result.actionResult;
+  }
+
+  const rscStream = renderToReadableStream(payload);
+
+  return new Response(rscStream, {
+    status: 200,
+    headers,
+  });
+}
+
+// ─── No-JS Form Action ───────────────────────────────────────────────────
+
+/**
+ * Handle a no-JS form action (progressive enhancement fallback).
+ *
+ * React embeds `$ACTION_REF` / `$ACTION_KEY` hidden fields in the form.
+ * We use `decodeAction` to resolve the action function from the form data,
+ * execute it, then redirect back to the form's page.
+ */
+async function handleFormAction(
+  req: Request,
+  config: ActionDispatchConfig
+): Promise<Response | FormRerender | null> {
+  // Clone before consuming — if this turns out not to be a server action form,
+  // we return null and the original request body must remain readable for
+  // downstream route handlers. Clone is cheap (shares the body buffer until read).
+  const formData = await req.clone().formData();
+
+  // Enforce field count limit after parsing FormData.
+  const fieldResult = enforceFieldLimit(formData, config.bodyLimits ?? {});
+  if (!fieldResult.ok) {
+    return new Response(null, { status: fieldResult.status });
+  }
+
+  // Check if this is actually a React server action form.
+  // If there's no $ACTION_REF_* or $ACTION_KEY, it's a regular form POST
+  // that should be handled by the route's route handler, not here.
+  // React uses `$ACTION_REF_` + identifierPrefix — since we don't set one,
+  // the suffix is empty. Check for any key starting with $ACTION_REF_ or $ACTION_ID_.
+  const allKeys = [...formData.keys()];
+  const hasActionField = allKeys.some(
+    (k) => k.startsWith('$ACTION_REF_') || k.startsWith('$ACTION_ID_')
+  );
+  if (!hasActionField && !formData.has('$ACTION_KEY')) {
+    return null;
+  }
+
+  // Capture submitted values for re-render on validation failure.
+  // Parse before decodeAction consumes the FormData.
+  const submittedValues = parseFormData(formData);
+
+  // decodeAction resolves the action function from the form data's hidden fields.
+  // It returns a bound function with the form data already applied.
+  const actionFn = (await decodeAction(formData)) as (...args: unknown[]) => Promise<unknown>;
+
+  // Execute the action — no additional args needed (form data is already bound).
+  // Errors are caught to prevent stack traces from leaking in the response.
+  let result;
+  try {
+    result = await executeAction(actionFn, [], {
+      renderer: config.revalidateRenderer,
+    });
+  } catch (error) {
+    console.error('[timber] server action error:', error);
+
+    // Return the error as flash data for re-render.
+    // handleActionError produces { serverError } for ActionErrors
+    // and { serverError: { code: 'INTERNAL_ERROR' } } for unexpected errors.
+    const errorResult = handleActionError(error);
+    return {
+      rerender: {
+        ...errorResult,
+        submittedValues,
+      },
+    };
+  }
+
+  // Handle redirect from the action (e.g. redirect() called in the action body)
+  if (result.redirectTo) {
+    return new Response(null, {
+      status: result.redirectStatus ?? 302,
+      headers: { Location: result.redirectTo },
+    });
+  }
+
+  // Re-render the page with the action result as flash data.
+  // The server component reads the flash via getFormFlash() and passes it
+  // to the client form component as the initial useActionState value.
+  // This handles both success ({ data }) and validation failure
+  // ({ validationErrors, submittedValues }) — the form is the single source of truth.
+  const actionResult = result.actionResult as FormFlashData;
+  return { rerender: actionResult };
+}

package/src/server/actions.ts

@@ -0,0 +1,236 @@
+/**
+ * Server action primitives: revalidatePath, revalidateTag, and the action handler.
+ *
+ * - revalidatePath(path) re-renders the route at that path and returns the RSC
+ *   flight payload for inline reconciliation.
+ * - revalidateTag(tag) invalidates cached shells and 'use cache' entries by tag.
+ *
+ * Both are callable from anywhere on the server — actions, API routes, handlers.
+ *
+ * The action handler processes incoming action requests, validates CSRF,
+ * enforces body limits, executes the action, and returns the response
+ * (with piggybacked RSC payload if revalidatePath was called).
+ *
+ * See design/08-forms-and-actions.md
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { CacheHandler } from '#/cache/index';
+import { RedirectSignal } from './primitives';
+import { withSpan } from './tracing';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/** Result of rendering a revalidation — element tree before RSC serialization. */
+export interface RevalidationResult {
+  /** React element tree (pre-serialization — passed to renderToReadableStream). */
+  element: unknown;
+  /** Resolved head elements for metadata. */
+  headElements: unknown[];
+}
+
+/** Renderer function that builds a React element tree for a given path. */
+export type RevalidateRenderer = (path: string) => Promise<RevalidationResult>;
+
+/** Per-request revalidation state — tracks revalidatePath/Tag calls within an action. */
+export interface RevalidationState {
+  /** Paths to re-render (populated by revalidatePath calls). */
+  paths: string[];
+  /** Tags to invalidate (populated by revalidateTag calls). */
+  tags: string[];
+}
+
+/** Options for creating the action handler. */
+export interface ActionHandlerConfig {
+  /** Cache handler for tag invalidation. */
+  cacheHandler?: CacheHandler;
+  /** Renderer for producing RSC payloads during revalidation. */
+  renderer?: RevalidateRenderer;
+}
+
+/** Result of handling a server action request. */
+export interface ActionHandlerResult {
+  /** The action's return value (serialized). */
+  actionResult: unknown;
+  /** Revalidation result if revalidatePath was called (element tree, not yet serialized). */
+  revalidation?: RevalidationResult;
+  /** Redirect location if a RedirectSignal was thrown during revalidation. */
+  redirectTo?: string;
+  /** Redirect status code. */
+  redirectStatus?: number;
+}
+
+// ─── Revalidation State ──────────────────────────────────────────────────
+
+// Per-request revalidation state stored in AsyncLocalStorage.
+// This ensures concurrent requests never share or overwrite each other's state
+// (the previous module-level global was vulnerable to cross-request pollution).
+const revalidationAls = new AsyncLocalStorage<RevalidationState>();
+
+/**
+ * Set the revalidation state for the current action execution.
+ * @internal — kept for test compatibility; prefer executeAction() which uses ALS.
+ */
+export function _setRevalidationState(state: RevalidationState): void {
+  // Enter ALS scope — this is only used by tests that call revalidatePath/Tag
+  // directly without going through executeAction().
+  revalidationAls.enterWith(state);
+}
+
+/**
+ * Clear the revalidation state after action execution.
+ * @internal — kept for test compatibility.
+ */
+export function _clearRevalidationState(): void {
+  revalidationAls.enterWith(undefined as unknown as RevalidationState);
+}
+
+/**
+ * Get the current revalidation state. Throws if called outside an action context.
+ * @internal
+ */
+function getRevalidationState(): RevalidationState {
+  const state = revalidationAls.getStore();
+  if (!state) {
+    throw new Error(
+      'revalidatePath/revalidateTag called outside of a server action context. ' +
+        'These functions can only be called during action execution.'
+    );
+  }
+  return state;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Re-render the route at `path` and include the RSC flight payload in the
+ * action response. The client reconciles inline — no separate fetch needed.
+ *
+ * Can be called from server actions, API routes, or any server-side context.
+ *
+ * @param path - The path to re-render (e.g. '/dashboard', '/todos').
+ */
+export function revalidatePath(path: string): void {
+  const state = getRevalidationState();
+  if (!state.paths.includes(path)) {
+    state.paths.push(path);
+  }
+}
+
+/**
+ * Invalidate all pre-rendered shells and 'use cache' entries tagged with `tag`.
+ * Does not return a payload — the next request for an invalidated route re-renders fresh.
+ *
+ * @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
+ */
+export function revalidateTag(tag: string): void {
+  const state = getRevalidationState();
+  if (!state.tags.includes(tag)) {
+    state.tags.push(tag);
+  }
+}
+
+// ─── Action Handler ──────────────────────────────────────────────────────
+
+/**
+ * Execute a server action and process revalidation.
+ *
+ * 1. Sets up revalidation state
+ * 2. Calls the action function
+ * 3. Processes revalidateTag calls (invalidates cache entries)
+ * 4. Processes revalidatePath calls (re-renders and captures RSC payload)
+ * 5. Returns the action result + optional RSC payload
+ *
+ * @param actionFn - The server action function to execute.
+ * @param args - Arguments to pass to the action.
+ * @param config - Handler configuration (cache handler, renderer).
+ */
+export async function executeAction(
+  actionFn: (...args: unknown[]) => Promise<unknown>,
+  args: unknown[],
+  config: ActionHandlerConfig = {},
+  spanMeta?: { actionFile?: string; actionName?: string }
+): Promise<ActionHandlerResult> {
+  const state: RevalidationState = { paths: [], tags: [] };
+  let actionResult: unknown;
+  let redirectTo: string | undefined;
+  let redirectStatus: number | undefined;
+
+  // Run the action inside ALS scope so revalidatePath/Tag resolve to this
+  // request's state object — concurrent requests each get their own scope.
+  await revalidationAls.run(state, async () => {
+    try {
+      actionResult = await withSpan(
+        'timber.action',
+        {
+          ...(spanMeta?.actionFile ? { 'timber.action_file': spanMeta.actionFile } : {}),
+          ...(spanMeta?.actionName ? { 'timber.action_name': spanMeta.actionName } : {}),
+        },
+        () => actionFn(...args)
+      );
+    } catch (error) {
+      if (error instanceof RedirectSignal) {
+        redirectTo = error.location;
+        redirectStatus = error.status;
+      } else {
+        throw error;
+      }
+    }
+  });
+
+  // Process tag invalidation
+  if (state.tags.length > 0 && config.cacheHandler) {
+    await Promise.all(state.tags.map((tag) => config.cacheHandler!.invalidate({ tag })));
+  }
+
+  // Process path revalidation — build element tree (not yet serialized)
+  let revalidation: RevalidationResult | undefined;
+  if (state.paths.length > 0 && config.renderer) {
+    // For now, render the first revalidated path.
+    // Multiple paths could be supported via multipart streaming in the future.
+    const path = state.paths[0];
+    try {
+      revalidation = await config.renderer(path);
+    } catch (renderError) {
+      if (renderError instanceof RedirectSignal) {
+        // Revalidation triggered a redirect (e.g., session expired)
+        redirectTo = renderError.location;
+        redirectStatus = renderError.status;
+      } else {
+        // Log but don't fail the action — revalidation is best-effort
+        console.error('[timber] revalidatePath render failed:', renderError);
+      }
+    }
+  }
+
+  return {
+    actionResult,
+    revalidation,
+    ...(redirectTo ? { redirectTo, redirectStatus } : {}),
+  };
+}
+
+/**
+ * Build an HTTP Response for a no-JS form submission.
+ * Standard POST → 302 redirect pattern.
+ *
+ * @param redirectPath - Where to redirect after the action executes.
+ */
+export function buildNoJsResponse(redirectPath: string, status: number = 302): Response {
+  return new Response(null, {
+    status,
+    headers: { Location: redirectPath },
+  });
+}
+
+/**
+ * Detect whether the incoming request is an RSC action request (with JS)
+ * or a plain HTML form POST (no JS).
+ *
+ * RSC action requests use Accept: text/x-component or Content-Type: text/x-component.
+ */
+export function isRscActionRequest(req: Request): boolean {
+  const accept = req.headers.get('Accept') ?? '';
+  const contentType = req.headers.get('Content-Type') ?? '';
+  return accept.includes('text/x-component') || contentType.includes('text/x-component');
+}

package/src/server/asset-headers.ts

@@ -0,0 +1,81 @@
+/**
+ * Static asset cache header utilities.
+ *
+ * Hashed assets (e.g. /assets/layout-abc123.css) are immutable — the hash
+ * changes when content changes. These get long-lived cache headers:
+ *   Cache-Control: public, max-age=31536000, immutable
+ *
+ * Unhashed assets (e.g. /favicon.ico) get a shorter cache with revalidation:
+ *   Cache-Control: public, max-age=3600, must-revalidate
+ *
+ * This is applied automatically by the framework for static assets served
+ * from the build output. Page responses are NOT affected — those are
+ * controlled by the developer via middleware.ts or proxy.ts.
+ *
+ * Design docs: 18-build-system.md, 06-caching.md
+ */
+
+/**
+ * Regex matching Vite-hashed asset filenames.
+ *
+ * Vite's default naming: `[name]-[hash].[ext]` where hash is 8+ hex chars.
+ * Also matches `[name].[hash].[ext]` pattern.
+ *
+ * Examples:
+ *   /assets/layout-a1b2c3d4.css  → match
+ *   /assets/page-e5f6g7h8.js     → match
+ *   /assets/chunk.a1b2c3d4.js    → match
+ *   /favicon.ico                  → no match
+ *   /index.html                   → no match
+ */
+const HASHED_ASSET_RE = /[-.][\da-f]{8,}\.\w+$/;
+
+/** One year in seconds (365 days). */
+const ONE_YEAR = 31_536_000;
+
+/** One hour in seconds. */
+const ONE_HOUR = 3_600;
+
+/** Cache-Control value for hashed (immutable) assets. */
+export const IMMUTABLE_CACHE = `public, max-age=${ONE_YEAR}, immutable`;
+
+/** Cache-Control value for unhashed static assets. */
+export const STATIC_CACHE = `public, max-age=${ONE_HOUR}, must-revalidate`;
+
+/**
+ * Check if a URL path looks like a hashed asset.
+ */
+export function isHashedAsset(pathname: string): boolean {
+  return HASHED_ASSET_RE.test(pathname);
+}
+
+/**
+ * Get the appropriate Cache-Control header for a static asset path.
+ *
+ * Returns `immutable` for hashed assets, short-lived for unhashed.
+ */
+export function getAssetCacheControl(pathname: string): string {
+  return isHashedAsset(pathname) ? IMMUTABLE_CACHE : STATIC_CACHE;
+}
+
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * Vite places all hashed chunks under `/assets/` — these get immutable caching.
+ * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
+ */
+export function generateHeadersFile(): string {
+  return `# Auto-generated by @timber/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/*
+  Cache-Control: ${STATIC_CACHE}
+`;
+}