@bakery-framework/core 2.3.0 → 2.4.0

package/package.json

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

package/src/core/config.ts

@@ -12,6 +12,10 @@ import { fs } from '../utils/fs'
 import { checkCacheVersion } from './cache-version'
 import { hostStore } from './context'
 
+// 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 = () => {}
 
 const defaultConfig: Required<AppConfig> = {
@@ -63,6 +67,7 @@ const defaultConfig: Required<AppConfig> = {
   sessions: {},
   root: 'src',
   hosts: {},
+  hostMounts: [],
   websocket: {
     message: NOOP,
     open: NOOP,

package/src/core/host-mounts.ts

@@ -0,0 +1,174 @@
+/**
+ * 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
+
+function mountPath(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 = mountPath(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

@@ -168,6 +168,17 @@ declare global {
     sessions?: import('./session').SessionOptions
 
     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

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,104 @@ 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 }
+
+  // A partial config (a test's, an embedder's) may carry no `hostMounts`.
+  const config = Bakery.config
+  const mounts = config.hostMounts?.length
+    ? compileHostMounts(config.hostMounts)
+    : null
+  const mount = mounts && findHostMount(mounts, getHostname(req, config))
+  if (mount && pagePathOnMount(path, config)) {
+    result = isPageRequest(req)
+      ? { path: mountedPath(path, mount.path), mount: mount.path, 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 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
+ * 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 +409,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 +485,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({