@briancray/belte 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "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 { createRouteDispatcher } from './createRouteDispatcher.ts'
+import { disableIdleTimeoutForStream } from './disableIdleTimeoutForStream.ts'
 import { findOpenPort } from './findOpenPort.ts'
 import { globToPathSet } from './globToPathSet.ts'
+import { internalErrorResponse } from './internalErrorResponse.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
@@ -112,6 +95,13 @@ export async function createServer({
     // 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),
+    /*
+    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)
         })
     }
 
@@ -412,6 +313,7 @@ export async function createServer({
     // Server<unknown> pins Bun's WebSocketData generic so upgrade({ data: {} }) typechecks.
     const server: Server<unknown> = Bun.serve({
         port,
+        idleTimeout,
 
         websocket: {
             open(ws) {

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/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
+}