@belte/belte 0.19.0

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

@@ -0,0 +1,106 @@
+import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+
+/*
+Turns a verb's resolved JSON Schema into OpenAPI query parameters — one
+per top-level property, marked required when the schema lists it. Used
+for GET/DELETE/HEAD operations, which carry their args on the query
+string (mirroring buildRpcRequest).
+*/
+function queryParameters(jsonSchema: Record<string, unknown>): Array<Record<string, unknown>> {
+    const properties = jsonSchema.properties as Record<string, unknown> | undefined
+    if (!properties) {
+        return []
+    }
+    const required = new Set((jsonSchema.required as string[] | undefined) ?? [])
+    return Object.entries(properties).map(([name, schema]) => ({
+        name,
+        in: 'query',
+        required: required.has(name),
+        schema,
+    }))
+}
+
+/*
+Request body schema for a multipart upload verb: the text fields from
+inputSchema, plus the binary parts. A File has no honest
+Standard-Schema→JSON-Schema conversion, so the file parts are advertised
+generically as additional binary properties rather than named per field.
+*/
+function multipartBodySchema(textSchema: Record<string, unknown>): Record<string, unknown> {
+    const textProperties = (textSchema.properties as Record<string, unknown> | undefined) ?? {}
+    const schema: Record<string, unknown> = {
+        type: 'object',
+        properties: { ...textProperties },
+        additionalProperties: { type: 'string', format: 'binary' },
+    }
+    const required = (textSchema.required as string[] | undefined) ?? []
+    if (required.length > 0) {
+        schema.required = required
+    }
+    return schema
+}
+
+/*
+Builds an OpenAPI 3.1 document from the verb registry — the HTTP surface
+every rpc exposes regardless of which non-browser clients it advertises.
+GET/DELETE/HEAD args become query parameters; POST/PUT/PATCH args become
+a JSON request body. operationId is the folder-prefixed command name so
+it lines up with the MCP tool / CLI subcommand identifiers.
+*/
+export function buildOpenApiSpec(info: {
+    title: string
+    version: string
+}): Record<string, unknown> {
+    const paths: Record<string, Record<string, unknown>> = {}
+    for (const entry of verbRegistry.values()) {
+        const url = entry.remote.url
+        const method = entry.remote.method
+        const jsonSchema = jsonSchemaForSchema(entry.inputSchema)
+        const description = jsonSchema.description as string | undefined
+        /*
+        When the verb declares an `outputSchema`, describe the 200 body
+        with it so external tooling sees the real return shape; otherwise
+        fall back to a bare OK.
+        */
+        const okResponse: Record<string, unknown> = { description: 'OK' }
+        if (entry.outputSchema) {
+            okResponse.content = {
+                'application/json': {
+                    schema: jsonSchemaForSchema(entry.outputSchema),
+                },
+            }
+        }
+        const operation: Record<string, unknown> = {
+            operationId: commandNameForUrl(url),
+            ...(description ? { description } : {}),
+            responses: { '200': okResponse },
+        }
+        if (carriesBodyArgs(method)) {
+            operation.requestBody = entry.filesSchema
+                ? {
+                      content: {
+                          'multipart/form-data': {
+                              schema: multipartBodySchema(jsonSchema),
+                          },
+                      },
+                  }
+                : { content: { 'application/json': { schema: jsonSchema } } }
+        } else {
+            const parameters = queryParameters(jsonSchema)
+            if (parameters.length > 0) {
+                operation.parameters = parameters
+            }
+        }
+        paths[url] ??= {}
+        const path = paths[url]
+        path[method.toLowerCase()] = operation
+    }
+    return {
+        openapi: '3.1.0',
+        info: { title: info.title, version: info.version },
+        paths,
+    }
+}

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

@@ -0,0 +1,22 @@
+import {
+    IMMUTABLE_ASSET_CACHE_CONTROL,
+    REVALIDATE_ASSET_CACHE_CONTROL,
+} from '../../shared/CACHE_CONTROL_VALUES.ts'
+
+/*
+Bun.build emits `[name]-[hash].[ext]` for chunks; hash is alnum and >=8 chars.
+Source maps inherit the same name (e.g. foo-abc12345.js.map), so the suffix may be `.map`.
+*/
+const HASHED = /-[a-z0-9]{8,}\.[a-z0-9]+(\.map)?$/i
+
+/*
+Returns the right `Cache-Control` for an asset path served under `/_app/`.
+Hashed chunk filenames are content-addressed and immutable; everything else
+(the entry bundle, the html shell, etc.) must revalidate every time.
+*/
+export function cacheControlForAsset(pathname: string): string {
+    if (HASHED.test(pathname)) {
+        return IMMUTABLE_ASSET_CACHE_CONTROL
+    }
+    return REVALIDATE_ASSET_CACHE_CONTROL
+}

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/createAssetHeaderCache.ts

@@ -0,0 +1,35 @@
+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 `zstd` variant with `Content-Encoding: zstd`.
+`cacheControlFor` lets callers vary the policy: hashed-aware for `/_app/`,
+fixed for public/.
+*/
+type AssetHeaderBundle = {
+    base: HeadersInit
+    zstd: HeadersInit
+}
+
+export function createAssetHeaderCache(
+    cacheControlFor: (pathname: string) => string,
+): (pathname: string) => AssetHeaderBundle {
+    const cache = new Map<string, AssetHeaderBundle>()
+    return function headersFor(pathname) {
+        const cached = cache.get(pathname)
+        if (cached) {
+            return cached
+        }
+        const base: HeadersInit = {
+            'Content-Type': mimeForExtension(pathname),
+            Vary: 'Accept-Encoding',
+            'Cache-Control': cacheControlFor(pathname),
+        }
+        const bundle: AssetHeaderBundle = { base, zstd: { ...base, 'Content-Encoding': 'zstd' } }
+        cache.set(pathname, bundle)
+        return bundle
+    }
+}

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

@@ -0,0 +1,63 @@
+import { PUBLIC_ASSET_CACHE_CONTROL } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { acceptsZstd } from './acceptsZstd.ts'
+import { containsTraversal } from './containsTraversal.ts'
+import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
+import { globToPathSet } from './globToPathSet.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 → zstd bytes
+    embedded into the binary, mirroring the `_app` asset embed.
+  - `publicDir` on disk (dev + `belte start`): files read straight from
+    `${cwd}/src/browser/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 })
+
+    return async function servePublicAsset(req, url) {
+        if (containsTraversal(req.url)) {
+            return undefined
+        }
+        const wantsZstd = acceptsZstd(req)
+        const { base, zstd } = headersFor(url.pathname)
+        if (publicAssets) {
+            const compressed = publicAssets[url.pathname]
+            if (!compressed) {
+                return undefined
+            }
+            if (wantsZstd) {
+                return new Response(compressed, { headers: zstd })
+            }
+            return new Response(await Bun.zstdDecompress(compressed), { headers: base })
+        }
+        if (!diskPaths.has(url.pathname)) {
+            return undefined
+        }
+        return new Response(Bun.file(publicDir + url.pathname), { headers: base })
+    }
+}

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

@@ -0,0 +1,100 @@
+import type { Pages } from '../../browser/types/Pages.ts'
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
+import type { HttpVerb } from '../../shared/types/HttpVerb.ts'
+import type { RemoteFunction } from '../../shared/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 },
+            })
+        }
+    }
+}