@wular/pnext 0.0.19 → 0.0.20

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(' ')

package/src/extensions.ts

@@ -376,6 +376,17 @@ export interface RenderExtensions {
     context: VaryParamsTrackingContext,
   ) => T
 
+  /**
+   * Give a `params`/`searchParams` promise Next 15's transitional SYNC surface (the resolved keys
+   * readable without `await`), behind compat.next.legacyRequestAPIs. The SAME promise comes back —
+   * callers hand a settled thenable to `use()`. Default: identity.
+   */
+  legacySyncProps: <T extends object>(
+    promise: Promise<T>,
+    kind: 'params' | 'searchParams',
+    value: T,
+  ) => Promise<T>
+
   /** Optional opaque state lifecycle around partial prerenders. */
   prerenderSidecar: PrerenderSidecarExtension
 }
@@ -476,6 +487,7 @@ function createRenderExtensions(): RenderExtensions {
     formatErrorLog: () => undefined,
     globalNotFoundEnabled: () => false,
     trackVaryParams: value => value,
+    legacySyncProps: promise => promise,
     prerenderSidecar: {
       begin: () => undefined,
       collect: () => Promise.resolve(undefined),
@@ -704,8 +716,11 @@ export function registerRevalidateBypassToken(token: () => string | undefined):
  * Run every registered response finalizer against `response` before it is
  * flushed, then return the response to send. Finalizers see request info + the
  * outgoing status/headers and mutate them in place; when a finalizer changes the
- * status (immutable on a Response) the body is re-wrapped with the new status. A
- * no-finalizer app (pure core) returns the response untouched.
+ * status (immutable on a Response) the body is re-wrapped with the new status.
+ *
+ * The document cache-control default is applied LAST, and only when nothing
+ * upstream claimed the header: an ISR/`use cache` route's SWR value, a route
+ * handler's own header and compat's RSC `private, no-store` all win over it.
  */
 export async function finalizeResponse(
   response: Response,
@@ -714,10 +729,10 @@ export async function finalizeResponse(
     routeKind: ResponseRouteKind
     routeMode?: ResponseRouteMode
     hints?: Record<string, unknown>
+    dev?: boolean
   },
 ): Promise<Response> {
   const finalizers = activeHost.request.responseFinalizers
-  if (finalizers.length === 0) return response
   const ctx: ResponseFinalizerContext = {
     request,
     routeKind: info.routeKind,
@@ -727,6 +742,7 @@ export async function finalizeResponse(
     headers: response.headers,
   }
   for (const finalizer of finalizers) await finalizer(ctx)
+  applyDocumentCacheControl(ctx, info.dev === true)
   if (ctx.status === response.status) return response
   return new Response(response.body, {
     status: ctx.status,
@@ -735,6 +751,56 @@ export async function finalizeResponse(
   })
 }
 
+/**
+ * What Next answers a DOCUMENT with, byte for byte (measured against stock
+ * next@16.2.12, `next start` and `next dev`; see tests/compat/conformance):
+ *
+ *   dev, every document          `no-cache, must-revalidate`
+ *   prod, per-request document   `private, no-cache, no-store, max-age=0, must-revalidate`
+ *   prod, pure prerender (200)   `s-maxage=31536000`
+ *   prod, ISR / `use cache`      `s-maxage=<revalidate>, stale-while-revalidate=<expire-revalidate>`
+ *   route handler                nothing, unless it sets `revalidate`
+ *
+ * Without one of these an intermediary is free to apply heuristic freshness to
+ * a personalised document. A non-200 is never a cacheable prerender in Next
+ * (its prerendered 404 still answers with the per-request value), so status
+ * gates the static case rather than the route's build-time disposition alone —
+ * which is also why no 404/500 render spells its own `no-store` any more: the
+ * prod value below already carries it, in Next's words.
+ */
+const DYNAMIC_DOCUMENT_CACHE_CONTROL = 'private, no-cache, no-store, max-age=0, must-revalidate'
+const DEV_DOCUMENT_CACHE_CONTROL = 'no-cache, must-revalidate'
+const DOCUMENT_EXPIRE_SECONDS = 31536000
+
+function applyDocumentCacheControl(ctx: ResponseFinalizerContext, dev: boolean): void {
+  if (ctx.routeKind !== 'html') return
+  if (ctx.headers.has('cache-control')) return
+  if (!(ctx.headers.get('content-type') ?? '').startsWith('text/html')) return
+  if (dev) {
+    ctx.headers.set('cache-control', DEV_DOCUMENT_CACHE_CONTROL)
+    return
+  }
+  if (ctx.status !== 200) {
+    ctx.headers.set('cache-control', DYNAMIC_DOCUMENT_CACHE_CONTROL)
+    return
+  }
+  // Compat sets the SWR value itself (its expireTime is configurable and it also
+  // covers pages-router getStaticProps); this only catches a core ISR document,
+  // which would otherwise be told never to cache a page that is cacheable for N.
+  const revalidate = ctx.routeMode === 'isr' ? ctx.hints?.revalidateSeconds : undefined
+  if (typeof revalidate === 'number' && revalidate > 0) {
+    const swr = Math.max(0, DOCUMENT_EXPIRE_SECONDS - revalidate)
+    ctx.headers.set('cache-control', `s-maxage=${revalidate}, stale-while-revalidate=${swr}`)
+    return
+  }
+  ctx.headers.set(
+    'cache-control',
+    ctx.routeMode === 'static'
+      ? `s-maxage=${DOCUMENT_EXPIRE_SECONDS}`
+      : DYNAMIC_DOCUMENT_CACHE_CONTROL,
+  )
+}
+
 export function setRequestExtensions(
   overrides: Partial<Omit<RequestExtensions, 'interceptors' | 'responseFinalizers'>>,
 ): void {

package/src/render/hooks.ts

@@ -22,7 +22,7 @@ import { restoreWithExtensionHost } from '../extensions'
 // ---------------------------------------------------------------------------
 
 /** Next compat is on (server actions, next/* modules, authInterrupts). */
-export function nextCompatEnabled(config: ResolvedConfig): boolean {
+export function nextCompatEnabled(config: Pick<ResolvedConfig, 'compat'>): boolean {
   return Boolean(config.compat?.next)
 }