@bakery-framework/core 2.3.0 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
   "keywords": [
     "bakery",

package/src/core/config.ts

@@ -11,6 +11,11 @@ import {
 import { fs } from '../utils/fs'
 import { checkCacheVersion } from './cache-version'
 import { hostStore } from './context'
+import { normalizeMountPath } from './host-mounts'
+
+// Re-exported for the CLI's boot checks, which reach config through this
+// subpath; the module itself imports nothing, so it can sit under the router.
+export { checkHostMounts } from './host-mounts'
 
 export const NOOP = () => {}
 
@@ -62,7 +67,9 @@ const defaultConfig: Required<AppConfig> = {
   // and says so rather than ending nothing.
   sessions: {},
   root: 'src',
+  domains: [],
   hosts: {},
+  hostMounts: [],
   websocket: {
     message: NOOP,
     open: NOOP,
@@ -103,6 +110,7 @@ export function clearHostConfigCache(): void {
   cachedConfig = null
   hostConfigCache.clear()
   hostLookup = null
+  staticDomains = null
 }
 
 export async function initConfig(): Promise<Readonly<ProcessedAppConfig>> {
@@ -214,6 +222,9 @@ function mergeHostConfig(
   const merged: any = { ...base }
 
   if (entry.root) merged.root = fs.resolve(entry.root)
+  if (entry.mount !== undefined) {
+    merged.mount = normalizeMountPath(entry.mount, 'mount')
+  }
   if (entry.importMap)
     merged.importMap = { ...base.importMap, ...entry.importMap }
   if (entry.middleware) merged.middleware = entry.middleware
@@ -235,7 +246,7 @@ function mergeHostConfig(
 }
 
 /**
- * The configured host entry for an already-lowercased hostname, or undefined.
+ * The configured host entries by lowercased key.
  *
  * A Map built from `Object.entries` rather than a lookup on `hosts` itself:
  * own enumerable keys only, so `Host: constructor` cannot reach a prototype
@@ -244,10 +255,7 @@ function mergeHostConfig(
  *
  * If two keys differ only in case, the first one declared wins.
  */
-function lookupHostEntry(
-  hosts: Record<string, HostEntry>,
-  hostname: string,
-): HostEntry | undefined {
+function hostEntries(hosts: Record<string, HostEntry>): Map<string, HostEntry> {
   if (!hostLookup || hostLookup.source !== hosts) {
     const entries = new Map<string, HostEntry>()
     for (const [key, entry] of Object.entries(hosts)) {
@@ -256,64 +264,180 @@ function lookupHostEntry(
     }
     hostLookup = { source: hosts, entries }
   }
+  return hostLookup.entries
+}
+
+/** One label of a domain. */
+const DOMAIN_LABEL = /^[a-z0-9_-]+$/
+
+/** An IPv4 address, or what `getHostname` leaves of a bracketed IPv6 one. */
+function isIpLiteral(name: string): boolean {
+  return name.startsWith('[') || /^\d{1,3}(?:\.\d{1,3}){3}$/.test(name)
+}
+
+/**
+ * `value` as a domain, lowercased and without a trailing dot, or null when it
+ * is not one. An IP address is not: it has no subdomains to name.
+ */
+function domainName(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  const domain = value.trim().toLowerCase().replace(/\.$/, '')
+  if (!domain || isIpLiteral(domain)) return null
+  return domain.split('.').every(label => DOMAIN_LABEL.test(label))
+    ? domain
+    : null
+}
+
+/** A static `domains` value, normalized once per value. */
+let staticDomains: { source: unknown; list: readonly string[] } | null = null
+
+/**
+ * The domains `'@'`, `'*'` and bare-label keys are read against: `localhost`
+ * and whatever `domains` says, longest first, so a nested one (`bpc.edu.ph`
+ * beside `edu.ph`) is tried before the one it sits in. A function is asked
+ * each time. An answer that is not a domain is left out, which `checkHosts`
+ * refuses at boot for a static one and cannot for a function's.
+ */
+function appDomains(config: Readonly<ProcessedAppConfig>): readonly string[] {
+  const { domains } = config
+  const fixed = typeof domains !== 'function'
+  if (fixed && staticDomains?.source === domains) return staticDomains.list
+
+  const value = fixed ? domains : domains()
+  const given = Array.isArray(value) ? value : value ? [value] : []
+  const named = given.map(domainName).filter(d => d !== null)
+  const list = [...new Set(['localhost', ...named])].sort(
+    (a, b) => b.length - a.length,
+  )
+  if (fixed) staticDomains = { source: domains, list }
+  return list
+}
+
+/** What a hostname matched under `hosts`. */
+type HostMatch = {
+  /** The key that matched, lowercased: what per-entry tables are keyed by. */
+  key: string
+  /**
+   * The tenant: what `hostKey()` prefixes (sessions, file caches) and what a
+   * resolved config is cached by. The hostname itself for an exact key, a
+   * bare label or `'@'`, which a finite set of keys and domains bounds. For
+   * `'*'` it is `*.` and the domain, so made-up subdomains share one tenant
+   * instead of each minting a cache bucket and a session namespace.
+   */
+  tenant: string
+  entry: HostEntry
+}
+
+/**
+ * The `hosts` entry `hostname` is served by, or null for the base config.
+ *
+ * An exact key first, so every name configured before the other forms
+ * existed still matches as it did. Then, under the longest domain the
+ * hostname sits in: the domain itself is `'@'`, one label in front of it is
+ * that label's key (`admin` for `admin.bpc.edu.ph`), and anything else in
+ * front of it is `'*'`. A bare label names one subdomain, not its children:
+ * `admin.x.bpc.edu.ph` is `'*'`'s. A hostname under none of the domains, an
+ * IP address included, matches only an exact key.
+ */
+function matchHost(hostname: string): HostMatch | null {
+  if (!hostname || !cachedConfig) return null
+  const config = getConfig()
+  const entries = hostEntries(config.hosts ?? {})
+  if (!entries.size) return null
+  const name = hostname.toLowerCase().replace(/\.$/, '')
+
+  const exact = entries.get(name)
+  if (exact) return { key: name, tenant: name, entry: exact }
+  if (isIpLiteral(name)) return null
+
+  for (const domain of appDomains(config)) {
+    if (name === domain) {
+      const apex = entries.get('@')
+      return apex ? { key: '@', tenant: domain, entry: apex } : null
+    }
+    if (!name.endsWith(`.${domain}`)) continue
+
+    const sub = name.slice(0, -domain.length - 1)
+    if (!sub.includes('.') && sub !== '@' && sub !== '*') {
+      const named = entries.get(sub)
+      if (named) return { key: sub, tenant: name, entry: named }
+    }
+    const rest = entries.get('*')
+    return rest ? { key: '*', tenant: `*.${domain}`, entry: rest } : null
+  }
+  return null
+}
 
-  return hostLookup.entries.get(hostname)
+/** The `hosts` key `hostname` matched, lowercased, or `''` for none. */
+export function hostEntryKey(hostname: string): string {
+  return matchHost(hostname)?.key ?? ''
 }
 
 /**
- * The canonical form of `hostname` if the app declares it under `hosts`, and
- * `''` otherwise, including when no `hosts` are configured at all.
+ * Check `domains` and every `hosts` entry's `mount` before anything binds, so
+ * a value that cannot mean anything stops the boot and names itself. A
+ * `domains` function is asked on each request instead, so its answers cannot
+ * be checked here.
+ */
+export function checkHosts(config: Readonly<ProcessedAppConfig>): void {
+  const { domains } = config
+  if (typeof domains !== 'function') {
+    const listed = Array.isArray(domains)
+    const values = listed ? domains : domains ? [domains] : []
+    values.forEach((value, i) => {
+      if (domainName(value) === null) {
+        throw new Error(
+          `domains${listed ? `[${i}]` : ''} ${JSON.stringify(value)} is not a domain: labels of letters, digits, '-' and '_' joined by dots, and not an IP address`,
+        )
+      }
+    })
+  }
+  for (const [key, entry] of Object.entries(config.hosts ?? {})) {
+    if (entry?.mount !== undefined) {
+      normalizeMountPath(entry.mount, `hosts['${key}'].mount`)
+    }
+  }
+}
+
+/**
+ * The tenant `hostname` belongs to (see `HostMatch.tenant`), and `''` when it
+ * matches no `hosts` entry, including when no `hosts` are configured at all.
  *
- * Same reasoning as `resolveHostConfig` below, which already refuses to cache
- * an unknown hostname: the value arrives on the `Host` header, so anything
- * derived from it that is *kept* (a config entry, a cache key, a file on disk
- *) has to be bounded by the configured set, or an unauthenticated client can
+ * Same reasoning as `resolveHostConfig` below, which refuses to cache an
+ * unknown hostname: the value arrives on the `Host` header, so anything
+ * derived from it that is *kept* (a config entry, a cache key, a file on disk)
+ * has to be bounded by the configured set, or an unauthenticated client can
  * grow it without limit. Collapsing unknown hosts to `''` puts them all in one
  * bucket, which is correct because they all get the base config and therefore
- * the same content.
+ * the same content; `'*'` collapses its subdomains to one tenant per domain
+ * for the same reason.
  *
- * Folded with `toLowerCase` for the reason spelled out below: hostnames are
- * case-insensitive, so `EXAMPLE.com` and `example.com` must be one key, not two.
+ * Folded with `toLowerCase`: hostnames are case-insensitive (RFC 4343), so
+ * `EXAMPLE.com` and `example.com` must be one key, not two. `toLowerCase`,
+ * not `toLocaleLowerCase`, which maps `I` to a dotless `ı` in a Turkish
+ * locale.
  */
 export function resolveHostname(hostname: string): string {
   // No config yet (a unit test that never called `initConfig`) means no `hosts`
   // to match against, which is the same answer as an unconfigured host.
-  if (!hostname || !cachedConfig) return ''
-  const hosts = getConfig().hosts
-  if (!hosts) return ''
-  const key = hostname.toLowerCase()
-  return lookupHostEntry(hosts, key) ? key : ''
+  return matchHost(hostname)?.tenant ?? ''
 }
 
 export function resolveHostConfig(
   hostname: string,
 ): Readonly<ProcessedAppConfig> {
   const base = getConfig()
-  const hosts = base.hosts
-  if (!hosts || !Object.keys(hosts).length) return base
-
-  // Hostnames are case-insensitive (RFC 4343) and nothing upstream normalizes
-  // the Host header, so a request to `EXAMPLE.com` used to miss an
-  // `example.com` entry and silently fall back to the base config. Both sides
-  // fold to lower case: `toLowerCase`, not `toLocaleLowerCase`, which would
-  // map `I` to a dotless `ı` in a Turkish locale.
-  const key = hostname.toLowerCase()
-
-  const cached = hostConfigCache.get(key)
+  const match = matchHost(hostname)
+  // An unknown hostname is deliberately not cached: it comes straight from
+  // the Host header, so caching misses let any client grow this map one
+  // made-up name at a time. A match is cached by its tenant, which the
+  // configured keys and domains bound.
+  if (!match) return base
+
+  const cached = hostConfigCache.get(match.tenant)
   if (cached) return cached
 
-  const entry = lookupHostEntry(hosts, key)
-  if (!entry) {
-    // Deliberately NOT cached. The hostname comes straight from the Host
-    // header, so caching unknown values let any client grow this map without
-    // bound: one request per made-up hostname until the process runs out of
-    // memory. Known hosts are a fixed, small set, so only those are cached.
-    // Normalizing above keeps that bound honest: without it, `EXAMPLE.com` and
-    // `example.com` would occupy two entries for one configured host.
-    return base
-  }
-
-  const merged = mergeHostConfig(base as ProcessedAppConfig, entry)
-  hostConfigCache.set(key, merged)
+  const merged = mergeHostConfig(base as ProcessedAppConfig, match.entry)
+  hostConfigCache.set(match.tenant, merged)
   return merged
 }

package/src/core/host-mounts.ts

@@ -0,0 +1,179 @@
+/**
+ * Host mounts: a host that serves one path subtree of the app at its root.
+ *
+ * `hostMounts: [{ host: 'kit.*', path: '/kit' }]` makes `kit.example.com/forms`
+ * the page `/kit/forms` is on every other host. The subtree stays part of the
+ * app: its pages load the app's modules, stylesheets and API from the root,
+ * the way they do on any host, so only page requests move into it. Which
+ * requests those are is `routeOf` in `router.ts`.
+ *
+ * Patterns rather than `hosts` keys, because a mount's hostname is often not
+ * known at boot: an app whose domain is a setting can still name "the `kit`
+ * label of whatever domain this is". A mount is also not a tenant. It changes
+ * which page a path names and nothing else, so sessions, caches and the
+ * `hosts` entries do not see it.
+ */
+
+export type HostMount = {
+  /**
+   * The hostnames the mount serves: a name (`kit.example.com`), a pattern in
+   * which `*` stands for one or more whole labels (`kit.*`,
+   * `*.docs.example.com`), or a function of the hostname, which it receives
+   * lowercased and without the port.
+   */
+  host: string | ((hostname: string) => boolean)
+  /** The subtree served at the host's root, such as `/kit`. */
+  path: string
+}
+
+export type CompiledHostMount = {
+  /** The subtree: a leading slash and no trailing one. */
+  readonly path: string
+  /** Whether a lowercased hostname without its port is served by the mount. */
+  matches(hostname: string): boolean
+}
+
+/** One label of a hostname pattern, `*` aside. */
+const LABEL = /^[a-z0-9_-]+$/
+
+/** `*` as a pattern label: one or more whole labels. */
+const ANY_LABELS = '[^.]+(?:\\.[^.]+)*'
+
+/**
+ * A hostname pattern as a regular expression. Throws naming `where` when
+ * `host` is not a name, or puts `*` inside a label: `k*t.example.com` would
+ * have to choose between matching part of a label and matching labels, and
+ * either reading surprises someone.
+ */
+export function hostPattern(host: string, where = 'host'): RegExp {
+  const labels = host.toLowerCase().split('.')
+  if (labels.some(label => label === '')) {
+    throw new Error(
+      `${where} '${host}' is not a hostname: a name has no empty label`,
+    )
+  }
+  const parts = labels.map(label => {
+    if (label === '*') return ANY_LABELS
+    if (!LABEL.test(label)) {
+      throw new Error(
+        `${where} '${host}' has the label '${label}': a label is letters, digits, '-' and '_', and '*' stands for whole labels only`,
+      )
+    }
+    return label
+  })
+  return new RegExp(`^${parts.join('\\.')}$`)
+}
+
+/**
+ * What every host serves from the app's root, a mounted one included: the
+ * framework's and the plugins' routes, the API, and the site-wide metadata
+ * RFC 8615 reserves. The router keeps requests under these out of a mount,
+ * and no mount may name a path under one.
+ */
+export const ROOT_ONLY = ['/_', '/api/', '/.well-known/'] as const
+
+/**
+ * A mount's path checked and normalized: a leading slash, no trailing one.
+ * Throws naming `where` for a path that cannot mean anything. Shared by
+ * `hostMounts` and a `hosts` entry's `mount`.
+ */
+export function normalizeMountPath(value: unknown, where: string): string {
+  if (typeof value !== 'string' || !value.startsWith('/')) {
+    throw new Error(
+      `${where} must be a path starting with '/': got ${JSON.stringify(value)}`,
+    )
+  }
+  const path = value.replace(/\/+$/, '')
+  if (path === '') {
+    throw new Error(
+      `${where} '${value}' is the whole app, which every host already serves`,
+    )
+  }
+  const segments = path.slice(1).split('/')
+  if (segments.some(s => s === '' || s === '.' || s === '..')) {
+    throw new Error(
+      `${where} '${value}' has an empty, '.' or '..' segment: a mount names one directory`,
+    )
+  }
+  if (/[?#*\\]/.test(path)) {
+    throw new Error(
+      `${where} '${value}' is a path, so it holds no '?', '#', '*' or '\\'`,
+    )
+  }
+  const reserved = ROOT_ONLY.find(prefix => `${path}/`.startsWith(prefix))
+  if (reserved) {
+    throw new Error(
+      `${where} '${value}' is under ${reserved}, which every host serves as it is`,
+    )
+  }
+  return path
+}
+
+function compile(mount: HostMount, where: string): CompiledHostMount {
+  if (!mount || typeof mount !== 'object') {
+    throw new Error(`${where} must be { host, path }`)
+  }
+  const path = normalizeMountPath(mount.path, `${where}.path`)
+  const { host } = mount
+  if (typeof host === 'function') return { path, matches: host }
+  if (typeof host !== 'string') {
+    throw new Error(
+      `${where}.host must be a hostname, a pattern such as 'kit.*', or a function of the hostname`,
+    )
+  }
+  const pattern = hostPattern(host, `${where}.host`)
+  return { path, matches: hostname => pattern.test(hostname) }
+}
+
+/**
+ * Compiled once per array: the processed config is frozen for the life of
+ * the process, and a test that swaps it in brings a new array, so identity is
+ * the whole validity check.
+ */
+const compiled = new WeakMap<
+  readonly HostMount[],
+  readonly CompiledHostMount[]
+>()
+
+/** `hostMounts` compiled, throwing at the first entry that cannot mean anything. */
+export function compileHostMounts(
+  mounts: readonly HostMount[],
+): readonly CompiledHostMount[] {
+  const cached = compiled.get(mounts)
+  if (cached) return cached
+  if (!Array.isArray(mounts)) {
+    throw new Error('hostMounts must be an array of { host, path }')
+  }
+  const result = mounts.map((mount, i) => compile(mount, `hostMounts[${i}]`))
+  compiled.set(mounts, result)
+  return result
+}
+
+/**
+ * Compile the app's `hostMounts` before anything binds, so an entry that
+ * cannot mean anything stops the boot and names itself, rather than throwing
+ * on the first request that reaches it.
+ */
+export function checkHostMounts(config: {
+  hostMounts: readonly HostMount[]
+}): void {
+  compileHostMounts(config.hostMounts)
+}
+
+/** The first mount serving `hostname`, or null. */
+export function findHostMount(
+  mounts: readonly CompiledHostMount[],
+  hostname: string,
+): CompiledHostMount | null {
+  if (!mounts.length) return null
+  const host = hostname.toLowerCase()
+  for (const mount of mounts) {
+    if (mount.matches(host)) return mount
+  }
+  return null
+}
+
+/** `path` on a mounted host, as the app names it: `/` is the mount itself. */
+export function mountedPath(path: string, mount: string): string {
+  return path === '/' ? mount : `${mount}${path}`
+}

package/src/global.d.ts

@@ -55,6 +55,13 @@ declare global {
 
   type HostEntry = {
     root?: string
+    /**
+     * A subtree of the app this host serves at its root: with
+     * `mount: '/kit'`, `/forms` on this host is the page `/kit/forms`. Only
+     * page requests move into it; what those pages load comes from the
+     * app's root. See `routeOf` in `router.ts`.
+     */
+    mount?: string
     importMap?: Record<string, string>
     middleware?: ((
       req: Request,
@@ -167,7 +174,28 @@ declare global {
      */
     sessions?: import('./session').SessionOptions
 
+    /**
+     * The app's domains, which three kinds of `hosts` key are read against:
+     * `'@'` is a domain itself, a bare label such as `'admin'` is
+     * `admin.<domain>`, and `'*'` is any other subdomain. `localhost` always
+     * counts, so the same keys work on `admin.localhost`. A function is asked
+     * on each request, for an app whose domain is a setting that can change
+     * while it runs, and has to answer without awaiting.
+     */
+    domains?: string | string[] | (() => string | string[])
+
     hosts?: Record<string, HostEntry>
+
+    /**
+     * Hosts that serve one path subtree of the app at their root:
+     * `{ host: 'kit.*', path: '/kit' }` makes `kit.example.com/forms` the
+     * page `/kit/forms`. Only page requests move into the subtree (a
+     * navigation, or a method other than GET and HEAD); the modules,
+     * stylesheets, files and API those pages load come from the app's root,
+     * as on any host. The first entry whose `host` matches wins. See
+     * `core/host-mounts.ts` and `routeOf` in `router.ts`.
+     */
+    hostMounts?: import('./core/host-mounts').HostMount[]
   }
 
   type ServerPlugin = _plugins.ServerPlugin
@@ -411,7 +439,13 @@ declare global {
     {
       blocked: Bun.Glob
     }
-  >
+  > & {
+    /**
+     * The subtree this host serves at its root, from its `hosts` entry's
+     * `mount`, normalized. Absent on the base config and on a host without one.
+     */
+    mount?: string
+  }
 
   type ServerWebSocket<T = MapOf<any>> = Override<
     Bun.ServerWebSocket,

package/src/router.ts

@@ -1,9 +1,16 @@
-import { Bakery, hostStore } from './core/bakery'
+import { Bakery, getHostname, hostStore } from './core/bakery'
 import { matchBlockedCached } from './core/context'
+import {
+  compileHostMounts,
+  findHostMount,
+  mountedPath,
+  ROOT_ONLY,
+} from './core/host-mounts'
 import { PluginHooks } from './core/plugins'
 import { DefaultErrorHandler } from './handlers/assets/static'
 import type { Handler } from './handlers/core/$base'
 import { ErrorHandler } from './handlers/core/$error'
+import { resolveMount } from './handlers/core/$mounts'
 import { WebSocketHandler } from './handlers/core/$websocket'
 import { errorMsg, getElapsed, log, serveLog } from './logger'
 import { Session } from './session'
@@ -82,14 +89,108 @@ function servesFiles(handler: any): boolean {
   return handler?.servesFiles !== false
 }
 
+/**
+ * How routing reads one request: the path it resolves, the host mount it
+ * moved into, and whether this URL's answer depends on the kind of request,
+ * which is what `processResponse` sends a `Vary` for.
+ */
+type Routing = { path: string; mount: string | null; varies: boolean }
+
+export type RequestRoute = Readonly<Pick<Routing, 'path' | 'mount'>>
+
+/** Weak, as `parsedUrl`'s memo is: an entry lives as long as its request. */
+const routings = new WeakMap<Request, Routing>()
+
+/**
+ * Whether `path` could be a page of a mounted subtree: nothing in `ROOT_ONLY`,
+ * no file named, and no plugin's route mount or proxy entry claiming it.
+ *
+ * "No file named" is a last segment with no extension. A page links its
+ * stylesheets, images and downloads by their root paths, and a navigation to
+ * one of them (a PDF opened in a tab) has to reach the file.
+ */
+function pagePathOnMount(
+  path: string,
+  config: Readonly<ProcessedAppConfig>,
+): boolean {
+  if (ROOT_ONLY.some(prefix => path.startsWith(prefix))) return false
+  if (path.slice(path.lastIndexOf('/') + 1).includes('.')) return false
+  if (resolveMount(path)) return false
+  for (const prefix in config.proxy) {
+    if (path.startsWith(prefix)) return false
+  }
+  return true
+}
+
+/**
+ * Whether `req` asks for a page rather than for something a page loads.
+ *
+ * A navigation (a tab or a frame loading the URL) is one, and so is any
+ * method but GET and HEAD: a form post, or a server action, which a Vue page
+ * posts to its own URL. A module import, a stylesheet, an image and a `fetch`
+ * are not, and that is the line that has to hold: an import of a TypeScript
+ * module is written `/kit/useDemo`, with no extension to tell it from a page,
+ * and moved into the subtree it would reach a catch-all page instead.
+ *
+ * A browser says which it is in `Sec-Fetch-Mode`. A client that sends no
+ * Fetch Metadata is navigating when it asks for HTML.
+ */
+function isPageRequest(req: Request): boolean {
+  if (req.method !== 'GET' && req.method !== 'HEAD') return true
+  if (req.headers.has('upgrade')) return false
+  const mode = req.headers.get('sec-fetch-mode')
+  if (mode) return mode === 'navigate'
+  return (req.headers.get('accept') ?? '').includes('text/html')
+}
+
+function routing(req: Request): Routing {
+  const cached = routings.get(req)
+  if (cached) return cached
+
+  // Shared with worker.ts, which has already asked for the same parse; a
+  // direct caller (test, embedder) gets it parsed here instead.
+  const path = parsedUrl(req).pathname
+  let result: Routing = { path, mount: null, varies: false }
+
+  // The host's `hosts` entry decides first (its `mount`, already resolved into
+  // the ambient config), then the first `hostMounts` pattern that matches. A
+  // partial config (a test's, an embedder's) may carry neither.
+  const config = Bakery.config
+  let mount = config.mount ?? null
+  if (!mount && config.hostMounts?.length) {
+    const patterns = compileHostMounts(config.hostMounts)
+    mount = findHostMount(patterns, getHostname(req, config))?.path ?? null
+  }
+  if (mount && pagePathOnMount(path, config)) {
+    result = isPageRequest(req)
+      ? { path: mountedPath(path, mount), mount, varies: true }
+      : { path, mount: null, varies: true }
+  }
+
+  routings.set(req, result)
+  return result
+}
+
+/**
+ * The path routing resolves for `req`, and the host mount it moved into.
+ *
+ * On a host with no `mount` (from its `hosts` entry, or a `hostMounts`
+ * pattern), that is the request's own path and no mount. On a mounted host, a
+ * page request (`isPageRequest`) for
+ * a path that can be a page (`pagePathOnMount`) resolves under the mount:
+ * `/forms` is `/kit/forms`, and `/` is `/kit`. Every other request keeps its
+ * path, so the modules, stylesheets and API a subtree's pages load still come
+ * from the app's root. Memoized per request.
+ */
+export function routeOf(req: Request): RequestRoute {
+  return routing(req)
+}
+
 export function handleRequest(
   req: Request,
 ): Handler.Response | MixedPromise<symbol>
 export async function handleRequest(req: Request) {
-  // Shared with worker.ts, which has already asked for the same parse; a
-  // direct caller (test, embedder) gets it parsed here instead.
-  const url = parsedUrl(req)
-  const path = url.pathname
+  const path = routing(req).path
 
   // One read of the config getter, not three: `Bakery.serveRoot` walks
   // `hostStore.getStore()?.config ?? getConfig()` on every access, and the
@@ -312,6 +413,21 @@ export async function handleRequestError(
   return DefaultErrorHandler.handle(path, req, error)
 }
 
+/** Add `tokens` to `res`'s `Vary`, keeping what it names and naming each once. */
+function addVary(res: Response, tokens: readonly string[]): void {
+  const existing = res.headers.get('Vary')
+  const named = new Set(
+    (existing ?? '')
+      .split(',')
+      .map(token => token.trim().toLowerCase())
+      .filter(Boolean),
+  )
+  if (named.has('*')) return
+  const missing = tokens.filter(token => !named.has(token.toLowerCase()))
+  if (!missing.length) return
+  res.headers.set('Vary', [existing, ...missing].filter(Boolean).join(', '))
+}
+
 export async function processResponse(
   data: Handler.Response | MixedPromise<symbol>,
   req: Request,
@@ -373,6 +489,11 @@ export async function processResponse(
   const cors = Bakery.config.cors
   if (cors) applyCors(cors, req, resp)
 
+  // On a mounted host one URL can answer a navigation from the subtree and a
+  // module import from the root (see `routeOf`), so a cache keyed on the URL
+  // alone could hand either one to the other.
+  if (routing(req).varies) addVary(resp, ['Sec-Fetch-Mode', 'Accept'])
+
   const final = ETag.sendResponse(req, resp)
   if (!(final instanceof Response)) {
     log({

package/src/utils/http/dom.ts

@@ -1,6 +1,7 @@
 import { readdir } from 'node:fs/promises'
 import { LRUCache } from '../../cache/lru'
 import { Bakery, hostStore } from '../../core/bakery'
+import { hostEntryKey } from '../../core/config'
 import type { MapOf } from '../../types'
 import { is } from '../common/misc'
 import { Try } from '../common/try'
@@ -64,7 +65,10 @@ export function initHostImportMaps() {
       imports[key] = value
     }
 
-    hostDepMaps.set(hostname, JSON.stringify({ imports }))
+    // By the key as matching folds it, and read back through `hostEntryKey`:
+    // a request's hostname is not the key under `'@'`, `'*'` or a bare
+    // label, and was not even for a name, whose case went unfolded.
+    hostDepMaps.set(hostname.toLowerCase(), JSON.stringify({ imports }))
   }
 }
 
@@ -154,7 +158,8 @@ export async function initImportMap() {
 export namespace DOMTools {
   export function importMap() {
     const hostname = hostStore.getStore()?.hostname
-    const map = (hostname && hostDepMaps.get(hostname)) || depMap
+    const key = hostname && hostDepMaps.size ? hostEntryKey(hostname) : ''
+    const map = (key && hostDepMaps.get(key)) || depMap
     return `<script type="importmap">${map}</script>`
   }