@briancray/belte 0.1.0

package/src/lib/server/rpc/defineVerb.ts

@@ -0,0 +1,103 @@
+import { buildRpcRequest } from '../../shared/buildRpcRequest.ts'
+import { NO_STORE } from '../../shared/cacheControlValues.ts'
+import { createRemoteFunction } from '../../shared/createRemoteFunction.ts'
+import { forwardHeaders } from '../../shared/forwardHeaders.ts'
+import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
+import type { ClientFlags } from '../../shared/types/ClientFlags.ts'
+import { requestContext } from '../runtime/requestContext.ts'
+import { parseArgs } from './parseArgs.ts'
+import { registerVerb } from './registerVerb.ts'
+import type { HttpVerb } from './types/HttpVerb.ts'
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+import type { RemoteHandler } from './types/RemoteHandler.ts'
+import type { StandardSchemaV1 } from './types/StandardSchemaV1.ts'
+
+/*
+Builds a RemoteFunction from an HTTP verb + RPC URL + handler. The bundler
+rewrites every `export const VERB = handler(fn)` inside an `$rpc/**` module
+so the verb (from the export name) and the URL (from the file path under
+`src/server/rpc/`, with `/rpc/` prefix) are threaded into defineVerb.
+
+The plain call (`fn(args)`) resolves to the Content-Type-decoded body;
+non-2xx responses throw HttpError. `.raw(args)` returns the underlying
+Response for callers that need status/headers/body streaming.
+`.fetch(req)` is the dispatch hook the framework's router uses to
+invoke the handler from an incoming HTTP request (with args parsed off
+the Request via parseArgs).
+
+Every raw invocation records the synthesized Request against the returned
+promise so cache() can stash it on the entry without re-building.
+*/
+export function defineVerb<Args, Return>(
+    method: HttpVerb,
+    url: string,
+    handler: RemoteHandler<Args, Return>,
+    opts?: {
+        schema?: StandardSchemaV1
+        jsonSchema?: Record<string, unknown>
+        clients?: Partial<ClientFlags>
+    },
+): RemoteFunction<Args, Return> {
+    const schema = opts?.schema
+    const jsonSchema = opts?.jsonSchema
+    const clients = resolveClientFlags(opts?.clients, schema !== undefined)
+
+    function buildRequest(args: Args | undefined): Request {
+        const store = requestContext.getStore()
+        const baseUrl = store ? store.url.href : 'http://localhost/'
+        const headers = store ? forwardHeaders(store.req.headers) : new Headers()
+        return buildRpcRequest({ method, url, args, baseUrl, headers })
+    }
+
+    /*
+    Handler bodies may throw synchronously (e.g. an `assert(...)` at the
+    top of the function). The `async function` wrapper coerces both sync
+    throws and returned non-promises into the Promise<Response> shape
+    callers expect, so an SSR caller's `await` always sees the rejection
+    through the cache layer's snapshot boundary instead of the error
+    escaping the request scope.
+    */
+    async function runHandler(args: Args | undefined): Promise<Response> {
+        return handler(args as Args) as unknown as Response
+    }
+
+    async function validateThenHandle(args: Args | undefined): Promise<Response> {
+        const result = await schema!['~standard'].validate(args)
+        if (result.issues) {
+            return new Response(JSON.stringify({ issues: result.issues }), {
+                status: 422,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Cache-Control': NO_STORE,
+                },
+            })
+        }
+        return runHandler(result.value as Args)
+    }
+
+    /*
+    `getRequest` is unused on the server path — handlers receive parsed
+    `args` directly. createRemoteFunction passes a thunk so the client
+    side can lazily synthesize its Request without forcing the server
+    to allocate one per SSR call.
+    */
+    function invoke(args: Args | undefined): Promise<Response> {
+        return schema ? validateThenHandle(args) : runHandler(args)
+    }
+
+    const remote = createRemoteFunction<Args, Return>({
+        method,
+        url,
+        clients,
+        buildRequest,
+        invoke,
+        parseArgsForFetch: (request) => parseArgs(method, request) as Promise<Args | undefined>,
+    })
+    registerVerb({
+        remote: remote as RemoteFunction<unknown, unknown>,
+        schema,
+        jsonSchema,
+        clients,
+    })
+    return remote
+}

package/src/lib/server/rpc/parseArgs.ts

@@ -0,0 +1,60 @@
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+/*
+Parses + merges every source of args available for a verb-defined handler:
+- body (json or form-encoded, ignored for GET/DELETE/HEAD)
+- url query string
+
+When both are present and the body is a plain object, the merge folds the
+query in on top so query keys win on collision. A non-object body (array,
+primitive, null) skips the merge entirely and is returned as-is — there's
+no key on the body to layer the query into, and the framework's args type
+is a single bag rather than a `{body, query}` envelope. Returns undefined
+when no source contributes any key.
+*/
+export async function parseArgs(method: HttpVerb, request: Request): Promise<unknown> {
+    /*
+    Skip the URL parse entirely when the raw request URL has no query —
+    typical POST/PUT/PATCH calls land here with a flat rpc URL and no
+    `?…`, so the `new URL(...)` constructor cost (which dwarfs the
+    indexOf check) is wasted work.
+    */
+    const queryStart = request.url.indexOf('?')
+    const hasQuery = queryStart !== -1
+    const url = hasQuery ? new URL(request.url) : undefined
+
+    let body: unknown
+    if (method !== 'GET' && method !== 'DELETE' && method !== 'HEAD') {
+        const contentType = (request.headers.get('content-type') ?? '').toLowerCase()
+        if (contentType.includes('application/json')) {
+            const text = await request.text()
+            if (text !== '') {
+                body = JSON.parse(text)
+            }
+        } else if (
+            contentType.includes('application/x-www-form-urlencoded') ||
+            contentType.includes('multipart/form-data')
+        ) {
+            const form = await request.formData()
+            body = Object.fromEntries(form)
+        }
+    }
+
+    if (body !== undefined && (typeof body !== 'object' || body === null || Array.isArray(body))) {
+        return body
+    }
+
+    if (!url) {
+        if (body === undefined) {
+            return undefined
+        }
+        return body
+    }
+
+    const bodyObject = (body ?? {}) as Record<string, unknown>
+    const merged = { ...bodyObject, ...Object.fromEntries(url.searchParams) }
+    if (Object.keys(merged).length === 0) {
+        return undefined
+    }
+    return merged
+}

package/src/lib/server/rpc/registerVerb.ts

@@ -0,0 +1,6 @@
+import type { VerbRegistryEntry } from './types/VerbRegistryEntry.ts'
+import { verbRegistry } from './verbRegistry.ts'
+
+export function registerVerb(entry: VerbRegistryEntry): void {
+    verbRegistry.set(entry.remote.url, entry)
+}

package/src/lib/server/rpc/types/HttpVerb.ts

@@ -0,0 +1 @@
+export type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'

package/src/lib/server/rpc/types/RawRemoteFunction.ts

@@ -0,0 +1,13 @@
+import type { HttpVerb } from './HttpVerb.ts'
+
+/*
+Bare-response remote function — same call shape as RemoteFunction but
+resolves to the underlying Response without Content-Type decode and
+without throwing on non-2xx. Produced as `.raw` on every RemoteFunction
+so callers that need status / headers / body streaming or want to
+implement custom error handling can opt out of the decode.
+*/
+export type RawRemoteFunction<Args> = ((args: Args) => Promise<Response>) & {
+    readonly method: HttpVerb
+    readonly url: string
+}

package/src/lib/server/rpc/types/RemoteFunction.ts

@@ -0,0 +1,35 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { Subscribable } from '../../../shared/types/Subscribable.ts'
+import type { HttpVerb } from './HttpVerb.ts'
+import type { RawRemoteFunction } from './RawRemoteFunction.ts'
+
+/*
+Remote function reference produced by GET/POST/... inside an `$rpc/**`
+module and consumed by rpc dispatch, cache(), SSR auto-hydration, and
+direct calls. Same callable signature on server and client — the bundler
+swaps the implementation for browser builds.
+
+The plain call resolves to the decoded body shape (sniffed from
+Content-Type) and throws HttpError on non-2xx. `.raw` is a sibling
+RemoteFunction whose call resolves to the underlying Response — same
+method, same url, same args, no decode. Pass `fn.raw` to cache() to
+memoise raw Responses against the same cache key as `fn` (both share one
+stored entry — the decode just happens on the way out for callers of
+`fn`). `.stream(args)` returns an iterable view of the Response body:
+SSE / JSONL handlers yield each frame; non-streaming handlers yield the
+decoded body once then complete. The result is a Subscribable, so it
+can be passed to subscribe() and shared across reactive consumers.
+For sustained broadcast / pub-sub use the `belte/sockets` primitive —
+HTTP rpc isn't the place for long-lived multi-publisher subscriptions.
+`.fetch(req)` is the framework's request-dispatch entry point — used by
+the router to invoke the handler from an incoming HTTP request, not
+for user code.
+*/
+export type RemoteFunction<Args, Return> = ((args: Args) => Promise<Return>) & {
+    readonly method: HttpVerb
+    readonly url: string
+    readonly clients: ClientFlags
+    readonly raw: RawRemoteFunction<Args>
+    stream(args?: Args): Subscribable<Return>
+    fetch(request: Request): Promise<Response>
+}

package/src/lib/server/rpc/types/RemoteHandler.ts

@@ -0,0 +1,22 @@
+import type { TypedResponse } from './TypedResponse.ts'
+
+/*
+Handler signature for verb-defined remote functions. Args is `undefined` for
+GETs/DELETEs with no query, JSON-shaped objects for json bodies, and
+form-shaped objects for form-encoded bodies. For binary or multipart bodies
+Args is `undefined` — read the raw Request via `request()` from
+`belte/server` instead.
+
+Return is the value type the call site sees after Content-Type-driven
+decoding (a parsed object for JSON, a string for text/*, a Blob otherwise,
+`undefined` for 204). The handler must return a Response at runtime; the
+`TypedResponse<Return>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`
+carries the body shape through the function's inferred return type so the
+verb helper can infer `Return` automatically — no need to annotate
+`GET<Args, Return>` when the handler returns one of the respond helpers.
+A bare `new Response(...)` is still acceptable: the brand is optional, so
+untagged Responses simply fall back to `Return = unknown`.
+*/
+export type RemoteHandler<Args, Return> = (
+    args: Args,
+) => TypedResponse<Return> | Promise<TypedResponse<Return>>

package/src/lib/server/rpc/types/RemoteRoutes.ts

@@ -0,0 +1,13 @@
+import type { RemoteFunction } from './RemoteFunction.ts'
+
+/*
+Manifest of RPC URL → module loader. Produced by the resolver plugin from
+every `.ts` under src/server/rpc — each file maps to one URL (derived from its
+path under `$rpc`, prefixed with `/rpc/`). Each module has exactly one
+named export, a RemoteFunction whose `.method` and `.url` were stamped in
+by the bundler rewrite.
+*/
+export type RemoteRoutes = Record<
+    string,
+    () => Promise<Record<string, RemoteFunction<unknown, unknown>>>
+>

package/src/lib/server/rpc/types/StandardSchemaV1.ts

@@ -0,0 +1,57 @@
+/*
+Mirror of the Standard Schema v1 spec interface (standardschema.dev). Any
+library that implements the spec — zod, valibot, arktype, etc. — produces
+values whose `~standard` property structurally matches this shape, so users
+can pass their existing schemas to verb helpers without an adapter.
+
+Kept inline (no `@standard-schema/spec` dep) because the spec is type-only
+and tiny; adding a package for ~30 lines of interface would be churn. The
+namespace pattern below is the spec's own convention — `InferInput` /
+`InferOutput` ride along the same export.
+*/
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>
+}
+
+// biome-ignore lint/style/useNamingConvention: matches the Standard Schema spec exactly
+export namespace StandardSchemaV1 {
+    export interface Props<Input = unknown, Output = Input> {
+        readonly version: 1
+        readonly vendor: string
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>
+        readonly types?: Types<Input, Output> | undefined
+    }
+
+    export type Result<Output> = SuccessResult<Output> | FailureResult
+
+    export interface SuccessResult<Output> {
+        readonly value: Output
+        readonly issues?: undefined
+    }
+
+    export interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>
+    }
+
+    export interface Issue {
+        readonly message: string
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined
+    }
+
+    export interface PathSegment {
+        readonly key: PropertyKey
+    }
+
+    export interface Types<Input = unknown, Output = Input> {
+        readonly input: Input
+        readonly output: Output
+    }
+
+    export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+        Schema['~standard']['types']
+    >['input']
+
+    export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+        Schema['~standard']['types']
+    >['output']
+}

package/src/lib/server/rpc/types/TypedResponse.ts

@@ -0,0 +1,18 @@
+/*
+A `Response` tagged with the body type the framework will hand back to
+callers after Content-Type-driven decoding. The tag is phantom — it
+adds no runtime field, only a type-level slot so the verb helpers can
+infer `Return` from the handler's return type instead of forcing every
+route to annotate it via `GET<Args, Return>`.
+
+The respond helpers (`json<T>`, `error`, `redirect`, `jsonl<F>`,
+`sse<F>`) all return a `TypedResponse<T>`, so a handler ending in
+`return json({ user })` exposes `{ user: ... }` as its body type; the
+verb overload picks it up via `RemoteHandler<Args, Return>`.
+
+`T` is optional on the brand so a plain `new Response(...)` (untagged)
+remains assignable to `TypedResponse<unknown>`; in that case `Return`
+just falls back to its `unknown` default, matching pre-existing
+behaviour for handlers that build Responses by hand.
+*/
+export type TypedResponse<T> = Response & { readonly __body?: T }

package/src/lib/server/rpc/types/VerbHelper.ts

@@ -0,0 +1,39 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { RemoteFunction } from './RemoteFunction.ts'
+import type { RemoteHandler } from './RemoteHandler.ts'
+import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
+
+/*
+Shared signature for every verb helper (GET / POST / …). Three overloads:
+
+  - `Verb(fn, { schema, clients? })` — `Args` infers from
+    `InferInput<Schema>`, the handler receives `InferOutput<Schema>`.
+    Generic order is `<Return, Schema>` so users can override `Return`
+    while letting `Schema` infer from `opts.schema`. `clients` controls
+    which surfaces (browser / mcp / cli) expose this verb.
+  - `Verb(fn, { clients })` — schemaless but with explicit client
+    targeting (e.g. server-internal RPC with `clients: { browser: false }`).
+  - `Verb(fn)` — bare handler. `Args` and `Return` come from the handler
+    type; `Return` is usually inferred via the `TypedResponse<T>` brand on
+    `json`/`error`/`redirect`/`jsonl`/`sse`.
+*/
+export type VerbHelper = {
+    <Return = unknown, Schema extends StandardSchemaV1 = StandardSchemaV1>(
+        fn: RemoteHandler<StandardSchemaV1.InferOutput<Schema>, Return>,
+        opts: {
+            schema: Schema
+            jsonSchema?: Record<string, unknown>
+            clients?: Partial<ClientFlags>
+        },
+    ): RemoteFunction<StandardSchemaV1.InferInput<Schema>, Return>
+    <Args = undefined, Return = unknown>(
+        fn: RemoteHandler<Args, Return>,
+        opts: {
+            jsonSchema?: Record<string, unknown>
+            clients: Partial<ClientFlags>
+        },
+    ): RemoteFunction<Args, Return>
+    <Args = undefined, Return = unknown>(
+        fn: RemoteHandler<Args, Return>,
+    ): RemoteFunction<Args, Return>
+}

package/src/lib/server/rpc/types/VerbRegistryEntry.ts

@@ -0,0 +1,17 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { RemoteFunction } from './RemoteFunction.ts'
+import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
+
+/*
+Per-verb registry record on the server side. MCP and CLI enumerate this
+to discover which RPCs are advertised (clients flags) and what input
+shape they expect (schema). The schema and resolved clients stay off the
+public RemoteFunction shape so the browser-side proxy doesn't need to
+carry server-only state.
+*/
+export type VerbRegistryEntry = {
+    remote: RemoteFunction<unknown, unknown>
+    schema: StandardSchemaV1 | undefined
+    jsonSchema: Record<string, unknown> | undefined
+    clients: ClientFlags
+}

package/src/lib/server/rpc/unprocessed.ts

@@ -0,0 +1,14 @@
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+
+/*
+Verb helpers (GET / POST / …) are placeholders — the bundler rewrites every
+`export const x = GET(fn)` inside `src/server/rpc/<file>.ts` into a call to
+defineVerb (server target) or remoteProxy (client target). If a call slips
+through, the bundler plugin didn't process the file; throwing here surfaces
+that cleanly instead of silently returning undefined.
+*/
+export function unprocessed<Args, Return>(verb: string): RemoteFunction<Args, Return> {
+    throw new Error(
+        `[belte] \`${verb}\` was called outside an $rpc module — verb helpers are only valid as the value of \`export const <filename> = ...\` inside a file under src/server/rpc/`,
+    )
+}

package/src/lib/server/rpc/verbRegistry.ts

@@ -0,0 +1,11 @@
+import type { VerbRegistryEntry } from './types/VerbRegistryEntry.ts'
+
+/*
+Process-wide registry of every verb-bound RPC declared in the app.
+defineVerb inserts on first construction (which happens at module-load
+time inside the rpc dispatcher cache or eagerly when MCP / CLI walks the
+rpc manifest). MCP server reads this to build its tools list; the CLI
+binary reads it to generate subcommands. The browser path never touches
+this — the client stub has no schema or clients metadata to register.
+*/
+export const verbRegistry = new Map<string, VerbRegistryEntry>()

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

@@ -0,0 +1,66 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
+import type { HttpVerb } from '../rpc/types/HttpVerb.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+
+const BODY_METHODS = new Set<HttpVerb>(['POST', 'PUT', 'PATCH'])
+
+/*
+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,
+    }))
+}
+
+/*
+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.schema, entry.jsonSchema)
+        const operation: Record<string, unknown> = {
+            operationId: commandNameForUrl(url),
+            responses: { '200': { description: 'OK' } },
+        }
+        if (BODY_METHODS.has(method)) {
+            operation.requestBody = {
+                content: { 'application/json': { schema: jsonSchema } },
+            }
+        } else {
+            const parameters = queryParameters(jsonSchema)
+            if (parameters.length > 0) {
+                operation.parameters = parameters
+            }
+        }
+        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,17 @@
+/*
+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 'public, max-age=31536000, immutable'
+    }
+    return 'public, max-age=0, must-revalidate'
+}

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

@@ -0,0 +1,66 @@
+import { containsTraversal } from './containsTraversal.ts'
+import { mimeForExtension } from './mimeForExtension.ts'
+import type { Assets } from './types/Assets.ts'
+
+const PUBLIC_CACHE_CONTROL = 'public, max-age=3600'
+
+/*
+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`.
+
+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.
+*/
+export function createPublicAssetServer({
+    publicDir,
+    publicAssets,
+}: {
+    publicDir: string
+    publicAssets?: Assets
+}): (req: Request, url: URL) => Promise<Response | undefined> {
+    const headerCache = new Map<string, { base: HeadersInit; zstd: HeadersInit }>()
+    function headersFor(pathname: string): { base: HeadersInit; zstd: HeadersInit } {
+        const cached = headerCache.get(pathname)
+        if (cached) {
+            return cached
+        }
+        const base: HeadersInit = {
+            'Content-Type': mimeForExtension(pathname),
+            Vary: 'Accept-Encoding',
+            'Cache-Control': PUBLIC_CACHE_CONTROL,
+        }
+        const bundle = { base, zstd: { ...base, 'Content-Encoding': 'zstd' } }
+        headerCache.set(pathname, bundle)
+        return bundle
+    }
+
+    return async function servePublicAsset(req, url) {
+        if (containsTraversal(req.url)) {
+            return undefined
+        }
+        const wantsZstd = (req.headers.get('accept-encoding') ?? '').toLowerCase().includes('zstd')
+        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(Bun.zstdDecompressSync(compressed), { headers: base })
+        }
+        const file = Bun.file(publicDir + url.pathname)
+        if (!(await file.exists())) {
+            return undefined
+        }
+        return new Response(file, { headers: base })
+    }
+}