@webjsdev/server 0.9.0 → 0.10.0

package/src/middleware-load.js

@@ -0,0 +1,248 @@
+/**
+ * Loading and wrapping middleware the way Next.js does.
+ *
+ *   - The root file is `middleware.{ts,js,mts,mjs}` or, Next 16's name,
+ *     `proxy.{ts,js,mts,mjs}`. Both at once is a boot error.
+ *   - The function is the default export, else a named `middleware`, else a
+ *     named `proxy` export (Next accepts all three).
+ *   - `export const config = { matcher }` scopes it: a string, an array, or
+ *     `{ source, has, missing }` objects. A request whose (base-path-stripped)
+ *     path matches no entry skips straight to `next()`.
+ *   - Returning `undefined` continues (Next's `NextResponse.next()` is the
+ *     default), `next()` is memoized so calling it twice runs the rest of the
+ *     chain once, and `next.waitUntil(promise)` keeps background work going
+ *     after the response without failing it.
+ *   - `request.cookies` is Next's RequestCookies over the request's cookies, and reading
+ *     `request.nextUrl` (Next's extended URL) throws in dev with the fix.
+ *   - A load failure FAILS CLOSED: a middleware that guards a route and cannot
+ *     load must never let the request through unguarded. The root one rejects
+ *     the analysis (dev overlay, prod readiness 503), a segment one answers 500.
+ *
+ * @module middleware-load
+ */
+import { join } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { devImport } from './dev-import.js';
+import { requestCookieStore, markDynamicAccess } from './context.js';
+import { parseCookieHeader, requestCookiesView } from './cookie-store.js';
+
+const MIDDLEWARE_FILES = ['middleware.ts', 'middleware.js', 'middleware.mts', 'middleware.mjs'];
+const PROXY_FILES = ['proxy.ts', 'proxy.js', 'proxy.mts', 'proxy.mjs'];
+
+/** @param {string} p */
+async function exists(p) {
+  try { await stat(p); return true; } catch { return false; }
+}
+
+/**
+ * The root middleware file, or null. Throws when both a `middleware.*` and a
+ * `proxy.*` exist, since only one can be the app's middleware.
+ * @param {string} appDir
+ * @returns {Promise<string | null>}
+ */
+export async function findRootMiddleware(appDir) {
+  let mw = null;
+  let px = null;
+  for (const n of MIDDLEWARE_FILES) if (!mw && await exists(join(appDir, n))) mw = n;
+  for (const n of PROXY_FILES) if (!px && await exists(join(appDir, n))) px = n;
+  if (mw && px) {
+    const err = new Error(`[webjs] both ${mw} and ${px} exist at the app root. They are the same thing (proxy is Next 16's name for middleware), so only one may exist. Delete one, or merge them.`);
+    /** @type {any} */ (err).code = 'WEBJS_APP_LAYOUT';
+    throw err;
+  }
+  const name = mw || px;
+  return name ? join(appDir, name) : null;
+}
+
+/**
+ * The middleware function a module exports: `default`, then `middleware`,
+ * then `proxy`. Throws naming the file when there is none.
+ * @param {Record<string, unknown>} mod
+ * @param {string} file
+ * @returns {Function}
+ */
+export function resolveMiddlewareExport(mod, file) {
+  for (const k of ['default', 'middleware', 'proxy']) {
+    if (typeof mod[k] === 'function') return /** @type {Function} */ (mod[k]);
+  }
+  throw new Error(`[webjs] ${file} exports no middleware function. Export it as the default, or as a named \`middleware\` (or \`proxy\`) function, as in Next.js.`);
+}
+
+/**
+ * @typedef {{ type: 'header' | 'cookie' | 'query' | 'host', key?: string, value?: string }} RouteHas
+ * @typedef {string | { source: string, has?: RouteHas[], missing?: RouteHas[] }} MatcherEntry
+ */
+
+/** `has` / `missing` value patterns, compiled once each (they come from the config, not the request). */
+const hasPatterns = new Map();
+
+/** @param {string} source */
+function hasPattern(source) {
+  let re = hasPatterns.get(source);
+  if (!re) { re = new RegExp(`^${source}$`); hasPatterns.set(source, re); }
+  return re;
+}
+
+/**
+ * A port of Next's `matchHas` (prepare-destination.ts): each `has` condition
+ * must hold and no `missing` one may. A condition with no `value` checks
+ * presence; a `value` is a regex anchored to the whole value.
+ * @param {Request} req
+ * @param {URL} url
+ * @param {RouteHas[]} [has]
+ * @param {RouteHas[]} [missing]
+ */
+export function matchHas(req, url, has = [], missing = []) {
+  /** @type {Map<string, string> | null} */
+  let cookies = null;
+  /** @param {RouteHas} item */
+  const holds = (item) => {
+    /** @type {string | undefined | null} */
+    let value;
+    switch (item.type) {
+      case 'header': value = req.headers.get(String(item.key).toLowerCase()); break;
+      case 'cookie': value = (cookies ||= parseCookieHeader(req.headers.get('cookie'))).get(String(item.key)); break;
+      case 'query': value = url.searchParams.get(String(item.key)); break;
+      case 'host': value = (req.headers.get('host') || url.host).split(':', 1)[0].toLowerCase(); break;
+      default: return false;
+    }
+    if (value == null || value === '') return false;
+    if (!item.value) return true;
+    return hasPattern(item.value).test(value);
+  };
+  return has.every(holds) && !missing.some(holds);
+}
+
+/**
+ * Compile `config.matcher` into a predicate over a request, or null when the
+ * middleware has no matcher (it runs for every request). Each source is a
+ * Next path pattern (`/dashboard/:path*`, `/((?!api|_next).*)`) compiled with
+ * URLPattern; a path with a trailing slash is retried without it.
+ * @param {unknown} matcher
+ * @param {string} file for the error message
+ * @returns {((req: Request, url: URL) => boolean) | null}
+ */
+export function compileMatcher(matcher, file) {
+  if (matcher == null) return null;
+  const list = Array.isArray(matcher) ? matcher : [matcher];
+  const entries = list.map((m) => {
+    const e = typeof m === 'string' ? { source: m } : m;
+    if (!e || typeof e.source !== 'string' || !e.source.startsWith('/')) {
+      throw new Error(`[webjs] ${file}: config.matcher entries must be a path starting with "/" or { source, has?, missing? }; got ${JSON.stringify(m)}.`);
+    }
+    let pattern;
+    try { pattern = new URLPattern({ pathname: e.source }); } catch (err) {
+      throw new Error(`[webjs] ${file}: config.matcher "${e.source}" is not a valid path pattern (${/** @type {Error} */ (err).message}).`);
+    }
+    // Compile the has / missing patterns now, so a bad one fails at load.
+    for (const item of [...(e.has || []), ...(e.missing || [])]) {
+      if (item && item.value) {
+        try { hasPattern(String(item.value)); } catch (err) {
+          throw new Error(`[webjs] ${file}: config.matcher has/missing value ${JSON.stringify(item.value)} is not a valid pattern: ${/** @type any */ (err).message}`);
+        }
+      }
+    }
+    return { pattern, has: e.has, missing: e.missing };
+  });
+  return (req, url) => {
+    const path = url.pathname;
+    const alt = path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : null;
+    return entries.some((e) => (e.pattern.test({ pathname: path }) || (alt !== null && e.pattern.test({ pathname: alt })))
+      && matchHas(req, url, e.has, e.missing));
+  };
+}
+
+/**
+ * Give a middleware's or a route handler's request Next's extras (#1686:
+ * `NextRequest` is what both receive in Next.js): `request.cookies` (Next's
+ * `RequestCookies`: a set there changes what the rest of this request reads and
+ * sends nothing to the browser, `cookies().set()` does that) and, in dev, a
+ * `request.nextUrl` that throws naming `new URL(request.url)`.
+ * @param {Request} req
+ * @param {boolean} dev
+ */
+export function decorateRequest(req, dev) {
+  try {
+    if (!Object.prototype.hasOwnProperty.call(req, 'cookies')) {
+      Object.defineProperty(req, 'cookies', { configurable: true, get: () => { markDynamicAccess(); return requestCookiesView(requestCookieStore()); } });
+    }
+    if (!Object.prototype.hasOwnProperty.call(req, 'nextUrl')) {
+      Object.defineProperty(req, 'nextUrl', {
+        configurable: true,
+        get() {
+          if (dev) throw new Error('[webjs] request.nextUrl is Next.js\'s extended URL, which WebJs does not add: middleware receives the platform Request. Use new URL(request.url) instead.');
+          return new URL(req.url);
+        },
+      });
+    }
+  } catch { /* a frozen request: leave it as the platform made it */ }
+}
+
+/**
+ * Wrap a middleware function with Next's call semantics (see the module doc).
+ * @param {Function} fn
+ * @param {((req: Request, url: URL) => boolean) | null} matcher
+ * @param {{ dev: boolean, file: string, logger?: { error?: (...a: any[]) => void } }} opts
+ * @returns {(req: Request, next: () => Promise<Response>) => Promise<Response>}
+ */
+export function wrapMiddleware(fn, matcher, opts) {
+  return async (req, next) => {
+    if (matcher) {
+      let url;
+      try { url = new URL(req.url); } catch { return next(); }
+      if (!matcher(req, url)) return next();
+    }
+    /** @type {Promise<Response> | null} */
+    let ran = null;
+    const once = /** @type {(() => Promise<Response>) & { waitUntil: (p: Promise<unknown>) => void }} */ (
+      Object.assign(() => (ran ||= Promise.resolve().then(next)), {
+        waitUntil(/** @type {Promise<unknown>} */ p) {
+          Promise.resolve(p).catch((e) => opts.logger?.error?.(`[webjs] next.waitUntil promise rejected in ${opts.file}`, { err: String(e) }));
+        },
+      }));
+    decorateRequest(req, opts.dev);
+    const result = await fn(req, once);
+    if (result === undefined || result === null) return once();
+    if (result instanceof Response) return result;
+    throw new Error(`[webjs] ${opts.file} returned ${typeof result === 'object' ? 'a non-Response object' : typeof result}. Middleware returns a Response to answer, or calls next() (returning nothing also continues).`);
+  };
+}
+
+/**
+ * Load a middleware module into its wrapped form. Throws (fail closed) when
+ * the module fails to import, exports no function, or has a bad matcher.
+ * @param {string} file
+ * @param {boolean} dev
+ * @param {{ error?: (...a: any[]) => void }} [logger]
+ */
+export async function loadMiddlewareFile(file, dev, logger) {
+  const mod = await devImport(file, dev);
+  // Segment middleware is loaded on every request, so the wrapper (and the
+  // URLPattern compile of its matcher) is memoized on the module object: the
+  // same module until its source changes (devImport keys a dev re-import on
+  // the file's content), so an edit gets a fresh wrapper and nothing else does.
+  const hit = WRAPPED.get(mod);
+  if (hit && hit.dev === dev && hit.logger === logger) return hit.wrapped;
+  const fn = resolveMiddlewareExport(mod, file);
+  const config = mod.config && typeof mod.config === 'object' ? /** @type {any} */ (mod.config) : {};
+  const matcher = compileMatcher(config.matcher, file);
+  const wrapped = wrapMiddleware(fn, matcher, { dev, file, logger });
+  WRAPPED.set(mod, { dev, logger, wrapped });
+  return wrapped;
+}
+
+/** @type {WeakMap<object, { dev: boolean, logger: unknown, wrapped: Function }>} */
+const WRAPPED = new WeakMap();
+
+/**
+ * Load the optional root middleware (or proxy). Null when there is none;
+ * throws when it cannot be loaded, so the analysis refuses to serve.
+ * @param {string} appDir
+ * @param {boolean} dev
+ * @param {{ error?: (...a: any[]) => void }} [logger]
+ */
+export async function loadRootMiddleware(appDir, dev, logger) {
+  const file = await findRootMiddleware(appDir);
+  if (!file) return null;
+  return loadMiddlewareFile(file, dev, logger);
+}

package/src/module-graph.js

@@ -46,7 +46,7 @@ export function appImportsMap(appDir) {
  * Expand a `package.json "imports"` subpath alias (e.g. `#lib/db.server.ts`
  * with the scaffold's catch-all `"#*": "./*"`) to its real APP-RELATIVE target
  * string (`./lib/db.server.ts`).
- * The security-critical seam (#555): the graph walker, auth gate, elision, and
+ * The security-critical seam (#555): the graph walker, auth gate, boot frontier, and
  * `no-server-import-in-browser-module` all route through `resolveImport`, so
  * expanding the alias here (to the real path) is what stops an alias from
  * laundering a `.server.ts` past those checks. Driven off the actual `"imports"`
@@ -124,6 +124,54 @@ const EXPORT_FROM_RE = /\bexport\b[^'";`]+?\sfrom\s+['"]([^'"]+)['"]/gd;
  */
 const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*[,)]/gd;
 
+/**
+ * Every import specifier a module's source names, with its position: static
+ * `import`, `export … from`, then string-literal dynamic `import('…')`, each
+ * group in source order. `start` / `end` delimit the specifier text inside its
+ * quotes in `src`, so a caller can splice it (#1689, the dev server's browser
+ * module versions).
+ *
+ * All three regexes run over the FULLY-BLANKED mask (see `parseFile`), so a
+ * keyword inside a comment, string, template or regex never anchors a match,
+ * and the specifier is read back from the raw source at the group indices.
+ * The static half is exactly what `parseFile` builds the graph from, so the two
+ * can never disagree. The dynamic half differs from the graph's own dynamic
+ * scan in one place: a dynamic import written inside a template `${}` hole is
+ * blanked here and so not listed (the graph scan reads hole code).
+ *
+ * A statement-leading type-only clause is skipped, because the TS stripper
+ * erases it and it never becomes a fetch or a runtime edge (#805):
+ * `import type { X }`, `import type * as X`, `import type Foo`,
+ * `export type { X }`, `export type *`. Two carve-outs keep this from
+ * over-dropping. `import type from '...'` is a VALUE default import whose
+ * binding is named `type`, and a MIXED `import { type A, b }` does not lead
+ * with `type`, so both are kept.
+ *
+ * @param {string} src
+ * @returns {Array<{ start: number, end: number, spec: string, dynamic: boolean }>}
+ */
+export function importSpecifierRanges(src) {
+  const masked = redactStringsAndTemplates(src, true);
+  /** @type {Array<{ start: number, end: number, spec: string, dynamic: boolean }>} */
+  const out = [];
+  for (const re of [IMPORT_RE, EXPORT_FROM_RE, DYNAMIC_IMPORT_RE]) {
+    const dynamic = re === DYNAMIC_IMPORT_RE;
+    for (const m of masked.matchAll(re)) {
+      if (!dynamic) {
+        // m[0] is over the mask, which keeps the binding syntax verbatim.
+        const lead = m[0];
+        const typeOnly =
+          /^(?:import|export)\s+type\s*[{*]/.test(lead) ||
+          (/^import\s+type\s+[A-Za-z_$]/.test(lead) && !/^import\s+type\s+from\b/.test(lead));
+        if (typeOnly) continue;
+      }
+      const [start, end] = /** @type {[number, number]} */ (m.indices?.[1]);
+      out.push({ start, end, spec: src.slice(start, end), dynamic });
+    }
+  }
+  return out;
+}
+
 /**
  * @typedef {Map<string, Set<string>>} ModuleGraph
  * A map of absolute file path → Set of absolute file paths it STATICALLY imports.
@@ -134,9 +182,9 @@ const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*[,)]/gd;
  * the static graph and keyed by it in a WeakMap. The authorization gate
  * (`reachableFromEntries`) unions these in so a lazily-imported app module is
  * servable instead of 404ing, but the preload walk (`transitiveDeps`) and the
- * elision analysis stay on the static graph ONLY: a dynamic import is lazy by
- * author intent, so eagerly preloading its target would over-fetch on every
- * page load, and feeding dynamic edges into elision could flip a verdict. The
+ * boot frontier stay on the static graph ONLY: a dynamic import is lazy by
+ * author intent, so eagerly preloading or booting its target would over-fetch
+ * on every page load. The
  * module is fetched at call time, now served correctly by the gate.
  * @type {WeakMap<ModuleGraph, ModuleGraph>}
  */
@@ -358,9 +406,10 @@ const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
  * @param {ModuleGraph} graph
  * @param {string[]} entryFiles absolute paths of browser-bound entries
  * @param {string} appDir
+ * @param {Set<string>} [stopAt]  files never admitted or walked (the route-table files)
  * @returns {Set<string>}
  */
-export function reachableFromEntries(graph, entryFiles, appDir) {
+export function reachableFromEntries(graph, entryFiles, appDir, stopAt) {
   // The gate unions in dynamic-import edges (#751) so a lazily-imported app
   // module (`await import('./widget.ts')`) is servable instead of 404ing. A
   // dynamically-imported module's OWN static imports are then walked normally
@@ -392,6 +441,9 @@ export function reachableFromEntries(graph, entryFiles, appDir) {
       for (const dep of set) {
         if (visited.has(dep)) continue;
         if (!dep.startsWith(appDir)) continue;
+        // A route-table file never loads in the browser (#1686), even when a
+        // component imports one, so it is neither servable nor walked.
+        if (stopAt && stopAt.has(dep)) continue;
         visited.add(dep);
         queue.push(dep);
       }
@@ -419,9 +471,8 @@ export function reachableFromEntries(graph, entryFiles, appDir) {
  * imported by a server file must never enter the importmap.
  *
  * `skip` files are neither collected nor traversed into, so a specifier
- * reachable ONLY through an elided component drops out along with the subtree
- * behind it (#197 / #170). Omit `skip` for the un-pruned superset the pin path
- * needs.
+ * reachable ONLY through a route module drops out along with the subtree
+ * behind it (#197 / #170). Omit `skip` for the un-pruned superset.
  *
  * @param {ModuleGraph} graph
  * @param {string[]} entryFiles  absolute paths
@@ -556,7 +607,7 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare, bareDynamic)
   // graph edge to whatever path that string names. Since this caller only
   // checks keyword-in-code-position, blank every literal body so a
   // code-example `import` string never becomes an edge.
-  // Scan for edges over the FULLY-BLANKED mask: every comment / string /
+  // `importSpecifierRanges` scans for edges over the FULLY-BLANKED mask: every comment / string /
   // template / regex body is blanked to spaces (delimiters kept), `${...}`
   // holes stay as code. Reason (#753, found differentially): a stray `import` /
   // `export` word inside a comment, template, OR regex literal must not anchor a
@@ -570,48 +621,23 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare, bareDynamic)
   // left for a per-match position guard to reject. The specifier itself is a
   // string (blanked here), so it is read back from raw `src` via the match's
   // group indices (the `d` flag).
-  const masked = redactStringsAndTemplates(src, true);
   /** @type {string[]} local (relative / aliased) static specifiers */
   const specs = [];
   /** @type {Set<string>} bare npm vendor specifiers imported by this file (#754) */
   const bareDeps = new Set();
-  for (const re of [IMPORT_RE, EXPORT_FROM_RE]) {
-    for (const m of masked.matchAll(re)) {
-      // A statement-leading `import type { X }` / `import type * as X` /
-      // `import type Foo` (default type import) / `export type { X }` /
-      // `export type *` is fully erased by the TS stripper, so it never becomes
-      // a browser fetch or a runtime edge. Skip it, so a type-only import of a
-      // `.server.ts` (a common, correct way to share a derived row type) is not
-      // mistaken for a runtime dependency by the gate / elision / the
-      // no-server-import check. Two carve-outs keep this from over-dropping:
-      //   - `import type from '...'` is a VALUE default import whose binding is
-      //     literally named `type` (the stripper keeps it), so `type` directly
-      //     followed by `from` is NOT type-only.
-      //   - a MIXED `import { type A, b }` does NOT lead with `type`, so it is
-      //     kept (its `b` binding is a real runtime edge).
-      // (m[0] here is over the mask, which keeps the binding syntax verbatim.)
-      // #805
-      const lead = m[0];
-      const typeOnly =
-        /^(?:import|export)\s+type\s*[{*]/.test(lead) ||
-        (/^import\s+type\s+[A-Za-z_$]/.test(lead) && !/^import\s+type\s+from\b/.test(lead));
-      if (typeOnly) continue;
-      // The specifier is read from RAW src at the match's captured-group indices
-      // (the group is the blanked string body in the mask; its position is the
-      // real specifier in src).
-      const spec = src.slice(m.indices[1][0], m.indices[1][1]);
-      // Only resolve relative imports + `#`-style subpath aliases (#555)
-      // within the project. A bare npm specifier (dayjs) has no alias match
-      // and is skipped FROM THE GRAPH, but recorded as a vendor edge so SSR
-      // can emit a modulepreload for the reached vendor URL (#754); an aliased
-      // `#lib/x.server.ts` IS followed so the graph / auth gate / elision see
-      // the real path through the alias.
-      if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) {
-        if (isVendorSpecifier(spec)) bareDeps.add(spec);
-        continue;
-      }
-      specs.push(spec);
+  for (const { spec, dynamic: isDynamic } of importSpecifierRanges(src)) {
+    if (isDynamic) continue;
+    // Only resolve relative imports + `#`-style subpath aliases (#555)
+    // within the project. A bare npm specifier (dayjs) has no alias match
+    // and is skipped FROM THE GRAPH, but recorded as a vendor edge so SSR
+    // can emit a modulepreload for the reached vendor URL (#754); an aliased
+    // `#lib/x.server.ts` IS followed so the graph / auth gate / frontier see
+    // the real path through the alias.
+    if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) {
+      if (isVendorSpecifier(spec)) bareDeps.add(spec);
+      continue;
     }
+    specs.push(spec);
   }
   // Dynamic `import('…')` with a string-literal specifier (#751): a separate
   // edge class so the gate admits the lazily-loaded module (no 404) without
@@ -704,7 +730,7 @@ export function resolveImport(spec, fromFile, appDir) {
   if (aliased) {
     // `#`-style subpath alias (#555): the app-relative target is resolved
     // against the app root, then run through the same extension fallback below
-    // so the boundary / elision / preload all see the real on-disk path.
+    // so the boundary / frontier / preload all see the real on-disk path.
     target = resolve(appDir, aliased);
   } else if (spec.startsWith('/')) {
     // Absolute from app root (how browser sees it)