@belte/belte 0.19.0

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

@@ -0,0 +1,45 @@
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheSnapshot } from '../../shared/types/CacheSnapshot.ts'
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+import { snapshotEntryFromCache } from './snapshotEntryFromCache.ts'
+
+/*
+Partitions the request-scoped cache for SSR. Entries settled by the time
+`render()` returns were consumed via `await` (render blocked on them) and ship
+inline in the document's `__SSR__` blob. Entries still pending were consumed
+via `{#await}` — render emitted their pending branch without blocking — so they
+go to `pending` for the response streamer to drain and resolve over the wire.
+
+Unlike the old buffer-everything path, this never awaits the pending promises:
+that's the whole point of streaming. Settled entries are read concurrently (the
+awaits are immediate since they're already resolved, but their body reads run in
+parallel); pending entries are handed back as-is for the streamer to await one
+chunk at a time.
+*/
+export async function serializeCacheSnapshot(store: CacheStore): Promise<CacheSnapshot> {
+    const settled: CacheEntry[] = []
+    const pending: CacheEntry[] = []
+    for (const entry of store.entries.values()) {
+        /* Producer entries carry no wire request — nothing to rehydrate against, skip. */
+        if (!entry.request) {
+            continue
+        }
+        const method = entry.request.method.toUpperCase()
+        if (method !== 'GET' && method !== 'DELETE') {
+            continue
+        }
+        if (entry.settled) {
+            settled.push(entry)
+        } else {
+            pending.push(entry)
+        }
+    }
+    const snapshots = await Promise.all(
+        settled.map((entry) => snapshotEntryFromCache(store, entry)),
+    )
+    const inline = snapshots.filter(
+        (snapshot): snapshot is CacheSnapshotEntry => snapshot !== undefined,
+    )
+    return { inline, pending }
+}

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

@@ -0,0 +1,13 @@
+import type { Server } from 'bun'
+
+/*
+Internal holder for the active Bun.serve instance. setActiveServer is
+called once from createServer after Bun.serve resolves; the public
+`server()` function and any internal callers read through this slot
+and throw when accessed before init completes. `Server<unknown>` matches
+Bun's generic — ws.data is opaque to user code since the only ws path
+is the framework-managed sockets dispatcher.
+*/
+export const serverSlot: { active: Server<unknown> | undefined } = {
+    active: undefined,
+}

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

@@ -0,0 +1,6 @@
+import type { Server } from 'bun'
+import { serverSlot } from './serverSlot.ts'
+
+export function setActiveServer(server: Server<unknown>): void {
+    serverSlot.active = server
+}

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

@@ -0,0 +1,81 @@
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+
+/*
+Awaits one cache entry and turns it into a wire-safe snapshot, or undefined
+when it can't ship. Shared by the inline snapshot path (settled entries,
+resolves immediately) and the streaming drain (pending {#await} entries,
+resolves whenever the underlying fetch lands). Only GET/DELETE with a textual
+Content-Type survive — other methods can't be replayed without the original
+request body, and binary bodies don't round-trip through JSON.
+
+Reads the body once and replaces the entry's promise with a string-bodied
+Response so later `shareable()` clones operate on a buffered body instead of
+teeing the original stream. Returns undefined on a rejected fetch (the client
+falls back to a live re-fetch on cache miss) or when the entry was evicted /
+replaced between resolution and read (a concurrent invalidate) so the snapshot
+never ships a key that no longer matches the live store.
+*/
+export async function snapshotEntryFromCache(
+    store: CacheStore,
+    entry: CacheEntry,
+): Promise<CacheSnapshotEntry | undefined> {
+    /* Producer entries have no wire request to replay — they never snapshot. */
+    if (!entry.request) {
+        return undefined
+    }
+    const method = entry.request.method.toUpperCase()
+    if (method !== 'GET' && method !== 'DELETE') {
+        return undefined
+    }
+    const response = await readSettled(entry.promise as Promise<Response>)
+    if (!response) {
+        return undefined
+    }
+    if (store.entries.get(entry.key) !== entry) {
+        return undefined
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (!isTextual(contentType)) {
+        return undefined
+    }
+    const body = await response.text()
+    entry.promise = Promise.resolve(
+        new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        }),
+    )
+    return {
+        key: entry.key,
+        url: entry.request.url,
+        method,
+        status: response.status,
+        statusText: response.statusText,
+        headers: Array.from(response.headers.entries()),
+        body,
+    }
+}
+
+async function readSettled(promise: Promise<Response>): Promise<Response | undefined> {
+    try {
+        return await promise
+    } catch {
+        return undefined
+    }
+}
+
+function isTextual(contentType: string): boolean {
+    if (contentType.startsWith('text/')) {
+        return true
+    }
+    if (contentType.includes('json')) {
+        return true
+    }
+    if (contentType.includes('xml')) {
+        return true
+    }
+    return false
+}

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

@@ -0,0 +1,37 @@
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+import type { StreamedResolution } from '../../shared/types/StreamedResolution.ts'
+import { snapshotEntryFromCache } from './snapshotEntryFromCache.ts'
+
+/*
+Drains the pending ({#await}) cache entries in resolution order — whichever
+fetch lands next is yielded next, so a slow entry never blocks a fast one
+behind it. Yields exactly one StreamedResolution per entry: the snapshot when
+serialization succeeds, or a `{ key, miss }` marker when the body can't ship so
+the client placeholder re-fetches instead of hanging on a deferred that never
+settles.
+*/
+export async function* streamCacheResolutions(
+    store: CacheStore,
+    pending: CacheEntry[],
+): AsyncIterable<StreamedResolution> {
+    /*
+    Tag each pending serialization with its key so the loop can drop exactly
+    the one that just settled. Deleting inside the `.then` instead would race
+    the loop — already-resolved promises empty the map before the first
+    Promise.race runs — so removal happens here, after the await.
+    */
+    const inflight = new Map<string, Promise<{ key: string; snapshot?: CacheSnapshotEntry }>>()
+    for (const entry of pending) {
+        inflight.set(
+            entry.key,
+            snapshotEntryFromCache(store, entry).then((snapshot) => ({ key: entry.key, snapshot })),
+        )
+    }
+    while (inflight.size > 0) {
+        const { key, snapshot } = await Promise.race(inflight.values())
+        inflight.delete(key)
+        yield snapshot ?? { key, miss: true }
+    }
+}

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

@@ -0,0 +1,86 @@
+/*
+Shared body builder for the streaming respond helpers (`jsonl`, `sse`).
+Both flow the same shape — pull from an AsyncIterator, encode each frame
+to bytes, emit a sentinel `error` frame on a generator throw, and route
+ReadableStream's `cancel` into `iter.return()` so the handler's
+`for await` exits via its normal control path. Only the per-frame
+encoding and the optional keepalive payload differ between the two.
+
+Keepalive is opt-in: SSE uses `: keepalive\n\n` every 15s so proxies
+don't drop an idle connection; jsonl has no spec-defined comment, so it
+omits keepalive entirely.
+*/
+
+export type StreamEncoder<T> = {
+    encodeFrame: (value: T) => string
+    encodeError: (message: string) => string
+    keepaliveMs?: number
+    keepalivePayload?: string
+}
+
+export function streamFromIterator<T>(
+    iterable: AsyncIterable<T>,
+    encoder: StreamEncoder<T>,
+): ReadableStream<Uint8Array> {
+    const textEncoder = new TextEncoder()
+    const iterator = iterable[Symbol.asyncIterator]()
+    let keepalive: ReturnType<typeof setInterval> | undefined
+
+    function stopKeepalive(): void {
+        if (keepalive !== undefined) {
+            clearInterval(keepalive)
+            keepalive = undefined
+        }
+    }
+
+    return new ReadableStream<Uint8Array>({
+        start(controller) {
+            if (encoder.keepaliveMs !== undefined && encoder.keepalivePayload !== undefined) {
+                const payload = textEncoder.encode(encoder.keepalivePayload)
+                keepalive = setInterval(() => {
+                    /*
+                    Every close/cancel path clears this interval synchronously,
+                    so a tick can't normally hit a closed controller — but
+                    enqueue throws on a closed/errored stream, and an uncaught
+                    throw in a timer crashes the process. Guard + self-stop.
+                    */
+                    try {
+                        controller.enqueue(payload)
+                    } catch {
+                        stopKeepalive()
+                    }
+                }, encoder.keepaliveMs)
+            }
+        },
+        async pull(controller) {
+            try {
+                const next = await iterator.next()
+                if (next.done) {
+                    stopKeepalive()
+                    controller.close()
+                    return
+                }
+                controller.enqueue(textEncoder.encode(encoder.encodeFrame(next.value)))
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error)
+                controller.enqueue(textEncoder.encode(encoder.encodeError(message)))
+                stopKeepalive()
+                controller.close()
+            }
+        },
+        cancel(reason) {
+            stopKeepalive()
+            /*
+            Route cancel into the generator's normal exit, but swallow a
+            rejection from its cleanup: a `finally` that throws on `.return()`
+            would otherwise surface as an unhandled rejection (process-fatal
+            under Bun's default) on a client disconnect — a path every
+            sse/jsonl/resolve stream hits routinely.
+            */
+            return iterator.return?.(reason)?.then(
+                () => undefined,
+                () => undefined,
+            )
+        },
+    })
+}

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

@@ -0,0 +1,64 @@
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+
+/*
+Cross-request holding area bridging an SSR render to its out-of-band resolution
+stream. When a page flushes with pending {#await} reads, renderPage stashes the
+request-scoped cache store plus its in-flight entries here under a random token
+and ships the token in `__SSR__`. The browser then opens the resolve endpoint,
+which TAKES the stash and awaits those SAME promises — so the handlers run once,
+not again, even though the resolve stream is a separate request.
+
+The SSR request scope exits as soon as the buffered document is sent, but the
+stash holds a reference so the store (and its in-flight promises) survive until
+the resolve stream drains them. A TTL evicts stashes whose client never connects
+(JS disabled, navigated away before hydration) so they can't leak.
+*/
+type StashedStream = {
+    store: CacheStore
+    pending: CacheEntry[]
+    timer: ReturnType<typeof setTimeout>
+}
+
+const streams = new Map<string, StashedStream>()
+
+const STASH_TTL_MS = 30_000
+
+/*
+The TTL bounds how long a stash lives, but not how many can pile up: a burst
+of streamed renders whose clients never connect would retain that many request
+stores until each times out. Cap the count and evict the oldest (insertion
+order on the Map) so peak memory stays bounded regardless of arrival rate.
+*/
+const MAX_STASHES = 1024
+
+export function stashPendingStream(store: CacheStore, pending: CacheEntry[]): string {
+    if (streams.size >= MAX_STASHES) {
+        const oldest = streams.keys().next().value
+        if (oldest !== undefined) {
+            const evicted = streams.get(oldest)
+            if (evicted) {
+                clearTimeout(evicted.timer)
+            }
+            streams.delete(oldest)
+        }
+    }
+    const token = crypto.randomUUID()
+    const timer = setTimeout(() => streams.delete(token), STASH_TTL_MS)
+    timer.unref?.()
+    streams.set(token, { store, pending, timer })
+    return token
+}
+
+/* Single-use: removes the stash so a token can't be drained twice. */
+export function takePendingStream(
+    token: string,
+): { store: CacheStore; pending: CacheEntry[] } | undefined {
+    const stashed = streams.get(token)
+    if (!stashed) {
+        return undefined
+    }
+    clearTimeout(stashed.timer)
+    streams.delete(token)
+    return { store: stashed.store, pending: stashed.pending }
+}

package/src/lib/server/runtime/types/Assets.ts

@@ -0,0 +1 @@
+export type Assets = Record<string, Uint8Array>

package/src/lib/server/runtime/types/RequestStore.ts

@@ -0,0 +1,27 @@
+import type { CacheStore } from '../../../shared/types/CacheStore.ts'
+
+/*
+Per-request state propagated through AsyncLocalStorage. Every field is
+populated once at the server's fetch boundary; helpers and verb-defined
+remote functions read from it without threading arguments through user code.
+The inbound request's AbortSignal is reached via `req.signal` rather than a
+separate field.
+*/
+export type RequestStore = {
+    url: URL
+    req: Request
+    cache: CacheStore
+    /*
+    The request's cookie jar, materialized lazily by the first cookies() call
+    and flushed to Set-Cookie headers when the scope returns. Undefined while a
+    request never touches cookies, so the common path parses and emits nothing.
+    */
+    cookies?: Bun.CookieMap
+    /*
+    File parts split off a multipart/form-data body by parseArgs, grouped by
+    field name, for files() to read. Files never enter the handler's args so the
+    input schema keeps validating a plain object; undefined when the request
+    carried no file parts.
+    */
+    files?: Record<string, File[]>
+}

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

@@ -0,0 +1,24 @@
+/*
+Merges a caller's `ResponseInit` over a respond helper's default headers.
+The helper's defaults seed the header set; the caller's headers overlay them
+per-key (so an explicit `cache-control` wins over the helper's `no-store`),
+and the rest of `init` (status, statusText) passes straight through. Shared
+by `json` / `jsonl` / `sse` / `error` / `redirect` so every helper accepts a
+final `ResponseInit` with identical override semantics.
+
+A helper that owns the status itself (`error`, `redirect`) passes it as the
+final `status` argument; it is applied last so it always wins over any
+`init.status`, keeping that precedence inside the helper rather than relying
+on each call site spreading in the right order.
+*/
+export function withResponseDefaults(
+    init: ResponseInit | undefined,
+    defaultHeaders: Record<string, string>,
+    status?: number,
+): ResponseInit {
+    const headers = new Headers(defaultHeaders)
+    new Headers(init?.headers).forEach((value, key) => {
+        headers.set(key, value)
+    })
+    return { ...init, headers, ...(status !== undefined && { status }) }
+}

package/src/lib/server/server.ts

@@ -0,0 +1,32 @@
+import type { Server } from 'bun'
+import { getActiveServer } from './runtime/getActiveServer.ts'
+import { inProcessServer } from './runtime/inProcessServer.ts'
+import { requestContext } from './runtime/requestContext.ts'
+
+/*
+Returns the active Bun.serve instance. Mirrors `request()`'s function-call
+shape so call sites appear in stack traces (a Proxy trap intermediates and
+obscures them).
+
+When no Bun.serve has booted, resolution forks on the request scope:
+- Inside a scope it is in-process dispatch (CLI / MCP / test client), which
+  never boots a server — return the no-op inProcessServer so handler idioms
+  (server().timeout/publish/requestIP …) run unchanged instead of throwing.
+  createServer sets the slot at boot before any request, so an empty slot
+  while a scope is live can only be in-process.
+- Outside any scope it is a genuine before-init misuse (module top-level /
+  app.ts init); keep throwing — silent undefined would mask it and strand
+  later property reads with cryptic errors.
+*/
+export function server(): Server<unknown> {
+    const active = getActiveServer()
+    if (active) {
+        return active
+    }
+    if (requestContext.getStore()) {
+        return inProcessServer
+    }
+    throw new Error(
+        '[belte] server() called before init — make sure your call happens inside or after app.ts init() resolves',
+    )
+}

package/src/lib/server/socket.ts

@@ -0,0 +1,31 @@
+import type { StandardSchemaV1 } from '../shared/types/StandardSchemaV1.ts'
+import type { Socket } from './sockets/types/Socket.ts'
+import type { SocketOptions } from './sockets/types/SocketOptions.ts'
+
+/*
+Declares a Socket inside a file under `src/server/sockets/`. Each file contains
+exactly one export, named after the file (e.g. `chat.ts` →
+`export const chat = socket<ChatMessage>(...)`). The bundler reads the
+export name from the filename and the socket name from the file path
+under `src/server/sockets/`, then rewrites this call to bind the name into the
+runtime implementation (defineSocket on the server, socketProxy on the
+client). Opts (history, clientPublish, schema, clients) live on the
+server side only; the client target discards them.
+
+When `schema` is set, `T` infers from `InferOutput<Schema>` and publish
+payloads validate against it on the server. `clients` controls which
+adapter surfaces (browser / mcp / cli) advertise the socket — defaults
+to browser-only when schemaless, all surfaces when a schema is present.
+
+This function exists only for the type signature; calling it directly
+means the bundler plugin didn't process the file, which throws.
+*/
+export function socket<Schema extends StandardSchemaV1>(
+    opts: SocketOptions<Schema> & { schema: Schema },
+): Socket<StandardSchemaV1.InferOutput<Schema>>
+export function socket<T = unknown>(opts?: SocketOptions): Socket<T>
+export function socket<T = unknown>(_opts?: SocketOptions): Socket<T> {
+    throw new Error(
+        '[belte] `socket(...)` was called outside an $sockets module — the socket helper is only valid as the value of `export const <filename> = ...` inside a file under src/server/sockets/',
+    )
+}