@bakery-framework/core 2.4.0 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "2.4.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,7 @@ 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.
@@ -66,6 +67,7 @@ const defaultConfig: Required<AppConfig> = {
   // and says so rather than ending nothing.
   sessions: {},
   root: 'src',
+  domains: [],
   hosts: {},
   hostMounts: [],
   websocket: {
@@ -108,6 +110,7 @@ export function clearHostConfigCache(): void {
   cachedConfig = null
   hostConfigCache.clear()
   hostLookup = null
+  staticDomains = null
 }
 
 export async function initConfig(): Promise<Readonly<ProcessedAppConfig>> {
@@ -219,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
@@ -240,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
@@ -249,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)) {
@@ -261,64 +264,180 @@ function lookupHostEntry(
     }
     hostLookup = { source: hosts, entries }
   }
+  return hostLookup.entries
+}
 
-  return hostLookup.entries.get(hostname)
+/** 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)
 }
 
 /**
- * The canonical form of `hostname` if the app declares it under `hosts`, and
- * `''` otherwise, including when no `hosts` are configured at all.
+ * `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.
  *
- * 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
+ * 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
+}
+
+/** The `hosts` key `hostname` matched, lowercased, or `''` for none. */
+export function hostEntryKey(hostname: string): string {
+  return matchHost(hostname)?.key ?? ''
+}
+
+/**
+ * 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 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

@@ -72,7 +72,12 @@ export function hostPattern(host: string, where = 'host'): RegExp {
  */
 export const ROOT_ONLY = ['/_', '/api/', '/.well-known/'] as const
 
-function mountPath(value: unknown, where: string): string {
+/**
+ * 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)}`,
@@ -108,7 +113,7 @@ function compile(mount: HostMount, where: string): CompiledHostMount {
   if (!mount || typeof mount !== 'object') {
     throw new Error(`${where} must be { host, path }`)
   }
-  const path = mountPath(mount.path, `${where}.path`)
+  const path = normalizeMountPath(mount.path, `${where}.path`)
   const { host } = mount
   if (typeof host === 'function') return { path, matches: host }
   if (typeof host !== 'string') {

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,6 +174,16 @@ 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>
 
     /**
@@ -422,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

@@ -152,15 +152,18 @@ function routing(req: Request): Routing {
   const path = parsedUrl(req).pathname
   let result: Routing = { path, mount: null, varies: false }
 
-  // A partial config (a test's, an embedder's) may carry no `hostMounts`.
+  // 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
-  const mounts = config.hostMounts?.length
-    ? compileHostMounts(config.hostMounts)
-    : null
-  const mount = mounts && findHostMount(mounts, getHostname(req, 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.path), mount: mount.path, varies: true }
+      ? { path: mountedPath(path, mount), mount, varies: true }
       : { path, mount: null, varies: true }
   }
 
@@ -171,8 +174,9 @@ function routing(req: Request): Routing {
 /**
  * The path routing resolves for `req`, and the host mount it moved into.
  *
- * On a host that no entry of `hostMounts` serves, that is the request's own
- * path and no mount. On a mounted host, a page request (`isPageRequest`) for
+ * 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

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>`
   }