@wular/pnext 0.0.1

package/src/routing/handler.ts

@@ -0,0 +1,271 @@
+import { isNotFoundError, isRedirectError } from '../api/navigation';
+import { getWorkUnit, runWithRequest } from '../request/context';
+import { nextResponseMeta, toNextRequest } from '../api/server';
+import { reportRequestError } from '../extensions';
+import type { NextRequest, RouteManifestEntry, RouteParamValue } from '../types';
+
+const routeMethods = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'] as const;
+
+type RouteMethod = (typeof routeMethods)[number];
+
+// Methods that are valid HTTP verbs but may be unimplemented on a route (405),
+// vs. tokens that are not HTTP methods at all (400). Next answers 400 for the
+// latter (e.g. a `HEADER` request) and 405 for a real-but-missing verb.
+const httpMethods = new Set([
+  'GET',
+  'HEAD',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'OPTIONS',
+  'CONNECT',
+  'TRACE',
+]);
+
+interface RouteHandlerContext {
+  params?: Promise<Record<string, RouteParamValue>>;
+}
+
+interface HandleRouteOptions {
+  /** Absolute route file path, used in the "no response returned" CLI error. */
+  routeFile?: string;
+}
+
+export interface RouteHandlerModule {
+  params?: () => Record<string, RouteParamValue>[] | Promise<Record<string, RouteParamValue>[]>;
+  GET?: RouteHandler;
+  HEAD?: RouteHandler;
+  POST?: RouteHandler;
+  PUT?: RouteHandler;
+  PATCH?: RouteHandler;
+  DELETE?: RouteHandler;
+  OPTIONS?: RouteHandler;
+}
+
+type RouteHandler = (
+  request: NextRequest,
+  context: RouteHandlerContext,
+) => Response | undefined | void | Promise<Response | undefined | void>;
+
+export async function handleRouteModule(
+  module: RouteHandlerModule,
+  request: Request,
+  params: Record<string, RouteParamValue>,
+  options: HandleRouteOptions = {},
+) {
+  // Response-headers channel for the handler's request scope: APIs like
+  // draftMode().enable() append set-cookie here while the handler runs, and
+  // the headers are merged onto whatever response goes out — including the
+  // synthesized redirect response when the handler throws redirect().
+  const responseHeaders = new Headers();
+  const method = request.method.toUpperCase();
+  try {
+    // A request method that is not a valid HTTP verb is a bad request, not an
+    // unimplemented one (Next returns 400 with an empty body).
+    if (!httpMethods.has(method)) return new Response(null, { status: 400 });
+
+    const handler = routeMethods.includes(method as RouteMethod)
+      ? module[method as RouteMethod]
+      : undefined;
+
+    if (!handler) {
+      if (method === 'HEAD' && module.GET) {
+        // Auto-HEAD from GET: run GET, validate it, then drop the body.
+        const response = finalizeResponse(
+          await callHandler(module.GET, request, params, responseHeaders),
+          request,
+          responseHeaders,
+          options,
+        );
+        return new Response(null, { status: response.status, headers: response.headers });
+      }
+      return missingMethodResponse(module, method);
+    }
+
+    return finalizeResponse(
+      await callHandler(handler, request, params, responseHeaders),
+      request,
+      responseHeaders,
+      options,
+    );
+  } catch (error) {
+    if (isRedirectError(error)) {
+      // POST submissions get a 303 (Next's behavior for redirect() and
+      // permanentRedirect() thrown in route handlers): the browser follows
+      // with a GET instead of replaying the POST against the target.
+      const status = method === 'POST' ? 303 : error.status;
+      return withResponseHeaders(
+        new Response(null, { status, headers: { location: error.location } }),
+        responseHeaders,
+      );
+    }
+    // notFound() thrown inside a handler is a 404 with an empty body.
+    if (isNotFoundError(error)) {
+      return withResponseHeaders(new Response(null, { status: 404 }), responseHeaders);
+    }
+    // Any other throw is a 500 with an empty body. Report it through the error
+    // funnel (onRequestError) here since core no longer sees it as uncaught.
+    await reportRequestError(
+      error,
+      { method, url: request.url, headers: request.headers },
+      { phase: 'handler', routeKind: 'route-handler', ...(getWorkUnit()?.responseHints ?? {}) },
+    );
+    console.error(error);
+    return new Response(null, { status: 500 });
+  }
+}
+
+/**
+ * Validate the handler's return value and apply the scope's collected headers.
+ * A handler must return a Response; `undefined` or a `NextResponse.next()`
+ * result is a 500 (with Next's contract-violation CLI error) rather than a
+ * passthrough.
+ */
+function finalizeResponse(
+  response: Response | undefined | void,
+  request: Request,
+  responseHeaders: Headers,
+  options: HandleRouteOptions,
+) {
+  const method = request.method.toUpperCase();
+  if (!response) {
+    const file = options.routeFile ?? '<route>';
+    console.error(
+      `No response is returned from route handler '${file}'. Expected a Response object but ` +
+        `received '${typeof response}' (method: ${method}, url: ${request.url}). Ensure you ` +
+        'return a `Response` or a `NextResponse` in all branches of your handler.',
+    );
+    return new Response(null, { status: 500 });
+  }
+  if (nextResponseMeta(response)?.kind === 'next') {
+    console.error('https://nextjs.org/docs/messages/next-response-next-in-app-route-handler');
+    return new Response(null, { status: 500 });
+  }
+  return withResponseHeaders(response, responseHeaders);
+}
+
+function callHandler(
+  handler: RouteHandler,
+  request: Request,
+  params: Record<string, RouteParamValue>,
+  responseHeaders: Headers,
+) {
+  const nextRequest = toNextRequest(request);
+  // Static routes (no dynamic segments) get no `params` in context — Next
+  // omits it, so `context.params` is `undefined` rather than a promise of `{}`.
+  const context: RouteHandlerContext =
+    Object.keys(params).length > 0 ? { params: Promise.resolve(params) } : {};
+  return runWithRequest(nextRequest, () => handler(nextRequest, context), params, {
+    responseHeaders,
+  });
+}
+
+/** Merge scope-collected headers (set-cookie appends, everything else sets) onto the response. */
+function withResponseHeaders(response: Response, extra: Headers) {
+  const withSetCookie = extra as Headers & { getSetCookie?: () => string[] };
+  const scopeCookies = withSetCookie.getSetCookie?.() ?? [];
+  let hasOthers = false;
+  extra.forEach((_, key) => {
+    if (key !== 'set-cookie') hasOthers = true;
+  });
+  if (scopeCookies.length === 0 && !hasOthers) return response;
+
+  const apply = (headers: Headers) => {
+    extra.forEach((value, key) => {
+      if (key !== 'set-cookie') headers.set(key, value);
+    });
+    // Cookie-jar merge (Next's ResponseCookies semantics): scope cookies
+    // (cookies().set during the handler) first, the response's own Set-Cookie
+    // headers override same-name entries, and every cookie is normalized with
+    // a default Path=/.
+    const responseCookies =
+      (headers as Headers & { getSetCookie?: () => string[] }).getSetCookie?.() ?? [];
+    const jar = new Map<string, string>();
+    for (const cookie of [...scopeCookies, ...responseCookies]) {
+      jar.set(cookieName(cookie), normalizeSetCookie(cookie));
+    }
+    headers.delete('set-cookie');
+    for (const cookie of jar.values()) headers.append('set-cookie', cookie);
+  };
+  try {
+    apply(response.headers);
+    return response;
+  } catch {
+    // Immutable headers (e.g. a Response forwarded from fetch): re-wrap.
+    const headers = new Headers(response.headers);
+    apply(headers);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+}
+
+function cookieName(setCookie: string) {
+  return (setCookie.split('=')[0] ?? '').trim();
+}
+
+function normalizeSetCookie(setCookie: string) {
+  return /;\s*path=/i.test(setCookie) ? setCookie : `${setCookie}; Path=/`;
+}
+
+export async function staticRouteParams(route: RouteManifestEntry, module: RouteHandlerModule) {
+  if (typeof module.GET !== 'function') return [];
+  // `dynamic = 'force-static'` and `dynamic = 'error'` both evaluate a static
+  // request; the latter lets request APIs fail at their call sites. A
+  // `revalidate` export opts a request-independent GET into static/ISR output.
+  const config = route.segmentConfig;
+  const optedStatic =
+    config?.dynamic === 'force-static' ||
+    config?.dynamic === 'error' ||
+    config?.revalidate === false ||
+    (typeof config?.revalidate === 'number' && config.revalidate > 0);
+  if (route.hasStaticParams) return module.params?.() ?? [];
+  if (route.usesRequest && !optedStatic) return [];
+  return route.mode === 'static' || optedStatic ? [{}] : [];
+}
+
+export function routeParamsFromPath(
+  route: Pick<RouteManifestEntry, 'catchAll' | 'params' | 'pattern'>,
+  pathname: string,
+) {
+  const match = new RegExp(`^${route.pattern}$`).exec(pathname);
+  const params: Record<string, RouteParamValue> = {};
+  if (!match) return params;
+
+  for (let index = 0; index < route.params.length; index += 1) {
+    params[route.params[index]!] = safeDecode(match[index + 1] ?? '');
+  }
+  if (route.catchAll) {
+    params[route.catchAll] = (match[route.params.length + 1] ?? '')
+      .split('/')
+      .filter(Boolean)
+      .map(safeDecode);
+  }
+  return params;
+}
+
+function missingMethodResponse(module: RouteHandlerModule, method: string) {
+  const headers = { Allow: allowedMethods(module).join(', ') };
+  if (method === 'OPTIONS') return new Response(null, { status: 204, headers });
+  return new Response(null, { status: 405, headers });
+}
+
+function allowedMethods(module: RouteHandlerModule) {
+  const allowed = new Set(routeMethods.filter(method => typeof module[method] === 'function'));
+  // GET implies auto-HEAD; every route gets auto-OPTIONS. The Allow header is
+  // sorted (Next emits e.g. `OPTIONS, POST`).
+  if (allowed.has('GET')) allowed.add('HEAD');
+  allowed.add('OPTIONS');
+  return [...allowed].sort();
+}
+
+function safeDecode(value: string) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/src/routing/href.ts

@@ -0,0 +1,203 @@
+import type { RouteParamValue } from '../types';
+
+export type SearchValue = string | number | boolean | null | undefined;
+export type SearchInput = URLSearchParams | Record<string, SearchValue | SearchValue[]>;
+
+export interface HrefParts {
+  params?: Record<string, RouteParamValue>;
+  search?: SearchInput;
+  hash?: string;
+}
+
+export function routeHref(route: string, options: HrefParts = {}) {
+  const path = applyTrailingSlash(fillParams(route, options.params ?? {}));
+  const search = searchString(options.search);
+  const hash = hashString(options.hash);
+  return `${path}${search}${hash}`;
+}
+
+declare global {
+  interface Window {
+    __PNEXT_TRAILING_SLASH__?: boolean;
+  }
+  var __PNEXT_TRAILING_SLASH__: boolean | undefined;
+}
+
+// With `trailingSlash: true` the server 308s bare page URLs to their slashed
+// form; Links render the canonical (slashed) href directly, like Next. Set
+// once per process by the server runtime from the resolved config. On the
+// client the value is read from the injected window global (register-render's
+// trailingSlashScript), mirroring basePath / skipTrailingSlash.
+let trailingSlashUrls = false;
+
+export function setTrailingSlashUrls(enabled: boolean) {
+  trailingSlashUrls = enabled;
+}
+
+function isTrailingSlashEnabled(): boolean {
+  if (trailingSlashUrls) return true;
+  if (process.browser || typeof window !== 'undefined') return window.__PNEXT_TRAILING_SLASH__ === true;
+  return globalThis.__PNEXT_TRAILING_SLASH__ === true;
+}
+
+export function getTrailingSlashUrls() {
+  return isTrailingSlashEnabled();
+}
+
+// The configured basePath ('' when unset). Set once per process by the server
+// runtime from the resolved config (registerServerRuntime), mirroring the
+// trailing-slash seam. Core render code (metadata) reads it through
+// withBasePath so file-convention asset hrefs (og-image, manifest) carry the
+// prefix without a compat/next.config import in core.
+let basePathPrefix = '';
+
+export function setBasePathPrefix(value: string) {
+  basePathPrefix = value;
+}
+
+export function getBasePathPrefix() {
+  return basePathPrefix;
+}
+
+/**
+ * Prefix a root-relative in-app path with the configured basePath (Next's
+ * addBasePath). Absolute/protocol-relative URLs, non-root-relative strings, and
+ * paths already under the basePath are returned unchanged. A no-basePath app is
+ * always a no-op. Any query/hash on the path rides along untouched.
+ */
+export function withBasePath(path: string) {
+  const base = basePathPrefix;
+  if (!base) return path;
+  if (!path.startsWith('/') || path.startsWith('//')) return path;
+  if (path === base || path.startsWith(`${base}/`)) return path;
+  return `${base}${path}`;
+}
+
+export function applyTrailingSlash(pathname: string) {
+  const [, path = '', rest = ''] = /^([^?#]*)([\s\S]*)$/.exec(pathname) ?? [];
+  if (!path.startsWith('/')) return pathname;
+  if (trailingSlashUrls) {
+    // Add the canonical trailing slash (skip root, already-slashed, and files).
+    if (path === '/' || path.endsWith('/') || /\.[^/]+$/.test(path)) return pathname;
+    return `${path}/${rest}`;
+  }
+  // trailingSlash:false — Next strips a trailing slash from hrefs so the anchor
+  // matches the canonical (unslashed) form and avoids a 308 on click. Root and
+  // file paths (`/a.txt/` is not a thing) are left alone.
+  if (path === '/' || !path.endsWith('/') || /\.[^/]+\/$/.test(path)) return pathname;
+  return `${path.replace(/\/+$/, '')}${rest}`;
+}
+
+function fillParams(route: string, params: Record<string, RouteParamValue>) {
+  const filled = route
+    // Optional catch-all `[[...slug]]` must be matched before the plain
+    // catch-all form so its doubled brackets aren't mis-parsed.
+    .replace(/\[\[\.\.\.([^\]]+)\]\]/g, (_match, key: string) => encodeParam(params[key], true))
+    .replace(/\[\.\.\.([^\]]+)\]/g, (_match, key: string) => encodeParam(params[key], true))
+    .replace(/\[([^\]]+)\]/g, (_match, key: string) => encodeParam(params[key], false));
+  // An absent optional catch-all (`[[...slug]]`) leaves a dangling `/`; drop it
+  // so /docs/:slug* with no params yields /docs, not /docs/.
+  return collapseTrailingSlash(filled);
+}
+
+function collapseTrailingSlash(pathname: string) {
+  if (pathname.length <= 1) return pathname;
+  return pathname.replace(/\/+$/, '') || '/';
+}
+
+function encodeParam(value: RouteParamValue | undefined, catchAll: boolean) {
+  if (Array.isArray(value)) {
+    const encoded = value.map(segment => encodeURIComponent(segment));
+    return catchAll ? encoded.join('/') : encoded[0] ?? '';
+  }
+  return encodeURIComponent(value ?? '');
+}
+
+function searchString(search: SearchInput | undefined) {
+  if (!search) return '';
+  const params = search instanceof URLSearchParams ? search : objectSearchParams(search);
+  const value = params.toString();
+  return value ? `?${value}` : '';
+}
+
+function objectSearchParams(search: Record<string, SearchValue | SearchValue[]>) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(search)) {
+    const values = Array.isArray(value) ? value : [value];
+    for (const item of values) {
+      if (item == null) continue;
+      params.append(key, String(item));
+    }
+  }
+  return params;
+}
+
+function hashString(hash: string | undefined) {
+  if (!hash) return '';
+  return hash.startsWith('#') ? hash : `#${hash}`;
+}
+
+/**
+ * Malformed percent-encoding in the request path (e.g. `/%2`, a lone `%` or an
+ * out-of-range escape) is a 400 "Bad Request" before any routing, matching
+ * Next. Returns the response when the path cannot be decoded, else null.
+ */
+export function malformedUrlResponse(request: Request): Response | null {
+  let pathname: string;
+  try {
+    pathname = new URL(request.url).pathname;
+  } catch {
+    return new Response('Bad Request', { status: 400 });
+  }
+  if (!pathname.includes('%')) return null;
+  try {
+    decodeURIComponent(pathname);
+    return null;
+  } catch {
+    return new Response('Bad Request', { status: 400 });
+  }
+}
+
+/**
+ * The canonical form of `pathname` under the given `trailingSlash` setting:
+ * with it on, a bare page path gains a trailing slash; with it off, a slashed
+ * path loses it. Root (`/`) and file-ish paths (an extension in the last
+ * segment) are always left untouched. Returns the pathname unchanged when it is
+ * already canonical.
+ */
+export function canonicalTrailingSlashPath(pathname: string, trailingSlash: boolean): string {
+  if (pathname === '/' || pathname === '') return pathname;
+  if (/\.[^/]+$/.test(pathname)) return pathname;
+  const slashed = pathname.endsWith('/');
+  if (trailingSlash ? slashed : !slashed) return pathname;
+  return trailingSlash
+    ? `${pathname.replace(/\/+$/, '')}/`
+    : pathname.replace(/\/+$/, '') || '/';
+}
+
+/**
+ * Next-style trailing-slash normalization: with `trailingSlash: true` page
+ * URLs 308-redirect to their slashed form; with it off (the default) slashed
+ * URLs redirect to the bare form. File-ish paths (extensions) and internal
+ * paths are untouched. Returns null when the URL is already canonical.
+ */
+export function trailingSlashRedirect(
+  config: { trailingSlash?: boolean; skipTrailingSlashRedirect?: boolean },
+  url: URL,
+  method: string,
+): Response | null {
+  // skipTrailingSlashRedirect: the app serves both slashed and unslashed URLs
+  // as-is, so no canonical redirect is ever emitted (route matching already
+  // tolerates a trailing slash via normalizePathname).
+  if (config.skipTrailingSlashRedirect) return null;
+  if (method !== 'GET' && method !== 'HEAD') return null;
+  const pathname = url.pathname;
+  if (pathname === '/' || pathname === '') return null;
+  if (pathname.startsWith('/__pnext') || pathname.startsWith('/assets/')) return null;
+  const target = canonicalTrailingSlashPath(pathname, Boolean(config.trailingSlash));
+  if (target === pathname) return null;
+  return new Response(null, {
+    status: 308,
+    headers: { location: `${target}${url.search}` },
+  });
+}