@timber-js/app 0.2.0-alpha.145 → 0.2.0-alpha.146

package/src/adapters/nitro.ts

@@ -471,7 +471,14 @@ const host = process.env.HOST || process.env.HOSTNAME || 'localhost';
 let boundPort = startPort;
 
 const server = createServer(async (req, res) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${boundPort}\`);
+  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
+  // origin comparison and absolute-URL construction when TLS is terminated
+  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
+  // X-Forwarded-Proto is intentionally not consulted here: on a direct
+  // connection it would be attacker-controlled. The CSRF layer honors it
+  // separately for reverse-proxy deployments.
+  const scheme = req.socket?.encrypted ? 'https' : 'http';
+  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
 
   // Try serving static files from the public directory first.
   const filePath = join(publicDir, url.pathname);
@@ -557,7 +564,7 @@ const server = createServer(async (req, res) => {
     // is silently dropped: defineCookie().setCookie() in actions, middleware
     // cookie writes, the framework's own session cookies, all of it. See
     // LOCAL-741.
-    const responseHeaders: Record<string, string | string[]> = {};
+    const responseHeaders = {};
     webResponse.headers.forEach((value, key) => {
       if (key.toLowerCase() !== 'set-cookie') {
         responseHeaders[key] = value;

package/src/cache/redis-handler.ts

@@ -1,15 +1,78 @@
 import type { CacheHandler } from './index';
 
 /**
- * Minimal Redis client interface — compatible with ioredis, node-redis, and
- * Cloudflare Workers Redis bindings. We depend on the interface, not the
- * implementation, so users bring their own Redis client.
+ * Minimal Redis client contract for `RedisCacheHandler`.
+ *
+ * This is deliberately NOT the native shape of any client library. ioredis,
+ * node-redis v4, and @upstash/redis all disagree on TTL argument shapes
+ * (positional `'EX'` vs `{ EX }` vs `{ ex }`), method casing (`sadd` vs
+ * `sAdd`), and array handling in `del` — a contract that pattern-matches one
+ * client lets another silently drop the expiry (TIM-1030: node-redis ignored
+ * the positional `'EX'` and wrote keys with no TTL). Instead, TTL semantics
+ * are explicit in the signature and you adapt your client with a thin
+ * wrapper, so a mismatch is a type error rather than silent unbounded
+ * keyspace growth.
+ *
+ * @example ioredis
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+ *   expire: (k, s) => redis.expire(k, s),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m),
+ *   smembers: (k) => redis.smembers(k),
+ * };
+ * ```
+ *
+ * @example node-redis v4
+ * ```ts
+ * import { createClient } from 'redis';
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * await redis.connect();
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),
+ *   expire: (k, s) => redis.expire(k, s),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sAdd(k, m),
+ *   smembers: (k) => redis.sMembers(k),
+ * };
+ * ```
+ *
+ * @example @upstash/redis
+ * ```ts
+ * import { Redis } from '@upstash/redis';
+ * // automaticDeserialization must be off: the handler stores JSON strings
+ * // and parses them itself — auto-parsing would hand back objects.
+ * const redis = new Redis({ url, token, automaticDeserialization: false });
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),
+ *   expire: (k, s) => redis.expire(k, s),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+ *   smembers: (k) => redis.smembers(k),
+ * };
+ * ```
  */
 export interface RedisClient {
+  /** `GET key` — the stored string, or null when absent. */
   get(key: string): Promise<string | null>;
-  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
-  del(key: string | string[]): Promise<number>;
-  sadd(key: string, ...members: string[]): Promise<number>;
+  /**
+   * `SET key value EX ttlSeconds` — store with an expiry. The TTL is a
+   * required positional argument so no adapter can forget it.
+   */
+  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+  /** `EXPIRE key seconds` — set/refresh a key's TTL (used for tag sets). */
+  expire(key: string, seconds: number): Promise<unknown>;
+  /** `DEL key` — delete a single key. Multi-key deletes loop per key. */
+  del(key: string): Promise<unknown>;
+  /** `SADD key member [member ...]` — add members to a set. */
+  sadd(key: string, ...members: string[]): Promise<unknown>;
+  /** `SMEMBERS key` — all members of a set. */
   smembers(key: string): Promise<string[]>;
 }
 
@@ -23,8 +86,9 @@ const TAG_PREFIX = 'timber:tag:';
  * invalidations. Tag-based invalidation uses Redis Sets to track which keys
  * belong to which tags.
  *
- * Bring your own Redis client — any client implementing the RedisClient
- * interface works (ioredis, node-redis, @upstash/redis, etc.).
+ * Bring your own Redis client wrapped to the {@link RedisClient} contract —
+ * see the adapter examples on the interface for ioredis, node-redis v4, and
+ * @upstash/redis.
  */
 export class RedisCacheHandler implements CacheHandler {
   private client: RedisClient;
@@ -62,7 +126,7 @@ export class RedisCacheHandler implements CacheHandler {
     // We use 2x TTL + 60s as the Redis expiry so stale entries remain
     // available for SWR background refetches.
     const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
-    await this.client.set(ck, payload, 'EX', redisTtlSeconds);
+    await this.client.set(ck, payload, redisTtlSeconds);
 
     // Track key membership in each tag set
     for (const tag of opts.tags) {
@@ -79,10 +143,10 @@ export class RedisCacheHandler implements CacheHandler {
       const tk = this.tagKey(opts.tag);
       const keys = await this.client.smembers(tk);
 
-      if (keys.length > 0) {
-        const cacheKeys = keys.map((k) => this.cacheKey(k));
-        await this.client.del(cacheKeys);
-      }
+      // One del per key: the only multi-key shape every client accepts.
+      // ioredis takes del(...keys), node-redis takes del(key | key[]), and
+      // @upstash/redis takes del(...keys) but breaks on an array argument.
+      await Promise.all(keys.map((k) => this.client.del(this.cacheKey(k))));
 
       // Clean up the tag set itself
       await this.client.del(tk);

package/src/cache/stable-stringify.ts

@@ -2,20 +2,83 @@
  * Deterministic JSON serialization with sorted object keys.
  * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }
  * produce the same string.
+ *
+ * Matches JSON.stringify semantics for toJSON: Date serializes to its ISO
+ * string, URL to its href, and class instances with a custom toJSON use it.
+ * Map and Set serialize their entries explicitly (insertion-order
+ * independent). Values that would serialize lossily — functions, symbols,
+ * and non-plain objects with no enumerable own state (RegExp, class
+ * instances holding data behind getters or internal slots) — throw instead:
+ * every such value would collapse to the same cache key, silently returning
+ * one argument's cached data for another (TIM-1020).
  */
 export function stableStringify(value: unknown): string {
-  if (value === null || value === undefined) return JSON.stringify(value);
-  if (typeof value !== 'object') return JSON.stringify(value);
+  if (value === null || value === undefined) return String(value);
+
+  const type = typeof value;
+  if (type === 'function' || type === 'symbol') {
+    throw new TypeError(
+      `stableStringify: cannot serialize a ${type} into a stable cache key — ` +
+        'all such values would collide. Provide an explicit `key` option to cache().'
+    );
+  }
+  if (type !== 'object') return JSON.stringify(value);
+
   if (Array.isArray(value)) {
     return '[' + value.map((item) => stableStringify(item)).join(',') + ']';
   }
 
+  // Honor toJSON like JSON.stringify does (Date → ISO string, URL → href,
+  // custom class serialization). JSON.stringify does not re-invoke toJSON
+  // on the value it returns, so a toJSON that returns `this` falls through
+  // to plain own-property serialization instead of recursing forever.
+  const withToJSON = value as { toJSON?: () => unknown };
+  if (typeof withToJSON.toJSON === 'function') {
+    const json = withToJSON.toJSON();
+    if (json !== value) return stableStringify(json);
+  }
+
+  // Map/Set have no enumerable own properties — serialize entries explicitly.
+  // Entries are sorted after serialization so insertion order doesn't change
+  // the key. The Map(/Set( prefixes can't collide with object ('{'), array
+  // ('['), or string ('"') output.
+  if (value instanceof Map) {
+    const entries = [...value.entries()].map(
+      ([k, v]) => stableStringify(k) + '=>' + stableStringify(v)
+    );
+    return 'Map(' + entries.sort().join(',') + ')';
+  }
+  if (value instanceof Set) {
+    const members = [...value].map((member) => stableStringify(member));
+    return 'Set(' + members.sort().join(',') + ')';
+  }
+
   const obj = value as Record<string, unknown>;
   const keys = Object.keys(obj).sort();
   const pairs: string[] = [];
   for (const key of keys) {
     if (obj[key] === undefined) continue;
+    // A callable own toJSON only reaches this loop via the returns-`this`
+    // fall-through above. It's the serialization protocol, not data —
+    // JSON.stringify omits it too.
+    if (key === 'toJSON' && typeof obj[key] === 'function') continue;
     pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));
   }
+
+  // A non-plain object that serializes to '{}' carries its state behind
+  // getters or internal slots (RegExp, sessions, ORM entities). Serializing
+  // it would give every instance the same cache key.
+  if (pairs.length === 0) {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      const name = (value as object).constructor?.name || 'Object';
+      throw new TypeError(
+        `stableStringify: ${name} instance has no serializable own state — ` +
+          'all instances would share one cache key. Provide an explicit `key` ' +
+          'option to cache(), or add a toJSON() method.'
+      );
+    }
+  }
+
   return '{' + pairs.join(',') + '}';
 }

package/src/cache/timber-cache.ts

@@ -3,6 +3,7 @@ import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
 import { addSpanEventSync } from '../server/tracing.js';
 import { logSwrRefetchFailed } from '../server/logger.js';
+import { getWaitUntil } from '../server/waituntil-bridge.js';
 import { fnv1aHash } from './fast-hash.js';
 
 const defaultSingleflight = createSingleflight();
@@ -44,7 +45,9 @@ let hasWarnedUnstableId = false;
  * - Singleflight: concurrent misses → single execution
  * - SWR: serve stale immediately, background refetch
  * - Tags as string[] or function of args
- * - No ALS dependency
+ * - No ALS dependency for correctness — cache() works outside a request
+ *   context. The waitUntil ALS bridge is read optionally so the SWR
+ *   background refetch survives handler return on Workers/Lambda.
  *
  * Cache hits/misses are recorded as OTEL span events on the enclosing
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
@@ -110,18 +113,27 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
         stale: true,
       });
       // Serve stale immediately, trigger background refetch
-      sf.do(`swr:${key}`, async () => {
-        try {
-          const fresh = await fn(...args);
-          const tags = resolveTags(opts, args);
-          await handler.set(key, fresh, { ttl: opts.ttl, tags });
-        } catch (err) {
-          // Failed refetch — stale entry continues to be served.
-          logSwrRefetchFailed({ cacheKey: key, error: err });
-        }
-      }).catch(() => {
-        // Singleflight promise rejection handled — stale continues.
-      });
+      const refetch = sf
+        .do(`swr:${key}`, async () => {
+          try {
+            const fresh = await fn(...args);
+            const tags = resolveTags(opts, args);
+            await handler.set(key, fresh, { ttl: opts.ttl, tags });
+          } catch (err) {
+            // Failed refetch — stale entry continues to be served.
+            logSwrRefetchFailed({ cacheKey: key, error: err });
+          }
+        })
+        .catch(() => {
+          // Singleflight promise rejection handled — stale continues.
+        });
+      // Platforms that cancel work when the handler returns (Cloudflare
+      // Workers, Lambda) would otherwise kill the refetch mid-flight —
+      // stale data re-served forever. Register the (never-rejecting)
+      // refetch with the request's waitUntil; undefined outside a request
+      // context or on platforms without lifecycle extension (Node servers
+      // keep floating promises alive, so behavior there is unchanged).
+      getWaitUntil()?.(refetch);
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 

package/src/client/browser-entry/action-dispatch.ts

@@ -18,6 +18,8 @@ import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runti
 import { getRouter, getRouterOrNull } from '#client-internal';
 import { setHardNavigating } from '../navigation-root.js';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
+import { decodeHeadHeader, HEAD_HEADER } from '../../shared/head-header.js';
+import type { HeadElement } from '../head.js';
 
 export function setupServerActions(): void {
   setServerCallback(async (id: string, args: unknown[]) => {
@@ -54,7 +56,7 @@ export function setupServerActions(): void {
       }
       hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
       hasRedirect = res.headers.get('X-Timber-Redirect') != null;
-      headElementsJson = res.headers.get('X-Timber-Head');
+      headElementsJson = res.headers.get(HEAD_HEADER);
       return res;
     });
 
@@ -88,7 +90,10 @@ export function setupServerActions(): void {
       const router = getRouterOrNull();
       if (router) {
         try {
-          const headElements = headElementsJson ? JSON.parse(headElementsJson) : null;
+          // Percent-encoded JSON — same wire format as the navigation path.
+          // A malformed header decodes to null (head update skipped), it
+          // does not fail the revalidation. See TIM-1058.
+          const headElements = decodeHeadHeader(headElementsJson) as HeadElement[] | null;
           router.applyRevalidation(wrapper._tree, headElements);
         } catch (e) {
           console.error('[timber] applyRevalidation failed after server action', e);

package/src/client/browser-entry/router-init.ts

@@ -22,7 +22,7 @@ import {
   setupNavigationApi,
   type NavigationApiController,
 } from '../navigation-api.js';
-import { getScrollY } from './scroll.js';
+import { getScrollY, scrollToHashTarget } from './scroll.js';
 
 export interface RouterInitOptions {
   initialElement?: unknown;
@@ -77,6 +77,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     },
     getCurrentUrl: () => window.location.pathname + window.location.search,
     getScrollY,
+    scrollToHash: scrollToHashTarget,
 
     decodeRsc: (fetchPromise: Promise<Response>) => {
       return createFromFetch(fetchPromise);

package/src/client/browser-entry/scroll.ts

@@ -16,6 +16,29 @@
  * naturally. We don't need to auto-detect overflow containers; only
  * explicitly marked containers are tracked.
  */
+/**
+ * Scroll the element matching a URL #fragment into view.
+ *
+ * Mirrors browser anchor behavior: looks up the decoded fragment by id,
+ * then by anchor name. Returns true when a matching element was found and
+ * scrolled; false otherwise (the router falls back to scroll-to-top, same
+ * as a full page load with an unknown fragment). See TIM-1035.
+ */
+export function scrollToHashTarget(hash: string): boolean {
+  const fragment = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (!fragment) return false;
+  let id: string;
+  try {
+    id = decodeURIComponent(fragment);
+  } catch {
+    return false;
+  }
+  const target = document.getElementById(id) ?? document.getElementsByName(id)[0];
+  if (!target) return false;
+  target.scrollIntoView();
+  return true;
+}
+
 export function getScrollY(): number {
   if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
     return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;

package/src/client/error-boundary.tsx

@@ -101,6 +101,13 @@ interface TimberErrorBoundaryState {
 // duplicate router.navigate() calls.
 const _handledRedirects = new WeakSet<object>();
 
+// Companion guard keyed by location: client-render redirect() (the
+// next/navigation shim) throws a FRESH error instance on every render
+// attempt, and React replays the errored render — so the WeakSet alone
+// would schedule the navigation twice. While a navigation to a location
+// is pending, further redirect errors for the same location are no-ops.
+let _pendingRedirectLocation: string | null = null;
+
 // ─── Component ───────────────────────────────────────────────────────────────
 
 export class TimberErrorBoundary extends Component<
@@ -167,18 +174,25 @@ export class TimberErrorBoundary extends Component<
       // than once for a single caught error (dev-mode double render, and
       // additional boundaries above us in the tree). Only schedule the
       // navigation on the first render that sees this error instance.
-      const alreadyHandled = _handledRedirects.has(error);
+      const alreadyHandled =
+        _handledRedirects.has(error) || _pendingRedirectLocation === parsed.location;
       if (!alreadyHandled) {
         _handledRedirects.add(error);
         const router = getRouterOrNull();
         if (router) {
+          _pendingRedirectLocation = parsed.location;
           // Schedule the navigation outside the render phase to avoid
           // setState-during-render warnings from router state updates.
           queueMicrotask(() => {
-            router.navigate(parsed.location, { replace: true }).catch(() => {
-              // Fall back to a hard navigation if the soft navigation fails.
-              window.location.href = parsed.location;
-            });
+            router
+              .navigate(parsed.location, { replace: true })
+              .catch(() => {
+                // Fall back to a hard navigation if the soft navigation fails.
+                window.location.href = parsed.location;
+              })
+              .finally(() => {
+                _pendingRedirectLocation = null;
+              });
           });
         } else {
           // No router available (shouldn't happen post-bootstrap) — fall

package/src/client/link.tsx

@@ -536,7 +536,10 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         event.preventDefault();
 
         const shouldScroll = scroll !== false;
-        const absoluteHref = resolved.pathname + resolved.search;
+        // Keep the #fragment — the router commits it to the address bar and
+        // scrolls to the matching element after render. The hash is stripped
+        // from the RSC fetch URL inside the router (TIM-1035).
+        const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
 
         startTransition(async () => {
           await router.navigate(absoluteHref, { scroll: shouldScroll });

package/src/client/navigation-api.ts

@@ -266,7 +266,11 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
         scroll: 'manual',
         focusReset: 'manual',
         async handler() {
-          await callbacks.onExternalNavigate(url, {
+          // Keep the #fragment — router.navigate splits it back off for the
+          // RSC fetch and scrolls to the matching element after render
+          // (TIM-1035). Traversals above stay hash-less: history-stack keys
+          // use pathname + search.
+          await callbacks.onExternalNavigate(url + destUrl.hash, {
             replace: event.navigationType === 'replace',
             signal: event.signal,
             scroll: linkMeta?.scroll,

package/src/client/navigation-root.tsx

@@ -58,6 +58,22 @@ function getTransitionCounter(): { id: number } {
   return g[NAV_TRANSITION_KEY] as { id: number };
 }
 
+/**
+ * Invalidate all in-flight navigation transitions. Any navigateTransition()
+ * call whose perform() has not yet committed will reject with AbortError
+ * instead of committing its element.
+ *
+ * Called by the router when a render supersedes in-flight navigations
+ * WITHOUT going through navigateTransition() — the cached popstate replay
+ * renders via transitionRender(), which doesn't bump the counter, so a
+ * stale forward navigation's setElement would otherwise pass the
+ * `counter.id !== transId` guard and commit the forward page over the
+ * replayed back page (TIM-1022).
+ */
+export function supersedeNavigationTransitions(): void {
+  getTransitionCounter().id += 1;
+}
+
 // ─── Hard Navigation Guard ──────────────────────────────────────
 
 /**