@briancray/belte 0.1.0

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

@@ -0,0 +1,84 @@
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+
+/*
+Drains the request-scoped cache store and returns a wire-safe snapshot of
+its entries. Only GET/DELETE entries with text/json bodies are included —
+POST/PUT/PATCH bodies can't be reconstructed on the client without also
+shipping the original request body, and binary bodies don't survive a JSON
+round-trip. Pending promises are awaited so the snapshot is fully resolved
+by the time SSR writes the document.
+
+The Response body is read once and the cache entry's promise is replaced
+with a fresh Response constructed from the text payload. Subsequent
+`shareable()` clones inside cache() then operate on a string-bodied
+Response instead of teeing the original streaming body twice per render.
+*/
+export async function serializeCacheSnapshot(store: CacheStore): Promise<CacheSnapshotEntry[]> {
+    const entries = Array.from(store.entries.values())
+    await Promise.allSettled(entries.map((entry) => entry.promise))
+
+    const snapshot: CacheSnapshotEntry[] = []
+    for (const entry of entries) {
+        const method = entry.request.method.toUpperCase()
+        if (method !== 'GET' && method !== 'DELETE') {
+            continue
+        }
+        /*
+        Between the awaitAll above and this read, a handler that calls
+        cache.invalidate() (or evicts via ttl=0) may have replaced this
+        entry. Skip the stale one — the live snapshot already reflects the
+        replacement, and including this entry would mismatch the active key.
+        */
+        const settled = store.entries.get(entry.key)
+        if (!settled || settled !== entry) {
+            continue
+        }
+        const response = await readSettled(entry.promise)
+        if (!response) {
+            continue
+        }
+        const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+        if (!isTextual(contentType)) {
+            continue
+        }
+        const body = await response.text()
+        const responseInit: ResponseInit = {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        }
+        entry.promise = Promise.resolve(new Response(body, responseInit))
+        snapshot.push({
+            key: entry.key,
+            url: entry.request.url,
+            method,
+            status: response.status,
+            statusText: response.statusText,
+            headers: Array.from(response.headers.entries()),
+            body,
+        })
+    }
+    return snapshot
+}
+
+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/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/streamFromIterator.ts

@@ -0,0 +1,76 @@
+/*
+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()
+            return iterator.return?.(reason)?.then(() => undefined)
+        },
+    })
+}

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

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

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

@@ -0,0 +1,6 @@
+export type CompileTarget =
+    | 'bun-darwin-arm64'
+    | 'bun-darwin-x64'
+    | 'bun-linux-arm64'
+    | 'bun-linux-x64'
+    | 'bun-windows-x64'

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

@@ -0,0 +1,15 @@
+import type { Server } from 'bun'
+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.
+*/
+export type RequestStore = {
+    url: URL
+    req: Request
+    signal: AbortSignal
+    cache: CacheStore
+    server: Server<unknown>
+}

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

@@ -0,0 +1,5 @@
+import type { CompileOptions } from 'svelte/compiler'
+
+export type SvelteConfig = {
+    compilerOptions?: Partial<CompileOptions>
+}

package/src/lib/server/server.ts

@@ -0,0 +1,19 @@
+import type { Server } from 'bun'
+import { getActiveServer } from './runtime/getActiveServer.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). Throws if accessed before
+Bun.serve has booted — silent undefined would mask the misuse and
+strand later property reads with cryptic errors.
+*/
+export function server(): Server<unknown> {
+    const active = getActiveServer()
+    if (!active) {
+        throw new Error(
+            '[belte] server() called before init — make sure your call happens inside or after app.ts init() resolves',
+        )
+    }
+    return active
+}

package/src/lib/server/socket.ts

@@ -0,0 +1,31 @@
+import type { StandardSchemaV1 } from './rpc/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/',
+    )
+}

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -0,0 +1,267 @@
+import type { ServerWebSocket } from 'bun'
+import { log } from '../../shared/log.ts'
+import { lookupSocket } from './lookupSocket.ts'
+import type { SocketClientFrame } from './types/SocketClientFrame.ts'
+import type { SocketRoutes } from './types/SocketRoutes.ts'
+
+type SocketDispatcher = {
+    open(ws: ServerWebSocket<unknown>): void
+    message(ws: ServerWebSocket<unknown>, data: string | Buffer): void
+    close(ws: ServerWebSocket<unknown>): void
+}
+
+/*
+Per-connection state: which sockets this ws is currently subscribed to
+(at the Bun-topic level), and which `sub` ids map to which socket. One
+ws can hold multiple subs against the same socket (e.g. one with
+history, one without); the Bun-topic subscription is reference-counted
+so we only `ws.unsubscribe` when the last local sub drops.
+*/
+type ConnectionState = {
+    subToSocket: Map<string, string>
+    socketSubs: Map<string, Set<string>>
+}
+
+/*
+Bridges the framework's socket registry to a single ws per client. All
+sockets multiplex over `/__belte/sockets`. Steady-state fan-out rides
+Bun's native `server.publish('socket:<name>', frame)` so the dispatcher
+is only on the path for sub/unsub bookkeeping and client-initiated pub
+validation; the published `msg` frames go from publisher to subscribers
+without touching JS per frame.
+
+`sub` opens a subscription: history is replayed (unless the client
+passed `tail: true`) directly to this ws, then the ws is added to the
+Bun topic. `unsub` drops the local sub and unsubscribes the ws from
+the Bun topic if no other local subs remain. `pub` validates the
+socket's `allowClientPublish` policy and calls `socket.publish` —
+which fans out to in-process iterators and republishes through Bun
+to other connected clients.
+
+Module-level lookups are cached per socket name: loading a socket
+module triggers its `defineSocket` call, which inserts into the
+registry. After that the dispatcher just reads the registry.
+*/
+export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher {
+    const moduleCache = new Map<string, Promise<void>>()
+    const connections = new WeakMap<ServerWebSocket<unknown>, ConnectionState>()
+
+    function ensureLoaded(name: string): Promise<void> | undefined {
+        const existing = moduleCache.get(name)
+        if (existing) {
+            return existing
+        }
+        const loader = sockets[name]
+        if (!loader) {
+            return undefined
+        }
+        const promise = loader().then(() => undefined)
+        moduleCache.set(name, promise)
+        return promise
+    }
+
+    function send(ws: ServerWebSocket<unknown>, frame: unknown): void {
+        if (ws.readyState !== 1) {
+            return
+        }
+        ws.send(JSON.stringify(frame))
+    }
+
+    function addSub(state: ConnectionState, name: string, sub: string): boolean {
+        state.subToSocket.set(sub, name)
+        let subs = state.socketSubs.get(name)
+        if (!subs) {
+            subs = new Set()
+            state.socketSubs.set(name, subs)
+        }
+        const wasEmpty = subs.size === 0
+        subs.add(sub)
+        return wasEmpty
+    }
+
+    function removeSub(state: ConnectionState, sub: string): string | undefined {
+        const name = state.subToSocket.get(sub)
+        if (!name) {
+            return undefined
+        }
+        state.subToSocket.delete(sub)
+        const subs = state.socketSubs.get(name)
+        if (!subs) {
+            return undefined
+        }
+        subs.delete(sub)
+        if (subs.size === 0) {
+            state.socketSubs.delete(name)
+            return name
+        }
+        return undefined
+    }
+
+    async function handleSub(
+        ws: ServerWebSocket<unknown>,
+        state: ConnectionState,
+        frame: Extract<SocketClientFrame, { type: 'sub' }>,
+    ): Promise<void> {
+        const loader = ensureLoaded(frame.socket)
+        if (!loader) {
+            send(ws, {
+                type: 'err',
+                sub: frame.sub,
+                message: `[belte] no socket registered at ${frame.socket}`,
+            })
+            send(ws, { type: 'end', sub: frame.sub })
+            return
+        }
+        try {
+            await loader
+        } catch (error) {
+            log.error(error)
+            send(ws, {
+                type: 'err',
+                sub: frame.sub,
+                message: error instanceof Error ? error.message : String(error),
+            })
+            send(ws, { type: 'end', sub: frame.sub })
+            return
+        }
+        const entry = lookupSocket(frame.socket)
+        if (!entry) {
+            send(ws, {
+                type: 'err',
+                sub: frame.sub,
+                message: `[belte] socket module at ${frame.socket} did not register a Socket export`,
+            })
+            send(ws, { type: 'end', sub: frame.sub })
+            return
+        }
+        const isFirstLocalSub = addSub(state, frame.socket, frame.sub)
+        if (isFirstLocalSub) {
+            ws.subscribe(`socket:${frame.socket}`)
+        }
+        /*
+        Replay history directly to this ws via ws.send (not
+        server.publish) so other connected subscribers don't see the
+        replay. Live messages published from now on flow through the
+        Bun topic the ws just joined; clients may observe live messages
+        interleaved with the tail of history, so user payloads should
+        carry an id/timestamp when ordering matters.
+
+        `replay === undefined` means full replay (bare `for await`);
+        a number is clamped to the buffer length so the client can ask
+        for "as many as available, up to N".
+        */
+        const history = entry.snapshotHistory()
+        const replayCount =
+            frame.replay === undefined ? history.length : Math.min(frame.replay, history.length)
+        if (replayCount > 0) {
+            const start = history.length - replayCount
+            for (let index = start; index < history.length; index++) {
+                send(ws, { type: 'msg', socket: frame.socket, message: history[index] })
+            }
+        }
+    }
+
+    function handleUnsub(
+        ws: ServerWebSocket<unknown>,
+        state: ConnectionState,
+        frame: Extract<SocketClientFrame, { type: 'unsub' }>,
+    ): void {
+        const emptied = removeSub(state, frame.sub)
+        if (emptied) {
+            ws.unsubscribe(`socket:${emptied}`)
+        }
+        send(ws, { type: 'end', sub: frame.sub })
+    }
+
+    async function handlePub(
+        ws: ServerWebSocket<unknown>,
+        frame: Extract<SocketClientFrame, { type: 'pub' }>,
+    ): Promise<void> {
+        const loader = ensureLoaded(frame.socket)
+        if (!loader) {
+            return
+        }
+        try {
+            await loader
+        } catch (error) {
+            log.error(error)
+            return
+        }
+        const entry = lookupSocket(frame.socket)
+        if (!entry) {
+            return
+        }
+        if (!entry.allowClientPublish) {
+            /*
+            Silent drop: the publish is rejected because the topic
+            wasn't declared `{ clientPublish: true }`. Surfacing this as
+            an error per-publish would tempt apps to attempt-then-handle
+            instead of routing through an HTTP route for auth. Log it
+            once per process at debug level (out of scope here) if
+            visibility is needed.
+            */
+            return
+        }
+        /*
+        publish() runs the topic's optional Standard Schema synchronously
+        and throws on failure (see defineSocket.validateSync). The
+        dispatcher invokes us via `void handlePub(...)`, so an unhandled
+        throw would surface as an unhandled promise rejection on every
+        malformed client frame. Catch + log so a buggy client can't take
+        the process down.
+        */
+        try {
+            entry.socket.publish(frame.message)
+        } catch (error) {
+            log.error(error)
+        }
+        /*
+        ws parameter retained for future per-ws auth context (cookies on
+        upgrade) the canPublish hook would consult.
+        */
+        void ws
+    }
+
+    return {
+        open(ws) {
+            connections.set(ws, { subToSocket: new Map(), socketSubs: new Map() })
+        },
+
+        message(ws, data) {
+            const state = connections.get(ws)
+            if (!state) {
+                return
+            }
+            const text = typeof data === 'string' ? data : data.toString('utf8')
+            let frame: SocketClientFrame
+            try {
+                frame = JSON.parse(text) as SocketClientFrame
+            } catch {
+                return
+            }
+            if (frame.type === 'sub') {
+                void handleSub(ws, state, frame)
+                return
+            }
+            if (frame.type === 'unsub') {
+                handleUnsub(ws, state, frame)
+                return
+            }
+            if (frame.type === 'pub') {
+                void handlePub(ws, frame)
+                return
+            }
+        },
+
+        close(ws) {
+            const state = connections.get(ws)
+            if (!state) {
+                return
+            }
+            connections.delete(ws)
+            for (const name of state.socketSubs.keys()) {
+                ws.unsubscribe(`socket:${name}`)
+            }
+        },
+    }
+}