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

package/src/server/actions.ts

@@ -2,10 +2,10 @@
  * 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.
+ *   flight payload for inline reconciliation. Server actions only.
+ * - revalidateTag(tag) invalidates timber.cache entries by tag. Callable from
+ *   any server code: deferred to the end of the action inside one, immediate
+ *   anywhere else.
  *
  * The action handler processes incoming action requests, validates CSRF,
  * enforces body limits, executes the action, and returns the response
@@ -14,33 +14,64 @@
  * See design/08-forms-and-actions.md
  */
 
-import type { CacheHandler } from '#/cache/index';
-import { RedirectSignal } from './primitives';
-import { withSpan } from './tracing';
-import { revalidationAls, type RevalidationState } from './als-registry.js';
-
+import { cache } from '../cache/cache-api.ts';
+import { canonicalize } from './canonicalize.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
+import { withSpan } from './tracing.ts';
+import { revalidationAls, type RevalidationState } from './als-registry.ts';
+import type { ReactCacheScope } from './react-cache-scope.ts';
 // ─── Types ───────────────────────────────────────────────────────────────
 
-/** Result of rendering a revalidation — element tree before RSC serialization. */
+/** Result of rendering a revalidation — payload root before RSC serialization. */
 export interface RevalidationResult {
-  /** React element tree (pre-serialization — passed to renderToReadableStream). */
-  element: unknown;
-  /** Resolved head elements for metadata. */
-  headElements: unknown[];
+  /**
+   * The payload root — tree plus the params it rendered with, exactly as an
+   * ordinary route payload. The client splits it in `applyActionResult`.
+   */
+  payload: unknown;
+  /**
+   * The `React.cache` scope the target route's middleware ran in. The
+   * revalidated tree renders in it, so middleware, access.ts and components
+   * share one scope — fresh, never the action body's (TIM-1529).
+   */
+  reactCacheScope: ReactCacheScope;
 }
 
 /** Renderer function that builds a React element tree for a given path. */
 export type RevalidateRenderer = (path: string) => Promise<RevalidationResult>;
 
+/**
+ * Thrown by a `RevalidateRenderer` that decided not to render: the path
+ * was rejected, its params failed coercion, or its middleware answered
+ * with a `Response` that cannot become an element tree. `executeAction`
+ * drops the revalidation — the action result is still delivered, with no
+ * `_tree` piggybacked — and, because the drop was a decision, does not
+ * return it as an error to report. Identified by `instanceof`, so the
+ * message text never reaches clients.
+ */
+export class RevalidationDropped extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RevalidationDropped';
+  }
+}
+
 // Re-export the type from the registry for public API consumers.
-export type { RevalidationState } from './als-registry.js';
+export type { RevalidationState } from './als-registry.ts';
 
 /** 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;
+  /**
+   * Pathname of the page the action was submitted from. When set,
+   * revalidatePath renders are skipped for non-matching paths — the
+   * server cache is already invalidated, so the next navigation fetches
+   * fresh data. See TIM-1454.
+   */
+  requestPathname?: string;
+  /** Search string of the action request URL (e.g. `?page=1`). */
+  requestSearch?: string;
 }
 
 /** Result of handling a server action request. */
@@ -49,10 +80,29 @@ export interface ActionHandlerResult {
   actionResult: unknown;
   /** Revalidation result if revalidatePath was called (element tree, not yet serialized). */
   revalidation?: RevalidationResult;
+  /**
+   * True when `revalidatePath()` was called only for pages other than the
+   * current one (TIM-1454). The client then evicts its caches and skips the
+   * refresh — nothing on screen was named. Whenever the current page was
+   * named this is false, even if other pages were named too: its re-render,
+   * or the refresh that replaces a dropped one, re-renders every layout it
+   * shares with them. Which paths were named is not reported: the client
+   * evicts every cached payload after any revalidation (TIM-1476), so a path
+   * list would carry nothing it acts on (TIM-1461).
+   */
+  onlyOtherPagesNamed: boolean;
   /** Redirect location if a RedirectSignal was thrown during revalidation. */
   redirectTo?: string;
   /** Redirect status code. */
   redirectStatus?: number;
+  /**
+   * Errors the action survived after its body returned: a `revalidateTag`
+   * invalidation that rejected, or a `revalidatePath` render that threw.
+   * Each is already logged. They are returned rather than reported here
+   * because reporting needs the request, which the caller owns; the caller
+   * passes each to `onRequestError` once.
+   */
+  revalidationErrors: unknown[];
 }
 
 // ─── Revalidation State ──────────────────────────────────────────────────
@@ -62,36 +112,11 @@ export interface ActionHandlerResult {
 // (the previous module-level global was vulnerable to cross-request pollution).
 
 /**
- * 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.
+ * Run `fn` inside a revalidation ALS scope.
+ * @internal — for tests that call revalidatePath/Tag directly without executeAction().
  */
-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;
+export function _runWithRevalidationState<T>(state: RevalidationState, fn: () => T): T {
+  return revalidationAls.run(state, fn);
 }
 
 // ─── Public API ──────────────────────────────────────────────────────────
@@ -100,28 +125,50 @@ function getRevalidationState(): RevalidationState {
  * 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.
+ * Only callable inside a server action: it attaches a render to the action
+ * response, and nothing else has one. To refresh cached data from a
+ * `route.ts` handler, a webhook, or a job, use `revalidateTag()` or
+ * `cache.invalidate()`.
  *
  * @param path - The path to re-render (e.g. '/dashboard', '/todos').
  */
 export function revalidatePath(path: string): void {
-  const state = getRevalidationState();
+  const state = revalidationAls.getStore();
+  if (!state || state.closed) {
+    throw new Error(
+      'revalidatePath() can only be called inside a server action: it re-renders ' +
+        'the route into the action response, and there is no action response here. ' +
+        'To refresh cached data from a route handler or other server code, call ' +
+        'revalidateTag() or cache.invalidate() for the tags the route reads.'
+    );
+  }
   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.
+ * Invalidate all timber.cache entries tagged with `tag`, and tombstone the
+ * pre-rendered component seeds that carry it.
+ * Does not return a payload — the next request for an invalidated entry re-executes.
+ *
+ * Callable from any server code. Inside a server action the invalidation is
+ * deferred until the action body returns, so a `revalidatePath()` render in
+ * the same action reads fresh data; the returned promise resolves at once.
+ * Anywhere else — a `route.ts` webhook, a job, or background work an action
+ * started that runs after the action body returned — it is
+ * `cache.invalidate({ tag })`, and the promise settles when the invalidation
+ * has. Await it before responding.
  *
  * @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
  */
-export function revalidateTag(tag: string): void {
-  const state = getRevalidationState();
+export function revalidateTag(tag: string): Promise<void> {
+  const state = revalidationAls.getStore();
+  if (!state || state.closed) return cache.invalidate({ tag });
   if (!state.tags.includes(tag)) {
     state.tags.push(tag);
   }
+  return Promise.resolve();
 }
 
 // ─── Action Handler ──────────────────────────────────────────────────────
@@ -146,6 +193,7 @@ export async function executeAction(
   spanMeta?: { actionFile?: string; actionName?: string }
 ): Promise<ActionHandlerResult> {
   const state: RevalidationState = { paths: [], tags: [] };
+  const revalidationErrors: unknown[] = [];
   let actionResult: unknown;
   let redirectTo: string | undefined;
   let redirectStatus: number | undefined;
@@ -163,36 +211,73 @@ export async function executeAction(
         () => actionFn(...args)
       );
     } catch (error) {
-      if (error instanceof RedirectSignal) {
+      if (isRedirectSignal(error)) {
         redirectTo = error.location;
         redirectStatus = error.status;
       } else {
         throw error;
       }
+    } finally {
+      // From here `paths` and `tags` are snapshotted below (or abandoned on
+      // a throw); later calls from un-awaited work must not queue into them.
+      state.closed = true;
     }
   });
 
-  // Process tag invalidation
-  if (state.tags.length > 0 && config.cacheHandler) {
-    await Promise.all(state.tags.map((tag) => config.cacheHandler!.invalidate({ tag })));
+  // Process tag invalidation through cache.invalidate so it records the
+  // invalidation epoch — an in-flight cached fn must not re-store data this
+  // mutation just invalidated (TIM-1028). cache.invalidate resolves the
+  // module-level handler singleton: setCacheHandler() is called at boot from
+  // rsc-entry when timber.config.ts provides a cacheHandler; otherwise falls
+  // back to in-memory LRU (TIM-599).
+  if (state.tags.length > 0) {
+    // cache.invalidate handles both data-cache clearing AND component-seed
+    // tombstone writes (design/45 §ISR mechanics) — no separate tombstone
+    // step needed here.
+    // Best-effort: the action body already executed and its mutation committed.
+    // Use allSettled so all tags settle before proceeding — Promise.all would
+    // short-circuit on the first rejection, leaving other invalidations (including
+    // component-seed tombstone writes) in-flight during revalidatePath rendering.
+    const results = await Promise.allSettled(state.tags.map((tag) => cache.invalidate({ tag })));
+    for (const r of results) {
+      if (r.status === 'rejected') {
+        console.error('[timber] revalidateTag invalidation failed:', r.reason);
+        revalidationErrors.push(r.reason);
+      }
+    }
   }
 
-  // Process path revalidation — build element tree (not yet serialized)
+  // Process path revalidation — build element tree (not yet serialized).
+  //
+  // TIM-1454: Only a path that matches the current page is rendered. When
+  // every call names another page, `onlyOtherPagesNamed` tells the client to
+  // evict its caches instead. The matching path is looked for across every
+  // call, not just the first: an action that calls revalidatePath('/other')
+  // and then revalidatePath('/current') must still re-render the current
+  // page (TIM-1461).
   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];
+  const { requestPathname, requestSearch } = config;
+  const isCurrentPage = (path: string) =>
+    !requestPathname || revalidationPathMatches(path, requestPathname, requestSearch);
+  const path = state.paths.find(isCurrentPage);
+  const onlyOtherPagesNamed = state.paths.length > 0 && path === undefined;
+
+  if (path !== undefined && config.renderer) {
     try {
       revalidation = await config.renderer(path);
     } catch (renderError) {
-      if (renderError instanceof RedirectSignal) {
-        // Revalidation triggered a redirect (e.g., session expired)
+      if (isRedirectSignal(renderError)) {
         redirectTo = renderError.location;
         redirectStatus = renderError.status;
+      } else if (isDenySignal(renderError)) {
+        console.error(
+          `[timber] revalidatePath dropped — target middleware denied (status ${renderError.status})`
+        );
+      } else if (renderError instanceof RevalidationDropped) {
+        console.error(`[timber] ${renderError.message}`);
       } else {
-        // Log but don't fail the action — revalidation is best-effort
         console.error('[timber] revalidatePath render failed:', renderError);
+        revalidationErrors.push(renderError);
       }
     }
   }
@@ -200,31 +285,33 @@ export async function executeAction(
   return {
     actionResult,
     revalidation,
+    onlyOtherPagesNamed,
+    revalidationErrors,
     ...(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.
+ * Check if a `revalidatePath(path)` argument matches the request pathname.
+ * Canonicalizes the revalidated path the same way the renderer does so
+ * equivalent paths compare equal. Returns true when the paths match or
+ * when comparison is inconclusive (validation failure → render to be safe).
  */
-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');
+function revalidationPathMatches(
+  revalidatedPath: string,
+  requestPathname: string,
+  requestSearch?: string
+): boolean {
+  const hashIdx = revalidatedPath.indexOf('#');
+  const noFragment = hashIdx >= 0 ? revalidatedPath.slice(0, hashIdx) : revalidatedPath;
+  const queryIdx = noFragment.indexOf('?');
+  const pathnameOnly = queryIdx >= 0 ? noFragment.slice(0, queryIdx) : noFragment;
+  const search = queryIdx >= 0 ? noFragment.slice(queryIdx) : '';
+  const canonical = canonicalize(pathnameOnly, true);
+  if (!canonical.ok) return true;
+  if (canonical.pathname !== requestPathname) return false;
+  // revalidatePath('/dashboard') (no search) matches any query variant.
+  // revalidatePath('/dashboard?tab=x') only matches that exact search.
+  if (search && search !== (requestSearch ?? '')) return false;
+  return true;
 }