what-isr 0.11.7 → 0.12.0

package/dist/index.min.js

@@ -1 +1 @@
-import{createHash as _}from"node:crypto";var z=new Set(["fbclid","gclid","_","mc_cid","mc_eid"]),R=["utm_"];function J(t){if(z.has(t))return!0;for(let e of R)if(t.startsWith(e))return!0;return!1}function b(t){if(!t)return"/";let e=String(t).split("?")[0].split("#")[0];return e.length>1&&e.endsWith("/")&&(e=e.slice(0,-1)),e||"/"}function H(t){if(!t)return[];if(typeof t=="string"){let a=t.startsWith("?")?t.slice(1):t;return a?[...new URLSearchParams(a).entries()]:[]}let e=[];for(let[a,n]of Object.entries(t))if(Array.isArray(n))for(let l of n)e.push([a,String(l)]);else e.push([a,String(n)]);return e}function E(t){return H(t).filter(([a])=>!J(a)).sort((a,n)=>a[0]===n[0]?a[1]<n[1]?-1:1:a[0]<n[0]?-1:1).map(([a,n])=>`${a}=${n}`).join("&")}function k(t){return t?Object.entries(t).sort((e,a)=>e[0]<a[0]?-1:1).map(([e,a])=>`${e}=${a}`).join("&"):""}function P({path:t,query:e,vary:a}={}){return[b(t),E(e),k(a)].join("\0")}function F(t){let e=_("sha256").update(t).digest("hex");return`${e.slice(0,2)}/${e.slice(2,4)}/${e.slice(4)}`}function C(t,e={},a=Date.now()){let n=Number(e.revalidate)||0,l=e.swr!=null?Number(e.swr):n;return{html:t.html||"",head:t.head||"",state:t.state??null,tags:t.tags||e.tags||[],path:t.path||e.path,status:t.status||200,partial:!!t.partial,renderedAt:a,maxAge:n,swrWindow:l,expiresAt:n>0?a+n*1e3:1/0}}function A(t,e=Date.now()){return t.expiresAt===1/0||e<t.expiresAt}function D(t,e=Date.now()){return A(t,e)?!0:t.swrWindow==null?!1:e<t.expiresAt+t.swrWindow*1e3}function N(t={},e={},a="MISS"){let n={"X-What-Cache":a};if(!((t.status==null||t.status===200)&&(t.maxAge>0||e.mode==="static"||e.mode==="hybrid")&&e.mode!=="server"))return n["Cache-Control"]="private, no-store",n;let m=t.partial?0:t.maxAge||0,s=t.swrWindow!=null?t.swrWindow:m;return n["Cache-Control"]=`public, s-maxage=${m}, stale-while-revalidate=${s}`,t.tags&&t.tags.length&&(n["Cache-Tag"]=t.tags.join(","),n["Surrogate-Key"]=t.tags.join(" ")),n}function U({store:t,render:e,cdn:a,now:n=Date.now,logger:l=console}={}){let p=new Map;function m(i){return P({path:i.path,query:i.query,vary:i.vary})}function s(i,r,f){let h=p.get(i);if(h)return h;let o=f||e,w=(async()=>{let x=await o(r,{}),y=C({...x,path:r.path},r.config||{},n());return y.status===200&&await t.set(i,y),y})().finally(()=>p.delete(i));return p.set(i,w),w}function u(i,r,f){return{html:i.html,head:i.head,state:i.state,status:i.status||200,cacheStatus:r,headers:N(i,f||{},r)}}async function g(i,r){let f=i.config||{};if(f.mode==="server"){let y=await(r||e)(i,{}),v=C({...y,path:i.path},f,n());return u(v,"BYPASS",f)}let h=m(i),o=await t.get(h),w=n();if(o&&A(o,w))return u(o,"HIT",f);if(o&&D(o,w))return s(h,i,r).catch(y=>l.error?.("[what-isr] background regenerate failed:",y)),u(o,"STALE",f);if(o&&f.onMiss==="stale-if-error")try{let y=await s(h,i,r);return u(y,"MISS",f)}catch(y){return l.error?.("[what-isr] regenerate failed, serving stale:",y),u(o,"STALE",f)}let x=await s(h,i,r);return u(x,"MISS",f)}async function c(i,{regenerate:r=!1,routeResolver:f}={}){let h=b(i),o=await t.deleteByPath(h);if(a&&a.purge&&await a.purge([i]),r){let w=f?f(h):{path:h,query:{},config:{}};await s(m(w),w).catch(x=>l.error?.("[what-isr] regen after revalidatePath failed:",x))}return o}async function d(i,{regenerate:r=!1,routeResolver:f}={}){let h=await t.deleteByTag(i);if(a&&a.purgeTags&&await a.purgeTags([i]),r&&f)for(let o of h){let w=f(o);w&&await s(m(w),w).catch(()=>{})}return h}return{handle:g,regenerate:i=>s(m(i),i),revalidatePath:c,revalidateTag:d,keyFor:m,store:t,_inFlight:p,_now:n,_cdn:a}}function M({maxEntries:t=1e3}={}){let e=new Map,a=new Map,n=new Map;function l(c,d,i){if(d==null)return;let r=c.get(d);r||c.set(d,r=new Set),r.add(i)}function p(c,d,i){if(d==null)return;let r=c.get(d);r&&(r.delete(i),r.size===0&&c.delete(d))}function m(c,d){if(d.tags)for(let i of d.tags)l(a,i,c);l(n,d.path,c)}function s(c,d){if(d.tags)for(let i of d.tags)p(a,i,c);p(n,d.path,c)}function u(c){let d=e.get(c);return d?(e.delete(c),s(c,d),!0):!1}function g(c,d){let i=c.get(d);if(!i)return[];let r=[...i];for(let f of r)u(f);return r}return{async get(c){let d=e.get(c);return d?(e.delete(c),e.set(c,d),d):null},async set(c,d){for(e.has(c)&&s(c,e.get(c)),e.set(c,d),m(c,d);e.size>t;){let i=e.keys().next().value;u(i)}},async delete(c){return u(c)},async deleteByTag(c){return g(a,c)},async deleteByPath(c){return g(n,c)},async clear(){e.clear(),a.clear(),n.clear()},async keys(){return[...e.keys()]}}}import{mkdir as V,writeFile as X,readFile as L,rename as Q,rm as $,readdir as j,stat as I}from"node:fs/promises";import{join as S,dirname as q}from"node:path";import{createHash as G}from"node:crypto";function B(t){return G("sha256").update(String(t)).digest("hex")}function Y({dir:t}){let e=S(t,"entries"),a=S(t,"tags"),n=S(t,"paths"),l=r=>S(e,F(r)+".json"),p=(r,f)=>S(r,B(f)+".json");async function m(r,f){await V(q(r),{recursive:!0});let h=`${r}.${process.pid}.${B(r).slice(0,8)}.tmp`;await X(h,f),await Q(h,r)}async function s(r){try{return JSON.parse(await L(r,"utf8"))}catch{return null}}async function u(r,f,h){let o=p(r,f),w=await s(o)||[];w.includes(h)||(w.push(h),await m(o,JSON.stringify(w)))}async function g(r,f,h){let o=p(r,f),w=await s(o);if(!w)return;let x=w.filter(y=>y!==h);x.length?await m(o,JSON.stringify(x)):await $(o,{force:!0})}async function c(r,f){let h=p(r,f),o=await s(h);if(!o)return[];for(let w of o)await d(w);return await $(h,{force:!0}),o}async function d(r){let f=await s(l(r));if(!f)return!1;await $(l(r),{force:!0});let h=f.entry||{};for(let o of h.tags||[])await g(a,o,r);return h.path&&await g(n,h.path,r),!0}async function i(){let r=[],f;try{f=await j(e)}catch{return r}for(let h of f){let o=S(e,h),w;try{w=await I(o)}catch{continue}if(w.isDirectory())for(let x of await j(o)){let y=S(o,x);try{if(!(await I(y)).isDirectory())continue}catch{continue}for(let v of await j(y)){if(!v.endsWith(".json"))continue;let T=await s(S(y,v));T&&T.key!=null&&r.push(T.key)}}}return r}return{async get(r){let f=await s(l(r));return f?f.entry:null},async set(r,f){let h=await s(l(r));if(h&&h.entry){for(let o of h.entry.tags||[])await g(a,o,r);h.entry.path&&await g(n,h.entry.path,r)}await m(l(r),JSON.stringify({key:r,entry:f}));for(let o of f.tags||[])await u(a,o,r);f.path&&await u(n,f.path,r)},async delete(r){return d(r)},async deleteByTag(r){return c(a,r)},async deleteByPath(r){return c(n,r)},async clear(){await $(t,{recursive:!0,force:!0})},async keys(){return i()}}}function Z({client:t,namespace:e="what"}={}){if(!t)throw new Error("[what-isr] createRedisStore requires { client }");let a=s=>`${e}:cache:${s}`,n=s=>`${e}:tag:${s}`,l=s=>`${e}:path:${s}`;async function p(s,u){if(u){for(let g of u.tags||[])await t.srem(n(g),s);u.path&&await t.srem(l(u.path),s)}}async function m(s){let u=await t.smembers(s)||[];for(let g of u)await t.del(a(g));return await t.del(s),u}return{async get(s){let u=await t.get(a(s));return u?JSON.parse(u):null},async set(s,u){let g=await this.get(s);g&&await p(s,g),await t.set(a(s),JSON.stringify(u));for(let c of u.tags||[])await t.sadd(n(c),s);u.path&&await t.sadd(l(u.path),s)},async delete(s){let u=await this.get(s);return await t.del(a(s)),await p(s,u),!!u},async deleteByTag(s){return m(n(s))},async deleteByPath(s){return m(l(s))},async clear(){if(typeof t.keys=="function"){let s=await t.keys(`${e}:*`);for(let u of s)await t.del(u)}},async keys(){if(typeof t.keys!="function")return[];let s=`${e}:cache:`;return(await t.keys(`${s}*`)).map(g=>g.slice(s.length))}}}async function tt(t,e={}){if(typeof t!="function")return{paths:[],fallback:!1};let a=await t(e);return{paths:a&&a.paths||[],fallback:a&&"fallback"in a?a.fallback:!1}}function et(t,e={}){return t.replace(/[:*]([A-Za-z0-9_]+)/g,(a,n)=>{let l=e[n];return l==null?"":String(l)})}function rt(t,e){return t.some(a=>{let n=a.params||{},l=new Set([...Object.keys(n),...Object.keys(e)]);for(let p of l)if(String(n[p])!==String(e[p]))return!1;return!0})}function at(t,e){return e?"serve":t==="blocking"?"render":t===!0?"skeleton":"notfound"}function nt(t,e){if(typeof t!="string"||typeof e!="string"||t.length!==e.length)return!1;let a=0;for(let n=0;n<t.length;n++)a|=t.charCodeAt(n)^e.charCodeAt(n);return a===0}function st(t,e={}){let{secret:a,header:n="x-what-revalidate-secret",regenerate:l=!1}=e;return async function(m){let s=(m.headers||{})[n]||(m.headers||{})[n.toLowerCase()];if(!a||!nt(s||"",a))return{status:401,body:{message:"Unauthorized"}};let u=m.body;if(!u||typeof u!="object")return{status:400,body:{message:"Invalid body"}};let{paths:g,tags:c,regenerate:d=l}=u;if(!Array.isArray(g)&&!Array.isArray(c))return{status:400,body:{message:"Provide `paths` and/or `tags` arrays"}};let i={paths:[],tags:[]};if(Array.isArray(g))for(let r of g)await t.revalidatePath(r,{regenerate:d}),i.paths.push(r);if(Array.isArray(c))for(let r of c)await t.revalidateTag(r,{regenerate:d}),i.tags.push(r);return{status:200,body:{revalidated:!0,...i}}}}function ot(t,e={}){let{maxConcurrent:a=4,random:n=Math.random,setTimer:l=setTimeout,clearTimer:p=clearTimeout,logger:m=console}=e,s=[],u=[],g=!1,c=0;function d(o){return Math.round(o*(1+n()*.1))}function i(o){o.timer=l(()=>r(o),d(o.intervalMs)),o.timer&&typeof o.timer.unref=="function"&&o.timer.unref()}function r(o){g&&(c<a?f(o):u.push(o))}async function f(o){c++;try{await t.regenerate(o.route)}catch(w){m.error?.("[what-isr] scheduled regenerate failed:",w)}finally{c--,g&&i(o),h()}}function h(){for(;g&&c<a&&u.length;)f(u.shift())}return{register(o,{intervalMs:w}){return s.push({route:o,intervalMs:w,timer:null}),this},start(){g=!0;for(let o of s)i(o);return this},stop(){g=!1;for(let o of s)o.timer!=null&&p(o.timer);return u.length=0,this},_tasks:s}}function O({zoneId:t,apiToken:e}={}){let a=`https://api.cloudflare.com/client/v4/zones/${t}/purge_cache`,n={Authorization:`Bearer ${e}`,"Content-Type":"application/json"};async function l(p){!t||!e||await fetch(a,{method:"POST",headers:n,body:JSON.stringify(p)})}return{purge:p=>l({files:p}),purgeTags:p=>l({tags:p})}}function K({serviceId:t,apiToken:e}={}){let a={"Fastly-Key":e,Accept:"application/json"};async function n(l){!t||!e||await fetch(`https://api.fastly.com/service/${t}/purge/${encodeURIComponent(l)}`,{method:"POST",headers:a})}return{async purge(l){for(let p of l){if(!e)return;await fetch(p,{method:"PURGE",headers:a})}},async purgeTags(l){for(let p of l)await n(p)}}}function W({token:t,projectId:e,teamId:a}={}){let n={Authorization:`Bearer ${t}`,"Content-Type":"application/json"},l=a?`?teamId=${a}`:"";async function p(m){!t||!e||await fetch(`https://api.vercel.com/v1/projects/${e}/cache/purge${l}`,{method:"POST",headers:n,body:JSON.stringify({tags:m})})}return{purge:()=>Promise.resolve(),purgeTags:p}}export{N as buildCacheHeaders,et as buildPath,P as cacheKey,U as createCacheEngine,O as createCloudflareCDN,K as createFastlyCDN,Y as createFilesystemStore,M as createMemoryStore,Z as createRedisStore,st as createRevalidateWebhook,ot as createScheduler,W as createVercelCDN,at as decideFallback,F as hashKey,A as isFresh,rt as isKnownParams,D as isServableStale,C as makeEntry,b as normalizePath,E as normalizeQuery,tt as resolveStaticPaths};
+import{createHash as H}from"node:crypto";var L="\0",G=new Set(["fbclid","gclid","_","mc_cid","mc_eid"]),Q=["utm_"];function Z(t){if(G.has(t))return!0;for(let e of Q)if(t.startsWith(e))return!0;return!1}function P(t){if(!t)return"/";let e=String(t).split("?")[0].split("#")[0];return e.length>1&&e.endsWith("/")&&(e=e.slice(0,-1)),e||"/"}function M(t){if(!t)return[];if(typeof t=="string"){let r=t.startsWith("?")?t.slice(1):t;return r?[...new URLSearchParams(r).entries()]:[]}let e=[];for(let[r,s]of Object.entries(t))if(Array.isArray(s))for(let c of s)e.push([r,String(c)]);else e.push([r,String(s)]);return e}var T=t=>encodeURIComponent(String(t));function q(t){return M(t).filter(([r])=>!Z(r)).sort((r,s)=>r[0]===s[0]?r[1]<s[1]?-1:1:r[0]<s[0]?-1:1).map(([r,s])=>`${T(r)}=${T(s)}`).join("&")}function tt(t){let e={};if(!t)return e;for(let r of String(t).split(";")){let s=r.indexOf("=");s<0||(e[r.slice(0,s).trim()]=r.slice(s+1).trim())}return e}function _(t){let e=t||{};return e.vary!=null?e.vary:(e.config||{}).vary}function D(t){if(t==null)return[];if(typeof t=="string")return t?[t]:[];if(!Array.isArray(t))return null;let e=[];for(let r of t){if(typeof r!="string"||!r)return null;e.push(r)}return e}function j(t,e){let r=D(t);if(r===null)return null;if(!r.length)return{};if(!e||typeof e!="object")return null;let s={};for(let[h,l]of Object.entries(e))s[h.toLowerCase()]=Array.isArray(l)?l.join(","):l;let c=tt(s.cookie),d={};for(let h of r){let l=String(h),g=l.indexOf(":"),m=g<0?"header":l.slice(0,g).toLowerCase(),n=g<0?l:l.slice(g+1);if(m==="cookie")d[l]=c[n]??"";else if(m==="header")d[l]=s[n.toLowerCase()]??"";else return null}return d}function et(t){return t?Object.entries(t).sort((e,r)=>e[0]<r[0]?-1:1).map(([e,r])=>`${T(e)}=${T(r)}`).join("&"):""}function E({path:t,query:e,vary:r,headers:s}={}){let c=typeof r=="string"||Array.isArray(r),d=r==null||typeof r=="object"&&!Array.isArray(r),h=c?j(r,s):d?r:null;if(h===null)throw new Error("[what-isr] cannot build a cache key: `vary` is declared but could not be resolved against the request (unsupported shape, or no request headers were supplied)");return[P(t),q(e),et(h)].join(L)}function C(t){let e=String(t),r=e.lastIndexOf(L);if(r<0)return e;let s=e.slice(r+1);return s.includes("=")?e.slice(0,r+1)+H("sha256").update(s).digest("hex"):e}function R(t){let e=H("sha256").update(t).digest("hex");return`${e.slice(0,2)}/${e.slice(2,4)}/${e.slice(4)}`}function F(t,e={},r=Date.now()){let s=e.mode==="hybrid"?60:0,c=e.revalidate!=null,d=Number(e.revalidate??s),h=Number.isFinite(d)?d:s,l=e.swr!=null?Number(e.swr):h,g=h>0?r+h*1e3:c?r:1/0;return{html:t.html||"",head:t.head||"",state:t.state??null,tags:t.tags||e.tags||[],path:t.path||e.path,status:t.status||200,partial:!!t.partial,private:!!(t.private||t.usedRequestHeaders),renderedAt:r,maxAge:h,swrWindow:l,expiresAt:g}}function N(t,e=Date.now()){return t.expiresAt===1/0||e<t.expiresAt}function W(t,e=Date.now()){return N(t,e)?!0:t.swrWindow==null?!1:e<t.expiresAt+t.swrWindow*1e3}function rt(t){let e=new Set;for(let r of t){let s=String(r),c=s.indexOf(":"),d=c<0?"header":s.slice(0,c).toLowerCase();e.add(d==="cookie"?"Cookie":c<0?s:s.slice(c+1))}return[...e].join(", ")}function K(t={},e={},r="MISS",s){let c={"X-What-Cache":r},d=s!==void 0?s:e.vary,h=D(d),l=h===null||h.length>0;if(h&&h.length>0&&(c.Vary=rt(h)),!((t.status==null||t.status===200)&&!l&&!t.private&&(t.maxAge>0||e.mode==="static"||e.mode==="hybrid")&&e.mode!=="server"))return c["Cache-Control"]="private, no-store",c;let n=t.partial?0:t.maxAge||0,o=t.swrWindow!=null?t.swrWindow:n;return c["Cache-Control"]=`public, s-maxage=${n}, stale-while-revalidate=${o}`,t.tags&&t.tags.length&&(c["Cache-Tag"]=t.tags.join(","),c["Surrogate-Key"]=t.tags.join(" ")),c}function I(t){if(typeof t!="string"||!t.startsWith("/")||/^[/\\]{2}/.test(t)||t.includes("\\"))return null;try{let e=new URL(t,"http://localhost");return e.origin!=="http://localhost"?null:e.pathname+e.search}catch{return null}}function nt({store:t,render:e,cdn:r,now:s=Date.now,logger:c=console}={}){let d=new Map;function h(a){return j(_(a),a.varyHeaders||a.headers)}function l(a){let w=h(a);if(w===null)throw new Error("[what-isr] route declares `vary` but the adapter supplied no request headers; refusing to cache");return E({path:a.path,query:a.query,vary:w})}function g(a,w,S){let y=d.get(a);if(y)return y;let i=S||e,u=(async()=>{let p=await i(w,{}),x=F({...p,path:w.path},w.config||{},s());return x.status===200&&!x.private&&await t.set(a,x),x})().finally(()=>d.delete(a));return d.set(a,u),u}function m(a,w,S){return{html:a.html,head:a.head,state:a.state,status:a.status||200,cacheStatus:w,headers:K(a,S.config||{},w,_(S))}}async function n(a,w){let S=a.config||{},y=h(a);if(S.mode==="server"||y===null){y===null&&c.warn?.(`[what-isr] ${a.path} declares \`vary\` but no request headers were supplied; bypassing the cache`);let v=await(w||e)(a,{}),b=F({...v,path:a.path,private:y===null||v.private},S,s());return m(b,"BYPASS",a)}let i=E({path:a.path,query:a.query,vary:y}),u=await t.get(i),p=s();if(u&&N(u,p))return m(u,"HIT",a);if(u&&W(u,p))return g(i,a,w).catch(v=>c.error?.("[what-isr] background regenerate failed:",v)),m(u,"STALE",a);if(u&&S.onMiss==="stale-if-error")try{let v=await g(i,a,w);return m(v,"MISS",a)}catch(v){return c.error?.("[what-isr] regenerate failed, serving stale:",v),m(u,"STALE",a)}let x=await g(i,a,w);return m(x,"MISS",a)}async function o(a,{regenerate:w=!1,routeResolver:S}={}){let y=I(typeof a=="string"?a:"");if(y===null)return c.warn?.(`[what-isr] refusing to revalidate a non-local path: ${a}`),[];let i=P(y),u=await t.deleteByPath(i);if(r&&r.purge&&await r.purge([y]),w){let p=S?S(i):{path:i,query:{},config:{}};try{await g(l(p),p)}catch(x){c.error?.("[what-isr] regen after revalidatePath failed:",x)}}return u}async function f(a,{regenerate:w=!1,routeResolver:S}={}){let y=await t.deleteByTag(a);if(r&&r.purgeTags&&await r.purgeTags([a]),w&&S)for(let i of y){let u=S(i);if(u)try{await g(l(u),u)}catch{}}return y}return{handle:n,regenerate:a=>g(l(a),a),revalidatePath:o,revalidateTag:f,keyFor:l,store:t,_inFlight:d,_now:s,_cdn:r}}function at({maxEntries:t=1e3}={}){let e=new Map,r=new Map,s=new Map;function c(n,o,f){if(o==null)return;let a=n.get(o);a||n.set(o,a=new Set),a.add(f)}function d(n,o,f){if(o==null)return;let a=n.get(o);a&&(a.delete(f),a.size===0&&n.delete(o))}function h(n,o){if(o.tags)for(let f of o.tags)c(r,f,n);c(s,o.path,n)}function l(n,o){if(o.tags)for(let f of o.tags)d(r,f,n);d(s,o.path,n)}function g(n){let o=e.get(n);return o?(e.delete(n),l(n,o),!0):!1}function m(n,o){let f=n.get(o);if(!f)return[];let a=[...f];for(let w of a)g(w);return a}return{async get(n){let o=e.get(n);return o?(e.delete(n),e.set(n,o),o):null},async set(n,o){for(e.has(n)&&l(n,e.get(n)),e.set(n,o),h(n,o);e.size>t;){let f=e.keys().next().value;g(f)}},async delete(n){return g(n)},async deleteByTag(n){return m(r,n)},async deleteByPath(n){return m(s,n)},async clear(){e.clear(),r.clear(),s.clear()},async keys(){return[...e.keys()]}}}import{mkdir as st,writeFile as ot,readFile as it,rename as ct,rm as $,readdir as O,stat as J}from"node:fs/promises";import{join as A,dirname as ut}from"node:path";import{createHash as ft,randomBytes as lt}from"node:crypto";function V(t){return ft("sha256").update(String(t)).digest("hex")}function dt({dir:t}){let e=A(t,"entries"),r=A(t,"tags"),s=A(t,"paths"),c=i=>A(e,R(i)+".json"),d=(i,u)=>A(i,V(u)),h=(i,u,p)=>A(d(i,u),V(p)+".json"),l=(i,u)=>A(i,V(u)+".json");async function g(i,u){await st(ut(i),{recursive:!0});let p=`${i}.${process.pid}.${lt(6).toString("hex")}.tmp`;await ot(p,u),await ct(p,i)}async function m(i){try{return JSON.parse(await it(i,"utf8"))}catch{return null}}async function n(i,u,p){await g(h(i,u,p),JSON.stringify(p))}async function o(i,u,p){await $(h(i,u,p),{force:!0});let x=await f(i,u);if(!x)return;let v=x.filter(b=>b!==p);v.length!==x.length&&(v.length?await g(l(i,u),JSON.stringify(v)):await $(l(i,u),{force:!0}))}async function f(i,u){let p=await m(l(i,u));return Array.isArray(p)?p.filter(x=>typeof x=="string"):null}async function a(i,u){let p=new Set(await f(i,u)||[]),x=d(i,u),v;try{v=await O(x)}catch{return[...p]}for(let b of v){if(!b.endsWith(".json"))continue;let k=await m(A(x,b));typeof k=="string"&&p.add(k)}return[...p]}async function w(i,u){let p=await a(i,u);for(let x of p)await S(x);return await $(d(i,u),{recursive:!0,force:!0}),await $(l(i,u),{force:!0}),p}async function S(i){let u=await m(c(i));if(!u)return!1;await $(c(i),{force:!0});let p=u.entry||{};for(let x of p.tags||[])await o(r,x,i);return p.path&&await o(s,p.path,i),!0}async function y(){let i=[],u;try{u=await O(e)}catch{return i}for(let p of u){let x=A(e,p),v;try{v=await J(x)}catch{continue}if(v.isDirectory())for(let b of await O(x)){let k=A(x,b);try{if(!(await J(k)).isDirectory())continue}catch{continue}for(let z of await O(k)){if(!z.endsWith(".json"))continue;let B=await m(A(k,z));B&&B.key!=null&&i.push(B.key)}}}return i}return{async get(i){let u=await m(c(C(i)));return u?u.entry:null},async set(i,u){let p=C(i),x=await m(c(p));if(x&&x.entry){for(let v of x.entry.tags||[])await o(r,v,p);x.entry.path&&await o(s,x.entry.path,p)}await g(c(p),JSON.stringify({key:p,entry:u}));for(let v of u.tags||[])await n(r,v,p);u.path&&await n(s,u.path,p)},async delete(i){return S(C(i))},async deleteByTag(i){return w(r,i)},async deleteByPath(i){return w(s,i)},async clear(){await $(t,{recursive:!0,force:!0})},async keys(){return y()}}}function pt({client:t,namespace:e="what"}={}){if(!t)throw new Error("[what-isr] createRedisStore requires { client }");let r=n=>`${e}:cache:${n}`,s=n=>`${e}:tag:${n}`,c=n=>`${e}:path:${n}`;function d(n,o=Date.now()){let f=n&&n.expiresAt;if(f==null||f===1/0||!Number.isFinite(f))return 0;let a=Number(n.swrWindow)||0;return Math.max(1,Math.ceil((f-o)/1e3)+a)}async function h(n){if(typeof t.scan=="function"){let o=new Set,f="0";do{let a=await t.scan(f,"MATCH",n,"COUNT",500),[w,S]=Array.isArray(a)?a:[a.cursor,a.keys];f=String(w);for(let y of S||[])o.add(y)}while(f!=="0");return[...o]}return typeof t.keys=="function"?await t.keys(n)||[]:[]}async function l(n){let o=await t.get(r(n));return o?JSON.parse(o):null}async function g(n,o){if(o){for(let f of o.tags||[])await t.srem(s(f),n);o.path&&await t.srem(c(o.path),n)}}async function m(n){let o=await t.smembers(n)||[];for(let f of o)await t.del(r(f));return await t.del(n),o}return{async get(n){return l(C(n))},async set(n,o){let f=C(n),a=await l(f);a&&await g(f,a),await t.set(r(f),JSON.stringify(o));let w=d(o);w>0&&typeof t.expire=="function"&&await t.expire(r(f),w);for(let S of o.tags||[])await t.sadd(s(S),f);o.path&&await t.sadd(c(o.path),f)},async delete(n){let o=C(n),f=await l(o);return await t.del(r(o)),await g(o,f),!!f},async deleteByTag(n){return m(s(n))},async deleteByPath(n){return m(c(n))},async clear(){for(let n of await h(`${e}:*`))await t.del(n)},async keys(){let n=`${e}:cache:`;return(await h(`${n}*`)).map(f=>f.slice(n.length))}}}async function ht(t,e={}){if(typeof t!="function")return{paths:[],fallback:!1};let r=await t(e);return{paths:r&&r.paths||[],fallback:r&&"fallback"in r?r.fallback:!1}}function yt(t,e={}){return t.replace(/[:*]([A-Za-z0-9_]+)/g,(r,s)=>{let c=e[s];return c==null?"":String(c)})}function wt(t,e){return t.some(r=>{let s=r.params||{},c=new Set([...Object.keys(s),...Object.keys(e)]);for(let d of c)if(String(s[d])!==String(e[d]))return!1;return!0})}function gt(t,e){return e?"serve":t==="blocking"?"render":t===!0?"skeleton":"notfound"}import{createHash as mt,timingSafeEqual as xt}from"node:crypto";function St(t,e){if(typeof t!="string"||typeof e!="string")return!1;let r=s=>mt("sha256").update(s).digest();return xt(r(t),r(e))}var vt=100;function At(t,e={}){let{secret:r,header:s="x-what-revalidate-secret",regenerate:c=!1,maxBatch:d=vt}=e;return async function(l){let g=(l.headers||{})[s]||(l.headers||{})[s.toLowerCase()];if(!r||!St(g||"",r))return{status:401,body:{message:"Unauthorized"}};let m=l.body;if(!m||typeof m!="object")return{status:400,body:{message:"Invalid body"}};let{paths:n,tags:o}=m;if(!Array.isArray(n)&&!Array.isArray(o))return{status:400,body:{message:"Provide `paths` and/or `tags` arrays"}};let f=(Array.isArray(n)?n.length:0)+(Array.isArray(o)?o.length:0);if(f>d)return{status:400,body:{message:`Too many entries: ${f} exceeds the ${d} per-request limit`}};let a={paths:[],tags:[]};if(Array.isArray(n))for(let w of n)await t.revalidatePath(w,{regenerate:c}),a.paths.push(w);if(Array.isArray(o))for(let w of o)await t.revalidateTag(w,{regenerate:c}),a.tags.push(w);return{status:200,body:{revalidated:!0,...a}}}}function bt(t,e={}){let{maxConcurrent:r=4,random:s=Math.random,setTimer:c=setTimeout,clearTimer:d=clearTimeout,logger:h=console}=e,l=[],g=[],m=!1,n=0;function o(y){return Math.round(y*(1+s()*.1))}function f(y){y.timer=c(()=>a(y),o(y.intervalMs)),y.timer&&typeof y.timer.unref=="function"&&y.timer.unref()}function a(y){m&&(n<r?w(y):g.push(y))}async function w(y){n++;try{await t.regenerate(y.route)}catch(i){h.error?.("[what-isr] scheduled regenerate failed:",i)}finally{n--,m&&f(y),S()}}function S(){for(;m&&n<r&&g.length;)w(g.shift())}return{register(y,{intervalMs:i}){return l.push({route:y,intervalMs:i,timer:null}),this},start(){m=!0;for(let y of l)f(y);return this},stop(){m=!1;for(let y of l)y.timer!=null&&d(y.timer);return g.length=0,this},_tasks:l}}function U({zoneId:t,apiToken:e}={}){let r=`https://api.cloudflare.com/client/v4/zones/${t}/purge_cache`,s={Authorization:`Bearer ${e}`,"Content-Type":"application/json"};async function c(d){!t||!e||await fetch(r,{method:"POST",headers:s,body:JSON.stringify(d)})}return{purge:d=>c({files:d}),purgeTags:d=>c({tags:d})}}function X({serviceId:t,apiToken:e,baseUrl:r}={}){let s={"Fastly-Key":e,Accept:"application/json"};function c(h){if(!r)return null;let l=I(h);if(l===null)return null;try{return new URL(l,r).href}catch{return null}}async function d(h){!t||!e||await fetch(`https://api.fastly.com/service/${t}/purge/${encodeURIComponent(h)}`,{method:"POST",headers:s})}return{async purge(h){if(e)for(let l of h){let g=c(l);g&&await fetch(g,{method:"PURGE",headers:s})}},async purgeTags(h){for(let l of h)await d(l)}}}function Y({token:t,projectId:e,teamId:r}={}){let s={Authorization:`Bearer ${t}`,"Content-Type":"application/json"},c=r?`?teamId=${r}`:"";async function d(h){!t||!e||await fetch(`https://api.vercel.com/v1/projects/${e}/cache/purge${c}`,{method:"POST",headers:s,body:JSON.stringify({tags:h})})}return{purge:()=>Promise.resolve(),purgeTags:d}}export{K as buildCacheHeaders,yt as buildPath,E as cacheKey,nt as createCacheEngine,U as createCloudflareCDN,X as createFastlyCDN,dt as createFilesystemStore,at as createMemoryStore,pt as createRedisStore,At as createRevalidateWebhook,bt as createScheduler,Y as createVercelCDN,gt as decideFallback,R as hashKey,N as isFresh,wt as isKnownParams,W as isServableStale,F as makeEntry,P as normalizePath,q as normalizeQuery,D as normalizeVaryDeclaration,ht as resolveStaticPaths,j as resolveVary};

package/index.d.ts

@@ -9,8 +9,16 @@ export interface PageCacheConfig {
   swr?: number;
   /** Purge handles for revalidateTag. */
   tags?: string[];
-  /** Split the cache by these request signals, e.g. 'cookie:theme'. */
-  vary?: string[];
+  /**
+   * Split the cache by these request signals, e.g. 'cookie:theme' or
+   * 'header:accept-language' ('x' alone means the 'x' header). The adapter must
+   * supply the matching request headers as `RouteMatch.varyHeaders`; without
+   * them the route is served uncached rather than shared between users.
+   *
+   * A bare string is accepted as shorthand for a one-element list. Any other
+   * shape is refused and the route is served uncached.
+   */
+  vary?: string[] | string;
   fallback?: 'blocking' | boolean;
   onMiss?: 'blocking' | string;
   /** Background regeneration interval, in seconds. */
@@ -25,6 +33,8 @@ export interface CacheEntry {
   status?: number;
   tags?: string[];
   path?: string;
+  /** Per-user render: never stored, never served from a shared cache. */
+  private?: boolean;
   /** Epoch ms when the entry was created. */
   createdAt: number;
   /** Seconds-to-stale snapshot from the page config. */
@@ -51,10 +61,28 @@ export function isFresh(entry: CacheEntry, now?: number): boolean;
 export function isServableStale(entry: CacheEntry, now?: number): boolean;
 
 // --- Keys ---
-export function cacheKey(routeMatch: RouteMatch): string;
+export function cacheKey(input: {
+  path: string;
+  query?: Record<string, string> | string;
+  vary?: string[] | string | Record<string, string>;
+  headers?: Record<string, string>;
+}): string;
 export function normalizePath(path: string): string;
 export function normalizeQuery(query: Record<string, string> | string): string;
 export function hashKey(key: string): string;
+/** Resolve a declared vary list against request headers; null if unresolvable. */
+export function resolveVary(
+  vary: string[] | string | Record<string, string> | undefined,
+  headers?: Record<string, string>
+): Record<string, string> | null;
+/**
+ * Coerce a `vary` declaration to canonical `string[]`, or null if the shape
+ * cannot be resolved. The cache key and the Cache-Control builder both read
+ * this, so they can never disagree about whether a route is per-user.
+ */
+export function normalizeVaryDeclaration(
+  vary: string[] | string | undefined | null
+): string[] | null;
 
 // --- CDN adapters (optional) ---
 export interface CDNAdapter {
@@ -62,7 +90,8 @@ export interface CDNAdapter {
   purgeTags(tags: string[]): Promise<void>;
 }
 export function createCloudflareCDN(options: { zoneId: string; apiToken: string }): CDNAdapter;
-export function createFastlyCDN(options: { serviceId: string; apiToken: string }): CDNAdapter;
+/** `baseUrl` is required for URL purge: only local paths resolved against it are purged. */
+export function createFastlyCDN(options: { serviceId: string; apiToken: string; baseUrl?: string }): CDNAdapter;
 export function createVercelCDN(options: { projectId: string; token: string; teamId?: string }): CDNAdapter;
 
 // --- Headers ---
@@ -92,6 +121,8 @@ export interface RouteMatch {
   params?: Record<string, string>;
   route?: unknown;
   request?: Request;
+  /** Request headers the route's `vary` names resolve against. */
+  varyHeaders?: Record<string, string>;
 }
 
 export interface RenderResult {
@@ -131,7 +162,7 @@ export function createCacheEngine(options?: {
 // --- Revalidation webhook ---
 export interface WebhookRequest {
   headers?: Record<string, string>;
-  body?: { paths?: string[]; tags?: string[]; secret?: string; regenerate?: boolean };
+  body?: { paths?: string[]; tags?: string[]; secret?: string };
 }
 export interface WebhookResponse {
   status: number;
@@ -139,7 +170,7 @@ export interface WebhookResponse {
 }
 export function createRevalidateWebhook(
   engine: CacheEngine,
-  options: { secret: string }
+  options: { secret: string; header?: string; regenerate?: boolean; maxBatch?: number }
 ): (req: WebhookRequest) => Promise<WebhookResponse>;
 
 // --- Poll scheduler ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-isr",
-  "version": "0.11.7",
+  "version": "0.12.0",
   "description": "What Framework - Origin-first ISR cache engine: stale-while-revalidate, on-demand & poll regeneration, no CDN required",
   "type": "module",
   "main": "src/index.js",
@@ -30,7 +30,7 @@
   "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",
   "peerDependencies": {
-    "what-server": "^0.11.7"
+    "what-server": "^0.12.0"
   },
   "peerDependenciesMeta": {
     "what-server": {

package/src/cdn/fastly.js

@@ -1,8 +1,23 @@
 // Fastly CDN adapter — surrogate-key purge (tags) and URL purge.
 
-export function createFastlyCDN({ serviceId, apiToken } = {}) {
+import { safeLocalPath } from '../local-path.js';
+
+export function createFastlyCDN({ serviceId, apiToken, baseUrl } = {}) {
   const headers = { 'Fastly-Key': apiToken, Accept: 'application/json' };
 
+  // A URL purge is a request to an arbitrary host carrying the Fastly API key,
+  // so only local paths resolved against the configured baseUrl are ever sent.
+  function purgeUrl(target) {
+    if (!baseUrl) return null;
+    const local = safeLocalPath(target);
+    if (local === null) return null;
+    try {
+      return new URL(local, baseUrl).href;
+    } catch {
+      return null;
+    }
+  }
+
   async function purgeKey(key) {
     if (!serviceId || !apiToken) return;
     await fetch(`https://api.fastly.com/service/${serviceId}/purge/${encodeURIComponent(key)}`, {
@@ -12,10 +27,11 @@ export function createFastlyCDN({ serviceId, apiToken } = {}) {
   }
 
   return {
-    async purge(urls) {
-      for (const url of urls) {
-        if (!apiToken) return;
-        await fetch(url, { method: 'PURGE', headers });
+    async purge(paths) {
+      if (!apiToken) return;
+      for (const p of paths) {
+        const url = purgeUrl(p);
+        if (url) await fetch(url, { method: 'PURGE', headers });
       }
     },
     async purgeTags(tags) {

package/src/headers.js

@@ -2,18 +2,53 @@
 // them lets ANY standards-compliant CDN do edge ISR for free (s-maxage +
 // stale-while-revalidate), and Cache-Tag/Surrogate-Key enable CDN tag purge.
 
+import { normalizeVaryDeclaration } from './key.js';
+
+// A declared vary source ('cookie:session') maps to the HTTP header a shared
+// cache would have to key on.
+function varyHeaderNames(vary) {
+  const names = new Set();
+  for (const raw of vary) {
+    const name = String(raw);
+    const i = name.indexOf(':');
+    const kind = i < 0 ? 'header' : name.slice(0, i).toLowerCase();
+    names.add(kind === 'cookie' ? 'Cookie' : (i < 0 ? name : name.slice(i + 1)));
+  }
+  return [...names].join(', ');
+}
+
 /**
- * @param {object} entry   { maxAge, swrWindow, tags?, partial?, status? }
- * @param {object} config  route page config { mode, ... }
+ * @param {object} entry   { maxAge, swrWindow, tags?, partial?, private?, status? }
+ * @param {object} config  route page config { mode, vary?, ... }
  * @param {string} cacheStatus  HIT | STALE | MISS | BYPASS
+ * @param {string[]} [vary] The declared vary the cache key used. Callers that
+ *   omit it fall back to config.vary, which is only correct when the routeMatch
+ *   carries no vary of its own.
  */
-export function buildCacheHeaders(entry = {}, config = {}, cacheStatus = 'MISS') {
+export function buildCacheHeaders(entry = {}, config = {}, cacheStatus = 'MISS', vary) {
   const headers = { 'X-What-Cache': cacheStatus };
 
+  // A route that varies on cookies/auth renders per user. The origin cache keys
+  // those variants separately, but a shared cache must never hold them, so no
+  // `public` here regardless of maxAge.
+  //
+  // This reads normalizeVaryDeclaration() rather than testing the raw value,
+  // because the cache key reads it too. When these two disagreed, a declaration
+  // like `vary: 'cookie:session'` produced a constant key AND a `public` header,
+  // and the two failures pointed the same way so nothing caught it. An
+  // unresolvable declaration (null) is treated as varying: refusing to mark it
+  // public is the fail-closed direction.
+  const rawDeclared = vary !== undefined ? vary : config.vary;
+  const declared = normalizeVaryDeclaration(rawDeclared);
+  const varies = declared === null || declared.length > 0;
+  if (declared && declared.length > 0) headers.Vary = varyHeaderNames(declared);
+
   // Non-200 responses (soft-404s, error pages) are never cacheable — the
   // origin engine doesn't store them, and a CDN must not either.
   const isOk = entry.status == null || entry.status === 200;
   const cacheable = isOk
+    && !varies
+    && !entry.private
     && (entry.maxAge > 0 || config.mode === 'static' || config.mode === 'hybrid')
     && config.mode !== 'server';
 

package/src/index.js

@@ -14,7 +14,7 @@ export { createRedisStore } from './stores/redis-store.js';
 export { makeEntry, isFresh, isServableStale } from './stores/store-interface.js';
 
 // Keying + headers
-export { cacheKey, normalizePath, normalizeQuery, hashKey } from './key.js';
+export { cacheKey, normalizePath, normalizeQuery, hashKey, resolveVary, normalizeVaryDeclaration } from './key.js';
 export { buildCacheHeaders } from './headers.js';
 
 // Dynamic paths (getStaticPaths)

package/src/isr.js

@@ -8,15 +8,27 @@
 // `render(routeMatch, ctx)` is INJECTED by the adapter (wraps renderPage +
 // serializeState) — the engine never imports what-server, keeping it standalone.
 
-import { cacheKey, normalizePath } from './key.js';
+import { cacheKey, normalizePath, resolveVary, declaredVary } from './key.js';
 import { makeEntry, isFresh, isServableStale } from './stores/store-interface.js';
 import { buildCacheHeaders } from './headers.js';
+import { safeLocalPath } from './local-path.js';
 
 export function createCacheEngine({ store, render, cdn, now = Date.now, logger = console } = {}) {
   const inFlight = new Map(); // key -> Promise<entry>  (dedupe)
 
+  // A route may declare `vary` (['cookie:session']) in its page config; the
+  // adapter supplies the request headers those names resolve against. Null means
+  // the values are unavailable, so the render is per-user and must not be cached.
+  function varyFor(routeMatch) {
+    return resolveVary(declaredVary(routeMatch), routeMatch.varyHeaders || routeMatch.headers);
+  }
+
   function keyFor(routeMatch) {
-    return cacheKey({ path: routeMatch.path, query: routeMatch.query, vary: routeMatch.vary });
+    const vary = varyFor(routeMatch);
+    if (vary === null) {
+      throw new Error('[what-isr] route declares `vary` but the adapter supplied no request headers; refusing to cache');
+    }
+    return cacheKey({ path: routeMatch.path, query: routeMatch.query, vary });
   }
 
   // Render + store, deduping concurrent calls for the same key. `renderOverride`
@@ -29,11 +41,12 @@ export function createCacheEngine({ store, render, cdn, now = Date.now, logger =
     const p = (async () => {
       const out = await doRender(routeMatch, {});
       const entry = makeEntry({ ...out, path: routeMatch.path }, routeMatch.config || {}, now());
-      // Only 200 renders are cached. Storing a non-200 (soft-404, error page)
-      // would serve it as a HIT until expiry — bad for correctness and SEO.
-      // The response is still returned to the caller with its real status;
-      // any previously cached good entry is left in place.
-      if (entry.status === 200) {
+      // Only public 200 renders are cached. Storing a non-200 (soft-404, error
+      // page) would serve it as a HIT until expiry (bad for correctness and
+      // SEO), and storing a per-user render would serve one visitor's HTML to
+      // everyone. The response is still returned to the caller with its real
+      // status; any previously cached good entry is left in place.
+      if (entry.status === 200 && !entry.private) {
         await store.set(key, entry);
       }
       return entry;
@@ -42,65 +55,85 @@ export function createCacheEngine({ store, render, cdn, now = Date.now, logger =
     return p;
   }
 
-  function serve(entry, cacheStatus, config) {
+  function serve(entry, cacheStatus, routeMatch) {
     return {
       html: entry.html,
       head: entry.head,
       state: entry.state,
       status: entry.status || 200,
       cacheStatus,
-      headers: buildCacheHeaders(entry, config || {}, cacheStatus),
+      headers: buildCacheHeaders(entry, routeMatch.config || {}, cacheStatus, declaredVary(routeMatch)),
     };
   }
 
   async function handle(routeMatch, renderOverride) {
     const config = routeMatch.config || {};
-
-    // Uncacheable (server-rendered) routes: always render, never store.
-    if (config.mode === 'server') {
+    const vary = varyFor(routeMatch);
+
+    // Uncacheable routes: server-rendered, or a `vary` declaration the adapter
+    // left unresolved (caching it would publish one user's HTML to everyone).
+    // Always render, never store.
+    if (config.mode === 'server' || vary === null) {
+      if (vary === null) {
+        logger.warn?.(`[what-isr] ${routeMatch.path} declares \`vary\` but no request headers were supplied; bypassing the cache`);
+      }
       const out = await (renderOverride || render)(routeMatch, {});
-      const entry = makeEntry({ ...out, path: routeMatch.path }, config, now());
-      return serve(entry, 'BYPASS', config);
+      const entry = makeEntry({ ...out, path: routeMatch.path, private: vary === null || out.private }, config, now());
+      return serve(entry, 'BYPASS', routeMatch);
     }
 
-    const key = keyFor(routeMatch);
+    const key = cacheKey({ path: routeMatch.path, query: routeMatch.query, vary });
     const entry = await store.get(key);
     const t = now();
 
     if (entry && isFresh(entry, t)) {
-      return serve(entry, 'HIT', config);
+      return serve(entry, 'HIT', routeMatch);
     }
 
     if (entry && isServableStale(entry, t)) {
       // Serve stale immediately; refresh in the background (deduped, non-blocking).
       regenerate(key, routeMatch, renderOverride).catch((e) => logger.error?.('[what-isr] background regenerate failed:', e));
-      return serve(entry, 'STALE', config);
+      return serve(entry, 'STALE', routeMatch);
     }
 
     // Cold miss or expired beyond the swr window.
     if (entry && config.onMiss === 'stale-if-error') {
       try {
         const fresh = await regenerate(key, routeMatch, renderOverride);
-        return serve(fresh, 'MISS', config);
+        return serve(fresh, 'MISS', routeMatch);
       } catch (e) {
         logger.error?.('[what-isr] regenerate failed, serving stale:', e);
-        return serve(entry, 'STALE', config);
+        return serve(entry, 'STALE', routeMatch);
       }
     }
 
     const fresh = await regenerate(key, routeMatch, renderOverride);
-    return serve(fresh, 'MISS', config);
+    return serve(fresh, 'MISS', routeMatch);
   }
 
   // --- On-demand invalidation (origin purge + optional CDN fan-out) ---
 
   async function revalidatePath(path, { regenerate: regen = false, routeResolver } = {}) {
-    const norm = normalizePath(path);
+    // Never let a caller-supplied target reach the CDN adapter: a purge carries
+    // the CDN API token, so an absolute URL would exfiltrate it (SSRF).
+    const local = safeLocalPath(typeof path === 'string' ? path : '');
+    if (local === null) {
+      logger.warn?.(`[what-isr] refusing to revalidate a non-local path: ${path}`);
+      return [];
+    }
+    const norm = normalizePath(local);
     const deleted = await store.deleteByPath(norm);
-    if (cdn && cdn.purge) await cdn.purge([path]);
+    if (cdn && cdn.purge) await cdn.purge([local]);
     if (regen) {
       const route = routeResolver ? routeResolver(norm) : { path: norm, query: {}, config: {} };
-      await regenerate(keyFor(route), route).catch((e) => logger.error?.('[what-isr] regen after revalidatePath failed:', e));
+      // keyFor() can throw (a route declaring `vary` with no headers), so it has
+      // to run inside the try: as an argument expression the .catch() never
+      // attached and the rejection escaped revalidatePath.
+      try {
+        await regenerate(keyFor(route), route);
+      } catch (e) {
+        logger.error?.('[what-isr] regen after revalidatePath failed:', e);
+      }
     }
     return deleted;
   }
@@ -111,7 +144,10 @@ export function createCacheEngine({ store, render, cdn, now = Date.now, logger =
     if (regen && routeResolver) {
       for (const key of deleted) {
         const route = routeResolver(key);
-        if (route) await regenerate(keyFor(route), route).catch(() => {});
+        if (!route) continue;
+        try {
+          await regenerate(keyFor(route), route);
+        } catch { /* best effort: a purge must not fail because a regen did */ }
       }
     }
     return deleted;

package/src/local-path.js

@@ -0,0 +1,23 @@
+// Revalidation targets must be same-origin local paths before they reach a CDN
+// adapter. A CDN purge sends the CDN API token as a request header, so an
+// attacker-supplied absolute URL ("https://attacker.example/x",
+// "http://169.254.169.254/") would exfiltrate that token and turn on-demand
+// revalidation into an SSRF primitive.
+//
+// Backslashes matter: browsers and `new URL()` treat "\" like "/", so
+// "/\evil.com" canonicalizes to http://evil.com. Reject anything starting with
+// two slash-or-backslash chars or containing a backslash, then canonicalize via
+// URL and require the localhost origin.
+
+/** @returns {string|null} the canonical local "path?query", or null if unsafe. */
+export function safeLocalPath(value) {
+  if (typeof value !== 'string' || !value.startsWith('/')) return null;
+  if (/^[/\\]{2}/.test(value) || value.includes('\\')) return null;
+  try {
+    const u = new URL(value, 'http://localhost');
+    if (u.origin !== 'http://localhost') return null;
+    return u.pathname + u.search;
+  } catch {
+    return null;
+  }
+}

package/src/stores/filesystem-store.js

@@ -4,8 +4,8 @@
 
 import { mkdir, writeFile, readFile, rename, rm, readdir, stat } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { createHash } from 'node:crypto';
-import { hashKey } from '../key.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { hashKey, redactVary } from '../key.js';
 
 function safeName(s) {
   return createHash('sha256').update(String(s)).digest('hex');
@@ -17,11 +17,20 @@ export function createFilesystemStore({ dir }) {
   const pathsDir = join(dir, 'paths');
 
   const entryFile = (key) => join(entriesDir, hashKey(key) + '.json');
-  const indexFile = (base, name) => join(base, safeName(name) + '.json');
+  const indexDir = (base, name) => join(base, safeName(name));
+  const indexFile = (base, name, key) => join(indexDir(base, name), safeName(key) + '.json');
+  // v0.11.7 and earlier wrote one JSON array per tag/path instead of a
+  // directory. Left unread, an in-place upgrade would silently orphan every
+  // pre-upgrade entry: revalidatePath would return [] while the webhook still
+  // reported success, and the entries would keep being served from disk.
+  const legacyIndexFile = (base, name) => join(base, safeName(name) + '.json');
 
   async function atomicWrite(file, contents) {
     await mkdir(dirname(file), { recursive: true });
-    const tmp = `${file}.${process.pid}.${safeName(file).slice(0, 8)}.tmp`;
+    // The temp name must be unique per write: two workers (or two concurrent
+    // writes in one process) targeting the same file would otherwise clobber
+    // each other's partial temp file before the rename.
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
     await writeFile(tmp, contents);
     await rename(tmp, file);
   }
@@ -34,30 +43,47 @@ export function createFilesystemStore({ dir }) {
     }
   }
 
+  // Reverse indexes are append-only directories with one file per key, not a
+  // shared JSON list: a read-modify-write of one list loses entries whenever two
+  // workers index different variants of the same path concurrently, orphaning an
+  // entry that revalidatePath would then never find.
   async function addToIndex(base, name, key) {
-    const file = indexFile(base, name);
-    const list = (await readJson(file)) || [];
-    if (!list.includes(key)) {
-      list.push(key);
-      await atomicWrite(file, JSON.stringify(list));
-    }
+    await atomicWrite(indexFile(base, name, key), JSON.stringify(key));
   }
 
   async function removeFromIndex(base, name, key) {
-    const file = indexFile(base, name);
-    const list = await readJson(file);
-    if (!list) return;
-    const next = list.filter((k) => k !== key);
-    if (next.length) await atomicWrite(file, JSON.stringify(next));
-    else await rm(file, { force: true });
+    await rm(indexFile(base, name, key), { force: true });
+    const legacy = await readLegacyIndex(base, name);
+    if (!legacy) return;
+    const next = legacy.filter((k) => k !== key);
+    if (next.length === legacy.length) return;
+    if (next.length) await atomicWrite(legacyIndexFile(base, name), JSON.stringify(next));
+    else await rm(legacyIndexFile(base, name), { force: true });
+  }
+
+  async function readLegacyIndex(base, name) {
+    const list = await readJson(legacyIndexFile(base, name));
+    return Array.isArray(list) ? list.filter((k) => typeof k === 'string') : null;
+  }
+
+  async function readIndex(base, name) {
+    const keys = new Set(await readLegacyIndex(base, name) || []);
+    const dirPath = indexDir(base, name);
+    let files;
+    try { files = await readdir(dirPath); } catch { return [...keys]; }
+    for (const f of files) {
+      if (!f.endsWith('.json')) continue;
+      const k = await readJson(join(dirPath, f));
+      if (typeof k === 'string') keys.add(k);
+    }
+    return [...keys];
   }
 
   async function deleteByIndex(base, name) {
-    const file = indexFile(base, name);
-    const keys = await readJson(file);
-    if (!keys) return [];
+    const keys = await readIndex(base, name);
     for (const k of keys) await removeKey(k);
-    await rm(file, { force: true });
+    await rm(indexDir(base, name), { recursive: true, force: true });
+    await rm(legacyIndexFile(base, name), { force: true });
     return keys;
   }
 
@@ -92,24 +118,35 @@ export function createFilesystemStore({ dir }) {
     return out;
   }
 
+  // Every key crossing into this store is redacted first, exactly as the Redis
+  // store does. The entry FILENAME was always safe (hashKey hashes the whole
+  // key), but the key is also written into the file BODY and into every reverse
+  // index file, and the vary segment carries raw header/cookie VALUES. A route
+  // declaring `vary: ['cookie:session']` was therefore writing each visitor's
+  // session token to disk in cleartext, three copies per entry, with no TTL on
+  // the index files: readable from a container image, a volume snapshot, a
+  // backup, or any log shipper tailing the cache dir. Redaction is idempotent,
+  // so the internal helpers (which read keys back out of index files) can pass
+  // them around without tracking whether they have been redacted already.
   return {
     async get(key) {
-      const rec = await readJson(entryFile(key));
+      const rec = await readJson(entryFile(redactVary(key)));
       return rec ? rec.entry : null;
     },
     async set(key, entry) {
+      const rk = redactVary(key);
       // de-index any previous version's tags/path first
-      const prev = await readJson(entryFile(key));
+      const prev = await readJson(entryFile(rk));
       if (prev && prev.entry) {
-        for (const t of prev.entry.tags || []) await removeFromIndex(tagsDir, t, key);
-        if (prev.entry.path) await removeFromIndex(pathsDir, prev.entry.path, key);
+        for (const t of prev.entry.tags || []) await removeFromIndex(tagsDir, t, rk);
+        if (prev.entry.path) await removeFromIndex(pathsDir, prev.entry.path, rk);
       }
-      await atomicWrite(entryFile(key), JSON.stringify({ key, entry }));
-      for (const t of entry.tags || []) await addToIndex(tagsDir, t, key);
-      if (entry.path) await addToIndex(pathsDir, entry.path, key);
+      await atomicWrite(entryFile(rk), JSON.stringify({ key: rk, entry }));
+      for (const t of entry.tags || []) await addToIndex(tagsDir, t, rk);
+      if (entry.path) await addToIndex(pathsDir, entry.path, rk);
     },
     async delete(key) {
-      return removeKey(key);
+      return removeKey(redactVary(key));
     },
     async deleteByTag(tag) {
       return deleteByIndex(tagsDir, tag);

package/src/stores/redis-store.js

@@ -1,6 +1,9 @@
 // Redis/KV cache store — the multi-instance story (N app servers share one
 // cache). Takes an INJECTED client (ioredis / node-redis shaped:
-// get/set/del/sadd/srem/smembers, optional keys) so this package keeps zero deps.
+// get/set/del/sadd/srem/smembers, optional expire/scan/keys) so this package
+// keeps zero deps.
+
+import { redactVary } from '../key.js';
 
 export function createRedisStore({ client, namespace = 'what' } = {}) {
   if (!client) throw new Error('[what-isr] createRedisStore requires { client }');
@@ -9,6 +12,43 @@ export function createRedisStore({ client, namespace = 'what' } = {}) {
   const tk = (tag) => `${namespace}:tag:${tag}`;
   const pk = (path) => `${namespace}:path:${path}`;
 
+  // Redis must reclaim an entry once it is past its swr window, otherwise the
+  // keyspace grows without bound. Entries with no expiry (durable static pages)
+  // get no TTL and are dropped by explicit purge only.
+  function ttlSeconds(entry, now = Date.now()) {
+    const expiresAt = entry && entry.expiresAt;
+    if (expiresAt == null || expiresAt === Infinity || !Number.isFinite(expiresAt)) return 0;
+    const swr = Number(entry.swrWindow) || 0;
+    return Math.max(1, Math.ceil((expiresAt - now) / 1000) + swr);
+  }
+
+  // SCAN, never KEYS: KEYS is O(N) and blocks single-threaded Redis for the
+  // whole keyspace scan.
+  async function scanKeys(pattern) {
+    if (typeof client.scan === 'function') {
+      const found = new Set();
+      let cursor = '0';
+      do {
+        const res = await client.scan(cursor, 'MATCH', pattern, 'COUNT', 500);
+        const [next, batch] = Array.isArray(res) ? res : [res.cursor, res.keys];
+        cursor = String(next);
+        for (const k of batch || []) found.add(k);
+      } while (cursor !== '0');
+      return [...found];
+    }
+    if (typeof client.keys === 'function') return (await client.keys(pattern)) || [];
+    return [];
+  }
+
+  // Every key crossing into Redis is redacted first: Redis stores key names and
+  // set members verbatim, so a raw vary segment would expose session cookies to
+  // SCAN, MONITOR and any RDB/AOF backup. Redaction is stable, so the path and
+  // tag reverse indexes (whose members are redacted keys) still resolve.
+  async function readEntry(rk) {
+    const v = await client.get(ck(rk));
+    return v ? JSON.parse(v) : null;
+  }
+
   async function deindex(key, entry) {
     if (!entry) return;
     for (const t of entry.tags || []) await client.srem(tk(t), key);
@@ -24,20 +64,23 @@ export function createRedisStore({ client, namespace = 'what' } = {}) {
 
   return {
     async get(key) {
-      const v = await client.get(ck(key));
-      return v ? JSON.parse(v) : null;
+      return readEntry(redactVary(key));
     },
     async set(key, entry) {
-      const prev = await this.get(key);
-      if (prev) await deindex(key, prev);
-      await client.set(ck(key), JSON.stringify(entry));
-      for (const t of entry.tags || []) await client.sadd(tk(t), key);
-      if (entry.path) await client.sadd(pk(entry.path), key);
+      const rk = redactVary(key);
+      const prev = await readEntry(rk);
+      if (prev) await deindex(rk, prev);
+      await client.set(ck(rk), JSON.stringify(entry));
+      const ttl = ttlSeconds(entry);
+      if (ttl > 0 && typeof client.expire === 'function') await client.expire(ck(rk), ttl);
+      for (const t of entry.tags || []) await client.sadd(tk(t), rk);
+      if (entry.path) await client.sadd(pk(entry.path), rk);
     },
     async delete(key) {
-      const entry = await this.get(key);
-      await client.del(ck(key));
-      await deindex(key, entry);
+      const rk = redactVary(key);
+      const entry = await readEntry(rk);
+      await client.del(ck(rk));
+      await deindex(rk, entry);
       return !!entry;
     },
     async deleteByTag(tag) {
@@ -47,15 +90,11 @@ export function createRedisStore({ client, namespace = 'what' } = {}) {
       return deleteBySet(pk(path));
     },
     async clear() {
-      if (typeof client.keys === 'function') {
-        const all = await client.keys(`${namespace}:*`);
-        for (const k of all) await client.del(k);
-      }
+      for (const k of await scanKeys(`${namespace}:*`)) await client.del(k);
     },
     async keys() {
-      if (typeof client.keys !== 'function') return [];
       const prefix = `${namespace}:cache:`;
-      const all = await client.keys(`${prefix}*`);
+      const all = await scanKeys(`${prefix}*`);
       return all.map((k) => k.slice(prefix.length));
     },
   };

package/src/stores/store-interface.js

@@ -15,6 +15,7 @@
 // @property {number} swrWindow   Grace seconds an expired entry is still served.
 // @property {number} [status]    HTTP status (for 404 stubs / fallback skeletons).
 // @property {boolean} [partial]  True for fallback skeletons (never durable).
+// @property {boolean} [private]  True for per-user renders (never stored/shared).
 //
 // @typedef {Object} CacheStore
 // @property {(key:string)=>Promise<Entry|null>} get
@@ -25,13 +26,36 @@
 // @property {()=>Promise<void>} clear
 // @property {()=>Promise<string[]>} keys
 
+// A hybrid route renders per-request data, so an entry without an explicit
+// `revalidate` must NOT be fresh forever. Static routes are content-addressed by
+// their build and stay durable until an explicit purge.
+const HYBRID_MAX_AGE = 60;
+
 /**
  * Fill an Entry's time fields from `now` + a route config. Used by the ISR
  * engine so every store receives consistent expiry metadata.
  */
 export function makeEntry(out, config = {}, now = Date.now()) {
-  const maxAge = Number(config.revalidate) || 0;
+  // `??`, not `||`: an explicit `revalidate: 0` is a real value and must not be
+  // replaced by the hybrid default.
+  const fallbackMaxAge = config.mode === 'hybrid' ? HYBRID_MAX_AGE : 0;
+  const hasExplicitRevalidate = config.revalidate != null;
+  const declaredMaxAge = Number(config.revalidate ?? fallbackMaxAge);
+  const maxAge = Number.isFinite(declaredMaxAge) ? declaredMaxAge : fallbackMaxAge;
   const swrWindow = config.swr != null ? Number(config.swr) : maxAge;
+
+  // maxAge 0 has two completely opposite meanings and they must not collapse:
+  //   - NOT declared, static route: the page is content-addressed by its build
+  //     and stays durable until an explicit purge. expiresAt = Infinity.
+  //   - declared `revalidate: 0`: "always revalidate", the same meaning it has
+  //     in Next. expiresAt = now, so isFresh() is false from the first read and
+  //     every request regenerates.
+  // Reading it as Infinity in the second case turned the one setting a developer
+  // reaches for to DISABLE caching into cache-forever, which is the worst
+  // possible direction for the bug to point.
+  const expiresAt = maxAge > 0
+    ? now + maxAge * 1000
+    : (hasExplicitRevalidate ? now : Infinity);
   return {
     html: out.html || '',
     head: out.head || '',
@@ -40,10 +64,11 @@ export function makeEntry(out, config = {}, now = Date.now()) {
     path: out.path || config.path,
     status: out.status || 200,
     partial: !!out.partial,
+    private: !!(out.private || out.usedRequestHeaders),
     renderedAt: now,
     maxAge,
     swrWindow,
-    expiresAt: maxAge > 0 ? now + maxAge * 1000 : Infinity,
+    expiresAt,
   };
 }
 

package/src/webhook.js

@@ -2,23 +2,27 @@
 // secret purges paths/tags so a Sanity/Contentful/WP "published" event can warm
 // or drop cache entries. The adapter mounts this at e.g. /__what_revalidate.
 
-// Constant-time string compare (timing-attack safe). Self-contained so the cache
-// package stays dependency-free and decoupled from what-server.
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+// Constant-time compare over fixed-width digests, so neither the secret's
+// contents nor its LENGTH leak through response timing.
 function safeEqual(a, b) {
   if (typeof a !== 'string' || typeof b !== 'string') return false;
-  if (a.length !== b.length) return false;
-  let result = 0;
-  for (let i = 0; i < a.length; i++) result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return result === 0;
+  const digest = (s) => createHash('sha256').update(s).digest();
+  return timingSafeEqual(digest(a), digest(b));
 }
 
+// One request must not be able to force an unbounded number of blocking origin
+// renders. CMS webhooks publish a handful of paths at a time.
+const MAX_BATCH = 100;
+
 /**
  * @param engine  cache engine (revalidatePath / revalidateTag)
- * @param options { secret, header='x-what-revalidate-secret', regenerate=false }
- * @returns async (reqLike:{headers, body:{paths?,tags?,regenerate?}}) -> { status, body }
+ * @param options { secret, header='x-what-revalidate-secret', regenerate=false, maxBatch=100 }
+ * @returns async (reqLike:{headers, body:{paths?,tags?}}) -> { status, body }
  */
 export function createRevalidateWebhook(engine, options = {}) {
-  const { secret, header = 'x-what-revalidate-secret', regenerate = false } = options;
+  const { secret, header = 'x-what-revalidate-secret', regenerate = false, maxBatch = MAX_BATCH } = options;
 
   return async function handle(reqLike) {
     const provided = (reqLike.headers || {})[header] || (reqLike.headers || {})[header.toLowerCase()];
@@ -31,21 +35,27 @@ export function createRevalidateWebhook(engine, options = {}) {
       return { status: 400, body: { message: 'Invalid body' } };
     }
 
-    const { paths, tags, regenerate: regen = regenerate } = body;
+    // `regenerate` is operator policy: the request body must not be able to turn
+    // blocking re-renders on.
+    const { paths, tags } = body;
     if (!Array.isArray(paths) && !Array.isArray(tags)) {
       return { status: 400, body: { message: 'Provide `paths` and/or `tags` arrays' } };
     }
+    const total = (Array.isArray(paths) ? paths.length : 0) + (Array.isArray(tags) ? tags.length : 0);
+    if (total > maxBatch) {
+      return { status: 400, body: { message: `Too many entries: ${total} exceeds the ${maxBatch} per-request limit` } };
+    }
 
     const revalidated = { paths: [], tags: [] };
     if (Array.isArray(paths)) {
       for (const p of paths) {
-        await engine.revalidatePath(p, { regenerate: regen });
+        await engine.revalidatePath(p, { regenerate });
         revalidated.paths.push(p);
       }
     }
     if (Array.isArray(tags)) {
       for (const t of tags) {
-        await engine.revalidateTag(t, { regenerate: regen });
+        await engine.revalidateTag(t, { regenerate });
         revalidated.tags.push(t);
       }
     }