@pyreon/zero 0.21.0 → 0.23.0

package/src/fs-router.ts

@@ -1107,7 +1107,8 @@ export function generateRouteModuleFromRoutes(
     // so `_hmrId` is dead metadata once built.
     opts.push(`hmrId: ${JSON.stringify(fullPath)}`)
     const optsStr = `, { ${opts.join(', ')} }`
-    imports.push(`const ${name} = lazy(() => import("${fullPath}")${optsStr})`)
+    // JSON.stringify for safe-embed — matches the `hmrId` line above.
+    imports.push(`const ${name} = lazy(() => import(${JSON.stringify(fullPath)})${optsStr})`)
     return name
   }
 

package/src/isr.ts

@@ -1,31 +1,176 @@
 import type { ISRConfig } from './types'
 
+// Dev-mode counter sink — see packages/internals/perf-harness for contract.
+// Zero cost in prod (gate folds to `false`, optional-chain short-circuits).
+const __DEV__ = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
+
 // ─── ISR Cache ───────────────────────────────────────────────────────────────
 
-interface CacheEntry {
+/** Serialized SSR response cached by the ISR layer (one per cache key). */
+export interface ISRCacheEntry {
   html: string
   headers: Record<string, string>
   timestamp: number
 }
 
 /**
- * In-memory ISR cache with stale-while-revalidate semantics.
+ * Pluggable backing store for the ISR cache. The default in-memory
+ * implementation (`createMemoryStore`) is per-process — fine for
+ * single-instance deploys, but multi-instance / horizontally-scaled
+ * apps need a SHARED store (Redis, Vercel KV, Cloudflare KV, Upstash,
+ * etc.) so revalidation in one instance is visible to all instances.
+ *
+ * The interface accepts BOTH sync and async returns: the in-memory
+ * default stays cheap (sync `Map` ops, no `Promise` allocation per
+ * request), while external stores return promises naturally. The
+ * handler awaits the result either way (`await` on a non-promise just
+ * returns the value).
+ *
+ * `get` is responsible for any LRU bookkeeping — external stores
+ * typically rely on their own TTL/eviction policy and can `return
+ * this.map.get(key)` directly; the in-memory store does a
+ * delete + re-insert to keep the Map's insertion-order LRU correct.
+ *
+ * `delete` is optional. It's only used when a future on-demand
+ * revalidation pathway needs to evict a specific key (the current
+ * stale-while-revalidate flow does not call it). External stores that
+ * don't support per-key invalidation can omit it.
+ */
+export interface ISRStore<E = ISRCacheEntry> {
+  get(key: string): Promise<E | undefined> | E | undefined
+  set(key: string, entry: E): Promise<void> | void
+  delete?(key: string): Promise<void> | void
+  /**
+   * Drop EVERY entry. Optional — external stores (Redis with TTL-only,
+   * Vercel KV with per-key invalidation, etc.) may not support a
+   * blanket purge. When omitted, `ISRHandler.revalidateAll()` throws a
+   * clear error pointing at the missing method. The default
+   * `createMemoryStore` implements it.
+   */
+  clear?(): Promise<void> | void
+}
+
+/**
+ * The default in-memory ISR store: a `Map` with insertion-order LRU
+ * eviction, capped at `maxEntries` (default `1000`). Drop in as
+ * `config.store` if you want to tweak the cap or wrap the store with
+ * instrumentation; pass a different `ISRStore` impl for Redis / KV /
+ * etc. backings.
+ *
+ * `get` does the LRU bump (re-inserts the touched entry at the
+ * newest position) so hot paths survive eviction even when the cap is
+ * small. Without that, `Map.get(...)` wouldn't update ordering and
+ * frequently-read entries could be evicted by occasional writes.
+ */
+export function createMemoryStore<E = ISRCacheEntry>(opts: {
+  maxEntries?: number
+} = {}): ISRStore<E> {
+  const cache = new Map<string, E>()
+  const maxEntries = Math.max(1, opts.maxEntries ?? 1000)
+  return {
+    get(key) {
+      const entry = cache.get(key)
+      if (entry !== undefined) {
+        cache.delete(key)
+        cache.set(key, entry)
+      }
+      return entry
+    },
+    set(key, entry) {
+      if (cache.has(key)) cache.delete(key)
+      cache.set(key, entry)
+      while (cache.size > maxEntries) {
+        const oldest = cache.keys().next().value
+        if (oldest === undefined) break
+        cache.delete(oldest)
+      }
+    },
+    delete(key) {
+      cache.delete(key)
+    },
+    clear() {
+      cache.clear()
+    },
+  }
+}
+
+// Internal alias for the default-shape entry — keeps function bodies tidy
+// while staying source-compatible with the public `ISRCacheEntry` export.
+type CacheEntry = ISRCacheEntry
+
+/**
+ * ISR handler with stale-while-revalidate semantics.
+ *
+ * Wraps an SSR handler and caches responses per URL path. Serves stale
+ * content immediately while revalidating in the background. The cache
+ * backing is **pluggable** via `config.store` (default:
+ * `createMemoryStore({ maxEntries: 1000 })`) — pass a custom `ISRStore`
+ * implementation backed by Redis / Vercel KV / Cloudflare KV / Upstash
+ * etc. to share state across horizontally-scaled instances. Without an
+ * external store, each instance has its own per-process cache (which
+ * is fine for single-instance deploys; behaviour-identical to the
+ * pre-pluggable-store implementation).
  *
- * Wraps an SSR handler and caches responses per URL path.
- * Serves stale content immediately while revalidating in the background.
+ * Default in-memory store: bounded by `config.maxEntries` (default
+ * `1000`) with insertion-order LRU eviction. Without the cap, unbounded
+ * URL spaces like `/user/:id` would grow cache memory without limit
+ * over the server's lifetime — a real leak in long-running deployments.
+ * `config.maxEntries` is ignored when a custom `config.store` is supplied
+ * (the custom store owns its own eviction policy).
+ */
+/**
+ * The fetch handler `createISRHandler` returns is also a callable
+ * carrying imperative invalidation methods. Webhooks, CMS notifications,
+ * admin endpoints etc. call these methods to drop one or all cached
+ * entries on demand — strictly more responsive than waiting for the
+ * TTL-based stale-while-revalidate cycle.
  *
- * Bounded by `config.maxEntries` (default: 1000) with LRU eviction. The
- * `Map` preserves insertion order, so re-inserting an entry on every
- * serve (touching it) keeps the LRU order correct. Without the cap,
- * unbounded URL spaces like `/user/:id` would grow cache memory without
- * limit over the server's lifetime — a real leak in long-running
- * deployments.
+ * The shape is `(req) => Promise<Response>` PLUS the methods, so
+ * existing consumers (`Bun.serve({ fetch: handler })`) keep working
+ * byte-identically.
  */
+export interface ISRHandler {
+  (req: Request): Promise<Response>
+  /**
+   * Drop the cache entry for a single path (or `cacheKey`-derived key).
+   * The next request for that key will MISS and re-render fresh. Returns
+   * `{ dropped: true }` if an entry was found and deleted, `{ dropped: false }`
+   * if no entry existed.
+   *
+   * Useful for webhook-driven invalidation: a CMS notifies that a post
+   * was updated, the webhook handler calls `isrHandler.revalidateNow('/posts/123')`,
+   * and the very next visitor gets the fresh content — no stale window.
+   *
+   * Idempotent. Safe to call against keys that don't exist (returns
+   * `dropped: false` cleanly).
+   */
+  revalidateNow(key: string): Promise<{ dropped: boolean }>
+  /**
+   * Drop ALL cached entries. Useful for "purge cache" admin actions or
+   * deploy-completion hooks that want a clean slate.
+   *
+   * The default in-memory store supports this via repeated `delete`
+   * calls under the hood; custom stores that omit `delete` (Redis with
+   * TTL-only, etc.) throw a clear error pointing at the missing method
+   * so the caller knows their store implementation can't honor the call.
+   */
+  revalidateAll(): Promise<void>
+}
+
 export function createISRHandler(
   handler: (req: Request) => Promise<Response>,
   config: ISRConfig,
-): (req: Request) => Promise<Response> {
-  const cache = new Map<string, CacheEntry>()
+): ISRHandler {
+  // Pluggable backing store. Default keeps the prior in-memory LRU
+  // behaviour byte-identical (same `maxEntries` default, same Map +
+  // delete+re-insert LRU bump) so existing callers see no behavioural
+  // change.
+  const store: ISRStore<CacheEntry>
+    = config.store
+      ?? createMemoryStore<CacheEntry>(
+        config.maxEntries !== undefined ? { maxEntries: config.maxEntries } : {},
+      )
   const revalidating = new Set<string>()
   const revalidateMs = config.revalidate * 1000
   // Bounded background-revalidation timeout. Without it, a handler that
@@ -47,7 +192,6 @@ export function createISRHandler(
   function isCacheable(res: Response): boolean {
     return res.status >= 200 && res.status < 300 && !res.headers.has('set-cookie')
   }
-  const maxEntries = Math.max(1, config.maxEntries ?? 1000)
   // M1.1 — cache-key derivation. Default keys by pathname only (the
   // pre-M1 behaviour). User-supplied `cacheKey` opts in to varying
   // by cookies / query / headers — required for auth-gated pages.
@@ -57,27 +201,6 @@ export function createISRHandler(
       ? (req, _url) => (config.cacheKey as (r: Request) => string)(req)
       : (_req, url) => url.pathname
 
-  function set(key: string, entry: CacheEntry): void {
-    // LRU: re-inserting moves the key to the newest position. Then if we're
-    // over the cap, drop the oldest (first in iteration order).
-    if (cache.has(key)) cache.delete(key)
-    cache.set(key, entry)
-    while (cache.size > maxEntries) {
-      const oldest = cache.keys().next().value
-      if (oldest === undefined) break
-      cache.delete(oldest)
-    }
-  }
-
-  function touch(key: string): CacheEntry | undefined {
-    const entry = cache.get(key)
-    if (entry !== undefined) {
-      cache.delete(key)
-      cache.set(key, entry)
-    }
-    return entry
-  }
-
   async function revalidate(url: URL, originalReq: Request) {
     // Re-derive key from the ORIGINAL request so cookies / headers /
     // query that varied the cache entry are preserved across revalidation.
@@ -88,23 +211,46 @@ export function createISRHandler(
     if (revalidating.has(key)) return
     revalidating.add(key)
 
+    // Hold the timer id outside try/Promise.race so the finally block
+    // can `clearTimeout` it on the SUCCESS path. Pre-fix the rejection
+    // setTimeout was left pending until REVALIDATE_TIMEOUT_MS (default
+    // 30s) every time `handler(req)` won the race — i.e. every
+    // successful revalidation. Under sustained traffic this accumulates
+    // hundreds of pending timer closures + rejection callbacks before
+    // they self-clear.
+    let timeoutId: ReturnType<typeof setTimeout> | undefined
     try {
-      // Forward the original request shape (headers + method) so the
-      // re-render sees the same auth context as the user's read.
-      const req = new Request(url.href, {
-        method: 'GET',
-        headers: originalReq.headers,
-      })
+      // Default: forward the original request shape (headers + method)
+      // so the re-render sees the same auth context as the user's read.
+      // Opt-in `revalidateRequest` hook lets auth-gated callers scope
+      // the revalidation explicitly — e.g. return `null` to skip
+      // revalidation for authenticated entries (stale stays stale until
+      // the next live request), or return an anonymous Request for
+      // non-personalized entries.
+      let req: Request
+      if (typeof config.revalidateRequest === 'function') {
+        const custom = config.revalidateRequest(originalReq)
+        if (custom === null) {
+          revalidating.delete(key)
+          return
+        }
+        req = custom
+      } else {
+        req = new Request(url.href, {
+          method: 'GET',
+          headers: originalReq.headers,
+        })
+      }
       // Bound the revalidation so a hung handler can't pin `key` in
       // `revalidating` forever (which would freeze the entry stale).
       const res = await Promise.race([
         handler(req),
-        new Promise<never>((_, reject) =>
-          setTimeout(
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(
             () => reject(new Error('[Pyreon ISR] revalidation timeout')),
             REVALIDATE_TIMEOUT_MS,
-          ),
-        ),
+          )
+        }),
       ])
       // Never overwrite a good stale entry with a bad re-render
       // (5xx/3xx) or poison it with a Set-Cookie response.
@@ -114,16 +260,24 @@ export function createISRHandler(
         res.headers.forEach((v, k) => {
           headers[k] = v
         })
-        set(key, { html, headers, timestamp: Date.now() })
+        await store.set(key, { html, headers, timestamp: Date.now() })
       }
     } catch {
       // Revalidation failed / timed out — stale cache entry remains valid
     } finally {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId)
+        // Leak-class I diagnostic — emit one per cleared timer. Healthy
+        // count = revalidation-attempts (every attempt should clear its
+        // timer in finally). A LOWER count than revalidations means
+        // clearTimeout failed to fire — the orphan-timer leak is back.
+        if (__DEV__) _countSink.__pyreon_count__?.('isr.revalidate.timerClear')
+      }
       revalidating.delete(key)
     }
   }
 
-  return async (req: Request): Promise<Response> => {
+  const fetch = async (req: Request): Promise<Response> => {
     // Only cache GET requests
     if (req.method !== 'GET') {
       return handler(req)
@@ -131,10 +285,11 @@ export function createISRHandler(
 
     const url = new URL(req.url)
     const key = deriveKey(req, url)
-    // `touch` moves the entry to the newest LRU position on read so
-    // hot paths survive eviction even when the cap is small. `get`
-    // wouldn't update ordering.
-    const entry = touch(key)
+    // The store's `get` is responsible for any LRU bookkeeping — the
+    // default in-memory store does delete + re-insert so hot paths
+    // survive eviction. External stores (Redis/KV) rely on their own
+    // TTL/eviction policy and typically just read directly.
+    const entry = await store.get(key)
 
     if (entry) {
       const age = Date.now() - entry.timestamp
@@ -175,7 +330,7 @@ export function createISRHandler(
       })
     }
 
-    set(key, { html, headers, timestamp: Date.now() })
+    await store.set(key, { html, headers, timestamp: Date.now() })
 
     return new Response(html, {
       status: 200,
@@ -186,4 +341,54 @@ export function createISRHandler(
       },
     })
   }
+
+  // Attach the imperative invalidation methods. The result is a
+  // callable (still works with `Bun.serve({ fetch: handler })`) plus
+  // `.revalidateNow(key)` and `.revalidateAll()` for webhook-driven
+  // cache busting.
+  const isrHandler = fetch as ISRHandler
+
+  isrHandler.revalidateNow = async (key: string) => {
+    // Get-then-delete so we can return an accurate `dropped` flag. The
+    // store's `delete` doesn't return whether anything existed, so the
+    // precheck is the only way to distinguish "actually dropped" from
+    // "no-op against missing key". For the default in-memory store the
+    // get is O(1); external stores pay one extra round-trip (acceptable
+    // for an invalidation API that fires on CMS webhooks, not on the
+    // hot path).
+    //
+    // `dropped: true` is only returned when (a) the entry existed AND
+    // (b) the store actually supported delete. A store without
+    // `delete?` returns `dropped: false` even if the entry existed —
+    // the caller's intent (make this key MISS next time) wasn't
+    // honored, so the honest answer is "no". Such stores rely on TTL
+    // for eviction.
+    const existed = (await store.get(key)) !== undefined
+    let dropped = false
+    if (existed && store.delete) {
+      await store.delete(key)
+      dropped = true
+    }
+    // Always clear the in-flight revalidation flag so the next request
+    // re-renders fresh rather than short-circuiting on the
+    // `revalidating.has(key)` guard — regardless of whether we
+    // physically dropped the entry.
+    revalidating.delete(key)
+    return { dropped }
+  }
+
+  isrHandler.revalidateAll = async () => {
+    if (!store.clear) {
+      throw new Error(
+        '[Pyreon ISR] revalidateAll() called against a store that does not implement `clear()`. The default in-memory store supports this; external stores (Redis/KV/etc.) must opt in by implementing `ISRStore.clear()`.',
+      )
+    }
+    await store.clear()
+    // Drop every in-flight revalidation flag — fresh requests should
+    // re-render rather than waiting on stale resolve callbacks pointing
+    // at entries we just purged.
+    revalidating.clear()
+  }
+
+  return isrHandler
 }

package/src/manifest.ts

@@ -221,24 +221,37 @@ await vercelAdapter().revalidate?.('/posts/123')
       name: 'createISRHandler',
       kind: 'function',
       signature:
-        'function createISRHandler(options: { handler: Handler; cacheTtl?: number; ... }): Handler',
+        'function createISRHandler(handler: (req: Request) => Promise<Response>, config: ISRConfig): ISRHandler',
       summary:
-        "Runtime ISR — on-demand SSR caching with TTL. Wraps an SSR handler so pages are rendered on the FIRST request, cached for `cacheTtl` ms (default 60s), and served stale until expiry. Distinct from build-time ISR (per-route `revalidate` export + `Adapter.revalidate`): runtime ISR caches at request time; build-time ISR triggers platform rebuilds. They can coexist: a `mode: 'isr'` app with per-route `revalidate` exports gets BOTH.",
+        "Runtime ISR — on-demand SSR caching with stale-while-revalidate. Wraps an SSR handler so pages are rendered on the FIRST request, cached per-URL (or per-`cacheKey`-derived key), and served stale until expiry while a background revalidate fires. The returned `ISRHandler` is still a callable `(req) => Promise<Response>` for `Bun.serve({ fetch: ... })`, but ALSO exposes imperative invalidation: `.revalidateNow(key)` drops one entry (returns `{ dropped: boolean }`), `.revalidateAll()` drops everything (when the store implements `clear()`). Pair with webhooks for CMS-driven cache busting — no stale window between content update and propagation. Distinct from build-time ISR (per-route `revalidate` export + `Adapter.revalidate`): runtime ISR caches at request time; build-time ISR triggers platform rebuilds. They can coexist: a `mode: 'isr'` app with per-route `revalidate` exports gets BOTH.",
       example: `import { createISRHandler, createServer } from '@pyreon/zero/server'
 
-// Wrap createServer's handler with ISR cache
 const ssrHandler = createServer({ routes })
-const isrHandler = createISRHandler({
-  handler: ssrHandler,
-  cacheTtl: 60_000,  // serve cached HTML for 60s
+const isr = createISRHandler(ssrHandler, { revalidate: 60 })
+
+// Use as the request handler
+Bun.serve({ fetch: isr })
+
+// CMS webhook: drop one entry
+app.post('/api/webhooks/post-updated', async (req) => {
+  const { postId } = await req.json()
+  const result = await isr.revalidateNow(\`/posts/\${postId}\`)
+  return Response.json(result) // { dropped: true | false }
 })
 
-export default isrHandler`,
+// Admin "purge cache" endpoint
+app.post('/admin/purge', async () => {
+  await isr.revalidateAll()
+  return new Response('ok')
+})`,
       mistakes: [
-        'Setting `cacheTtl: 0` and expecting "never cache" — pass-through is the explicit handler call (no `createISRHandler` wrapper). `cacheTtl: 0` is a degenerate state',
-        "Sharing the ISR handler across server instances without external cache — each server's in-memory cache diverges. For multi-instance deploys, swap to a shared cache layer (Redis adapter not built in; user-side concern)",
+        'Treating the returned handler as a plain function — it ALSO carries `.revalidateNow(key)` and `.revalidateAll()` methods. Webhook-driven invalidation is the canonical way to bust the cache; waiting for the TTL is the fallback',
+        'Calling `.revalidateAll()` against a store that does not implement `clear()` — throws a clear error. External stores (Redis with TTL-only) must opt in by implementing the method',
+        'Expecting `revalidateNow(key)` against a store without `delete?()` to physically drop the entry — returns `{ dropped: false }` honestly; such stores rely on TTL for eviction',
+        'Sharing the ISR handler across server instances without external cache — each server\'s in-memory cache diverges. For multi-instance deploys, swap `config.store` to a shared cache layer (Redis / Vercel KV / Cloudflare KV)',
+        'Setting `revalidate: 0` and expecting "never cache" — pass-through is the explicit handler call (no `createISRHandler` wrapper). Use `revalidate: Number.MAX_SAFE_INTEGER` for "cache forever, invalidate only via `revalidateNow`"',
       ],
-      seeAlso: ['zero', 'Adapter'],
+      seeAlso: ['zero', 'Adapter', 'ISRStore', 'createMemoryStore'],
     },
     {
       name: 'vercelAdapter',

package/src/server.ts

@@ -35,7 +35,8 @@ export {
 
 // ─── ISR ────────────────────────────────────────────────────────────────────
 
-export { createISRHandler } from "./isr";
+export type { ISRCacheEntry, ISRStore } from "./isr";
+export { createISRHandler, createMemoryStore } from "./isr";
 
 // ─── Vercel revalidate handler (M3.1) ───────────────────────────────────────
 

package/src/ssg-plugin.ts

@@ -1152,12 +1152,23 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
         // `ssg.pathWrite` / `ssg.pathRedirect` / `ssg.pathError` to see
         // per-path settle distribution.
         if (__DEV__) _countSink.__pyreon_count__?.('ssg.pathRender')
+        // Hold the timer id outside try/Promise.race so the finally
+        // block can `clearTimeout` it on the success path. Pre-fix the
+        // rejection setTimeout was left pending until 30s every time
+        // `renderPath(p)` won the race (i.e. every successful render).
+        // Concurrent worker pool × N paths under default `concurrency: 4`
+        // → up to N pending timer closures across the whole build,
+        // each pinning a rejection callback.
+        let timeoutId: ReturnType<typeof setTimeout> | undefined
         try {
           const result = await Promise.race([
             renderPath(p),
-            new Promise<never>((_, reject) =>
-              setTimeout(() => reject(new Error(`Prerender timeout for "${p}" (30s)`)), 30_000),
-            ),
+            new Promise<never>((_, reject) => {
+              timeoutId = setTimeout(
+                () => reject(new Error(`Prerender timeout for "${p}" (30s)`)),
+                30_000,
+              )
+            }),
           ])
 
           if (result.kind === 'redirect') {
@@ -1225,6 +1236,8 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
               errors.push({ path: `${p} (onPathError)`, error: callbackError })
             }
           }
+        } finally {
+          if (timeoutId !== undefined) clearTimeout(timeoutId)
         }
       }
 
@@ -1395,11 +1408,16 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
               : []
 
         for (const locale of localeEntries) {
+          // Hold the timer id outside try/Promise.race so the finally
+          // block can `clearTimeout` it on the success path. Same shape
+          // as the per-path render timeout above — every successful
+          // 404 render leaked a 30s pending timer pre-fix.
+          let timeoutId: ReturnType<typeof setTimeout> | undefined
           try {
             const result = await Promise.race([
               handlerMod.__renderNotFound(locale),
-              new Promise<never>((_, reject) =>
-                setTimeout(
+              new Promise<never>((_, reject) => {
+                timeoutId = setTimeout(
                   () =>
                     reject(
                       new Error(
@@ -1407,8 +1425,8 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
                       ),
                     ),
                   30_000,
-                ),
-              ),
+                )
+              }),
             ])
             if (result) {
               const html = injectIntoTemplate(template, result)
@@ -1433,6 +1451,8 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
               path: locale == null ? '404.html' : `${locale}/404.html`,
               error,
             })
+          } finally {
+            if (timeoutId !== undefined) clearTimeout(timeoutId)
           }
         }
       }