@abide/abide 0.28.0

package/src/lib/server/runtime/containsTraversal.ts

@@ -0,0 +1,37 @@
+/*
+Inspects the raw request URL (not the parsed pathname) for path-traversal
+patterns. The WHATWG URL parser decodes `%2E%2E` to `..` and then collapses
+dot-segments out of the pathname during normalization, so by the time
+`url.pathname` is observable any encoded traversal has been masked. The
+remaining literal `..` check guards against any future URL-parser quirk
+that lets a normalised path through.
+
+Hot path early-out: if none of the suspect substrings appear in the raw
+URL we never lowercase the whole string nor walk segments.
+*/
+export function containsTraversal(rawUrl: string): boolean {
+    if (rawUrl.includes('\\')) {
+        return true
+    }
+    if (rawUrl.includes('..') && segmentContainsDotDot(rawUrl)) {
+        return true
+    }
+    if (rawUrl.indexOf('%') === -1) {
+        return false
+    }
+    const lower = rawUrl.toLowerCase()
+    return lower.includes('%2e%2e') || lower.includes('%2f') || lower.includes('%5c')
+}
+
+function segmentContainsDotDot(rawUrl: string): boolean {
+    const queryStart = rawUrl.indexOf('?')
+    const pathEnd = queryStart === -1 ? rawUrl.length : queryStart
+    const pathStart = rawUrl.indexOf('/', rawUrl.indexOf('://') + 3)
+    if (pathStart === -1 || pathStart >= pathEnd) {
+        return false
+    }
+    return rawUrl
+        .slice(pathStart, pathEnd)
+        .split('/')
+        .some((segment) => segment === '..')
+}

package/src/lib/server/runtime/createAppAssetServer.ts

@@ -0,0 +1,76 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
+import { acceptsGzip } from './acceptsGzip.ts'
+import { cacheControlForAsset } from './cacheControlForAsset.ts'
+import { containsTraversal } from './containsTraversal.ts'
+import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
+import { globToPathSet } from './globToPathSet.ts'
+import { respondWithEmbeddedAsset } from './respondWithEmbeddedAsset.ts'
+import type { Assets } from './types/Assets.ts'
+
+/*
+Serves the build's `_app` assets (hashed chunks, css, sourcemaps). Two
+sources, picked at construction — the sibling of createPublicAssetServer for
+the framework-owned tree:
+
+  - `assets` (standalone compile): a map of request path → gzip bytes
+    embedded into the binary.
+  - `distDir` on disk (dev + `abide start`): files served straight from
+    `dist`, with the precompressed `.gz` sibling set snapshotted once at
+    boot so a gzip-capable client gets those bytes without on-the-fly
+    compression.
+
+Unlike the public server this answers every `/_app/` request itself (404 on
+a miss — nothing falls through past the build tree). The path-traversal
+guard inspects the raw request URL because the WHATWG parser normalizes
+encoded `..` segments away before `url.pathname` is visible.
+*/
+export async function createAppAssetServer({
+    distDir,
+    assets,
+}: {
+    distDir: string
+    assets?: Assets
+}): Promise<(req: Request, url: URL) => Promise<Response>> {
+    // Per-pathname asset header bundles, hashed-chunk-aware Cache-Control.
+    const headersForAsset = createAssetHeaderCache(cacheControlForAsset)
+    const diskGzipPaths = assets
+        ? new Set<string>()
+        : await globToPathSet(
+              `${distDir}/_app`,
+              '**/*.gz',
+              (file) => `/_app/${file.replace(/\.gz$/, '')}`,
+          )
+
+    return async function serveAppAsset(req, url) {
+        if (containsTraversal(req.url)) {
+            return new Response('Not Found', {
+                status: 404,
+                headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
+            })
+        }
+        if (assets) {
+            const compressed = assets[url.pathname]
+            /* Miss-check before header work: the header cache keys on
+               (request-controlled) pathnames, so building bundles for junk
+               `/_app/*` probes would grow it without bound. */
+            if (!compressed) {
+                return new Response('Not Found', {
+                    status: 404,
+                    headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
+                })
+            }
+            return respondWithEmbeddedAsset(
+                compressed,
+                acceptsGzip(req),
+                headersForAsset(url.pathname),
+            )
+        }
+        const { base: baseHeaders, gzip: gzipHeaders } = headersForAsset(url.pathname)
+        const diskPath = distDir + url.pathname
+        if (acceptsGzip(req) && diskGzipPaths.has(url.pathname)) {
+            return new Response(Bun.file(`${diskPath}.gz`), { headers: gzipHeaders })
+        }
+        return new Response(Bun.file(diskPath), { headers: baseHeaders })
+    }
+}

package/src/lib/server/runtime/createAssetHeaderCache.ts

@@ -0,0 +1,31 @@
+import { mimeForExtension } from './mimeForExtension.ts'
+
+/*
+A static-asset response's headers depend only on its pathname (extension →
+Content-Type, path → Cache-Control), so each distinct pathname's header bundle
+is built once and reused across every hit on that chunk — avoiding a per-request
+allocation on a cold page load that pulls dozens of files. Each bundle carries
+the plain `base` headers plus a `gzip` variant with `Content-Encoding: gzip`.
+`cacheControlFor` lets callers vary the policy: hashed-aware for `/_app/`,
+fixed for public/.
+*/
+type AssetHeaderBundle = {
+    base: HeadersInit
+    gzip: HeadersInit
+}
+
+export function createAssetHeaderCache(
+    cacheControlFor: (pathname: string) => string,
+): (pathname: string) => AssetHeaderBundle {
+    const cache = new Map<string, AssetHeaderBundle>()
+    return function headersFor(pathname) {
+        return cache.getOrInsertComputed(pathname, () => {
+            const base: HeadersInit = {
+                'Content-Type': mimeForExtension(pathname),
+                Vary: 'Accept-Encoding',
+                'Cache-Control': cacheControlFor(pathname),
+            }
+            return { base, gzip: { ...base, 'Content-Encoding': 'gzip' } }
+        })
+    }
+}

package/src/lib/server/runtime/createPublicAssetServer.ts

@@ -0,0 +1,67 @@
+import { PUBLIC_ASSET_CACHE_CONTROL } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { acceptsGzip } from './acceptsGzip.ts'
+import { containsTraversal } from './containsTraversal.ts'
+import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
+import { globToPathSet } from './globToPathSet.ts'
+import { respondWithEmbeddedAsset } from './respondWithEmbeddedAsset.ts'
+import type { Assets } from './types/Assets.ts'
+
+/*
+Serves files from the project's `public/` folder at the site root. Two
+sources, picked at construction:
+
+  - `publicAssets` (standalone compile): a map of root path → gzip bytes
+    embedded into the binary, mirroring the `_app` asset embed.
+  - `publicDir` on disk (dev + `abide start`): files read straight from
+    `${cwd}/src/ui/public`, with the set of paths snapshotted once at
+    boot (see below).
+
+Returns a server fn that resolves to `undefined` when no public file
+matches the request path, so the caller falls through to its own 404 /
+middleware path. The path-traversal guard mirrors serveStaticAsset's
+defence against encoded `..` segments in the raw URL.
+
+Async because disk mode globs `publicDir` once at construction to build a
+Set of the available paths: every page nav and RPC falls through here, so
+a Set lookup beats a filesystem stat per miss. A file added to public/
+after boot needs a server restart to be seen — the same restart a code
+change already triggers under `bun --watch`.
+*/
+export async function createPublicAssetServer({
+    publicDir,
+    publicAssets,
+}: {
+    publicDir: string
+    publicAssets?: Assets
+}): Promise<(req: Request, url: URL) => Promise<Response | undefined>> {
+    const headersFor = createAssetHeaderCache(() => PUBLIC_ASSET_CACHE_CONTROL)
+    // `dot: true` keeps dotfiles (e.g. `.well-known/…`) servable, matching a raw disk stat.
+    const diskPaths = publicAssets
+        ? new Set<string>()
+        : await globToPathSet(publicDir, '**/*', (file) => `/${file}`, { dot: true })
+
+    /*
+    Existence is checked before any header work: every page nav and RPC
+    falls through here on its way to the 404/middleware path, and the
+    header cache keys on (request-controlled) pathnames — building bundles
+    for misses would grow it without bound.
+    */
+    return async function servePublicAsset(req, url) {
+        if (containsTraversal(req.url)) {
+            return undefined
+        }
+        if (publicAssets) {
+            const compressed = publicAssets[url.pathname]
+            if (!compressed) {
+                return undefined
+            }
+            return respondWithEmbeddedAsset(compressed, acceptsGzip(req), headersFor(url.pathname))
+        }
+        if (!diskPaths.has(url.pathname)) {
+            return undefined
+        }
+        return new Response(Bun.file(publicDir + url.pathname), {
+            headers: headersFor(url.pathname).base,
+        })
+    }
+}

package/src/lib/server/runtime/createReachable.ts

@@ -0,0 +1,109 @@
+import { createLivenessWatch } from '../../shared/createLivenessWatch.ts'
+
+/*
+The reachability registry behind `abide/server/reachable`. A probe transport
+and the timings are injected so the public name wires them from env + a real
+HEAD while tests drive scripted outcomes on tiny intervals.
+
+Per origin, the first read awaits one real probe (the FAITHFUL first answer —
+its latency, including a full timeout when the host is down, is the price of
+not guessing) and then hands the origin to a createLivenessWatch that re-probes
+every `intervalMs` to keep the value warm. Every later read resolves instantly
+off that warm value, fresh within one interval — the faithful cost is paid once.
+
+The inaugural probe runs DIRECTLY, not through the watch: the watch's
+failureLimit (anti-flap) is right for the ongoing poll but would make a down
+host take failureLimit× the timeout to answer on the first call. The watch's
+injected probe doubles as the idle reaper — a host nobody has read in `idleMs`
+stops polling (stop() during the probe changes the watched url, so the watch
+discards the result and never reschedules); the next read restarts it cold.
+*/
+export function createReachable(options: {
+    probe: (origin: string) => Promise<boolean>
+    intervalMs: number
+    idleMs: number
+}): {
+    reachable: (host: string | URL) => Promise<boolean>
+    /* Stop every origin's poll — graceful shutdown, and test isolation. */
+    stop: () => void
+    /* `using registry = createReachable(...)` — disposal stops every poll. */
+    [Symbol.dispose]: () => void
+} {
+    type Entry = {
+        alive: boolean
+        /* The inaugural probe while it is still in flight; concurrent cold reads await the same one. */
+        inflight: Promise<boolean> | undefined
+        watch: ReturnType<typeof createLivenessWatch> | undefined
+        lastReadAt: number
+    }
+    const registry = new Map<string, Entry>()
+
+    /* The ongoing poll's probe: reap an idle origin, else run the real probe. */
+    function watchProbe(origin: string): Promise<boolean> {
+        const entry = registry.get(origin)
+        if (entry && Date.now() - entry.lastReadAt > options.idleMs) {
+            entry.watch?.stop()
+            registry.delete(origin)
+            /* Discarded — stop() moved the watched url, so the watch won't reschedule. */
+            return Promise.resolve(false)
+        }
+        return options.probe(origin)
+    }
+
+    function startWatch(entry: Entry, origin: string): void {
+        entry.watch = createLivenessWatch({
+            probe: watchProbe,
+            onChange: (alive) => {
+                entry.alive = alive
+            },
+            intervalMs: options.intervalMs,
+        })
+        entry.watch.watch(origin)
+    }
+
+    async function reachable(host: string | URL): Promise<boolean> {
+        /*
+        HEAD the origin root: this answers host connectivity, not endpoint
+        health. A bare host string defaults to https (the external-dependency
+        norm); an explicit http://… is honored.
+        */
+        const url =
+            typeof host === 'string' && !/^https?:\/\//i.test(host) ? `https://${host}` : host
+        const origin = new URL(url).origin
+        const existing = registry.get(origin)
+        if (existing) {
+            existing.lastReadAt = Date.now()
+            return existing.inflight ?? existing.alive
+        }
+        /* Cold: optimistic seed, but the first read awaits a real probe before returning. */
+        const entry: Entry = {
+            alive: true,
+            inflight: undefined,
+            watch: undefined,
+            lastReadAt: Date.now(),
+        }
+        registry.set(origin, entry)
+        /* A rejecting probe reads as unreachable, not a permanent wedge: without
+           the catch a thrown probe leaves inflight set forever (every later read
+           returns the rejected promise) and never starts the watch. */
+        entry.inflight = options
+            .probe(origin)
+            .catch(() => false)
+            .then((alive) => {
+                entry.alive = alive
+                entry.inflight = undefined
+                startWatch(entry, origin)
+                return alive
+            })
+        return entry.inflight
+    }
+
+    function stop(): void {
+        for (const entry of registry.values()) {
+            entry.watch?.stop()
+        }
+        registry.clear()
+    }
+
+    return { reachable, stop, [Symbol.dispose]: stop }
+}

package/src/lib/server/runtime/createRouteDispatcher.ts

@@ -0,0 +1,127 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
+import { NAV_HEADER } from '../../shared/NAV_HEADER.ts'
+import { REMOTE_FUNCTION } from '../../shared/REMOTE_FUNCTION.ts'
+import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
+import type { HttpVerb } from '../../shared/types/HttpVerb.ts'
+import type { RemoteFunction } from '../../shared/types/RemoteFunction.ts'
+import type { Pages } from '../../ui/types/Pages.ts'
+import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
+import { crossOriginGate } from './crossOriginGate.ts'
+import type { RequestStore } from './types/RequestStore.ts'
+
+type AnyRemoteFunction = RemoteFunction<unknown, unknown>
+
+/* Resolves a matched route to a Response, given the request and its scope. */
+type RouteHandler = (
+    req: Request,
+    pathParams: Record<string, string>,
+    store: RequestStore,
+) => Promise<Response>
+
+/* Renders the page at `routeUrl` — injected so dispatch is testable without SSR. */
+type RenderPage = (
+    routeUrl: string,
+    params: Record<string, string>,
+    store: RequestStore,
+) => Promise<Response>
+
+/* The framework's 405 — `Allow` names the permitted verb(s), body and NO_STORE shared so the rpc and page branches can't drift. */
+function methodNotAllowed(allow: string): Response {
+    return new Response('Method Not Allowed', {
+        status: 405,
+        headers: { Allow: allow, 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
+    })
+}
+
+/*
+Owns route dispatch: deciding, per registered URL, whether a request hits an
+rpc verb, a page render, or nothing — and the method-matching that picks the
+status. Page URLs (under src/ui/pages/) serve GET/HEAD by rendering; rpc
+URLs (under src/server/rpc/, `/rpc/...`) dispatch to the single declared verb,
+405 on method mismatch; an unregistered URL is 404. Page and rpc URLs are
+disjoint by construction, so each route lands in exactly one branch.
+
+`renderPage` is injected rather than built here: dispatch decisions (the
+405/404 branches and the rpc method match) are the behaviour worth testing,
+and keeping the page render behind the seam lets a test exercise them with a
+stub instead of booting a server. The rpc-module loader is memoised internally
+so each module loads once.
+*/
+export function createRouteDispatcher({
+    pages,
+    rpc,
+    renderPage,
+}: {
+    pages: Pages
+    rpc: RemoteRoutes
+    renderPage: RenderPage
+}): (routeUrl: string) => RouteHandler {
+    const loadRpc = memoizeByKey((url): Promise<AnyRemoteFunction | undefined> | undefined => {
+        const loader = rpc[url]
+        if (!loader) {
+            return undefined
+        }
+        /*
+        Each $rpc module has exactly one named export, validated at build
+        time. Pick the first REMOTE_FUNCTION-branded export — exact, so an
+        incidental re-export carrying method/url props can't be mistaken
+        for the verb.
+        */
+        return loader().then((mod) => {
+            for (const value of Object.values(mod)) {
+                if (typeof value === 'function' && REMOTE_FUNCTION in value) {
+                    return value as AnyRemoteFunction
+                }
+            }
+            return undefined
+        })
+    })
+
+    return function buildRouteHandler(routeUrl: string): RouteHandler {
+        const hasPage = pages[routeUrl] !== undefined
+        const hasRpc = rpc[routeUrl] !== undefined
+        return async function routeHandler(req, pathParams, store) {
+            const method = req.method as HttpVerb
+            if (hasRpc) {
+                const fn = await loadRpc(routeUrl)
+                if (fn && fn.method === method) {
+                    const forbidden = crossOriginGate(req, store.url, {
+                        allowReadOnly: true,
+                        optOut: fn.crossOrigin === true,
+                        hint: 'Declare `crossOrigin: true` on the verb to accept cross-site calls.',
+                    })
+                    if (forbidden) {
+                        return forbidden
+                    }
+                    return fn.fetch(req)
+                }
+                return methodNotAllowed(fn ? fn.method : '')
+            }
+            if (hasPage) {
+                if (method !== 'GET' && method !== 'HEAD') {
+                    return methodNotAllowed('GET, HEAD')
+                }
+                /*
+                SPA navigation probe: the client router fetches the destination
+                with NAV_HEADER purely so app.handle runs (auth/redirect gating)
+                before it mounts the page itself. Reaching here means handle()
+                already passed — it called next — so a bare 204 says "cleared,
+                mount it client-side" without paying for a render. A redirect or
+                block from handle() short-circuits before next and never arrives.
+                */
+                if (req.headers.has(NAV_HEADER)) {
+                    return new Response(null, {
+                        status: 204,
+                        headers: { 'Cache-Control': NO_STORE },
+                    })
+                }
+                return renderPage(routeUrl, pathParams, store)
+            }
+            return new Response('Not Found', {
+                status: 404,
+                headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
+            })
+        }
+    }
+}