@thomas.f/prnext 0.1.17-alpha → 0.1.18-alpha

package/compat/redis-cache.cjs

@@ -0,0 +1,201 @@
+'use strict';
+const {createHash,randomBytes}=require('node:crypto');
+const MAX_VALUE=2*1024*1024,MAX_META=65536;
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const ACQUIRE=`
+if not redis.call('HGET',KEYS[2],'_incarnation') then redis.call('HSET',KEYS[2],'_incarnation',ARGV[3],'_epoch',ARGV[3]) end
+redis.call('PEXPIRE',KEYS[2],ARGV[4])
+local epoch=redis.call('HGET',KEYS[2],'_epoch');local incarnation=redis.call('HGET',KEYS[2],'_incarnation')
+if redis.call('SET',KEYS[1],ARGV[1],'NX','PX',ARGV[2]) then return {1,epoch,incarnation} end
+return {0}`;
+const RELEASE=`if redis.call('GET',KEYS[1])==ARGV[1] then return redis.call('DEL',KEYS[1]) end return 0`;
+const READ=`
+local fields=redis.call('HMGET',KEYS[1],'meta','value')
+if not fields[1] or not fields[2] or string.len(fields[1])>65536 or string.len(fields[2])>tonumber(ARGV[2]) then return nil end
+local meta=cjson.decode(fields[1]); local extra=cjson.decode(ARGV[1]); local stale=0
+if redis.call('HGET',KEYS[2],'_incarnation')~=meta.incarnation then return nil end
+local t=redis.call('TIME'); local now=tonumber(t[1])*1000+math.floor(tonumber(t[2])/1000)
+local seen={}
+for _,id in ipairs(meta.tagIds) do seen[id]=true end
+for _,id in ipairs(extra) do seen[id]=true end
+for id,_ in pairs(seen) do
+ local value=redis.call('HGET',KEYS[2],id)
+ if value then
+  local tag=cjson.decode(value)
+  if tag.generation~=(meta.versions[id] or '0') then
+   if tag.deadline>=0 and tag.deadline<=now then return nil end
+   stale=1
+  end
+ end
+end
+return {fields[1],fields[2],math.max(0,now-meta.storedAt),stale}`;
+const WRITE=`
+if redis.call('GET',KEYS[3])~=ARGV[1] or redis.call('HGET',KEYS[2],'_epoch')~=ARGV[2] then return 0 end
+local meta=cjson.decode(ARGV[3]); meta.versions={};meta.incarnation=ARGV[5];meta.writer=ARGV[1]
+local t=redis.call('TIME'); local now=tonumber(t[1])*1000+math.floor(tonumber(t[2])/1000)
+meta.storedAt=now-tonumber(ARGV[6])
+for _,id in ipairs(meta.tagIds) do
+ local value=redis.call('HGET',KEYS[2],id)
+ meta.versions[id]=value and cjson.decode(value).generation or '0'
+end
+local encoded=cjson.encode(meta)
+if string.len(encoded)>65536 then return 0 end
+redis.call('HSET',KEYS[1],'meta',encoded,'value',ARGV[4])
+redis.call('PEXPIRE',KEYS[1],ARGV[7]);redis.call('PEXPIRE',KEYS[2],ARGV[8]);return 1`;
+const INVALIDATE=`
+local generation=ARGV[3];local ids=cjson.decode(ARGV[4]);local added=0
+for _,id in ipairs(ids) do if redis.call('HEXISTS',KEYS[1],id)==0 then added=added+1 end end
+if redis.call('HLEN',KEYS[1])+added>4098 then redis.call('DEL',KEYS[1]) end
+if not redis.call('HGET',KEYS[1],'_incarnation') then redis.call('HSET',KEYS[1],'_incarnation',generation) end
+redis.call('HSET',KEYS[1],'_epoch',generation)
+local t=redis.call('TIME');local now=tonumber(t[1])*1000+math.floor(tonumber(t[2])/1000)
+local expiry=tonumber(ARGV[1]);local deadline=expiry<0 and -1 or now+expiry
+for _,id in ipairs(ids) do redis.call('HSET',KEYS[1],id,cjson.encode({generation=generation,deadline=deadline})) end
+redis.call('PEXPIRE',KEYS[1],ARGV[2])
+return 1`;
+const REMOVE=`local meta=redis.call('HGET',KEYS[1],'meta');if meta and cjson.decode(meta).writer==ARGV[1] then return redis.call('DEL',KEYS[1]) end return 0`;
+
+function tags(values=[]){
+  if(!Array.isArray(values)||values.length>256||values.some(value=>typeof value!=='string'||!value||Buffer.byteLength(value)>8192))throw new TypeError('Redis cache tags must be bounded nonempty strings.');
+  return [...new Set(values)];
+}
+function positive(value,fallback,min,max,name){value??=fallback;if(!Number.isSafeInteger(value)||value<min||value>max)throw new TypeError(`Redis cache ${name} must be between ${min} and ${max}.`);return value;}
+function pause(ms,signal){return new Promise((resolve,reject)=>{const done=error=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);error?reject(error):resolve();};const abort=()=>done(signal.reason);const timer=setTimeout(done,ms);signal?.addEventListener('abort',abort,{once:true});if(signal?.aborted)abort();});}
+function boundedRead(reader,ms){return new Promise((resolve,reject)=>{const timer=setTimeout(()=>reject(new Error('Redis cache value read timed out.')),ms);reader.read().then(value=>{clearTimeout(timer);resolve(value);},error=>{clearTimeout(timer);reject(error);});});}
+
+/** First-party Cache Components handler; Redis is loaded only when configured. */
+function createRedisCache(options={},maxValueBytes=MAX_VALUE){
+  if(!options||typeof options!=='object'||Array.isArray(options))throw new TypeError('Redis cache options must be an object.');
+  const known=new Set(['namespace','urlEnv','client','leaseMs','waitMs','commandTimeoutMs','maxAgeSeconds']);
+  for(const key of Object.keys(options))if(!known.has(key))throw new TypeError(`Unknown Redis cache option: ${key}`);
+  if(options.client!==undefined&&typeof options.client?.withTypeMapping!=='function')throw new TypeError('Redis cache client must be a node-redis client.');
+  if(typeof options.namespace!=='string'||!options.namespace||Buffer.byteLength(options.namespace)>256)throw new TypeError('Redis cache requires an application-specific namespace.');
+  const urlEnv=options.urlEnv??'REDIS_URL';if(typeof urlEnv!=='string'||!/^[_A-Za-z][_A-Za-z0-9]*$/.test(urlEnv))throw new TypeError('Redis cache urlEnv must name an environment variable.');
+  const leaseMs=positive(options.leaseMs,30000,1000,120000,'leaseMs'),waitMs=positive(options.waitMs,2500,100,3500,'waitMs');
+  const commandTimeoutMs=positive(options.commandTimeoutMs,1000,100,2000,'commandTimeoutMs'),maxAgeSeconds=positive(options.maxAgeSeconds,604800,1,2592000,'maxAgeSeconds');
+  if(waitMs+2*commandTimeoutMs>4500)throw new TypeError('Redis cache waitMs plus twice commandTimeoutMs must not exceed 4500 ms.');
+  const prefix='prnext:v1:{'+hash(options.namespace)+'}:',epochKey=prefix+'tags',retention=String(maxAgeSeconds*1000+leaseMs+60000);
+  let owned,connecting,closed=false;
+  async function client(){
+    if(closed)throw new Error('Redis cache is closed.');
+    if(options.client){
+      if(options.client.isReady===false)throw new Error('Redis cache client is not connected.');
+      return options.client;
+    }
+    if(owned?.isReady)return owned;
+    if(!connecting){
+      connecting=(async()=>{
+        const url=process.env[urlEnv];
+        if(!url||!/^rediss?:\/\//.test(url))throw new Error(`Set ${urlEnv} to a Redis connection URL.`);
+        // Use node-redis's base client; Redis Stack command packages are not
+        // needed by this provider's bounded EVAL/HASH protocol.
+        const {createClient}=require('@redis/client');
+        owned?.destroy();owned=createClient({url,disableOfflineQueue:true,commandsQueueMaxLength:128,socket:{connectTimeout:commandTimeoutMs,reconnectStrategy:false}});
+        owned.on('error',()=>{});await owned.connect();return owned;
+      })().finally(()=>{connecting=undefined;});
+    }
+    return connecting;
+  }
+  async function command(args,signal){
+    const connection=await client();
+    // '$' (36) is RESP's binary-safe bulk-string type, as exposed by node-redis.
+    const binary=connection.withTypeMapping({36:Buffer});
+    const deadline=AbortSignal.timeout(commandTimeoutMs);
+    return binary.sendCommand(args,{abortSignal:signal?AbortSignal.any([signal,deadline]):deadline});
+  }
+  const keys=key=>{if(typeof key!=='string'||!key||Buffer.byteLength(key)>8192)throw new TypeError('Invalid Redis cache key.');const id=hash(key);return {entry:prefix+'entry:'+id,lock:prefix+'lease:'+id};};
+  async function acquire(key,{signal}={}){
+    const {lock}=keys(key),token=randomBytes(24).toString('hex'),until=performance.now()+waitMs;
+    for(;;){
+      signal?.throwIfAborted();
+      const started=performance.now();
+      const result=await command(['EVAL',ACQUIRE,'2',lock,epochKey,token,String(leaseMs),randomBytes(24).toString('hex'),retention],signal);
+      if(Number(result[0])===1){let released=false;return {token,started,epoch:String(result[1]),incarnation:String(result[2]),async release(){if(released)return;released=true;await command(['EVAL',RELEASE,'1',lock,token]);}};}
+      if(performance.now()>=until)throw Object.assign(new Error('Redis cache fill wait exceeded its budget.'),{code:'PRNEXT_REDIS_BUSY'});
+      await pause(Math.min(50,Math.max(1,until-performance.now())),signal);
+    }
+  }
+  async function get(key,softTags=[]){
+    const result=await command(['EVAL',READ,'2',keys(key).entry,epochKey,JSON.stringify(tags(softTags).map(hash)),String(maxValueBytes)]);
+    if(!result)return undefined;
+    const meta=JSON.parse(result[0].toString('utf8')),bytes=result[1];
+    if(meta.version!==1||!Buffer.isBuffer(bytes)||bytes.length>maxValueBytes)throw new Error('Invalid Redis cache entry.');
+    const age=Number(result[2]);if(!Number.isFinite(age)||age<0)throw new Error('Invalid Redis cache age.');
+    let offset=0;
+    return {tags:meta.tags,stale:meta.stale,revalidate:Number(result[3])?0:meta.revalidate,expire:meta.expire,timestamp:Math.max(0,Date.now()-age),
+      value:new ReadableStream({pull(controller){if(offset===bytes.length){controller.close();return;}const end=Math.min(bytes.length,offset+65536);controller.enqueue(new Uint8Array(bytes.subarray(offset,end)));offset=end;}},{highWaterMark:0})};
+  }
+  async function set(key,pending,{lease,softTags=[]}={}){
+    if(!lease||!Number.isFinite(lease.started)){
+      // Observe and release a caller's value even when its lease is missing.
+      // An unfenced producer must never publish after an invalidation.
+      void Promise.resolve(pending).then(entry=>entry.value.cancel()).catch(()=>{});
+      throw new Error('Redis cache writes require the lease returned by acquire().');
+    }
+    const entry=await pending,entryTags=tags(entry.tags);
+    for(const field of ['timestamp','stale','revalidate','expire'])if(!Number.isFinite(entry[field])||entry[field]<0)throw new TypeError('Invalid Redis cache '+field);
+    const reader=entry.value.getReader(),chunks=[];let size=0,complete=false;
+    const until=performance.now()+commandTimeoutMs;
+    let reads=0;
+    try{for(;;){if(performance.now()>=until||++reads>10000)throw new Error('Redis cache value read timed out.');const part=await boundedRead(reader,Math.max(1,until-performance.now()));if(part.done){complete=true;break;}if(!(part.value instanceof Uint8Array)||(size+=part.value.byteLength)>maxValueBytes)throw new Error(`Redis cache value exceeds ${maxValueBytes/1024/1024} MiB.`);chunks.push(Buffer.from(part.value));}}
+    finally{if(!complete)void reader.cancel().catch(()=>{});reader.releaseLock();}
+    const meta={version:1,tags:entryTags,tagIds:tags([...entryTags,...softTags]).map(hash),stale:entry.stale,revalidate:entry.revalidate,expire:entry.expire};
+    const metadata=JSON.stringify(meta);if(Buffer.byteLength(metadata)>MAX_META)throw new Error('Redis cache metadata exceeds 64 KiB.');
+    const ttl=Math.ceil(Math.min(maxAgeSeconds,entry.expire)*1000);if(ttl<=0)return;
+    const {entry:entryKey,lock}=keys(key);
+    return Number(await command(['EVAL',WRITE,'3',entryKey,epochKey,lock,lease.token,lease.epoch,metadata,Buffer.concat(chunks,size),lease.incarnation,String(Math.max(0,performance.now()-lease.started)),String(ttl),retention]))===1;
+  }
+  async function updateTags(values,durations){
+    const list=tags(values);if(!list.length)return;
+    const expire=durations?.expire;if(expire!==undefined&&(!Number.isFinite(expire)||expire<0))throw new TypeError('Invalid Redis tag expiration.');
+    await command(['EVAL',INVALIDATE,'1',epochKey,String(expire===undefined?-1:Math.ceil(expire*1000)),retention,randomBytes(24).toString('hex'),JSON.stringify(list.map(hash))]);
+  }
+  return {get,set,acquire,updateTags,
+    async release(key,lease){if(lease?.token)await command(['EVAL',RELEASE,'1',keys(key).lock,lease.token]);},
+    async remove(key,lease){if(lease?.token)await command(['EVAL',REMOVE,'1',keys(key).entry,lease.token]);},
+    async refreshTags(){},async getExpiration(){return Infinity;},async close(){closed=true;await connecting?.catch(()=>{});if(owned?.isOpen)owned.destroy();}};
+}
+
+/** Legacy incremental handler for HTML/ISR, fetch and unstable_cache. */
+function createRedisIncrementalCache(options){
+  const {serialize,deserialize}=require('node:v8');
+  const backend=createRedisCache({leaseMs:60000,...options},16*1024*1024);
+  const keyFor=key=>'incremental:v8-'+process.versions.v8.split('.')[0]+':'+key;
+  function leaseFor(lease){
+    if(!lease||!['token','epoch','incarnation'].every(field=>typeof lease[field]==='string'&&/^[a-f0-9]{48}$/.test(lease[field]))||!Number.isFinite(lease.startedAt))throw new Error('Incremental Redis writes require a valid generation lease.');
+    return {...lease,started:performance.now()-Math.max(0,Date.now()-lease.startedAt)};
+  }
+  return class RedisIncrementalCache {
+    get prnextLeaseVersion(){return 1;}
+    async acquire(key,{signal}={}){
+      const lease=await backend.acquire(keyFor(key),{signal});
+      return {token:lease.token,epoch:lease.epoch,incarnation:lease.incarnation,startedAt:Date.now()};
+    }
+    async release(key,lease){await backend.release(keyFor(key),lease);}
+    async get(key,context={}){
+      const entry=await backend.get(keyFor(key),tags([...new Set([...(context.tags||[]),...(context.softTags||[])])]));
+      if(!entry)return null;
+      const bytes=Buffer.from(await new Response(entry.value).arrayBuffer());
+      const payload=deserialize(bytes);
+      if(payload?.version!==1||!Number.isFinite(payload.lastModified)||!payload.value||typeof payload.value.kind!=='string')throw new Error('Invalid incremental Redis payload.');
+      return {value:payload.value,lastModified:payload.lastModified,isStale:entry.revalidate===0};
+    }
+    async set(key,value,context={}){
+      const lease=leaseFor(context.prnextLease);
+      if(value===null){await backend.remove(keyFor(key),lease);return true;}
+      const raw=context.cacheControl?.revalidate??value.revalidate??value._prnext?.revalidate??false;
+      if(raw!==false&&(!Number.isFinite(raw)||raw<0))throw new TypeError('Invalid incremental Redis revalidate value.');
+      if(raw===0)return true;
+      const revalidate=raw===false?31536000:raw;
+      const entryTags=tags([...new Set([...(context.tags||[]),...(context.softTags||[])])]);
+      const bytes=serialize({version:1,lastModified:Date.now(),value});
+      if(bytes.length>16*1024*1024)throw new Error('Incremental Redis entry exceeds 16 MiB.');
+      return backend.set(keyFor(key),Promise.resolve({timestamp:Date.now(),stale:0,revalidate,expire:Math.max(revalidate,options?.maxAgeSeconds??604800),tags:entryTags,
+        value:new ReadableStream({start(controller){controller.enqueue(bytes);controller.close();}})}),{lease});
+    }
+    async revalidateTag(values,durations){await backend.updateTags(Array.isArray(values)?values:[values],durations);}
+    resetRequestCache(){}
+    async close(){await backend.close();}
+  };
+}
+module.exports={createRedisCache,createRedisIncrementalCache};

package/compat/redis-cache.d.cts

@@ -0,0 +1,37 @@
+/// <reference types="node" />
+export interface RedisCacheOptions {
+  /** Unique application namespace, shared by its replicas. */
+  namespace: string;
+  /** Runtime environment variable; the URL is never embedded in a build. Default REDIS_URL. */
+  urlEnv?: string;
+  /** An already-connected node-redis client. Its lifecycle remains yours. */
+  client?: {readonly isReady?: boolean; withTypeMapping(mapping: {36: BufferConstructor}): {sendCommand(args: (string | Buffer)[], options?: {abortSignal?: AbortSignal}): Promise<unknown>}};
+  leaseMs?: number;
+  waitMs?: number;
+  commandTimeoutMs?: number;
+  maxAgeSeconds?: number;
+}
+interface CacheEntry {value: ReadableStream<Uint8Array>; tags: string[]; timestamp: number; stale: number; revalidate: number; expire: number}
+interface Lease {token: string; started: number; epoch: string; incarnation: string; release(): Promise<void>}
+export declare function createRedisCache(options: RedisCacheOptions): {
+  get(key: string, softTags?: string[]): Promise<CacheEntry | undefined>;
+  set(key: string, entry: Promise<CacheEntry>, options?: {lease?: Lease; softTags?: string[]}): Promise<void>;
+  acquire(key: string, options?: {signal?: AbortSignal}): Promise<Lease>;
+  refreshTags(): Promise<void>;
+  getExpiration(): Promise<number>;
+  updateTags(tags: string[], durations?: {expire: number}): Promise<void>;
+  close(): Promise<void>;
+};
+
+export interface IncrementalRedisLease {token: string; epoch: string; incarnation: string; startedAt: number}
+/** Configure its returned constructor as cacheHandler; Cache Components use createRedisCache separately. */
+export declare function createRedisIncrementalCache(options: RedisCacheOptions): new (context?: unknown) => {
+  readonly prnextLeaseVersion: 1;
+  acquire(key: string, options?: {signal?: AbortSignal}): Promise<IncrementalRedisLease>;
+  release(key: string, lease: IncrementalRedisLease): Promise<void>;
+  get(key: string, context?: {tags?: string[]; softTags?: string[]}): Promise<{value: unknown; lastModified: number; isStale?: boolean} | null>;
+  set(key: string, value: unknown, context?: {prnextLease?: IncrementalRedisLease; tags?: string[]; softTags?: string[]; cacheControl?: {revalidate: number | false}}): Promise<boolean>;
+  revalidateTag(tags: string | string[], durations?: {expire?: number}): Promise<void>;
+  resetRequestCache(): void;
+  close(): Promise<void>;
+};

package/compat/server-primitives.cjs

@@ -1,5 +1,5 @@
 'use strict';
-const { CookieStore, ResponseCookieStore } = require('./cookies.cjs');
+const { RequestCookieStore, ResponseCookieStore } = require('./cookies.cjs');
 const { hasBasePath, addBasePath, removeBasePath } = require('./paths.cjs');
 const { localePath, withLocale } = require('./locale.cjs');
 
@@ -14,21 +14,37 @@ function middlewareHeaders(init, headers) {
   headers.set('x-middleware-override-headers', names.join(','));
 }
 
+function nextDataPath(pathname) {
+  const match = /^\/_next\/data\/([^/]+)\/(.*)\.json$/.exec(pathname);
+  if (!match) return { pathname };
+  const parts = match[2].split('/');
+  return { buildId: match[1], pathname: parts[0] === 'index' ? '/' : '/' + parts.join('/') };
+}
+
 class NextURL extends URL {
   constructor(input, baseOrOptions, options) {
     const base = typeof baseOrOptions === 'string' || baseOrOptions instanceof URL ? baseOrOptions : undefined;
     const config = options || (base ? {} : baseOrOptions) || {};
     super(input, base || config.base);
     this._nextConfig = config.nextConfig || {};
+    this._forceLocale = config.forceLocale === true;
+    this._parseData = !(this._nextConfig.skipProxyUrlNormalize ?? this._nextConfig.skipMiddlewareUrlNormalize);
     this._trailingSlash = super.pathname === '/' ? !!this._nextConfig.trailingSlash : super.pathname.endsWith('/');
     this._basePath = hasBasePath(super.pathname, this._nextConfig.basePath) ? this._nextConfig.basePath || '' : '';
-    this._locale = this._nextConfig.i18n ? localePath(removeBasePath(super.pathname, this._basePath), {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
+    const logical = this._parseData ? nextDataPath(removeBasePath(super.pathname, this._basePath)) : { pathname: removeBasePath(super.pathname, this._basePath) };
+    this._buildId = logical.buildId;
+    this._locale = this._nextConfig.i18n ? localePath(logical.pathname, {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
+  }
+  get pathname() {
+    const raw = removeBasePath(super.pathname, this._basePath);
+    return localePath(this._parseData ? nextDataPath(raw).pathname : raw, this._nextConfig.i18n).pathname;
   }
-  get pathname() { return localePath(removeBasePath(super.pathname, this._basePath), this._nextConfig.i18n).pathname; }
   set pathname(value) { super.pathname = addBasePath(withLocale(String(value).startsWith('/') ? value : `/${value}`, this._locale, this.defaultLocale), this._basePath); }
   get defaultLocale() { return this.domainLocale?.defaultLocale || this._nextConfig.i18n?.defaultLocale; }
   get domainLocale() { return this._nextConfig.i18n?.domains?.find(value=>value.domain.toLowerCase()===this.host.toLowerCase()); }
   get locale() { return this._locale; }
+  get buildId() { return this._buildId; }
+  set buildId(value) { this._buildId = value; }
   set locale(value) {
     if (!this._nextConfig.i18n?.locales.includes(value)) throw new TypeError(`Unknown locale: ${value}`);
     const pathname=this.pathname;this._locale=value;this.pathname=pathname;
@@ -43,8 +59,13 @@ class NextURL extends URL {
   set trailingSlash(value) { this._trailingSlash = value; }
   get href() {
     const url = new URL(super.href);
-    if (this._nextConfig.i18n) url.pathname=addBasePath(withLocale(this.pathname,this._locale,this.defaultLocale),this._basePath);
-    if (this._trailingSlash) { if (!url.pathname.endsWith('/')) url.pathname += '/'; }
+    let pathname = withLocale(this.pathname, this._locale, this._buildId || this._forceLocale ? undefined : this.defaultLocale);
+    if (this._buildId) {
+      pathname = pathname.replace(/\/$/, '');
+      pathname = '/_next/data/' + this._buildId + pathname + (this.pathname === '/' ? '/index.json' : '.json');
+    }
+    url.pathname = addBasePath(pathname, this._basePath);
+    if (this._trailingSlash && !this._buildId) { if (!url.pathname.endsWith('/')) url.pathname += '/'; }
     else if (url.pathname !== '/') url.pathname = url.pathname.replace(/\/$/, '');
     return url.href;
   }
@@ -54,19 +75,18 @@ class NextURL extends URL {
     super.href = value;
     this._trailingSlash = super.pathname === '/' ? !!this._nextConfig.trailingSlash : super.pathname.endsWith('/');
     this._basePath = hasBasePath(super.pathname, this._nextConfig.basePath) ? this._nextConfig.basePath || '' : '';
-    this._locale = this._nextConfig.i18n ? localePath(removeBasePath(super.pathname, this._basePath), {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
+    const logical = this._parseData ? nextDataPath(removeBasePath(super.pathname, this._basePath)) : { pathname: removeBasePath(super.pathname, this._basePath) };
+    this._buildId = logical.buildId;
+    this._locale = this._nextConfig.i18n ? localePath(logical.pathname, {...this._nextConfig.i18n,defaultLocale:this.defaultLocale}).locale : '';
   }
-  clone() { return new NextURL(this.href, { nextConfig: this._nextConfig }); }
+  clone() { return new NextURL(this.href, { nextConfig: this._nextConfig, forceLocale: this._forceLocale }); }
 }
 
 class NextRequest extends Request {
   constructor(input, init) {
     super(input, init);
     this.nextUrl = new NextURL(this.url, { nextConfig: init?.nextConfig || input?.nextUrl?._nextConfig });
-    this.cookies = new CookieStore(this.headers.get('cookie') || '', {
-      mutable: true,
-      onChange: () => this.headers.set('cookie', this.cookies.toString()),
-    });
+    this.cookies = new RequestCookieStore(this.headers);
   }
 }
 

package/compat/server.d.cts

@@ -1,7 +1,20 @@
 import type { CookieStore } from './headers.cjs';
 export interface NextURLConfig { i18n?: import('./index.js').NextConfig['i18n']; basePath?: string; trailingSlash?: boolean; skipMiddlewareUrlNormalize?: boolean; skipProxyUrlNormalize?: boolean }
-export class NextURL extends URL { constructor(input: string | URL, options?: { base?: string | URL; nextConfig?: NextURLConfig }); constructor(input: string | URL, base: string | URL, options?: { nextConfig?: NextURLConfig }); clone(): NextURL; locale: string; readonly defaultLocale?: string; readonly domainLocale?: NonNullable<NonNullable<import('./index.js').NextConfig['i18n']>['domains']>[number]; basePath: string; trailingSlash: boolean }
-export class NextRequest extends Request { constructor(input: RequestInfo | URL, init?: RequestInit & { nextConfig?: NextURLConfig }); nextUrl: NextURL; cookies: CookieStore }
+export class NextURL extends URL { constructor(input: string | URL, options?: { base?: string | URL; nextConfig?: NextURLConfig; forceLocale?: boolean }); constructor(input: string | URL, base: string | URL, options?: { nextConfig?: NextURLConfig; forceLocale?: boolean }); clone(): NextURL; buildId: string | undefined; locale: string; readonly defaultLocale?: string; readonly domainLocale?: NonNullable<NonNullable<import('./index.js').NextConfig['i18n']>['domains']>[number]; basePath: string; trailingSlash: boolean }
+export interface RequestCookie { name: string; value: string }
+export interface RequestCookieStore extends Iterable<[string, RequestCookie]> {
+  readonly size: number;
+  get(name: string | {name: string}): RequestCookie | undefined;
+  getAll(name?: string | {name: string}): RequestCookie[];
+  has(name: string): boolean;
+  set(name: string, value: string): this;
+  set(cookie: RequestCookie): this;
+  delete(name: string): boolean;
+  delete(names: string[]): boolean[];
+  clear(): this;
+  toString(): string;
+}
+export class NextRequest extends Request { constructor(input: RequestInfo | URL, init?: RequestInit & { nextConfig?: NextURLConfig }); nextUrl: NextURL; cookies: RequestCookieStore }
 export interface MiddlewareResponseInit extends ResponseInit { request?: { headers?: Headers } }
 export class NextResponse<Body = unknown> extends Response {
   cookies: CookieStore;

package/compat/static-generation.cjs

@@ -27,6 +27,13 @@ function dynamicUsage(reason, request = context()) {
 function staticBailout(reason, request = context()) {
   if (diagnostics.enabled) diagnostics.record('dynamic', { route: diagnostics.route(request), reason });
   const state = request?.staticState;
+  if (!state && request?.navigationStage && ['an uncached fetch', 'connection()', 'unstable_noStore()'].includes(reason)
+      && !require('./data-cache.cjs').inCacheScope()) require('./navigation-stages.cjs').postponeStage(reason);
+  const requirement = request?.cacheConfig?.ensureStatic;
+  if (!state && (request?.navigationStage === 'shell' && ['shell', 'prefetch', 'navigation'].includes(requirement)
+      || request?.navigationStage === 'prefetch' && ['prefetch', 'navigation'].includes(requirement))) {
+    require('./navigation-stages.cjs').postponeStage(reason);
+  }
   if (!state) return true;
   if (state.partial && state.mode === 'auto') {
     state.dynamicReasons.add(reason);

package/compat/use-cache.cjs

@@ -35,6 +35,9 @@ function recordCacheDependency({ tags = [], revalidate } = {}) {
 }
 function metadata(scope, context) { return { ...scope.life, revalidate: Math.min(scope.life.revalidate, scope.life.expire), tags: [...scope.tags], paths: getCachePaths(context), ...(scope.externalCache ? { externalCache: true } : {}) }; }
 function propagate(info, parent, context) {
+  if (context?.staticState && context.cacheConfig?.ensureStatic === 'navigation' && (info.expire < 300 || info.stale < 30 || info.revalidate === 0)) {
+    dynamicUsage('a cache lifetime with expire below 300 seconds, stale below 30 seconds, or revalidate=0', context);
+  }
   trackStaticDependency(info, context);
   if (!parent || parent === true) return;
   if (info.externalCache) parent.externalCache = true;

package/docs/ai/compatibility.md

@@ -18,12 +18,181 @@ transpilation, image/font tooling and caching deserve targeted build and browser
 tests. Support for one configuration shape does not imply support for all
 upstream plugin behavior.
 
+## Instrumentation and tracing
+
+Use a single `instrumentation.ts`, `.js`, `.mjs` or `.cjs` at the project root
+or in `src`. Export an optional async `register()` for runtime initialization
+and an optional async `onRequestError(error, request, context)` for reporting.
+The `Instrumentation.onRequestError` type is exported from PRNext's root API.
+`process.env.NEXT_RUNTIME` distinguishes `nodejs` and `edge`; conditional imports
+keep Node SDKs out of an Edge bundle. Registration runs once per server realm,
+including the separate RSC realm, before application requests. A production
+prerender does not run the runtime startup hook. Request-time ISR and PPR
+regeneration initialize their server realm and report failures through the same
+hooks. Repeated propagation of an RSC error to the HTML worker does not report
+the same error again.
+
+```ts
+import type { Instrumentation } from '@thomas.f/prnext'
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./observability.node')
+  }
+}
+
+export const onRequestError: Instrumentation.onRequestError = async (
+  error, request, context
+) => {
+  await reportError(error, request, context)
+}
+```
+
+`reportError` above is an application function, not a PRNext API. Initialization
+has a 30-second budget. Each error hook has a five-second budget; reporting
+failure does not replace the application failure. Redirect/not-found control
+signals are excluded. Hooks receive request information: the application owns
+redaction before sending that information to a third party.
+
+For built-in correlated traces, explicitly set
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to an OTLP HTTP collector's complete traces
+URL and `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json`. Alternatively,
+`OTEL_EXPORTER_OTLP_ENDPOINT` supplies a base URL with `/v1/traces` appended.
+`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS` (or general
+`OTEL_EXPORTER_OTLP_HEADERS`) and `OTEL_SDK_DISABLED=true` are supported. Keep
+exporter credentials in the server environment. This built-in path supports
+HTTP JSON, not gRPC or HTTP protobuf; use your own SDK for other protocols.
+
+Native HTTP spans cover static and dynamic responses through body completion
+or cancellation. Node, RSC and fetch spans share W3C trace context. Export queues
+are bounded and telemetry is best effort; an unavailable collector does not
+block a site response. Built-in span attributes exclude bodies, cookie values,
+query strings and authorization headers. An application-installed
+`@opentelemetry/api` can use the same parent context when its SDK installs a
+context manager in `register`. No SDK is installed automatically, and this does
+not certify every vendor integration.
+
+## Production bytes and navigation
+
+Production CSS Modules use deterministic compact class and animation names.
+Global classes and declared composition exports retain their meaning; development
+keeps readable names. Internal JavaScript exports are shortened by the selected
+compiler, while public exports and dynamic imports keep their interfaces. Asset
+hashes and source maps remain compiler-owned.
+
+App navigation can negotiate binary differential Flight responses. Every request
+still runs fresh rendering and access checks. The server retains at most 64
+completed bases, 32 MiB in total, with a two-MiB per-base limit and 30-second
+expiry. Bases are keyed by deployment and credentials; an unknown, expired or
+incompatible base produces ordinary Flight. The browser retains one completed
+base, streams reconstructed bytes to React and can retry one failed differential
+navigation as a full GET. Server Actions are never replayed through this path.
+Per worker, at most eight captures and two encoders run together. Additional
+requests use ordinary Flight, keeping transient transport work bounded too.
+
 Configuration uses one `next.config.*` or `prnext.config.*` file and rejects
-unknown keys rather than ignoring them. `reactCompiler: false` is accepted;
-enabling React Compiler is explicitly unsupported. `typedRoutes: true` is
+unknown keys rather than ignoring them. React Compiler is available through an
+explicit `reactCompiler` option described below. `typedRoutes: true` is
 implemented through PRNext's generated route registry. Do not copy a full
 Next.js configuration template into a new application.
 
+The repository's reference tests build and run matching applications against
+Next.js 16.4.3, including mounted App navigation, form Actions and cookies,
+metadata, Pages locale routing, redirects, APIs and selected webpack loader
+contracts. These executable examples cover specific behavior; they do not
+certify every Next.js application or plugin. `NextRequest.nextUrl` understands
+data-route build IDs and locales, and request-cookie mutations synchronize the
+request header. Request cookies have different mutation results from response
+cookies; do not use them interchangeably.
+
+A locked real-application fixture additionally exercises Better Auth 1.7.14
+(email/password, session cookies and logout), Drizzle ORM 0.45.4 over SQLite
+through its proxy driver, next-intl 4.14.9 (server and client translations),
+and the MDX 3.1.1 webpack loader against Next.js 16.4.3. It covers authenticated
+Server Actions, user-owned rows, cookie/locale isolation, client navigation and
+Server Component `after()` callbacks. This is evidence for those workflows,
+not a guarantee for every plugin, provider or deployment configuration.
+
+PRNext-specific options such as `prerender` and `htmlOnly` are described in
+[Build and deployment](deployment.md). Do not pass them to an upstream Next.js
+build when comparing the two implementations.
+
+## TypeScript 7 and earlier compilers
+
+PRNext uses the application's installed TypeScript. TypeScript 7 runs through its
+official native `tsc` command for production checks, `prnext typecheck` and live
+development diagnostics. Install TypeScript normally, including its platform
+optional dependencies. PRNext does not download a compiler during a build.
+TypeScript 5 and 6 retain their compiler API integration.
+
+Checks use `--noEmit` and keep incremental compiler state in an owned temporary
+directory. Development reports updated errors and clears fixed diagnostics;
+new source files and configuration changes restart the native watch generation.
+`typedRoutes` also supports native TypeScript and preserves JSONC comments when
+adding its generated declaration to the config. Compiler support does not imply
+that every application is ready for TypeScript 7's own language/config changes.
+
+## React Compiler
+
+Enable the bundled official React Compiler in the project's existing config:
+
+```js
+export default {
+  reactCompiler: true,
+};
+```
+
+No separate compiler installation is required. The default is disabled;
+`reactCompiler: false` preserves the uncompiled component path. Enabled builds
+optimize project-owned browser components in both Pages and App applications,
+in development and production. App Client Components also use the transform in
+their isolated server-rendering graph. The Pages server graph stays uncompiled,
+including APIs, custom Document code and data-loader utilities, so ordinary
+server functions never acquire client-only memoization hooks. React Server
+Components, Server Action modules, PRNext internals, generated entrypoints and
+npm packages are not compiled. Keep the matching React 19 peer versions required
+by the installed framework.
+
+Ordinary `.mts`/`.cts` hook helpers can be optimized; server/client directives
+in those extensions remain unsupported. Decorated `.mts`/`.cts` utility modules
+keep their native compilation path while importing React components can still
+be optimized.
+
+For gradual adoption, use `reactCompiler: { compilationMode: 'annotation' }`, then
+put `"use memo";` at the beginning of each component or hook to optimize. In
+either mode, `"use no memo";` excludes an individual function. Supported object
+options are `compilationMode: 'infer' | 'annotation'`,
+`panicThreshold: 'none' | 'critical_errors' | 'all_errors'` and `target: '19'`.
+Defaults are `'infer'`, `'none'` and `'19'`; other fields are rejected.
+
+After a successful build, inspect the compiler's actual results:
+
+```sh
+prnext compiler
+prnext compiler --json
+```
+
+The report names observed functions, their project-relative files, optimization
+or skip status, and the compiler's reasons. These are transform decisions;
+server-code removal and tree shaking can later omit a function from the browser
+bundle. Cached transforms retain their
+diagnostics and are identified as reused. Browser and server graphs do not
+inflate the function count. An incremental build can reuse graph inputs without
+observing every transform; the report states that scope rather than claiming
+complete application coverage. Disabled compilation is reported explicitly.
+The report describes the last successful build, stays outside public assets and
+does not include source code. A failed build preserves the previous report.
+
+The compiler can skip code that cannot be safely optimized. Follow the Rules of
+React and check actual behavior rather than assuming every component was
+compiled. It reduces repeated component work; it does not guarantee faster
+server responses, smaller JavaScript or a specific speed multiplier. Validate
+hydration, interactions and Fast Refresh in the application, then compare a
+production build with the option enabled and disabled. Compilation adds build
+work; PRNext caches pure transforms with their compiler version and settings.
+
+See the [official React Compiler documentation](https://react.dev/learn/react-compiler).
+
 Only explicit private Next.js import adapters are supported. Do not add arbitrary
 `next/dist/...` imports or install another Next runtime to satisfy one: isolate
 or replace the incompatible dependency, retain the original framework where