@webjsdev/server 0.8.13 → 0.8.15

package/src/importmap.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { digestHex } from './crypto-utils.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { withBasePath } from './base-path.js';
+import { withAssetHash } from './asset-hash.js';
 
 // Local attribute escaper. Matches ssr.js's escapeAttr (the source
 // of truth for HTML attribute escaping in this package). Kept inline
@@ -53,7 +54,7 @@ let _basePath = '';
  */
 export async function setBasePath(basePath) {
   _basePath = basePath || '';
-  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
 }
 
 /**
@@ -87,7 +88,7 @@ let _vendorIntegrity = {};
 export async function setVendorEntries(entries, integrity) {
   _extraEntries = entries;
   _vendorIntegrity = integrity || {};
-  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
 }
 
 /**
@@ -228,7 +229,7 @@ let _coreEntries = {
  */
 export async function setCoreInstall(coreDir, distMode) {
   _coreEntries = buildCoreEntries(coreDir, !!distMode);
-  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
 }
 
 /**
@@ -319,7 +320,21 @@ export function buildCoreEntries(coreDir, distMode) {
   return out;
 }
 
-export function buildImportMap() {
+/**
+ * Build the import map object.
+ *
+ * @param {{ fingerprint?: boolean }} [opts]  When `fingerprint` is true (the
+ *   default, used by the SERVED map in `importMapTag`), same-origin targets
+ *   get a `?v=<content-hash>` suffix for immutable caching (issue #243); a
+ *   cross-origin CDN target is left untouched (`withAssetHash` skips it, so
+ *   its SRI key is unchanged). When false (used by the internal
+ *   `importMapHash()` computation), no `?v` is appended, so the published
+ *   build id stays a STABLE deploy fingerprint independent of per-file
+ *   content hashes (the build id only needs to be stable within a deploy).
+ *   In dev, `withAssetHash` is a no-op regardless, so both forms are equal.
+ */
+export function buildImportMap(opts = {}) {
+  const fingerprint = opts.fingerprint !== false;
   const merged = {
     ..._coreEntries,
     ..._extraEntries,
@@ -333,11 +348,18 @@ export function buildImportMap() {
   /** @type {Record<string, string>} */
   const imports = {};
   // 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);
+  // (issue #256), THEN (issue #243) append `?v=<content-hash>` to a
+  // same-origin target for immutable caching. The order is basePath then
+  // `?v`, so a sub-path app emits `<basePath>/app/foo.js?v=hash`.
+  // `withBasePath` is a no-op when the base path is empty and leaves a
+  // cross-origin `https://` CDN vendor target untouched; `withAssetHash`
+  // is a no-op in dev / when disabled and also leaves a cross-origin target
+  // untouched (only the framework's own `/__webjs/*` core + same-origin
+  // app/public targets get a `?v`).
+  for (const k of Object.keys(merged).sort()) {
+    const based = withBasePath(merged[k], _basePath);
+    imports[k] = fingerprint ? withAssetHash(based, _basePath) : based;
+  }
 
   // Emit `integrity` per the importmap-integrity spec (Chrome 132+,
   // Safari 18.4+, Firefox flagged). Browsers without support ignore
@@ -366,6 +388,43 @@ export function buildImportMap() {
   return out;
 }
 
+/**
+ * Derive the cross-origin vendor CDN origins from the resolved vendor
+ * importmap, most-common first (issue #243, auto vendor preconnect). For an
+ * UNPINNED app resolving vendors live from a cross-origin CDN (ga.jspm.io,
+ * or jsdelivr / unpkg / skypack with `--from`), this returns that origin so
+ * the head can warm DNS + TLS + TCP before the importmap resolves. A
+ * same-origin PINNED app (vendors served from `/__webjs/vendor/*` on the
+ * app's own origin), or an app with no cross-origin vendors, returns `[]`.
+ *
+ * Derived from the resolved targets (`_extraEntries`, the vendor map), NOT a
+ * hardcoded string, so a `--from jsdelivr` app preconnects to jsdelivr. The
+ * origins are deduped + sorted by frequency (the primary CDN first) and the
+ * list is bounded so a map spanning several CDNs cannot emit an unbounded
+ * preconnect set.
+ *
+ * @param {number} [max]  cap on the number of origins returned (default 2)
+ * @returns {string[]}  e.g. `['https://ga.jspm.io']`
+ */
+export function vendorPreconnectOrigins(max = 2) {
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  for (const target of Object.values(_extraEntries)) {
+    if (typeof target !== 'string') continue;
+    // Only an absolute `scheme://host` cross-origin url has an origin to
+    // preconnect. A same-origin `/__webjs/vendor/*` (downloaded-pin) target
+    // is `/`-rooted and skipped (no cross-origin to warm).
+    if (!/^https?:\/\//i.test(target)) continue;
+    let origin;
+    try { origin = new URL(target).origin; } catch { continue; }
+    counts.set(origin, (counts.get(origin) || 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, Math.max(0, max))
+    .map(([origin]) => origin);
+}
+
 /**
  * Serialise the import map to an HTML script tag string.
  *

package/src/ssr.js

@@ -1,8 +1,9 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { renderToString, isNotFound, isRedirect, lookupModuleUrl, isLazy, cspNonce } from '@webjsdev/core';
-import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPreconnectOrigins } from './importmap.js';
 import { withBasePath } from './base-path.js';
+import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { readToken, newToken, cookieHeader } from './csrf.js';
 import { transitiveDeps } from './module-graph.js';
@@ -786,8 +787,14 @@ function wrapHead(opts) {
   // (read from importmap.js's module state), the same value the importmap
   // targets were prefixed with, so the boot specifiers and the map agree.
   const bp = basePath();
+  // Content-hash asset URLs (issue #243): after base-path-prefixing, append
+  // `?v=<hash>` to a same-origin module specifier for immutable caching. A
+  // no-op in dev (so the boot script is byte-identical) and for a bare/
+  // cross-origin specifier; same compose order as the importmap targets
+  // (basePath then `?v`).
+  const fp = (u) => withAssetHash(withBasePath(u, bp), bp);
   const imports = opts.moduleUrls
-    .map((u) => `import ${jsonForScriptTag(withBasePath(u, bp))};`)
+    .map((u) => `import ${jsonForScriptTag(fp(u))};`)
     .join('\n');
   const rawLazyEntries = opts.lazyComponents && Object.keys(opts.lazyComponents).length
     ? opts.lazyComponents
@@ -795,9 +802,14 @@ function wrapHead(opts) {
   // The lazy map's values are same-origin module URLs `observeLazy` will
   // dynamically import, so prefix them with the base path too (no-op when
   // empty).
-  const lazyEntries = rawLazyEntries && bp
+  // The lazy map's values are same-origin module URLs `observeLazy` will
+  // dynamically import, so base-path-prefix AND content-hash them (#243), the
+  // same as the eager boot specifiers. `fp` is a pure no-op in dev and at the
+  // root mount with fingerprinting off, so the mapped map equals the raw one
+  // byte-for-byte there; only prod fingerprinting / a sub-path mount changes it.
+  const lazyEntries = rawLazyEntries
     ? Object.fromEntries(
-        Object.entries(rawLazyEntries).map(([tag, u]) => [tag, withBasePath(u, bp)]),
+        Object.entries(rawLazyEntries).map(([tag, u]) => [tag, fp(u)]),
       )
     : rawLazyEntries;
   const lazyBoot = lazyEntries
@@ -1102,16 +1114,20 @@ function wrapHead(opts) {
   // decided on the ORIGINAL url, so the integrity lookup still keys on the
   // unprefixed map url and a cross-origin CDN url (never prefixed) keeps its
   // crossorigin attribute.
-  const bpPreload = basePath();
+  // Content-hash (#243): the href additionally gets a `?v=<hash>` after the
+  // base-path prefix (a no-op in dev / for a cross-origin url), but
+  // `crossorigin` / `integrity` are still decided on the ORIGINAL url, so the
+  // integrity lookup keys on the unprefixed/unhashed map url and a cross-origin
+  // CDN url (never prefixed, never hashed) keeps its crossorigin attribute.
   for (const url of opts.moduleUrls) {
     linkTags.push(
-      `<link rel="modulepreload" href="${escapeAttr(withBasePath(url, bpPreload))}"` +
+      `<link rel="modulepreload" href="${escapeAttr(fp(url))}"` +
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
   for (const url of opts.preloads || []) {
     linkTags.push(
-      `<link rel="modulepreload" href="${escapeAttr(withBasePath(url, bpPreload))}"` +
+      `<link rel="modulepreload" href="${escapeAttr(fp(url))}"` +
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
@@ -1125,6 +1141,58 @@ function wrapHead(opts) {
     }
   }
 
+  // preconnect / dns-prefetch hints (issue #243). `metadata.preconnect` and
+  // `metadata.dnsPrefetch` each take a URL string, `{ url, crossorigin? }`, or
+  // an array of those. A preconnect warms DNS + TLS + TCP; dns-prefetch only
+  // resolves DNS (no crossorigin). The framework ALSO auto-emits ONE preconnect
+  // to the resolved vendor CDN origin for an unpinned cross-origin app, so the
+  // browser warms that connection before the importmap resolves. The author's
+  // declared origins are tracked so the auto one is not a duplicate.
+  /** @type {Set<string>} the origins the author already declared a preconnect to */
+  const declaredPreconnectOrigins = new Set();
+  /** @param {unknown} hint @returns {{ url: string, crossorigin?: string|boolean } | null} */
+  const normalizeHint = (hint) => {
+    if (typeof hint === 'string') return hint ? { url: hint } : null;
+    if (hint && typeof hint === 'object' && typeof (/** @type {any} */ (hint).url) === 'string') {
+      return /** @type {any} */ (hint);
+    }
+    return null;
+  };
+  /** @param {unknown} value @returns {Array<{ url: string, crossorigin?: string|boolean }>} */
+  const toHints = (value) => {
+    if (value == null) return [];
+    const list = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const h of list) {
+      const n = normalizeHint(h);
+      if (n) out.push(n);
+    }
+    return out;
+  };
+  /** @param {string|boolean|undefined} co @returns {string} */
+  const crossoriginAttr = (co) => {
+    if (co === undefined || co === false) return '';
+    if (co === true || co === '') return ' crossorigin';
+    return ` crossorigin="${escapeAttr(String(co))}"`;
+  };
+  for (const h of toHints(m.preconnect)) {
+    try { declaredPreconnectOrigins.add(new URL(h.url).origin); } catch { /* relative / opaque; track by raw href instead */ declaredPreconnectOrigins.add(h.url); }
+    linkTags.push(`<link rel="preconnect" href="${escapeAttr(h.url)}"${crossoriginAttr(h.crossorigin)}>`);
+  }
+  for (const h of toHints(m.dnsPrefetch)) {
+    // dns-prefetch never carries crossorigin (it only resolves DNS).
+    linkTags.push(`<link rel="dns-prefetch" href="${escapeAttr(h.url)}">`);
+  }
+  // Auto vendor preconnect: warm the cross-origin vendor CDN connection for an
+  // unpinned app. Deduped against an author-declared preconnect to the same
+  // origin; emits none for a same-origin pinned app or one with no cross-origin
+  // vendors (vendorPreconnectOrigins returns []). crossorigin is required (the
+  // importmap fetches the module as a CORS request).
+  for (const origin of vendorPreconnectOrigins()) {
+    if (declaredPreconnectOrigins.has(origin)) continue;
+    linkTags.push(`<link rel="preconnect" href="${escapeAttr(origin)}" crossorigin>`);
+  }
+
   // icons: { icon, apple, shortcut, other }. Each entry can be a string
   // (URL), an object { url, sizes?, type? }, or an array of those.
   //   - icon    → <link rel="icon">

package/src/testing.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Type overlay for `@webjsdev/server/testing` (the handle() test harness, #267).
+ *
+ * The runtime is packages/server/src/testing.js (JSDoc-annotated JavaScript);
+ * this overlay exists so a TypeScript app's `import { testRequest, getCsrf }
+ * from '@webjsdev/server/testing'` resolves precise types instead of emitting
+ * TS7016. The same declarations are re-exported from the package's main
+ * `index.d.ts` (the helpers ship from both entry points). Zero runtime cost.
+ */
+
+/** The `handle(req)` function returned by `createRequestHandler`. */
+export type Handle = (req: Request) => Promise<Response> | Response;
+
+/** A `createRequestHandler` return value, or a bare `handle` function. */
+export type AppOrHandle = { handle: Handle; appDir: string } | Handle;
+
+/** A CSRF token + cookie + header-name triple minted off the first SSR response. */
+export interface CsrfPair {
+  /** The bare token value for the `x-webjs-csrf` request header. */
+  token: string;
+  /** The header NAME (`x-webjs-csrf`). */
+  header: string;
+  /** The `name=value` cookie string for the `Cookie` request header. */
+  cookie: string;
+}
+
+/**
+ * Coerce a bare path, full URL string, or pre-built `Request` into a `Request`.
+ * A bare path is prefixed with a dummy origin; `init` is merged when provided.
+ */
+export declare function toRequest(input: string | Request, init?: RequestInit): Request;
+
+/**
+ * Fire a request through the real `handle()` pipeline and return the `Response`.
+ * The documented one-liner: `await testRequest(app.handle, '/about')`.
+ */
+export declare function testRequest(
+  handle: Handle,
+  input: string | Request,
+  init?: RequestInit,
+): Promise<Response>;
+
+/** Read the `webjs_csrf` cookie value off a response's `Set-Cookie` header(s). */
+export declare function readCsrfCookie(res: Response): string | null;
+
+/** Collect all `Set-Cookie` header values off a response. */
+export declare function getSetCookies(res: Response): string[];
+
+/** Reduce raw `Set-Cookie` strings to a single `name=value; name2=value2` `Cookie` header value. */
+export declare function cookiesToHeader(setCookies: string[]): string;
+
+/**
+ * Mint a `{ token, header, cookie }` CSRF triple off the first SSR response.
+ * `path` is the GET path used to issue the cookie (default `/`).
+ */
+export declare function getCsrf(handle: Handle, path?: string): Promise<CsrfPair>;
+
+/** Merge an extra cookie string into a `RequestInit`'s `Cookie` header. */
+export declare function withCookies(init: RequestInit | undefined, cookieValue: string): RequestInit;
+
+/** Merge a session cookie string into a `RequestInit`'s `Cookie` header. */
+export declare function withSessionCookie(init: RequestInit | undefined, sessionCookie: string): RequestInit;
+
+/**
+ * Drive the REAL credentials login (`POST /api/auth/signin/credentials` by
+ * default) and capture the genuine signed session `Set-Cookie`.
+ */
+export declare function loginAndGetCookies(
+  handle: Handle,
+  credentials: { email: string; password: string },
+  opts?: {
+    loginPath?: string;
+    method?: string;
+    body?: BodyInit;
+    contentType?: string;
+    expectStatuses?: number[];
+  },
+): Promise<{ cookies: string; setCookies: string[]; response: Response }>;
+
+/**
+ * Compute the `/__webjs/action/<hash>/<fn>` RPC endpoint path for an action,
+ * addressing it the same way the generated client stub does.
+ */
+export declare function actionEndpoint(
+  appDir: string,
+  serverFilePath: string,
+  fnName: string,
+): Promise<string>;
+
+/**
+ * Round-trip an action through its REAL RPC endpoint (serializer + CSRF + prod
+ * error sanitization) and return the parsed return value.
+ */
+export declare function invokeActionForTest<T = unknown>(
+  app: AppOrHandle,
+  serverFilePath: string,
+  fnName: string,
+  args?: unknown[],
+  opts?: {
+    csrf?: CsrfPair;
+    appDir?: string;
+    extraCookies?: string;
+    throwOnError?: boolean;
+  },
+): Promise<T>;
+
+/**
+ * Lower-level variant of `invokeActionForTest` that returns the raw `Response`
+ * (never throws on a non-2xx), so a test can assert the status directly.
+ */
+export declare function rawActionRequest(
+  app: AppOrHandle,
+  serverFilePath: string,
+  fnName: string,
+  args?: unknown[],
+  opts?: {
+    csrf?: CsrfPair | null;
+    omitCsrf?: boolean;
+    appDir?: string;
+    extraCookies?: string;
+    contentType?: string;
+  },
+): Promise<Response>;