@wular/pnext 0.0.1

package/src/compat/lifecycle/after.ts

@@ -0,0 +1,173 @@
+// after() - next/server (COMPAT).
+//
+// Registers work to run AFTER the response is fully sent. It builds on the core request work-unit:
+// queueAfterTask enqueues onto the per-request after-queue that core flushes exactly once when the
+// response closes - on every path (stream end, redirect(), notFound(), thrown error, client abort).
+// Nested after() works because the flush runs the queue inside the work unit and re-drains newly
+// enqueued tasks.
+//
+// When the surrounding platform provides the Vercel request-context waitUntil, each after task is also
+// handed to it so a serverless platform keeps the invocation alive until it settles. When no work unit
+// is active, the task runs on the microtask queue as a best-effort fallback.
+
+import { captureCacheScope } from '../../cache/context';
+import {
+  captureRequestScope,
+  currentRequest,
+  getWorkUnit,
+  queueAfterTask,
+  setPhase,
+} from '../../request/context';
+import { currentRenderCacheMeta } from '../cache/revalidate';
+import {
+  afterRequestApisAllowed,
+  recordRequestPath,
+  runWithAfterRequestApiScope,
+} from './after-scope';
+
+type AfterTask<T> = Promise<T> | (() => T | Promise<T>);
+
+const requestContextSymbol = Symbol.for('@next/request-context');
+
+/**
+ * Marks an error that escaped an after() task during a BUILD prerender. The build's per-route
+ * skip-and-warn catch reads it to fail the build instead of silently degrading the route to dynamic -
+ * Next fails the build when after() throws while prerendering.
+ */
+export const AFTER_PRERENDER_ERROR = Symbol.for('pnext.afterPrerenderError');
+
+interface VercelRequestContext {
+  get?: () => { waitUntil?: (promise: Promise<unknown>) => void } | undefined;
+}
+
+/** The platform waitUntil, when a Vercel-style request context is present. */
+function platformWaitUntil(): ((promise: Promise<unknown>) => void) | undefined {
+  const holder = (globalThis as Record<symbol, unknown>)[requestContextSymbol] as
+    | VercelRequestContext
+    | undefined;
+  return holder?.get?.()?.waitUntil;
+}
+
+/**
+ * Run a single after task, forwarding its settled promise to the platform
+ * waitUntil when available. Errors are logged with Next's exact `after()` prefix
+ * (phase-changes/cookies asserts the "An error occurred in a function passed to
+ * `after()`:" text) and never rethrown, so one failing task cannot break others.
+ */
+async function runAfterTask<T>(task: AfterTask<T>): Promise<void> {
+  const promise = Promise.resolve()
+    .then(() => (typeof task === 'function' ? task() : task))
+    .then(
+      () => undefined,
+      error => {
+        console.error(
+          `An error occurred in a function passed to \`after()\`: ${
+            error instanceof Error ? (error.stack ?? `${error.name}: ${error.message}`) : String(error)
+          }`,
+        );
+      },
+    );
+  platformWaitUntil()?.(promise);
+  await promise;
+}
+
+/**
+ * Like runAfterTask but for build prerenders: the task's rejection propagates
+ * so a throwing after() fails the page's prerender (next-after-app-static),
+ * rather than being logged and swallowed. The settled promise is still forwarded
+ * to the platform waitUntil (with errors swallowed there to avoid an unhandled
+ * rejection) so a serverless platform keeps the invocation alive until it ends.
+ */
+async function settleAfterTask<T>(task: AfterTask<T>): Promise<void> {
+  const promise = Promise.resolve().then(() =>
+    typeof task === 'function' ? task() : task,
+  );
+  platformWaitUntil()?.(promise.then(() => undefined, () => undefined));
+  try {
+    await promise;
+  } catch (error) {
+    // Tag so the build's per-route catch fails the build rather than degrading
+    // the route to dynamic. The tag rides the same error object up through the
+    // static after-drain (which re-throws it) to cli/build.ts.
+    if (error && typeof error === 'object') {
+      (error as Record<symbol, unknown>)[AFTER_PRERENDER_ERROR] = true;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Run a prerender after() task in the 'after' phase, naming its route. The
+ * runtime flush sets the work unit to phase 'after' before draining; a build
+ * prerender drains through the render cache meta instead, so the phase + route
+ * are set here so request-API guards fire with Next's exact message (both
+ * no-op when there is no work unit, e.g. a route-handler prerender).
+ */
+function runInPrerenderAfterPhase<T>(
+  route: string | undefined,
+  requestApisAllowed: boolean,
+  fn: () => T,
+): T {
+  setPhase('after');
+  if (route) recordRequestPath(route);
+  return runWithAfterRequestApiScope(requestApisAllowed, fn);
+}
+
+/**
+ * next/server after(): schedule a callback or promise to run once the response
+ * has been fully sent. Legal in dynamic pages, route handlers, server actions,
+ * middleware, and generateMetadata().
+ */
+export function after<T>(task: AfterTask<T>): void {
+  // Capture the request scope at call time so a callback registered during a route handler or server
+  // action still resolves request APIs when it runs later in the flush. A page render does NOT capture:
+  // its after() callbacks run detached, so headers()/cookies()/connection() throw Next's "used inside
+  // after()" error. The phase distinguishes them - renders stay 'render', handlers set routeKind,
+  // actions set phase 'action'.
+  const unit = getWorkUnit();
+  const isHandlerOrAction =
+    unit?.phase === 'action' ||
+    unit?.phase === 'middleware' ||
+    unit?.routeKind === 'route-handler';
+  const isNestedRequestAfter =
+    unit?.phase === 'after' && Boolean(currentRequest()) && afterRequestApisAllowed();
+  // Handlers and actions capture the live request scope so headers()/cookies() keep working inside their
+  // after() callbacks. A page render (or generateMetadata) instead captures only the React cache()
+  // scope, so cache() shares the render's memo cache in the callback while the request scope stays
+  // detached and headers()/cookies()/connection() still throw Next's "used inside after()" error.
+  const withScope =
+    isHandlerOrAction || isNestedRequestAfter
+      ? captureRequestScope()
+      : captureCacheScope();
+  // Static-generation render (build prerender or ISR regeneration): there is
+  // no response close to flush against, so the task queues on the render's
+  // cache meta and the render drains it once produce settles (Next waits for
+  // after() during prerendering). Build prerenders propagate rejections so a
+  // throwing after() fails the page's prerender (next-after-app-static);
+  // runtime regenerations log-and-continue like every other runtime path.
+  const meta = currentRenderCacheMeta();
+  if (meta && (meta.prerender === true || meta.blockingStaleFetches === true)) {
+    // A build/ISR prerender runs with no work unit, so the top-level routeKind check above cannot tell a
+    // route-handler prerender from a page one - meta.handler does. A handler prerender captures the live
+    // request scope so request APIs resolve inside after(); a page prerender keeps only the cache scope
+    // so they throw "used inside after()".
+    const prerenderScope = meta.handler ? captureRequestScope() : withScope;
+    const route = meta.route;
+    const requestApisAllowed = Boolean(meta.handler);
+    const run = meta.prerender
+      ? () =>
+          prerenderScope(() =>
+            runInPrerenderAfterPhase(route, requestApisAllowed, () => settleAfterTask(task)),
+          )
+      : () => prerenderScope(() => runWithAfterRequestApiScope(requestApisAllowed, () => runAfterTask(task)));
+    (meta.afterTasks ??= []).push(run);
+    return;
+  }
+  const requestApisAllowed = Boolean(isHandlerOrAction || isNestedRequestAfter);
+  const queued = queueAfterTask(() =>
+    withScope(() => runWithAfterRequestApiScope(requestApisAllowed, () => runAfterTask(task))),
+  );
+  if (queued) return;
+  // No active work unit (e.g. called at module scope): best-effort microtask.
+  void withScope(() => runWithAfterRequestApiScope(requestApisAllowed, () => runAfterTask(task)));
+}

package/src/compat/lifecycle/error-funnel.ts

@@ -0,0 +1,306 @@
+// onRequestError funnel (COMPAT).
+//
+// Implements RequestExtensions.onRequestError: core calls it once per failed request with the error,
+// request info and work-unit context. Compat classifies control-flow errors
+// (notFound/redirect/forbidden/unauthorized/dynamic bailouts) and skips them, then forwards real errors
+// to the user's instrumentation onRequestError(error, { path, method, headers }, context).
+//
+// Dedupe: the same request may surface an error at both the render site and the top-level catch, so a
+// per-work-unit flag ensures the user hook fires exactly once.
+
+import { getWorkUnit } from '../../request/context';
+import { getRequestRuntime } from '../../routing/request-runtime';
+import { selectRouteForRequest } from '../../routing/routes';
+import path from 'node:path';
+import type { RouteManifestEntry } from '../../types';
+import type { RequestErrorContext, RequestErrorInfo } from '../../extensions';
+import {
+  isForbiddenError,
+  isNotFoundError,
+  isRedirectError,
+  isUnauthorizedError,
+} from '../../api/navigation';
+import { isPostpone } from '../../ppr';
+import { markErrorLogged } from '../../utils/error-log';
+import { getUserOnRequestError, instrumentationReady } from './instrumentation';
+
+const ERROR_REPORTED_KEY = Symbol.for('pnext.errorReported');
+
+/** True for Next control-flow errors that must NOT be reported to the hook. */
+function isControlFlowError(error: unknown): boolean {
+  return (
+    isRedirectError(error) ||
+    isNotFoundError(error) ||
+    isForbiddenError(error) ||
+    isUnauthorizedError(error) ||
+    isPostpone(error) ||
+    isNextDynamicNoSsr(error)
+  );
+}
+
+/** next/dynamic ssr:false bailout digest (skip-next-internal-error asserts skip). */
+function isNextDynamicNoSsr(error: unknown): boolean {
+  const digest = (error as { digest?: unknown } | null | undefined)?.digest;
+  return (
+    digest === 'NEXT_DYNAMIC_NO_SSR_CODE' ||
+    (typeof digest === 'string' && digest.startsWith('DYNAMIC_SERVER_USAGE'))
+  );
+}
+
+/**
+ * Convert a pnext route pattern (`/app-page/dynamic/:id`, `:slug*` catch-alls)
+ * into Next's display form (`/app-page/dynamic/[id]`, `[...slug]`), which the
+ * onRequestError `routePath` field reports. Mirrors pnext-cli's toNextRoute.
+ */
+function toDisplayRoute(route: RouteManifestEntry): string {
+  let value = route.route || '/';
+  if (route.catchAll) {
+    const pattern = route.catchAllOptional
+      ? `[[...${route.catchAll}]]`
+      : `[...${route.catchAll}]`;
+    value = value.replace(`:${route.catchAll}*`, pattern);
+  }
+  for (const param of route.params) value = value.replace(`:${param}`, `[${param}]`);
+  return value;
+}
+
+/** Return `Pages Router` when route files live under pages/, otherwise `App Router`. */
+function routeKindFromFile(
+  runtimeRoot: string | undefined,
+  route: RouteManifestEntry,
+): 'Pages Router' | 'App Router' {
+  if (!runtimeRoot) {
+    return 'App Router';
+  }
+  const normalized = path.normalize(route.file);
+  const pagesRoot = path.join(runtimeRoot, 'pages');
+  const appRoot = path.join(runtimeRoot, 'app');
+  return normalized.startsWith(pagesRoot + path.sep) || normalized === pagesRoot
+    ? 'Pages Router'
+    : normalized.startsWith(appRoot + path.sep) || normalized === appRoot
+      ? 'App Router'
+      : 'App Router';
+}
+
+interface RouteMatch {
+  route: RouteManifestEntry;
+  routePath: string;
+}
+
+function resolveRoute(pathname: string): RouteMatch | undefined {
+  const runtime = getRequestRuntime();
+  if (!runtime) return undefined;
+  const selectedPath = pathname.split('?')[0] ?? pathname;
+  const matched = selectRouteForRequest(runtime.routes, selectedPath, undefined);
+  if (!matched) return undefined;
+  return { route: matched.route, routePath: toDisplayRoute(matched.route) };
+}
+
+/**
+ * Resolve the matched route's display pattern for the failing request from the
+ * live routing runtime (the same seam otel uses for `next.route`). Returns
+ * undefined outside a request scope or when no route matches (e.g. a 404).
+ */
+function resolveRoutePath(path: string): string | undefined {
+  try {
+    return resolveRoute(path)?.routePath;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Map the work-unit facts onto Next's onRequestError context. pnext is
+ * app-router only, so routerKind is always 'App Router'. routeType is 'route'
+ * for route handlers and 'render' for page renders. routePath is the matched
+ * route's display pattern. renderSource is reported for page renders (route
+ * handlers leave it undefined). A dedicated revalidateReason is threaded in when
+ * core reports an ISR revalidation error.
+ */
+function errorDigest(error: unknown): string | undefined {
+  const digest = (error as { digest?: unknown } | null | undefined)?.digest;
+  return typeof digest === 'string' ? digest : undefined;
+}
+
+function buildContext(
+  error: unknown,
+  context: RequestErrorContext,
+  path: string,
+): Record<string, unknown> {
+  const runtime = getRequestRuntime();
+  const match = runtime ? resolveRoute(path) : undefined;
+  const out: Record<string, unknown> = {};
+  out.routerKind = match
+    ? routeKindFromFile(runtime?.config.root, match.route)
+    : 'App Router';
+  out.routeType = context.routeKind === 'route-handler' ? 'route' : 'render';
+  const routePath = match ? match.routePath : resolveRoutePath(path);
+  if (routePath) out.routePath = routePath;
+  if (context.routeKind === 'html') {
+    out.renderSource =
+      (context as { renderSource?: string }).renderSource ?? 'react-server-components';
+  }
+  const revalidateReason = (context as { revalidateReason?: string }).revalidateReason;
+  if (revalidateReason) out.revalidateReason = revalidateReason;
+  const digest = errorDigest(error);
+  if (digest) out.digest = digest;
+  return out;
+}
+
+/**
+ * Next's onRequestError context for a thrown server action. Shared by the action endpoint path and the
+ * render-funnel path: an inline `<form action>` action throws DURING the page re-render, so core's
+ * render funnel reports it first and wins the per-work-unit dedupe - it must carry the same action
+ * context the endpoint would (routeType 'action', RSC-payload source) or the suite sees a render context.
+ */
+function buildActionContext(error: unknown, path: string): Record<string, unknown> {
+  const runtime = getRequestRuntime();
+  const match = runtime ? resolveRoute(path) : undefined;
+  const out: Record<string, unknown> = {
+    routerKind: match ? routeKindFromFile(runtime?.config.root, match.route) : 'App Router',
+    routeType: 'action',
+    renderSource: 'react-server-components-payload',
+  };
+  const routePath = match ? match.routePath : resolveRoutePath(path);
+  if (routePath) out.routePath = routePath;
+  const digest = errorDigest(error);
+  if (digest) out.digest = digest;
+  return out;
+}
+
+/** True when the failing request is a server-action invocation (JS/form dispatch). */
+function isServerActionRequest(headers: Headers): boolean {
+  if (headers.has('next-action')) return true;
+  const accept = headers.get('accept') ?? '';
+  return accept.includes('text/x-component');
+}
+
+/**
+ * Report a thrown server-action error to the user's onRequestError hook. The
+ * action endpoint swallows the throw into a masked 500 response, so core's funnel
+ * never sees it; this is the action-path equivalent. Context mirrors Next's
+ * action error shape (`routeType: 'action'`, RSC-payload render source) the
+ * on-request-error/server-action-error suite asserts. Skips control-flow errors
+ * (redirect()/notFound()) and never throws.
+ */
+export async function reportActionErrorToUser(error: unknown, request: Request): Promise<void> {
+  if (isControlFlowError(error)) return;
+
+  const unit = getWorkUnit();
+  if (unit) {
+    const bag = (unit.compat ??= {});
+    if (bag[ERROR_REPORTED_KEY]) return;
+    bag[ERROR_REPORTED_KEY] = true;
+  }
+
+  await instrumentationReady();
+  const hook = getUserOnRequestError();
+  if (!hook) return;
+
+  let path = request.url;
+  try {
+    const parsed = new URL(request.url);
+    path = parsed.pathname + parsed.search;
+  } catch {
+    // request.url is already a path.
+  }
+
+  try {
+    await hook(
+      error,
+      { path, method: request.method, headers: headersToObject(request.headers) },
+      buildActionContext(error, path),
+    );
+  } catch (hookError) {
+    console.error('instrumentation onRequestError failed:', hookError);
+  }
+}
+
+function headersToObject(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+
+/**
+ * RequestExtensions.onRequestError implementation. Skips control-flow errors,
+ * dedupes per work unit, and forwards to the user hook. Never throws.
+ */
+export async function reportRequestErrorToUser(
+  error: unknown,
+  requestInfo: RequestErrorInfo,
+  context: RequestErrorContext,
+): Promise<void> {
+  if (isControlFlowError(error)) return;
+
+  const unit = getWorkUnit();
+  if (unit) {
+    const bag = (unit.compat ??= {});
+    if (bag[ERROR_REPORTED_KEY]) return;
+    bag[ERROR_REPORTED_KEY] = true;
+  }
+
+  await instrumentationReady();
+  const hook = getUserOnRequestError();
+  if (!hook) return;
+
+  // `path` is the original URL incl. search (dynamic-routes asserts search present).
+  let path = requestInfo.url;
+  try {
+    const parsed = new URL(requestInfo.url);
+    path = parsed.pathname + parsed.search;
+  } catch {
+    // requestInfo.url is already a path.
+  }
+
+  // An inline `<form action>` action throws inside the page re-render, so this
+  // render funnel reports before the action endpoint and wins the dedupe — emit
+  // the action context so it matches what the endpoint would have reported.
+  const hookContext = isServerActionRequest(requestInfo.headers)
+    ? buildActionContext(error, path)
+    : buildContext(error, context, path);
+
+  try {
+    await hook(
+      error,
+      { path, method: requestInfo.method, headers: headersToObject(requestInfo.headers) },
+      hookContext,
+    );
+  } catch (hookError) {
+    console.error('instrumentation onRequestError failed:', hookError);
+  }
+}
+
+let guardInstalled = false;
+
+/**
+ * Server-lifecycle safety net for SSR errors that escape as unhandled promise rejections instead of
+ * surfacing through a render catch.
+ *
+ * A `'use client'` component that throws during server rendering is stringified by
+ * preact-render-to-string's async pass, which RESOLVES the render to an empty string while floating the
+ * component's own rejected promise. That rejection is never awaited by the render pipeline, so without
+ * this guard it reaches the process as an unhandledRejection and takes down every in-flight and
+ * subsequent request.
+ *
+ * Installed once, compat-only:
+ *   - Control-flow signals are navigation intents, not failures. They are absorbed silently, never
+ *     logged, matching Next's skip-next-internal-error contract - the raw digests would otherwise print
+ *     the internal strings those tests assert are absent.
+ *   - A real error is logged once, deduped against the render/handler catch's own log, so it is never
+ *     silently lost. The listener's mere presence stops the default process crash.
+ *
+ * The correct request-scoped report for such an error requires the renderer to catch the async client
+ * throw at the SSR site and route it through reportRequestError; this net only guarantees survival.
+ */
+export function installUnhandledRejectionGuard(): void {
+  if (guardInstalled) return;
+  if (typeof process === 'undefined' || typeof process.on !== 'function') return;
+  guardInstalled = true;
+  process.on('unhandledRejection', (reason: unknown) => {
+    if (isControlFlowError(reason)) return;
+    if (markErrorLogged(reason)) console.error(reason);
+  });
+}

package/src/compat/lifecycle/error-serialize.ts

@@ -0,0 +1,87 @@
+// Error serialization for boundaries (COMPAT).
+//
+// Implements RenderExtensions.serializeError: Next's digest protocol plus prod message redaction for
+// the `{ name, message, digest }` object handed to an error.js / global-error.js boundary.
+//
+//   - A user-supplied `.digest` string passes through unchanged.
+//   - A real server error without a digest gets a stable hash digest.
+//   - In production the message is redacted to React's minified #441 text; in dev the original message
+//     survives (non-Error throws arrive as 'undefined' / 'null' upstream).
+//
+// NOTE: this function must NOT log the error to the server console. Core's renderer already logs the
+// render error exactly once right before it calls serializeError(); logging here too double-prints it.
+
+import type { SerializeErrorContext, SerializedError } from '../../extensions';
+import { isTaggedPrimitiveThrow, tagPrimitiveThrow, untagPrimitiveThrow } from '../client/errors/primitive-throw';
+
+// React's production redaction text for RSC render errors (#441). Boundary
+// suites assert this verbatim in prod.
+const REDACTED_MESSAGE =
+  'Minified React error #441; visit https://react.dev/errors/441 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.';
+
+// Next uses next/dist/compiled/string-hash; any stable non-negative hash whose
+// decimal string matches /\w+/ satisfies the compat assertions.
+function stableDigest(input: string): string {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash * 33) ^ input.charCodeAt(i);
+  }
+  return (hash >>> 0).toString();
+}
+
+function customDigest(error: Error): string | undefined {
+  const digest = (error as { digest?: unknown }).digest;
+  return typeof digest === 'string' && digest.length > 0 ? digest : undefined;
+}
+
+// Next appends an error-code suffix to the hash digest when the thrown value
+// was not an Error: prod RSC wraps a nullish throw and reports `@E394`
+// (test/e2e/app-dir/errors asserts `digest: '<hash>@E394'` in the prod log).
+function digestSuffix(error: Error): string {
+  if (!isTaggedPrimitiveThrow(error)) return '';
+  const raw = untagPrimitiveThrow(error);
+  return raw === null || raw === undefined ? '@E394' : '';
+}
+
+/**
+ * RenderExtensions.wrapThrownValue: wrap a non-Error server throw the way Next's RSC transport does -
+ * `Error: <String(value)>` with the synthetic `at stringify (<anonymous>)` stack frame the prod log
+ * snapshot asserts, and the raw value tagged so the digest picks up the nullish suffix.
+ */
+export function wrapThrownValue(value: unknown): Error {
+  const error = tagPrimitiveThrow(value);
+  error.stack = `Error: ${error.message}\n    at stringify (<anonymous>)`;
+  return error;
+}
+
+/**
+ * RenderExtensions.formatErrorLog: Next's prod server-log shape for a render error - the error's
+ * inspected form with the digest as an own property, asserted byte-exact by the errors suite's inline
+ * snapshots.
+ */
+export function formatErrorLog(trace: string, digest: string, error?: Error): string {
+  // An error funneled out of a 'use cache' scope carries Next's environment tag;
+  // util.inspect prints it before the digest, so the log must too.
+  const environmentName = (error as { environmentName?: unknown } | undefined)?.environmentName;
+  const environment =
+    typeof environmentName === 'string' ? `  environmentName: '${environmentName}',\n` : '';
+  return `⨯ ${trace} {\n${environment}  digest: '${digest}'\n}`;
+}
+
+export function serializeBoundaryError(ctx: SerializeErrorContext): SerializedError {
+  const { error, dev } = ctx;
+  const custom = customDigest(error);
+  const digest =
+    custom ?? stableDigest(`${error.message}${error.stack ?? ''}`) + digestSuffix(error);
+
+  // Boundary components render `${error}` (e.g. `Global error: ${error}`), so
+  // the prop must stringify as `Error: <message>` like React's transported
+  // error. Return a real Error carrying the (possibly redacted) message + digest.
+  const boundaryError = new Error(dev ? error.message : REDACTED_MESSAGE) as Error & {
+    digest?: string;
+  };
+  boundaryError.name = error.name || 'Error';
+  boundaryError.digest = digest;
+  boundaryError.stack = undefined;
+  return boundaryError;
+}