@wular/pnext 0.0.18 → 0.0.20

package/src/dev/restart/route-facts.ts

@@ -13,19 +13,17 @@
 // One file PER ROUTE, not one index: the whole table is large and the first page only ever asks
 // about the route it is serving, so as a single index its JSON.parse landed, in full, on that
 // request and gave most of the walk back.
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import type { ResolvedConfig } from '../../config'
 import { setRouteFactsStore, type RouteFacts, type RouteFactsStore } from '../../routing/routes'
 import { traceEnabled } from '../../utils/trace-flags'
 import { restartCacheEnabled } from './enabled'
-
-/** `[file, mtimeMs, size, contentHash]` — the same record shape the key cache uses. */
-type SourceEntry = [string, number, number, string]
+import { hash, lazyRecordCacheKey, revalidate, sourceEntry, type SourceEntry } from './record'
 
 interface RecordFile {
   version: number
-  /** Everything the facts depend on that is not a walked source (see cacheKey). */
+  /** Everything the facts depend on that is not a walked source (see restart/record.ts). */
   key: string
   files: SourceEntry[]
   facts: RouteFacts
@@ -34,45 +32,10 @@ interface RecordFile {
 /** Bumped whenever a record's shape changes; an older record is simply ignored. */
 const RECORD_VERSION = 1
 
-const hash = (value: string) => Bun.hash(value).toString(36)
-
-/**
- * The facts of a route whose own sources did not move can still change when the
- * thing that *interprets* them does: the resolved config (compat on/off, route
- * extensions, aliases) or pnext itself. Both go in the record's key, so either
- * one moving makes every record read as a miss instead of half-validating it.
- */
-function cacheKey(config: ResolvedConfig): string | undefined {
-  try {
-    const shape = JSON.stringify(config, (_key, value: unknown) =>
-      typeof value === 'function' ? '[fn]' : value,
-    )
-    return hash(`${RECORD_VERSION}\n${pnextBuildStamp()}\n${shape}`)
-  } catch {
-    // A config that will not serialize (cycles, exotic values) simply opts out.
-    return undefined
-  }
-}
-
-/**
- * mtime+size of the route scanner this process is running. The facts are the framework's own reading of
- * the app's sources, so a pnext that changed since the record was written must re-derive them rather than
- * inherit the old answers - which is what keeps this safe while pnext itself is being edited.
- */
-function pnextBuildStamp() {
-  try {
-    const self = Bun.fileURLToPath(import.meta.url)
-    const scanner = path.join(path.dirname(path.dirname(self)), 'routing', 'routes.ts')
-    const info = statSync(scanner, { throwIfNoEntry: false })
-    return info ? `${info.mtimeMs}:${info.size}` : self
-  } catch {
-    return 'unknown'
-  }
-}
-
 interface FactsCache {
   dir: string
-  key: string
+  /** Resolved on first use, not at install; see restart/record.ts. */
+  key: () => string | undefined
   /** Records written this process, so a repeat save does not re-serialize. */
   written: Set<string>
 }
@@ -81,11 +44,9 @@ export function installRouteFactsCache(config: ResolvedConfig) {
   if (!restartCacheEnabled()) return
   // eslint-disable-next-line turbo/no-undeclared-env-vars
   if (process.env.PNEXT_DEV_FACTS_CACHE === '0') return
-  const key = cacheKey(config)
-  if (!key) return
   const cache: FactsCache = {
     dir: path.join(config.outPath, 'cache', 'route-facts'),
-    key,
+    key: lazyRecordCacheKey(config, RECORD_VERSION),
     written: new Set(),
   }
   setRouteFactsStore(createStore(cache))
@@ -132,7 +93,7 @@ function readRecord(cache: FactsCache, routeId: string): RecordFile | undefined
   } catch {
     return undefined
   }
-  if (parsed?.version !== RECORD_VERSION || parsed.key !== cache.key) return undefined
+  if (parsed?.version !== RECORD_VERSION || parsed.key !== cache.key()) return undefined
   if (!parsed.facts || !Array.isArray(parsed.files)) return undefined
   return parsed
 }
@@ -143,11 +104,13 @@ function readRecord(cache: FactsCache, routeId: string): RecordFile | undefined
  * once per process per route.
  */
 function write(cache: FactsCache, routeId: string, files: SourceEntry[], facts: RouteFacts) {
-  if (cache.written.has(routeId)) return
+  const key = cache.key()
+  // A config that will not serialize has no key, so nothing is recorded for it.
+  if (!key || cache.written.has(routeId)) return
   cache.written.add(routeId)
   const contents = JSON.stringify({
     version: RECORD_VERSION,
-    key: cache.key,
+    key,
     files,
     facts,
   } satisfies RecordFile)
@@ -174,48 +137,6 @@ function factsSources(facts: RouteFacts): SourceEntry[] | undefined {
   return entries
 }
 
-function sourceEntry(file: string): SourceEntry | undefined {
-  try {
-    const source = readFileSync(file, 'utf8')
-    // Stat AFTER the read: a file that changes between the two records the
-    // older stat, so the next boot re-hashes rather than trusting a stale one.
-    const info = statSync(file, { throwIfNoEntry: false })
-    if (!info) return undefined
-    return [file, info.mtimeMs, info.size, hash(source)]
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * The recorded sources, re-stated: `files` itself when nothing moved, a fresh list when only stats moved,
- * `undefined` when any content actually differs - or a source is gone, which is the same thing, since the
- * walk has to run again.
- */
-function revalidate(files: SourceEntry[]): SourceEntry[] | undefined {
-  let moved = false
-  const checked: SourceEntry[] = []
-  for (const entry of files) {
-    const [file, mtimeMs, size, contentHash] = entry
-    const info = statSync(file, { throwIfNoEntry: false })
-    if (!info) return undefined
-    if (info.mtimeMs === mtimeMs && info.size === size) {
-      checked.push(entry)
-      continue
-    }
-    let source: string
-    try {
-      source = readFileSync(file, 'utf8')
-    } catch {
-      return undefined
-    }
-    if (hash(source) !== contentHash) return undefined
-    moved = true
-    checked.push([file, info.mtimeMs, info.size, contentHash])
-  }
-  return moved ? checked : files
-}
-
 /** Bisect seam: `PNEXT_TRACE=server` prints the hit/miss split at exit. */
 const stats = { hits: 0, misses: 0 }
 if (traceEnabled('server')) {

package/src/dev/server.ts

@@ -32,13 +32,22 @@ import {
   serverBundleTargetForRuntime,
 } from '../runtime/loader'
 import { applyProxyResponse, createProxyRunner, validateProxyFiles } from '../routing/proxy'
-import { renderGlobalNotFoundResponse, renderPageResponse } from '../render/renderer'
-import { getFontExtensions } from '../render/hooks'
-import { clearMetadataFileCaches, metadataRouteHandlerModule } from '../routing/metadata-files'
+import { errorLogTrace, renderGlobalNotFoundResponse, renderPageResponse } from '../render/renderer'
+import { markErrorLogged } from '../utils/error-log'
+import { escapeHtml } from '../utils/html'
+import { internalErrorHtml } from './internal-error'
+import { getFontExtensions, nextCompatEnabled } from '../render/hooks'
+import {
+  clearMetadataFileCaches,
+  discoverStaticMetadataFiles,
+  metadataRouteHandlerModule,
+  staticMetadataCacheControl,
+} from '../routing/metadata-files'
 import { handleRouteModule, type RouteHandlerModule } from '../routing/handler'
 import { malformedUrlResponse, trailingSlashRedirect } from '../routing/href'
-import { withForwardedHeaders } from '../routing/forwarded'
+import { type PeerAddressSource, withForwardedHeaders } from '../routing/forwarded'
 import {
+  assertNoServerActionsWithoutCompat,
   findLayouts,
   matchRoute,
   materializeRouteFactsPaced,
@@ -107,6 +116,13 @@ interface DevServerOptions {
   warm?: boolean
 }
 
+// Bun closes the socket itself at this point, so a stalled render surfaces as a
+// bare 499; the abort log reads the same constant to attribute it.
+const DEV_IDLE_TIMEOUT_SECONDS = 60
+const DEV_IDLE_TIMEOUT_MS = DEV_IDLE_TIMEOUT_SECONDS * 1000
+// Long before that, warn once that the render is still going.
+const DEV_PAGE_STALL_WARNING_MS = 20_000
+
 const clientBuilds = new Map<string, Promise<string>>()
 const clientChunks = new Map<string, string>()
 
@@ -370,20 +386,28 @@ export async function startDevServer(options: DevServerOptions) {
   const server = Bun.serve({
     hostname,
     port,
-    idleTimeout: 60,
+    idleTimeout: DEV_IDLE_TIMEOUT_SECONDS,
     fetch(request, server) {
       // One work unit spans the whole request; its after-queue flushes once the
       // response fully closes (stream end, redirect, notFound, error, abort).
       inFlight++
-      return runWithWorkUnit('render', () => handleDevRequest(request, server)).finally(() => {
-        inFlight--
-      })
+      // The handler's own catch covers the routing/render body. This covers the
+      // rest of it - the prologue that runs before that try, and every
+      // `return finish(...)` whose rejection a bare return hands straight past
+      // it. A rejection reaching Bun is Bun's fallback page, or a reset socket.
+      return runWithWorkUnit('render', () => handleDevRequest(request, server))
+        .catch((error: unknown) => devLastResortResponse(error, request))
+        .finally(() => {
+          inFlight--
+        })
     },
+    // Nothing should reach here now, but Bun's own fallback is never the answer.
+    error: (error: Error) => devLastResortError(error),
   })
 
   async function handleDevRequest(
     request: Request,
-    server: { timeout(request: Request, seconds: number): void },
+    server: PeerAddressSource & { timeout(request: Request, seconds: number): void },
   ): Promise<Response> {
     const prologueStart = performance.now()
     // The compat implementation graph loads here, on the first request, not at
@@ -394,11 +418,11 @@ export async function startDevServer(options: DevServerOptions) {
     const unit = getWorkUnit()
     const badRequest = malformedUrlResponse(request)
     if (badRequest) return badRequest
-    request = withForwardedHeaders(request)
+    request = withForwardedHeaders(request, server)
     let url = new URL(request.url)
     const profile = devRequestProfile(request, url)
     if (profile) logDevProfile(profile, 'prologue (bootstrap/headers/url)', prologueStart)
-    let pageLog = pendingDevPageLoadLog(routes, request, url)
+    let pageLog = startDevPageStallTimer(pendingDevPageLoadLog(routes, request, url))
     // Work this request wants started, but only once its own response is out.
     let afterResponse: (() => void) | undefined
     const logAbort = () => {
@@ -415,7 +439,7 @@ export async function startDevServer(options: DevServerOptions) {
         finalizeResponse(
           response,
           { method: request.method, url: new URL(request.url), headers: request.headers },
-          { routeKind: unit?.routeKind ?? 'html', routeMode: unit?.routeMode },
+          { routeKind: unit?.routeKind ?? 'html', routeMode: unit?.routeMode, dev: true },
         ),
       )
       const logged = logDevPageResponse(pending, finalized)
@@ -446,7 +470,9 @@ export async function startDevServer(options: DevServerOptions) {
         request = proxyResult.request
         proxyResponse = proxyResult.response
         url = new URL(request.url)
-        pageLog = pendingDevPageLoadLog(routes, request, url, pageLog?.start)
+        const rewrittenLog = pendingDevPageLoadLog(routes, request, url, pageLog?.start)
+        clearDevPageStallTimer(pageLog)
+        pageLog = startDevPageStallTimer(rewrittenLog)
 
         const rewrittenPrefetchResponse = maybeDevPagePrefetchResponse(
           routes,
@@ -468,7 +494,7 @@ export async function startDevServer(options: DevServerOptions) {
       if (assetResponse) return finish(applyProxyResponse(assetResponse, proxyResponse))
 
       const clientChunkResponse = await profileDevStep(profile, 'client chunk lookup', () =>
-        maybeDevClientChunk(config, routes, url.pathname),
+        maybeDevClientChunk(config, url.pathname),
       )
       if (clientChunkResponse) return finish(applyProxyResponse(clientChunkResponse, proxyResponse))
 
@@ -518,6 +544,14 @@ export async function startDevServer(options: DevServerOptions) {
         )
       }
 
+      const metadataFile = await profileDevStep(profile, 'static metadata file', () =>
+        maybeStaticMetadataFile(config, url),
+      )
+      if (metadataFile) {
+        setWorkUnitRoute('static-asset')
+        return finish(applyProxyResponse(metadataFile, proxyResponse))
+      }
+
       const staticResponse = await profileDevStep(profile, 'static lookup', () =>
         maybeStaticFile(config.publicPath, url.pathname),
       )
@@ -566,7 +600,10 @@ export async function startDevServer(options: DevServerOptions) {
           applyProxyResponse(
             new Response('Not Found', {
               status: 404,
-              headers: { 'content-type': 'text/plain' },
+              headers: {
+                'cache-control': 'private, no-cache, no-store, max-age=0, must-revalidate',
+                'content-type': 'text/plain;charset=utf-8',
+              },
             }),
             proxyResponse,
           ),
@@ -636,6 +673,9 @@ export async function startDevServer(options: DevServerOptions) {
       }
 
       setWorkUnitRoute('html', matched.route.mode === 'static' ? 'static' : 'dynamic')
+      // Same refusal the build makes, at the only point dev has one: a core app
+      // with a 'use server' module gets the error document, not a dead form.
+      assertNoServerActionsWithoutCompat([matched.route], nextCompatEnabled(config), config.root)
       pageRequestsSeen++
       noteDevCompileStart(matched.route)
       noteDevRouteServed(config, matched.route)
@@ -710,8 +750,7 @@ export async function startDevServer(options: DevServerOptions) {
       )
     } catch (error) {
       request.signal.removeEventListener('abort', logAbort)
-      // The error funnel (compat classifies + reports) fires from this single
-      // catch, then dev rethrows so Bun surfaces its own overlay/500.
+      // The error funnel (compat classifies + reports) fires from this single catch.
       await reportRequestError(
         error,
         { method: request.method, url: request.url, headers: request.headers },
@@ -719,7 +758,11 @@ export async function startDevServer(options: DevServerOptions) {
       )
       logDevPageError(pageLog)
       flushWorkUnit(unit)
-      throw error
+      // Rethrowing here handed the request to Bun, which answered with its raw
+      // __bunfallback payload page (or dropped the connection outright). Nothing
+      // downstream can render this one - the render pipeline is where it came
+      // from - so dev answers with its own document, always.
+      return devLastResortResponse(error, request)
     }
   }
 
@@ -734,6 +777,42 @@ export async function startDevServer(options: DevServerOptions) {
   return Object.assign(server, { warmup })
 }
 
+/**
+ * Dev's last resort: an error that escaped the render pipeline's own boundaries.
+ * Reaching here means pnext could not build a document the normal way, so the
+ * internal-error page (full trace + prefilled report) is the honest answer.
+ * Must not throw - it is the thing that runs when everything else already did.
+ */
+function devLastResortResponse(error: unknown, request: Request): Response {
+  let route = request.url
+  try {
+    route = new URL(request.url).pathname
+  } catch {
+    // A malformed URL is exactly the kind of request that gets here; keep the raw text.
+  }
+  return devLastResortError(error, route, request.url)
+}
+
+function devLastResortError(error: unknown, route = '(unknown)', url = route): Response {
+  const resolved = error instanceof Error ? error : new Error(String(error))
+  if (markErrorLogged(resolved)) console.error(errorLogTrace(resolved))
+  let html: string
+  try {
+    html = internalErrorHtml({
+      error: resolved,
+      route,
+      url,
+      digest: (resolved as Error & { digest?: string }).digest,
+    })
+  } catch {
+    html = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>pnext error</title></head><body><h1>pnext could not render this request</h1><pre>${escapeHtml(resolved.stack ?? resolved.message)}</pre></body></html>`
+  }
+  return new Response(html, {
+    status: 500,
+    headers: { 'content-type': 'text/html; charset=utf-8' },
+  })
+}
+
 /**
  * The Ready banner is printed by the caller in the microtask that resolves
  * `startDevServer`, so a timer callback is the earliest point that provably
@@ -1164,29 +1243,32 @@ async function buildDevClient(config: ResolvedConfig, route: RouteManifestEntry)
   return build
 }
 
-async function maybeDevClientChunk(
-  config: ResolvedConfig,
-  routes: RouteManifestEntry[],
-  pathname: string,
-) {
+async function maybeDevClientChunk(config: ResolvedConfig, pathname: string) {
   const chunkMatch = /^\/__pnext\/client\/chunks\/(.+\.js)$/.exec(pathname)
   if (!chunkMatch?.[1]) return null
-  const cached = clientChunks.get(chunkMatch[1])
-  if (cached && existsSync(cached)) {
-    return devChunkResponse(await readFile(cached))
-  }
-
-  for (const route of routes) {
-    if (!route.client && route.clientReferences.length === 0) continue
-    const cacheKey = await routeClientCacheKey(config, route)
-    const outDir = path.join(config.outPath, 'cache', 'client', cacheKey)
-    await buildDevClient(config, route)
-    const file = path.join(outDir, 'chunks', chunkMatch[1])
-    if (!isInside(path.join(outDir, 'chunks'), file) || !existsSync(file)) continue
-    return devChunkResponse(await readFile(file))
+  const file = await resolveDevClientChunk(config, chunkMatch[1])
+  return file ? devChunkResponse(await readFile(file)) : null
+}
+
+// A chunk only exists because some build emitted it, so a miss never justifies building: wait out
+// the in-flight builds, then look across the generations on disk (chunk names are content hashes).
+// Building instead cost one full client build per route for a single stale chunk URL.
+async function resolveDevClientChunk(config: ResolvedConfig, name: string) {
+  const indexed = clientChunks.get(name)
+  if (indexed && existsSync(indexed)) return indexed
+  await Promise.allSettled([...clientBuilds.values()])
+  const settled = clientChunks.get(name)
+  if (settled && existsSync(settled)) return settled
+
+  const clientRoot = path.join(config.outPath, 'cache', 'client')
+  for (const generation of await readdir(clientRoot).catch(() => [])) {
+    const chunksDir = path.join(clientRoot, generation, 'chunks')
+    const file = path.join(chunksDir, name)
+    if (!isInside(chunksDir, file) || !existsSync(file)) continue
+    clientChunks.set(name, file)
+    return file
   }
-
-  return null
+  return undefined
 }
 
 /**
@@ -1221,6 +1303,20 @@ async function indexClientChunks(outDir: string) {
   }
 }
 
+// File-convention metadata assets (app/icon.png, apple-icon.png, favicon.ico, opengraph-image.png)
+// are emitted by the BUILD, so dev - which has no build output - served none of them and every dev
+// document 404'd the very icon/manifest links it had just rendered. Serve the source bytes at the
+// URL the document references. Icon/apple-icon queries carry a content identity;
+// favicon and manifest use their documented bare routes.
+async function maybeStaticMetadataFile(config: ResolvedConfig, url: URL) {
+  const target = url.pathname.replace(/^\/+/, '')
+  const file = discoverStaticMetadataFiles(config.appPath).find(item => item.outputPath === target)
+  if (!file || !existsSync(file.file)) return null
+  return new Response(await readFile(file.file), {
+    headers: { 'content-type': file.contentType, 'cache-control': staticMetadataCacheControl },
+  })
+}
+
 async function maybeStaticFile(publicPath: string, pathname: string) {
   const filePath = path.join(publicPath, pathname.replace(/^\/+/, ''))
   if (!isInside(publicPath, filePath) || !existsSync(filePath)) return null
@@ -1260,12 +1356,23 @@ function findClientReferenceCss(routes: RouteManifestEntry[], id: string) {
     .find(reference => reference.id === id && reference.cssImports?.length)
 }
 
+// Build assets are emitted under `/_next/static/` for a compat app (assetPathname) and `/assets/`
+// for core; the dev server answers to both spellings so the document's href and the served route
+// cannot drift. Only a flat name aliases - `/_next/static/chunks|media/*` are Next's own paths and
+// keep falling through to their handlers.
+function builtAssetPathname(config: ResolvedConfig, pathname: string) {
+  if (pathname.startsWith('/assets/')) return pathname
+  const alias = /^\/_next\/static\/([^/]+)$/.exec(pathname)
+  return alias?.[1] && nextCompatEnabled(config) ? `/assets/${alias[1]}` : null
+}
+
 async function maybeBuiltAsset(
   config: ResolvedConfig,
   routes: RouteManifestEntry[],
-  pathname: string,
+  requestPathname: string,
 ) {
-  if (!pathname.startsWith('/assets/')) return null
+  const pathname = builtAssetPathname(config, requestPathname)
+  if (!pathname) return null
   if (pathname === '/assets/global.css') {
     await buildDevAsset(config, pathname, () => buildGlobalCss(config, { dev: true }))
   } else {
@@ -1352,6 +1459,7 @@ interface PendingDevPageLoadLog {
   pathname: string
   route: string
   start: number
+  stallTimer?: ReturnType<typeof setTimeout>
 }
 
 interface DevPageLoadLog {
@@ -1360,6 +1468,7 @@ interface DevPageLoadLog {
   route: string
   status: number
   durationMs: number
+  note?: string
 }
 
 function pendingDevPageLoadLog(
@@ -1378,8 +1487,61 @@ function pendingDevPageLoadLog(
   }
 }
 
+// One timer per page request: if the render never resolves, the stall announces
+// itself well before Bun's idle timeout turns it into a mystery 499.
+function startDevPageStallTimer(pending: PendingDevPageLoadLog | undefined) {
+  if (!pending) return pending
+  const delay = Math.max(0, DEV_PAGE_STALL_WARNING_MS - (performance.now() - pending.start))
+  pending.stallTimer = setTimeout(() => {
+    console.warn(
+      formatDevPageStallWarning({
+        method: pending.method,
+        pathname: pending.pathname,
+        route: pending.route,
+        elapsedMs: performance.now() - pending.start,
+      }),
+    )
+  }, delay)
+  pending.stallTimer.unref?.()
+  return pending
+}
+
+function clearDevPageStallTimer(pending: PendingDevPageLoadLog | undefined) {
+  if (!pending?.stallTimer) return
+  clearTimeout(pending.stallTimer)
+  pending.stallTimer = undefined
+}
+
+export function formatDevPageStallWarning(entry: {
+  method: string
+  pathname: string
+  route: string
+  elapsedMs: number
+}) {
+  const route = entry.route === entry.pathname ? '' : dim(`(${entry.route})`)
+  return [
+    yellow('⚠'),
+    dim('page'),
+    dim(entry.method),
+    cyan(entry.pathname),
+    route,
+    yellow('still rendering'),
+    dim('after'),
+    durationLabel(entry.elapsedMs),
+    dim('- no response yet'),
+  ]
+    .filter(Boolean)
+    .join(' ')
+}
+
+// A 499 that lands on the idle timeout is Bun hanging up on us, not the client.
+export function devPageAbortNote(durationMs: number) {
+  return durationMs >= DEV_IDLE_TIMEOUT_MS ? 'dev server idle timeout' : undefined
+}
+
 function logDevPageResponse(pending: PendingDevPageLoadLog | undefined, response: Response) {
   if (!pending) return response
+  clearDevPageStallTimer(pending)
   logDevPageLoad({
     method: pending.method,
     pathname: pending.pathname,
@@ -1392,6 +1554,7 @@ function logDevPageResponse(pending: PendingDevPageLoadLog | undefined, response
 
 function logDevPageError(pending: PendingDevPageLoadLog | undefined) {
   if (!pending) return
+  clearDevPageStallTimer(pending)
   logDevPageLoad({
     method: pending.method,
     pathname: pending.pathname,
@@ -1403,12 +1566,15 @@ function logDevPageError(pending: PendingDevPageLoadLog | undefined) {
 
 function logDevPageAbort(pending: PendingDevPageLoadLog | undefined) {
   if (!pending) return
+  clearDevPageStallTimer(pending)
+  const durationMs = performance.now() - pending.start
   logDevPageLoad({
     method: pending.method,
     pathname: pending.pathname,
     route: pending.route,
     status: 499,
-    durationMs: performance.now() - pending.start,
+    durationMs,
+    note: devPageAbortNote(durationMs),
   })
 }
 
@@ -1443,6 +1609,7 @@ export function formatDevPageLoadLog(entry: DevPageLoadLog) {
     statusLabel(entry.status),
     dim('in'),
     durationLabel(entry.durationMs),
+    entry.note ? yellow(`(${entry.note})`) : '',
   ]
     .filter(Boolean)
     .join(' ')