@briancray/belte 0.7.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.7.0",
+    "version": "0.8.1",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

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

@@ -0,0 +1,100 @@
+import type { Pages } from '../../browser/types/Pages.ts'
+import { NO_STORE } from '../../shared/cacheControlValues.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
+import type { HttpVerb } from '../rpc/types/HttpVerb.ts'
+import type { RemoteFunction } from '../rpc/types/RemoteFunction.ts'
+import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.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, '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/browser/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 Svelte 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 export that looks like a RemoteFunction so the
+        framework stays tolerant of incidental re-exports.
+        */
+        return loader().then((mod) => {
+            for (const value of Object.values(mod)) {
+                if (typeof value === 'function' && 'method' in value && 'url' 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) {
+                    return fn.fetch(req)
+                }
+                return methodNotAllowed(fn ? fn.method : '')
+            }
+            if (hasPage) {
+                if (method !== 'GET' && method !== 'HEAD') {
+                    return methodNotAllowed('GET, HEAD')
+                }
+                return renderPage(routeUrl, pathParams, store)
+            }
+            return new Response('Not Found', {
+                status: 404,
+                headers: { 'Cache-Control': NO_STORE },
+            })
+        }
+    }
+}

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

@@ -8,18 +8,14 @@ import { createMcpResourceServer } from '../../mcp/createMcpResourceServer.ts'
 import { setMcpResourceServer } from '../../mcp/mcpResourceServerSlot.ts'
 import type { McpServer } from '../../mcp/types/McpServer.ts'
 import { NO_STORE, SSR_CACHE_CONTROL } from '../../shared/cacheControlValues.ts'
-import { createCacheStore } from '../../shared/createCacheStore.ts'
 import { isDebugEnabled } from '../../shared/isDebugEnabled.ts'
 import { log } from '../../shared/log.ts'
-import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { nearestLayoutPrefix, normalizeLayoutPrefixes } from '../../shared/nearestLayoutPrefix.ts'
 import { toBunRoutePattern } from '../../shared/toBunRoutePattern.ts'
 import type { AppModule } from '../AppModule.ts'
 import { handleCliDownload } from '../cli/handleCliDownload.ts'
 import { handleCliInstall } from '../cli/handleCliInstall.ts'
 import type { PromptRoutes } from '../prompts/types/PromptRoutes.ts'
-import type { HttpVerb } from '../rpc/types/HttpVerb.ts'
-import type { RemoteFunction } from '../rpc/types/RemoteFunction.ts'
 import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
 import { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
 import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
@@ -29,12 +25,16 @@ import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
-import { findOpenPort } from './findOpenPort.ts'
+import { createRouteDispatcher } from './createRouteDispatcher.ts'
+import { disableIdleTimeoutForStream } from './disableIdleTimeoutForStream.ts'
 import { globToPathSet } from './globToPathSet.ts'
+import { internalErrorResponse } from './internalErrorResponse.ts'
+import { listenOnOpenPort } from './listenOnOpenPort.ts'
 import { logBrowserOnlyRoutes } from './logBrowserOnlyRoutes.ts'
+import { parseIdleTimeout } from './parseIdleTimeout.ts'
 import { parsePort } from './parsePort.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
-import { requestContext } from './requestContext.ts'
+import { runWithRequestScope } from './runWithRequestScope.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
 import { serializeCacheSnapshot } from './serializeCacheSnapshot.ts'
 import { setActiveServer } from './setActiveServer.ts'
@@ -48,21 +48,6 @@ function wantsJson(req: Request): boolean {
 // SSR placeholders the shell carries; filled in a single pass per render.
 const SSR_MARKER = /<!--ssr:(head|body|state)-->/g
 
-/*
-The framework's default 500 response — a `<pre>` stack dump. Shared by the
-per-request catch and Bun.serve's global error() fallback so the two can't
-drift. Only reached when the app supplies no `handleError` hook.
-*/
-function internalErrorResponse(err: unknown): Response {
-    return new Response(`<pre>${String((err as Error)?.stack ?? err)}</pre>`, {
-        status: 500,
-        headers: {
-            'Content-Type': 'text/html; charset=utf-8',
-            'Cache-Control': NO_STORE,
-        },
-    })
-}
-
 const IDENTITY_PATH = '/__belte/identity'
 const SOCKETS_PATH = '/__belte/sockets'
 const SOCKETS_REST_PREFIX = '/__belte/sockets/'
@@ -79,8 +64,6 @@ conventional root path where external tooling and scanners expect to find it
 */
 const OPENAPI_PATH = '/openapi.json'
 
-type AnyRemoteFunction = RemoteFunction<unknown, unknown>
-
 /*
 Starts a Bun HTTP server that ties together the framework conventions:
 page.svelte + layout.svelte under src/browser/pages/ for views, one named export
@@ -109,9 +92,16 @@ export async function createServer({
     distDir = `${process.cwd()}/dist`,
     publicDir = `${process.cwd()}/src/browser/public`,
     resourcesDir = `${process.cwd()}/src/mcp/resources`,
-    // No PORT set → scan for the first open port at/above 3000 rather than
-    // hardcoding 3000, so a second app boots cleanly instead of colliding.
-    port = parsePort(process.env.PORT) ?? findOpenPort(3000),
+    // A configured PORT is honored as-is; left undefined, the real listener
+    // scans upward from 3000 at bind time (see buildServer / listenOnOpenPort).
+    port = parsePort(process.env.PORT),
+    /*
+    Bun's per-connection idle timeout in seconds (its own default is 10).
+    Surfaced for apps whose unary handlers legitimately compute longer than
+    that; streaming responses opt out per-request via disableIdleTimeoutForStream
+    regardless of this floor.
+    */
+    idleTimeout = parseIdleTimeout(process.env.BELTE_IDLE_TIMEOUT) ?? 10,
 }: {
     pages: Pages
     rpc: RemoteRoutes
@@ -130,6 +120,7 @@ export async function createServer({
     publicDir?: string
     resourcesDir?: string
     port?: number
+    idleTimeout?: number
 }): Promise<Server<unknown>> {
     setRegistryManifests({ rpc, sockets, prompts })
     setMcpResourceServer(createMcpResourceServer({ resourcesDir, mcpResources }))
@@ -153,26 +144,6 @@ export async function createServer({
               (file) => `/_app/${file.replace(/\.zst$/, '')}`,
           )
 
-    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 export that looks like a RemoteFunction so the
-        framework stays tolerant of incidental re-exports.
-        */
-        return loader().then((mod) => {
-            for (const value of Object.values(mod)) {
-                if (typeof value === 'function' && 'method' in value && 'url' in value) {
-                    return value as AnyRemoteFunction
-                }
-            }
-            return undefined
-        })
-    })
-
     const logRequests = isDebugEnabled('belte')
 
     // Per-pathname asset header bundles, hashed-chunk-aware Cache-Control.
@@ -274,51 +245,11 @@ export async function createServer({
     }
 
     /*
-    Per-route handler bound by buildRoutes(). Receives a BunRequest with
-    `params` filled from the route pattern (only pages use path params;
-    $rpc URLs are flat). Page URLs (under src/browser/pages/) serve GET/HEAD by
-    rendering; rpc URLs (under src/server/rpc/, prefixed with `/rpc/`) dispatch
-    to the single declared verb-bound handler. URLs are disjoint by
-    construction so each path goes to exactly one branch.
+    Route dispatch — rpc-vs-page-vs-404 resolution and method matching — lives
+    behind createRouteDispatcher; renderPage is injected so those decisions stay
+    testable without SSR. buildRoutes() below binds the returned handler per URL.
     */
-    function buildRouteHandler(routeUrl: string) {
-        const hasPage = pages[routeUrl] !== undefined
-        const hasRpc = rpc[routeUrl] !== undefined
-        return async function routeHandler(
-            req: Request,
-            pathParams: Record<string, string>,
-            store: RequestStore,
-        ): Promise<Response> {
-            const method = req.method as HttpVerb
-            if (hasRpc) {
-                const fn = await loadRpc(routeUrl)
-                if (fn && fn.method === method) {
-                    return fn.fetch(req)
-                }
-                const allow = fn ? fn.method : ''
-                return new Response('Method Not Allowed', {
-                    status: 405,
-                    headers: {
-                        Allow: allow,
-                        'Cache-Control': NO_STORE,
-                    },
-                })
-            }
-            if (hasPage) {
-                if (method !== 'GET' && method !== 'HEAD') {
-                    return new Response('Method Not Allowed', {
-                        status: 405,
-                        headers: { Allow: 'GET, HEAD', 'Cache-Control': NO_STORE },
-                    })
-                }
-                return renderPage(routeUrl, pathParams, store)
-            }
-            return new Response('Not Found', {
-                status: 404,
-                headers: { 'Cache-Control': NO_STORE },
-            })
-        }
-    }
+    const buildRouteHandler = createRouteDispatcher({ pages, rpc, renderPage })
 
     /*
     Page URLs (folder paths, e.g. `/media/[id]`) get translated to Bun's
@@ -361,42 +292,12 @@ export async function createServer({
             store: RequestStore,
         ) => Promise<Response>,
     ): Promise<Response> {
-        return runWithStore(req, async (store) => {
-            if (!app?.handle) {
-                return handler(req, pathParams, store)
-            }
-            return app.handle(req, (next) => handler(next, pathParams, store))
-        })
-    }
-
-    function runWithStore(
-        req: Request,
-        body: (store: RequestStore) => Promise<Response>,
-    ): Promise<Response> {
-        const url = new URL(req.url)
-        const store: RequestStore = {
-            url,
-            req,
-            cache: createCacheStore(),
-        }
-        return requestContext.run(store, async () => {
-            const start = logRequests ? Bun.nanoseconds() : 0
-            let response: Response
-            try {
-                response = await body(store)
-            } catch (error) {
-                if (app?.handleError) {
-                    response = await app.handleError(error, req)
-                } else {
-                    log.error(error)
-                    response = internalErrorResponse(error)
-                }
-            }
-            if (logRequests) {
-                const ms = (Bun.nanoseconds() - start) / 1e6
-                log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
-            }
-            return response
+        return runWithRequestScope(req, { app, logRequests }, async (store) => {
+            const response = app?.handle
+                ? await app.handle(req, (next) => handler(next, pathParams, store))
+                : await handler(req, pathParams, store)
+            // Streaming bodies (sse/jsonl, socket tail) opt out of the idle timeout.
+            return disableIdleTimeoutForStream(server, req, response)
         })
     }
 
@@ -409,136 +310,155 @@ export async function createServer({
     a busy socket doesn't iterate JS per subscriber per message.
     */
     const socketDispatcher = createSocketDispatcher(sockets)
-    // Server<unknown> pins Bun's WebSocketData generic so upgrade({ data: {} }) typechecks.
-    const server: Server<unknown> = Bun.serve({
-        port,
 
-        websocket: {
-            open(ws) {
-                socketDispatcher.open(ws)
-            },
-            message(ws, data) {
-                socketDispatcher.message(ws, data)
-            },
-            close(ws) {
-                socketDispatcher.close(ws)
+    /*
+    Bind the real server on `boundPort`. Only the port varies between scan
+    attempts, so the rest of the config lives inline and just the port is spread
+    in — passing the literal straight to Bun.serve keeps contextual typing of the
+    websocket handlers (and Server<unknown> pins Bun's WebSocketData generic so
+    upgrade({ data: {} }) typechecks).
+    */
+    const bindAt = (boundPort: number): Server<unknown> =>
+        Bun.serve({
+            port: boundPort,
+            idleTimeout,
+
+            websocket: {
+                open(ws) {
+                    socketDispatcher.open(ws)
+                },
+                message(ws, data) {
+                    socketDispatcher.message(ws, data)
+                },
+                close(ws) {
+                    socketDispatcher.close(ws)
+                },
             },
-        },
 
-        routes,
+            routes,
 
-        async fetch(req, bunServer) {
-            const url = new URL(req.url)
-            /*
-            Identity probe — answered directly, ahead of any app.handle middleware,
-            so the bundle's connect screen can confirm a URL really is a belte
-            server (and which app) before pointing the desktop window at it. It
-            must stay reachable even when the app guards everything behind auth,
-            hence the early return that bypasses dispatchRequest.
-            */
-            if (url.pathname === IDENTITY_PATH) {
-                return Response.json(
-                    {
-                        belte: true,
-                        name: appInfo?.name ?? cliName,
-                        version: appInfo?.version ?? '0.0.0',
-                    },
-                    { headers: { 'Cache-Control': NO_STORE } },
-                )
-            }
-            if (url.pathname === SOCKETS_PATH) {
-                if (bunServer.upgrade(req, { data: {} })) {
-                    return undefined as unknown as Response
+            async fetch(req, bunServer) {
+                const url = new URL(req.url)
+                /*
+                Identity probe — answered directly, ahead of any app.handle middleware,
+                so the bundle's connect screen can confirm a URL really is a belte
+                server (and which app) before pointing the desktop window at it. It
+                must stay reachable even when the app guards everything behind auth,
+                hence the early return that bypasses dispatchRequest.
+                */
+                if (url.pathname === IDENTITY_PATH) {
+                    return Response.json(
+                        {
+                            belte: true,
+                            name: appInfo?.name ?? cliName,
+                            version: appInfo?.version ?? '0.0.0',
+                        },
+                        { headers: { 'Cache-Control': NO_STORE } },
+                    )
                 }
-                return new Response('Upgrade failed', { status: 400 })
-            }
-            /*
-            HTTP face of a socket (`/__belte/sockets/<name>`) — tail over
-            SSE / JSON and publish — for the CLI and MCP. Runs through
-            dispatchRequest so app.handle auth applies, like the rpc paths.
-            The socket name may contain `/` (nested files), so it's the
-            whole remaining pathname, percent-decoded.
-            */
-            if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
-                const name = decodeURIComponent(url.pathname.slice(SOCKETS_REST_PREFIX.length))
-                return dispatchRequest(req, {}, async () => socketDispatcher.rest(req, name))
-            }
-            if (url.pathname === MCP_PATH && mcp) {
-                return dispatchRequest(req, {}, async () => mcp.handle(req))
-            }
-            if (url.pathname === CLI_PATH) {
-                return dispatchRequest(req, {}, async () => handleCliInstall(req, cliName))
-            }
-            if (url.pathname.startsWith(CLI_DOWNLOAD_PREFIX)) {
-                const platform = url.pathname.slice(CLI_DOWNLOAD_PREFIX.length)
-                return dispatchRequest(req, {}, async () =>
-                    handleCliDownload(req, platform, cliName, cliCwd),
-                )
-            }
-            if (url.pathname === OPENAPI_PATH) {
-                return dispatchRequest(req, {}, async () => {
-                    await ensureRegistriesLoaded()
-                    const spec = buildOpenApiSpec({
-                        title: appInfo?.name ?? cliName,
-                        version: appInfo?.version ?? '0.0.0',
-                    })
-                    return Response.json(spec, { headers: { 'Cache-Control': NO_STORE } })
-                })
-            }
-            /*
-            Static assets sidestep ALS + the per-request CacheStore + the
-            app.handle middleware: they have no need for cache() and the
-            allocation overhead matters on a cold page load that pulls
-            dozens of chunks. The global server.error() handler still
-            catches anything that goes wrong inside serveStaticAsset.
-            */
-            if (url.pathname.startsWith('/_app/')) {
-                if (!logRequests) {
-                    return serveStaticAsset(req, url)
+                if (url.pathname === SOCKETS_PATH) {
+                    if (bunServer.upgrade(req, { data: {} })) {
+                        return undefined as unknown as Response
+                    }
+                    return new Response('Upgrade failed', { status: 400 })
                 }
-                const start = Bun.nanoseconds()
-                const response = await serveStaticAsset(req, url)
-                const ms = (Bun.nanoseconds() - start) / 1e6
-                log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
-                return response
-            }
-            /*
-            Files under public/ are served at the site root, sidestepping
-            ALS + middleware like the /_app/ assets do. A miss returns
-            undefined so the request falls through to the 404 / middleware
-            path below.
-            */
-            const publicResponse = await servePublicAsset(req, url)
-            if (publicResponse) {
-                if (logRequests) {
-                    log.request(
-                        req.method,
-                        `${url.pathname}${url.search}`,
-                        publicResponse.status,
-                        0,
+                /*
+                HTTP face of a socket (`/__belte/sockets/<name>`) — tail over
+                SSE / JSON and publish — for the CLI and MCP. Runs through
+                dispatchRequest so app.handle auth applies, like the rpc paths.
+                The socket name may contain `/` (nested files), so it's the
+                whole remaining pathname, percent-decoded.
+                */
+                if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
+                    const name = decodeURIComponent(url.pathname.slice(SOCKETS_REST_PREFIX.length))
+                    return dispatchRequest(req, {}, async () => socketDispatcher.rest(req, name))
+                }
+                if (url.pathname === MCP_PATH && mcp) {
+                    return dispatchRequest(req, {}, async () => mcp.handle(req))
+                }
+                if (url.pathname === CLI_PATH) {
+                    return dispatchRequest(req, {}, async () => handleCliInstall(req, cliName))
+                }
+                if (url.pathname.startsWith(CLI_DOWNLOAD_PREFIX)) {
+                    const platform = url.pathname.slice(CLI_DOWNLOAD_PREFIX.length)
+                    return dispatchRequest(req, {}, async () =>
+                        handleCliDownload(req, platform, cliName, cliCwd),
                     )
                 }
-                return publicResponse
-            }
-            /*
-            Unknown routes still run through dispatchRequest so user-defined
-            app.handle middleware can rewrite the request, serve a custom
-            404, or branch on the URL. The inner handler returns the
-            framework's default 404 when nothing intervenes.
-            */
-            return dispatchRequest(req, {}, async () => {
-                return new Response('Not Found', {
-                    status: 404,
-                    headers: { 'Cache-Control': NO_STORE },
+                if (url.pathname === OPENAPI_PATH) {
+                    return dispatchRequest(req, {}, async () => {
+                        await ensureRegistriesLoaded()
+                        const spec = buildOpenApiSpec({
+                            title: appInfo?.name ?? cliName,
+                            version: appInfo?.version ?? '0.0.0',
+                        })
+                        return Response.json(spec, { headers: { 'Cache-Control': NO_STORE } })
+                    })
+                }
+                /*
+                Static assets sidestep ALS + the per-request CacheStore + the
+                app.handle middleware: they have no need for cache() and the
+                allocation overhead matters on a cold page load that pulls
+                dozens of chunks. The global server.error() handler still
+                catches anything that goes wrong inside serveStaticAsset.
+                */
+                if (url.pathname.startsWith('/_app/')) {
+                    if (!logRequests) {
+                        return serveStaticAsset(req, url)
+                    }
+                    const start = Bun.nanoseconds()
+                    const response = await serveStaticAsset(req, url)
+                    const ms = (Bun.nanoseconds() - start) / 1e6
+                    log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
+                    return response
+                }
+                /*
+                Files under public/ are served at the site root, sidestepping
+                ALS + middleware like the /_app/ assets do. A miss returns
+                undefined so the request falls through to the 404 / middleware
+                path below.
+                */
+                const publicResponse = await servePublicAsset(req, url)
+                if (publicResponse) {
+                    if (logRequests) {
+                        log.request(
+                            req.method,
+                            `${url.pathname}${url.search}`,
+                            publicResponse.status,
+                            0,
+                        )
+                    }
+                    return publicResponse
+                }
+                /*
+                Unknown routes still run through dispatchRequest so user-defined
+                app.handle middleware can rewrite the request, serve a custom
+                404, or branch on the URL. The inner handler returns the
+                framework's default 404 when nothing intervenes.
+                */
+                return dispatchRequest(req, {}, async () => {
+                    return new Response('Not Found', {
+                        status: 404,
+                        headers: { 'Cache-Control': NO_STORE },
+                    })
                 })
-            })
-        },
+            },
+
+            error(err) {
+                log.error(err)
+                return internalErrorResponse(err)
+            },
+        })
 
-        error(err) {
-            log.error(err)
-            return internalErrorResponse(err)
-        },
-    })
+    /*
+    A configured PORT binds that exact port — a collision surfaces loudly rather
+    than silently moving, since something connecting to the app needs a known
+    address. With none set, scan upward from 3000 binding the real listener, so
+    whichever server wins the port keeps it (no probe-release gap to lose it in,
+    which used to crash boot on EADDRINUSE instead of stepping to the next port).
+    */
+    const server: Server<unknown> =
+        port === undefined ? listenOnOpenPort(bindAt, 3000) : bindAt(port)
 
     /*
     Publishes the live server through `belte/server` before invoking the

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

@@ -0,0 +1,23 @@
+import type { Server } from 'bun'
+import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
+
+/*
+Opts a streaming response out of Bun's per-connection idle timeout. A stream
+can stay quiet for longer than the 10s default between frames, which Bun would
+otherwise read as an idle connection and close mid-stream. `server.timeout(req,
+0)` clears the timeout for just this in-flight request, leaving the global
+default in place for ordinary request/response traffic. Streaming is detected
+by Content-Type (the shared signal the CLI/MCP drain paths use) rather than
+`body instanceof ReadableStream`, since every bodied Response exposes one.
+Non-stream responses pass through untouched.
+*/
+export function disableIdleTimeoutForStream(
+    server: Server<unknown>,
+    req: Request,
+    response: Response,
+): Response {
+    if (isStreamingResponse(response)) {
+        server.timeout(req, 0)
+    }
+    return response
+}

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

@@ -0,0 +1,17 @@
+import { NO_STORE } from '../../shared/cacheControlValues.ts'
+
+/*
+The framework's default 500 response — a `<pre>` stack dump. Shared by the
+per-request scope's catch (runWithRequestScope) and Bun.serve's global
+error() fallback so the two can't drift. Only reached when the app supplies
+no `handleError` hook.
+*/
+export function internalErrorResponse(error: unknown): Response {
+    return new Response(`<pre>${String((error as Error)?.stack ?? error)}</pre>`, {
+        status: 500,
+        headers: {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    })
+}

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

@@ -0,0 +1,36 @@
+import type { Server } from 'bun'
+
+// Ports tried upward from `start` before giving up and letting the kernel assign one.
+const SCAN_RANGE = 100
+
+/*
+Binds the real server, scanning upward from `start` for the first free port.
+The listener that wins a port is the one that keeps it: unlike probing a
+throwaway server and releasing it before the real bind, this leaves no window
+for the chosen port to be stolen in between — the gap that crashed boot on
+EADDRINUSE instead of stepping to the next port. `bindAt` does the actual
+Bun.serve; only an in-use port is retried, any other failure propagates. After
+SCAN_RANGE occupied ports it binds port 0 so the kernel assigns any free port.
+*/
+export function listenOnOpenPort(
+    bindAt: (port: number) => Server<unknown>,
+    start: number,
+): Server<unknown> {
+    for (let port = start; port < start + SCAN_RANGE; port++) {
+        try {
+            return bindAt(port)
+        } catch (error) {
+            if (!isAddressInUse(error)) {
+                throw error
+            }
+            // port in use — try the next one up
+        }
+    }
+    // every candidate was taken; bind to 0 so the kernel picks a free port
+    return bindAt(0)
+}
+
+// Bun reports a taken port as an Error carrying code 'EADDRINUSE'.
+function isAddressInUse(error: unknown): boolean {
+    return error instanceof Error && (error as { code?: string }).code === 'EADDRINUSE'
+}

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

@@ -0,0 +1,10 @@
+import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+
+/*
+Parses BELTE_IDLE_TIMEOUT into Bun's per-connection idle timeout in seconds.
+Bun accepts 0–255 (0 disables the timeout); returns undefined for missing,
+empty, or out-of-range/non-integer input so the caller keeps its default.
+*/
+export function parseIdleTimeout(value: string | undefined): number | undefined {
+    return parseBoundedEnvInt(value, 0, 255)
+}

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

@@ -1,16 +1,11 @@
+import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+
 /*
-Parses a PORT env value into a usable TCP port, returning undefined for
-missing, empty, or out-of-range/non-integer input so the caller can fall back
-to a default. A bare Number() turns '' into 0 (a random kernel-assigned port)
-and 'abc' into NaN, both silently wrong; this rejects them instead.
+Parses a PORT env value into a usable TCP port (0–65535), returning undefined
+for missing, empty, or out-of-range/non-integer input so the caller can fall
+back to a default. A bare Number() would turn '' into 0 (a random
+kernel-assigned port) and 'abc' into NaN, both silently wrong.
 */
 export function parsePort(value: string | undefined): number | undefined {
-    if (value === undefined || value.trim() === '') {
-        return undefined
-    }
-    const port = Number(value)
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
-        return undefined
-    }
-    return port
+    return parseBoundedEnvInt(value, 0, 65535)
 }

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

@@ -0,0 +1,47 @@
+import { createCacheStore } from '../../shared/createCacheStore.ts'
+import { log } from '../../shared/log.ts'
+import type { AppModule } from '../AppModule.ts'
+import { internalErrorResponse } from './internalErrorResponse.ts'
+import { requestContext } from './requestContext.ts'
+import type { RequestStore } from './types/RequestStore.ts'
+
+/*
+Establishes the per-request scope and runs `body` inside it: a fresh
+CacheStore plus request metadata published through the AsyncLocalStorage
+RequestStore (so cache() and request()/server() resolve without threading
+args), the app's handleError — or the framework's 500 fallback — on a thrown
+body, and optional request logging. The single seam every dynamic route
+crosses; extracted from createServer so the scope, error, and logging
+behaviour is exercisable through this interface without booting a Bun server.
+*/
+export function runWithRequestScope(
+    req: Request,
+    options: { app?: AppModule; logRequests: boolean },
+    body: (store: RequestStore) => Promise<Response>,
+): Promise<Response> {
+    const url = new URL(req.url)
+    const store: RequestStore = {
+        url,
+        req,
+        cache: createCacheStore(),
+    }
+    return requestContext.run(store, async () => {
+        const start = options.logRequests ? Bun.nanoseconds() : 0
+        let response: Response
+        try {
+            response = await body(store)
+        } catch (error) {
+            if (options.app?.handleError) {
+                response = await options.app.handleError(error, req)
+            } else {
+                log.error(error)
+                response = internalErrorResponse(error)
+            }
+        }
+        if (options.logRequests) {
+            const ms = (Bun.nanoseconds() - start) / 1e6
+            log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
+        }
+        return response
+    })
+}

package/src/lib/shared/parseBoundedEnvInt.ts

@@ -0,0 +1,20 @@
+/*
+Parses an env string into an integer within [min, max], returning undefined for
+missing, empty, or out-of-range/non-integer input so the caller can fall back to
+a default. A bare Number() turns '' into 0 and 'abc' into NaN, both silently
+wrong; this rejects them instead.
+*/
+export function parseBoundedEnvInt(
+    value: string | undefined,
+    min: number,
+    max: number,
+): number | undefined {
+    if (value === undefined || value.trim() === '') {
+        return undefined
+    }
+    const parsed = Number(value)
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        return undefined
+    }
+    return parsed
+}