@webjsdev/server 0.8.11 → 0.8.13

package/src/dev.js

@@ -47,6 +47,7 @@ process.emitWarning = function (warning, type, code, ctor) {
 };
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
+import { generateRouteTypes } from './route-types.js';
 import { ssrPage, ssrNotFound } from './ssr.js';
 import { loadPageAction, runPageAction } from './page-action.js';
 import { handleApi } from './api.js';
@@ -112,9 +113,16 @@ function resolveRequestId(req) {
 function shouldAccessLog(pathname) {
   return !pathname.startsWith('/__webjs/');
 }
-import { setVendorEntries, setCoreInstall, publishBuildId } from './importmap.js';
+import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath } from './importmap.js';
+import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
+import {
+  compileRedirectRules,
+  applyRedirects,
+  readTrailingSlashPolicy,
+  applyTrailingSlash,
+} from './redirects.js';
 import { readBodyLimits, computeServerTimeouts } from './body-limit.js';
 import { applyConditionalGet, BUFFERED_MARKER } from './conditional-get.js';
 import { commitHtmlCache } from './html-cache.js';
@@ -261,6 +269,61 @@ export async function readHeaderRules(appDir) {
   }
 }
 
+/**
+ * Read the declarative redirect config (`webjs.redirects`) from the app's
+ * package.json and compile it to URLPattern rules (issue #254). A missing,
+ * malformed, or unreadable config yields an empty rule set (no redirects),
+ * never a throw. Patterns are compiled ONCE here at boot, not per request.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof compileRedirectRules>>}
+ */
+export async function readRedirectRules(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return compileRedirectRules(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the trailing-slash policy (`webjs.trailingSlash`) from the app's
+ * package.json (issue #255). A missing, malformed, or unreadable config
+ * yields `'ignore'` (no canonicalization), never a throw, so an
+ * unconfigured app is unchanged.
+ *
+ * @param {string} appDir
+ * @returns {Promise<'never' | 'always' | 'ignore'>}
+ */
+export async function readTrailingSlashFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readTrailingSlashPolicy(pkg);
+  } catch {
+    return 'ignore';
+  }
+}
+
+/**
+ * Read the sub-path base path (`webjs.basePath`) from the app's
+ * package.json (issue #256). A missing, malformed, or unreadable config
+ * yields `''` (root mount), never a throw, so an unconfigured app is
+ * byte-identical to before this feature. Normalized to `''` or
+ * `/segment[/segment...]` by `readBasePath`.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string>}
+ */
+export async function readBasePathFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readBasePath(pkg);
+  } catch {
+    return '';
+  }
+}
+
 /**
  * Read the CSP config (`webjs.csp`) from the app's package.json and
  * normalize it (issue #233). A missing, malformed, or unreadable config
@@ -380,6 +443,15 @@ export async function createRequestHandler(opts) {
       logger.error?.('[webjs] onError hook threw (ignored)', { err: String(e) });
     }
   }
+  // Sub-path deployment base path (issue #256), read once from the app's
+  // package.json `webjs.basePath` and bound into the importmap builder BEFORE
+  // setCoreInstall / setVendorEntries so every importmap target (and the
+  // recomputed hash) reflects the prefix. Empty (the default) makes both the
+  // ingress strip and the emit-side prefix pure no-ops, so an unconfigured app
+  // is byte-identical to before this feature.
+  const basePathValue = await readBasePathFromApp(appDir);
+  await setBasePath(basePathValue);
+
   const coreDir = locateCoreDir(appDir);
   // Switch the importmap between dist/ bundles and src/ per-file
   // URLs depending on whether the resolved @webjsdev/core install
@@ -446,11 +518,53 @@ export async function createRequestHandler(opts) {
   // Hints, and WebSocket lookups need it available before the first request.
   const routeTable = await buildRouteTable(appDir);
 
+  // Emit `.webjs/routes.d.ts` (typed Route union + per-route params, #258) in
+  // dev so an editor's tsserver always has up-to-date route types without the
+  // developer remembering to run `webjs types`. Best-effort and fire-and-
+  // forget: a failure logs and never blocks boot. Re-emitted after each route
+  // rebuild (see doRebuild) so adding/removing a route refreshes the types.
+  /** @returns {Promise<void>} */
+  async function emitRouteTypes() {
+    try {
+      const { mkdir, writeFile, rename } = await import('node:fs/promises');
+      const text = await generateRouteTypes(appDir);
+      const outDir = join(appDir, '.webjs');
+      await mkdir(outDir, { recursive: true });
+      // Write to a temp sibling then rename, so tsserver (which reads this
+      // file) never observes a half-written body if two rebuilds race. rename
+      // is atomic within the same dir. Both paths sit under the watcher-ignored
+      // .webjs/, so neither the temp write nor the rename re-triggers a rebuild.
+      const dest = join(outDir, 'routes.d.ts');
+      const tmp = join(outDir, `routes.d.ts.${process.pid}.tmp`);
+      await writeFile(tmp, text);
+      await rename(tmp, dest);
+    } catch (e) {
+      logger.warn?.(`[webjs] could not write .webjs/routes.d.ts (route types): ${e?.message || e}`);
+    }
+  }
+  if (dev) void emitRouteTypes();
+
   // Per-path response-header rules (issue #232), read once from the
   // app's package.json `webjs.headers`. Static config, so no rebuild
   // re-read; the secure defaults need no config and apply regardless.
   const headerRules = await readHeaderRules(appDir);
 
+  // Declarative redirect rules (issue #254), read once from the app's
+  // package.json `webjs.redirects` and compiled to URLPattern rules at
+  // boot (never per request). Empty when unconfigured, so an app with no
+  // redirects is unchanged. Applied at the very start of request handling,
+  // before routing / SSR / asset serving, so a moved URL returns a 308/307
+  // immediately.
+  const redirectRules = await readRedirectRules(appDir);
+
+  // Trailing-slash policy (issue #255), read once from the app's package.json
+  // `webjs.trailingSlash`. Default `'ignore'` (no canonicalization), so an
+  // unconfigured app is unchanged; `'never'` (recommended) strips a trailing
+  // slash and `'always'` adds one, each via a 308 to the canonical form.
+  // Applied in produce() AFTER the declarative redirects, so an explicit
+  // redirect rule wins first and the two never loop.
+  const trailingSlashPolicy = await readTrailingSlashFromApp(appDir);
+
   // CSP config (issue #233), read once from the app's package.json
   // `webjs.csp`. OFF by default: when disabled no nonce is minted and no
   // Content-Security-Policy header is set, so an unconfigured app is
@@ -715,6 +829,10 @@ export async function createRequestHandler(opts) {
     // The route table is the only eager artifact (cheap directory scan); rebuild
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
+    // Refresh the generated route types (#258) so adding/removing a route file
+    // updates `.webjs/routes.d.ts` without a manual `webjs types`. Dev only,
+    // best-effort (see emitRouteTypes).
+    if (dev) void emitRouteTypes();
     clearVendorCache();
     state.tsCache.clear();
     // Invalidate the lazy analysis; the next request rebuilds the graph,
@@ -762,6 +880,19 @@ export async function createRequestHandler(opts) {
 
       let pathname = '/';
       try { pathname = new URL(req.url).pathname; } catch { /* keep default */ }
+      // Sub-path deployment (issue #256): the per-path response-header rules
+      // (`webjs.headers`) author their `source` patterns app-root-relative,
+      // exactly like `webjs.redirects` / `webjs.trailingSlash` (which the
+      // ingress strip in produce() already sees root-relative). So match the
+      // header rules against the STRIPPED path too, keeping the whole config
+      // surface consistent under a base path. `pathname` itself (used for the
+      // access log) stays the RAW path the client hit. No-op when basePath is
+      // empty or the request is not under it.
+      let headerPathname = pathname;
+      if (basePathValue) {
+        const s = stripBasePath(pathname, basePathValue);
+        if (s !== null) headerPathname = s;
+      }
       const startedAt = performance.now();
 
       let res;
@@ -788,7 +919,7 @@ export async function createRequestHandler(opts) {
       // Applied to every served response (documents, assets, the core
       // runtime, probes), since the defaults are universally safe.
       let merged = applySecurityHeaders(res, {
-        pathname,
+        pathname: headerPathname,
         https: webRequestIsHttps(req),
         prod: !dev,
         rules: headerRules,
@@ -826,6 +957,14 @@ export async function createRequestHandler(opts) {
       // stripped here regardless. Best-effort: a store failure is swallowed.
       try {
         const reqUrl = new URL(req.url);
+        // Sub-path deployment (issue #256): the HTML cache READ (in ssrPage)
+        // and `revalidatePath` both key on the app-root-relative path, so key
+        // the WRITE on the stripped path too, or a cached page would never
+        // hit. No-op when basePath is empty / the path is not under it.
+        if (basePathValue) {
+          const s = stripBasePath(reqUrl.pathname, basePathValue);
+          if (s !== null) reqUrl.pathname = s;
+        }
         merged = await commitHtmlCache(req, merged, reqUrl);
       } catch { /* never let the cache write crash the response */ }
 
@@ -847,7 +986,10 @@ export async function createRequestHandler(opts) {
       // duration / requestId (no bodies, no secrets). Suppressed for the
       // framework's own /__webjs/* probe + static traffic so it does not spam.
       // Best-effort: a logger that throws must not take the response down.
-      if (shouldAccessLog(pathname)) {
+      // Use the STRIPPED path for the suppression check (issue #256) so a
+      // framework probe at `<basePath>/__webjs/*` is suppressed just like the
+      // root-mounted `/__webjs/*`. The logged `path` stays the RAW client URL.
+      if (shouldAccessLog(headerPathname)) {
         try {
           logger.info?.('request', {
             requestId: reqId,
@@ -866,6 +1008,69 @@ export async function createRequestHandler(opts) {
   /** @param {Request} req */
   function produce(req) {
     return (async () => {
+      // Sub-path deployment ingress strip (issue #256). When `webjs.basePath`
+      // is set and the request path is under it, STRIP the prefix and rewrite
+      // the Request so EVERYTHING downstream (redirects, trailing-slash, the
+      // probes, the `/__webjs/*` checks, the source-file gate, route matching,
+      // SSR) sees a ROOT-relative path and works UNCHANGED. This single strip
+      // is why the rest of the framework needs no per-site changes. A request
+      // whose path is NOT under the base path is not for this mounted app, so
+      // return a 404 (the safe default for a mounted app). Empty basePath (the
+      // default) is a pure pass-through, so an unconfigured app is unchanged.
+      if (basePathValue) {
+        let reqUrl;
+        try { reqUrl = new URL(req.url); } catch { reqUrl = null; }
+        if (reqUrl) {
+          const stripped = stripBasePath(reqUrl.pathname, basePathValue);
+          if (stripped === null) {
+            // Not under the base path: this request is not for this app.
+            return new Response('Not found', {
+              status: 404,
+              headers: { 'content-type': 'text/plain; charset=utf-8' },
+            });
+          }
+          if (stripped !== reqUrl.pathname) {
+            reqUrl.pathname = stripped;
+            // Rewrite the Request with the stripped URL, preserving method,
+            // headers, and body. `duplex: 'half'` is required by the spec when
+            // a body stream is present on a non-GET/HEAD request.
+            const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+            req = new Request(
+              reqUrl.toString(),
+              /** @type {any} */ ({
+                method: req.method,
+                headers: req.headers,
+                body: hasBody ? req.body : undefined,
+                duplex: hasBody ? 'half' : undefined,
+                redirect: req.redirect,
+                signal: req.signal,
+              }),
+            );
+          }
+        }
+      }
+
+      // Declarative redirects (issue #254): apply the configured old-path ->
+      // new-path rules at the VERY START of request handling, before the
+      // probes, routing, SSR, or asset serving. A matched source returns a
+      // 308 (permanent, the SEO default) / 307 (temporary) / configured
+      // status immediately, so a moved URL never reaches the router.
+      // `applyRedirects` skips /__webjs/* itself, so the framework probes /
+      // runtime below are never redirected. The secure-header + conditional-GET
+      // funnel in handle() still wraps this Response, like any other.
+      const redirectResp = applyRedirects(req, redirectRules);
+      if (redirectResp) return redirectResp;
+
+      // Trailing-slash canonicalization (issue #255): after the explicit
+      // redirects above (so an explicit rule wins first and the two never
+      // form a loop), 308-redirect a non-canonical path to the policy's
+      // canonical form (`never` strips a trailing slash, `always` adds one).
+      // Default `'ignore'` is a no-op. The root `/` and file paths are
+      // exempt; `/__webjs/*` is exempt too (defense in depth, the redirects
+      // above already skip it). The funnel in handle() still wraps this.
+      const slashResp = applyTrailingSlash(req, trailingSlashPolicy);
+      if (slashResp) return slashResp;
+
       // Health and readiness probes are answered BEFORE ensureReady so a probe
       // never blocks on the analysis. `/__webjs/health` is liveness (the
       // process is up and accepting connections). `/__webjs/ready` is 503 until
@@ -950,14 +1155,25 @@ export async function createRequestHandler(opts) {
    * BEFORE running SSR: resolves a pathname to its page-route module URLs
    * without loading them. Returns null for non-page paths.
    *
+   * Sub-path deployment (issue #256): the HTTP layer passes the RAW request
+   * pathname (still carrying the base path, since the ingress strip happens
+   * inside `produce`, not here), so strip it for route matching and prefix
+   * the emitted module URLs so the early-hint preloads resolve under the
+   * prefix. A path not under the base path yields null (no hints).
+   *
    * @param {string} pathname
    */
   function routeFor(pathname) {
-    const page = matchPage(state.routeTable, pathname);
+    const matchPathname = basePathValue
+      ? stripBasePath(pathname, basePathValue)
+      : pathname;
+    if (matchPathname === null) return null;
+    const page = matchPage(state.routeTable, matchPathname);
     if (!page) return null;
     const moduleUrls = [page.route.file, ...page.route.layouts].map((f) => {
       let rel = f.startsWith(appDir) ? f.slice(appDir.length) : f;
-      return rel.split('\\').join('/').replace(/^\/?/, '/');
+      const url = rel.split('\\').join('/').replace(/^\/?/, '/');
+      return withBasePath(url, basePathValue);
     });
     return { moduleUrls };
   }
@@ -997,6 +1213,25 @@ export async function createRequestHandler(opts) {
  * etc.) sitting in front of this process. See the deployment docs for
  * the recommended topology.
  *
+/**
+ * Paths under the app root whose changes must NOT trigger a dev rebuild.
+ * `node_modules` / `.git` are noise. `.webjs/` is the framework's generated
+ * artefact dir (the #258 routes.d.ts and the vendor pin) that the dev server
+ * itself writes on startup and on every rebuild, so without this skip the
+ * write fires a watch event, triggers a rebuild, re-writes the file, and loops
+ * forever. `prisma/dev*` / `prisma/migrations` churn during db:migrate. The
+ * prisma branch is prefix-only (no trailing separator) so the SQLite sidecars
+ * `prisma/dev.db` / `prisma/dev.db-journal` match too; the others stay
+ * separator-anchored so an unrelated name like `node_modules.bak/foo` does not.
+ *
+ * @param {string} filename relative path from an fs.watch `event.filename`
+ * @returns {boolean} true when the change should be ignored
+ */
+export function shouldIgnoreWatchPath(filename) {
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/.test(filename || '');
+}
+
+/**
  * @param {{
  *   appDir: string,
  *   port?: number,
@@ -1032,18 +1267,9 @@ export async function startServer(opts) {
     // `fs.promises.watch`. Stable on macOS, Windows, and Linux as of
     // Node 24. No external dep needed.
     //
-    // fs.watch returns relative paths in event.filename. We apply
-    // the same ignore filter chokidar used before: skip
-    // node_modules, .git, and prisma's dev artefacts (dev.db,
-    // dev.db-journal, migrations/) which the dev server writes
-    // during db:migrate and would otherwise loop.
-    //
-    // The prisma branch uses prefix-only matching (no required
-    // trailing separator) so the SQLite sidecar files like
-    // `prisma/dev.db` and `prisma/dev.db-journal` are ignored too.
-    // node_modules / .git stay separator-anchored so unrelated
-    // names like `node_modules.bak/foo` don't get caught.
-    const IGNORE = /(?:^|[\\/])(?:node_modules|\.git)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/;
+    // fs.watch returns relative paths in event.filename. `shouldIgnoreWatchPath`
+    // (module-level, exported for tests) skips node_modules, .git, .webjs/, and
+    // prisma's dev artefacts so a file the dev server itself writes never loops.
     const rebuild = debounce(() => app.rebuild(), 80);
     watcherAbort = new AbortController();
     (async () => {
@@ -1051,7 +1277,7 @@ export async function startServer(opts) {
         const events = fsWatch(app.appDir, { recursive: true, signal: watcherAbort.signal });
         for await (const event of events) {
           const filename = event.filename || '';
-          if (IGNORE.test(filename)) continue;
+          if (shouldIgnoreWatchPath(filename)) continue;
           rebuild();
         }
       } catch (err) {
@@ -1075,8 +1301,11 @@ export async function startServer(opts) {
     try {
       const url = urlFromRequest(req);
 
-      // SSE: handled specially; doesn't fit the req→Response model.
-      if (url.pathname === '/__webjs/events') {
+      // SSE: handled specially; doesn't fit the req→Response model. Match the
+      // base-path-stripped pathname so the reload stream answers at
+      // `<basePath>/__webjs/events` under a sub-path deploy (#256). With no
+      // basePath this is a pure pass-through (the bare path still matches).
+      if (stripBasePath(url.pathname, basePath()) === '/__webjs/events') {
         if (!dev) { res.writeHead(404); res.end(); return; }
         res.writeHead(200, {
           'content-type': 'text/event-stream',
@@ -1195,7 +1424,7 @@ async function tryServeFrameworkStatic(path, method, ctx) {
   // Dev live-reload client.
   if (path === '/__webjs/reload.js') {
     if (!dev) return new Response('Not found', { status: 404 });
-    return new Response(RELOAD_CLIENT_JS, {
+    return new Response(reloadClientJs(basePath()), {
       headers: { 'content-type': 'application/javascript; charset=utf-8' },
     });
   }
@@ -2012,7 +2241,17 @@ function locatePackageDir(appDir, pkgName) {
   return null;
 }
 
-const RELOAD_CLIENT_JS = `// webjs dev reload client
-const es = new EventSource('/__webjs/events');
+/**
+ * The dev live-reload client. The `EventSource` URL is a framework-emitted
+ * same-origin path, so it must carry the base path under a sub-path deploy
+ * (#256), like the importmap targets and the RPC stub. No-op when basePath
+ * is empty.
+ * @param {string} bp the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+function reloadClientJs(bp) {
+  return `// webjs dev reload client
+const es = new EventSource(${JSON.stringify(withBasePath('/__webjs/events', bp))});
 es.addEventListener('reload', () => location.reload());
 `;
+}

package/src/importmap.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { digestHex } from './crypto-utils.js';
 import { jsonForScriptTag } from './script-tag-json.js';
+import { withBasePath } from './base-path.js';
 
 // Local attribute escaper. Matches ssr.js's escapeAttr (the source
 // of truth for HTML attribute escaping in this package). Kept inline
@@ -26,6 +27,45 @@ function escapeAttr(s) {
 /** @type {Record<string, string>} */
 let _extraEntries = {};
 
+/**
+ * The normalized `webjs.basePath` for a sub-path deployment (issue #256),
+ * `''` (the default) for a root mount. When non-empty, every same-origin
+ * absolute importmap TARGET (the `/__webjs/core/*` core entries and any
+ * same-origin `/__webjs/vendor/*` local vendor target) is prefixed with it
+ * so module resolution works under the prefix. A cross-origin `https://`
+ * CDN vendor target is absolute and is left untouched. Set once at boot by
+ * `setBasePath`, which recomputes the importmap hash so `importMapHash()`
+ * stays synchronous on the hot path.
+ *
+ * @type {string}
+ */
+let _basePath = '';
+
+/**
+ * Bind the importmap to a sub-path deployment's base path (issue #256).
+ * Called once at boot by `dev.js`. With the empty default the map is
+ * byte-identical to a root mount. The importmap hash is recomputed eagerly
+ * (like `setCoreInstall` / `setVendorEntries`) so `importMapHash()` stays
+ * synchronous on the per-request SSR path.
+ *
+ * @param {string} basePath the normalized base path (`''` = root mount)
+ * @returns {Promise<void>}
+ */
+export async function setBasePath(basePath) {
+  _basePath = basePath || '';
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+}
+
+/**
+ * The active base path, for callers that prefix their own emitted URLs
+ * against the same value (ssr.js's boot specifiers, preloads, reload src).
+ *
+ * @returns {string}
+ */
+export function basePath() {
+  return _basePath;
+}
+
 /**
  * SRI integrity hashes keyed by FINAL URL (post-importmap-rewrite).
  * Populated only when a pin file with `integrity` is present;
@@ -292,7 +332,12 @@ export function buildImportMap() {
   // even though the content didn't actually change.
   /** @type {Record<string, string>} */
   const imports = {};
-  for (const k of Object.keys(merged).sort()) imports[k] = merged[k];
+  // Prefix every same-origin absolute target with the sub-path base
+  // (issue #256). `withBasePath` is a no-op when the base path is empty
+  // (so a root-mounted app's map is byte-identical) and leaves a
+  // cross-origin `https://` CDN vendor target untouched (only the
+  // framework's own `/__webjs/*` and same-origin vendor targets move).
+  for (const k of Object.keys(merged).sort()) imports[k] = withBasePath(merged[k], _basePath);
 
   // Emit `integrity` per the importmap-integrity spec (Chrome 132+,
   // Safari 18.4+, Firefox flagged). Browsers without support ignore
@@ -305,11 +350,17 @@ export function buildImportMap() {
   // unrelated pin file edits, and leak removed URLs to the wire.
   const out = { imports };
   const usedUrls = new Set(Object.values(imports));
-  const intKeys = Object.keys(_vendorIntegrity).filter(k => usedUrls.has(k)).sort();
+  // Integrity keys are the FINAL post-rewrite URLs, so prefix a same-origin
+  // local vendor key with the base path to match its (now prefixed) imports
+  // value. A cross-origin CDN key is untouched by `withBasePath` and lines
+  // up with its unprefixed imports value.
+  const intKeys = Object.keys(_vendorIntegrity)
+    .filter(k => usedUrls.has(withBasePath(k, _basePath)))
+    .sort();
   if (intKeys.length) {
     /** @type {Record<string, string>} */
     const integrity = {};
-    for (const k of intKeys) integrity[k] = _vendorIntegrity[k];
+    for (const k of intKeys) integrity[withBasePath(k, _basePath)] = _vendorIntegrity[k];
     out.integrity = integrity;
   }
   return out;