@briancray/belte 0.1.0

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

@@ -0,0 +1,160 @@
+import { createPushIterator } from '../../shared/createPushIterator.ts'
+import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
+import { getActiveServer } from '../runtime/getActiveServer.ts'
+import { registerSocket } from './registerSocket.ts'
+import type { Socket } from './types/Socket.ts'
+import type { SocketOptions } from './types/SocketOptions.ts'
+
+/*
+Server-side construction of a Socket. The bundler rewrites every
+`export const NAME = socket(opts)` inside `src/server/sockets/<file>.ts` into
+`__belteDefineSocket__("<name>", opts)` so the file path becomes the
+socket's identity. Each subscriber gets its own queue + notifier, the
+optional history buffer is shared, and outbound fan-out rides Bun's
+native `server.publish` so connected ws clients are notified by the
+runtime in C rather than per-client iteration in JS.
+
+The Socket itself is the AsyncIterable: `for await (const m of chat)`
+replays the full history buffer then tails live. `chat.tail(count)`
+opens a subscription that replays the last `count` items (default `0`,
+clamped to the configured `history` max). When `ttl` is set, history
+entries older than `ttl` ms are evicted lazily on every read/append —
+no timer runs in the background. `chat.publish(m)` is isomorphic —
+called server-side it both notifies in-process iterators and broadcasts
+to remote subscribers; called client-side (via socketProxy) it sends a
+`pub` frame the dispatcher validates and forwards.
+*/
+export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<T> {
+    const historySize = opts.history ?? 0
+    const ttl = opts.ttl
+    const schema = opts.schema
+    const jsonSchema = opts.jsonSchema
+    const clients = resolveClientFlags(opts.clients, schema !== undefined)
+    type BufferEntry = { value: T; expiresAt: number | undefined }
+    const buffer: BufferEntry[] = []
+    const subscribers = new Set<(message: T) => void>()
+    const topic = `socket:${name}`
+
+    /*
+    History entries are stored with an expiry timestamp. When `ttl` is set,
+    every read/append starts by dropping leading entries whose expiry has
+    passed — entries are appended in order so the expired prefix is
+    contiguous. No timer/setInterval is needed: expiry is lazy.
+    */
+    function pruneExpired(now: number): void {
+        if (ttl === undefined) {
+            return
+        }
+        let drop = 0
+        for (const entry of buffer) {
+            if (entry.expiresAt !== undefined && entry.expiresAt <= now) {
+                drop++
+            } else {
+                break
+            }
+        }
+        if (drop > 0) {
+            buffer.splice(0, drop)
+        }
+    }
+
+    /*
+    Active server is set once per process during createServer's boot,
+    immediately after Bun.serve resolves, and never reassigned. Resolve
+    it lazily on the first publish then keep the reference so subsequent
+    publishes skip the per-call getter.
+    */
+    let cachedServer: ReturnType<typeof getActiveServer>
+    /*
+    When a schema is attached, publish() validates synchronously and
+    throws on bad payloads. Standard Schema's validate() is generally
+    async — but for the synchronous server-side publish path we treat
+    a Promise return as a programming error (publish must be sync to
+    preserve in-process notify ordering). Schemas that need async
+    refinement should pre-validate at the call site instead.
+    */
+    function validateSync(message: T): T {
+        if (!schema) {
+            return message
+        }
+        const result = schema['~standard'].validate(message)
+        if (result instanceof Promise) {
+            throw new Error(
+                `[belte] socket "${name}" schema returned a Promise — sockets require sync validation`,
+            )
+        }
+        if (result.issues) {
+            throw new Error(
+                `[belte] socket "${name}" publish payload failed validation: ${JSON.stringify(result.issues)}`,
+            )
+        }
+        return result.value as T
+    }
+    function publish(message: T): void {
+        const validated = validateSync(message)
+        if (historySize > 0) {
+            const now = Date.now()
+            pruneExpired(now)
+            buffer.push({ value: validated, expiresAt: ttl === undefined ? undefined : now + ttl })
+            if (buffer.length > historySize) {
+                buffer.shift()
+            }
+        }
+        for (const notify of subscribers) {
+            notify(validated)
+        }
+        const server = cachedServer ?? (cachedServer = getActiveServer())
+        if (server) {
+            server.publish(topic, JSON.stringify({ type: 'msg', socket: name, message: validated }))
+        }
+    }
+
+    /*
+    replay === 'all' replays the entire buffer (bare `for await`);
+    a number replays the last min(count, buffer.length) items.
+    */
+    function iterate(replay: number | 'all'): AsyncIterable<T> {
+        return {
+            [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+                let subscriber: ((message: T) => void) | undefined
+                const iter = createPushIterator<T>(() => {
+                    if (subscriber) {
+                        subscribers.delete(subscriber)
+                    }
+                })
+                pruneExpired(Date.now())
+                const replayCount =
+                    replay === 'all' ? buffer.length : Math.min(replay, buffer.length)
+                if (replayCount > 0) {
+                    const start = buffer.length - replayCount
+                    for (let index = start; index < buffer.length; index++) {
+                        iter.push((buffer[index] as BufferEntry).value)
+                    }
+                }
+                subscriber = (message: T) => iter.push(message)
+                subscribers.add(subscriber)
+                return iter
+            },
+        }
+    }
+
+    const self: Socket<T> = {
+        name,
+        clients,
+        publish,
+        tail: (count = 0) => iterate(count),
+        [Symbol.asyncIterator]: () => iterate('all')[Symbol.asyncIterator](),
+    }
+    registerSocket({
+        socket: self as Socket<unknown>,
+        allowClientPublish: opts.clientPublish ?? false,
+        schema,
+        jsonSchema,
+        clients,
+        snapshotHistory: () => {
+            pruneExpired(Date.now())
+            return buffer.map((entry) => entry.value)
+        },
+    })
+    return self
+}

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

@@ -0,0 +1,6 @@
+import { socketRegistry } from './socketRegistry.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+export function lookupSocket(name: string): SocketRegistryEntry | undefined {
+    return socketRegistry.get(name)
+}

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

@@ -0,0 +1,6 @@
+import { socketRegistry } from './socketRegistry.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+export function registerSocket(entry: SocketRegistryEntry): void {
+    socketRegistry.set(entry.socket.name, entry)
+}

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

@@ -0,0 +1,9 @@
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Process-wide registry of every Socket declared in the app. defineSocket
+inserts on first construction; the dispatcher reads on every `sub` /
+`pub` frame so it can find the right Socket by name and check the
+opted-in `allowClientPublish` policy.
+*/
+export const socketRegistry = new Map<string, SocketRegistryEntry>()

package/src/lib/server/sockets/types/Socket.ts

@@ -0,0 +1,21 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+
+/*
+Bidirectional named broadcast primitive. Declared once with `socket<T>()`
+inside a file under `src/server/sockets/`; the same import resolves to a server-side
+fan-out and a client-side ws proxy by build target. Iterating the socket
+opens a subscription with full history replay if the topic was declared
+with `{ history: n }`. `.tail(count)` opens one that replays the last
+`count` items (default `0`, clamped to the topic's history max) before
+tailing live. `publish` is isomorphic: server code publishes in-process
+and fans out to remote subscribers; client code sends a `pub` frame the
+dispatcher validates against the topic's `clientPublish` flag. `clients`
+exposes which adapter surfaces (browser / mcp / cli) advertise this
+socket.
+*/
+export interface Socket<T> extends AsyncIterable<T> {
+    readonly name: string
+    readonly clients: ClientFlags
+    publish(message: T): void
+    tail(count?: number): AsyncIterable<T>
+}

package/src/lib/server/sockets/types/SocketClientFrame.ts

@@ -0,0 +1,18 @@
+/*
+Wire frame the browser sends over the multiplexed socket connection.
+`sub` opens a subscription against `socket`. The optional `replay`
+controls history: omitted = full replay (default `for await`); a
+number = at most that many trailing items (clamped server-side to the
+topic's history max). `unsub` closes one. `pub` publishes a message —
+the dispatcher checks the topic's `clientPublish` flag before fanning
+out.
+
+`sub` is the per-subscription id minted client-side; the server treats
+it as opaque and routes inbound `msg|err|end` frames back to the same
+id so one ws can multiplex many subscriptions to the same or different
+sockets.
+*/
+export type SocketClientFrame =
+    | { type: 'sub'; sub: string; socket: string; replay?: number }
+    | { type: 'unsub'; sub: string }
+    | { type: 'pub'; socket: string; message: unknown }

package/src/lib/server/sockets/types/SocketOptions.ts

@@ -0,0 +1,22 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { StandardSchemaV1 } from '../../rpc/types/StandardSchemaV1.ts'
+
+/*
+Server-side options passed when declaring a socket via `socket<T>(opts)`.
+History buffer (replayed on first iteration), per-frame TTL (history
+entries older than `ttl` ms are evicted before replay), and the client-
+publish gate (off by default — server-only topics ignore pub frames
+coming over the wire). Optional Standard Schema validates payloads on
+publish and gives MCP / CLI a typed payload to describe. `clients`
+controls which non-browser surfaces (mcp / cli) expose this socket;
+browser is the historical default. All server-only state the bundler
+strips out of the client stub.
+*/
+export type SocketOptions<Schema extends StandardSchemaV1 = StandardSchemaV1> = {
+    history?: number
+    ttl?: number
+    clientPublish?: boolean
+    schema?: Schema
+    jsonSchema?: Record<string, unknown>
+    clients?: Partial<ClientFlags>
+}

package/src/lib/server/sockets/types/SocketRegistryEntry.ts

@@ -0,0 +1,18 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { StandardSchemaV1 } from '../../rpc/types/StandardSchemaV1.ts'
+import type { Socket } from './Socket.ts'
+
+/*
+Per-socket registry record. The Socket itself stays uniform between
+server and client by parking policy state (history snapshot, client
+publish gate, payload schema, client targeting) here instead of leaking
+into the public Socket shape.
+*/
+export type SocketRegistryEntry = {
+    socket: Socket<unknown>
+    allowClientPublish: boolean
+    schema: StandardSchemaV1 | undefined
+    jsonSchema: Record<string, unknown> | undefined
+    clients: ClientFlags
+    snapshotHistory(): unknown[]
+}

package/src/lib/server/sockets/types/SocketRoutes.ts

@@ -0,0 +1,10 @@
+import type { Socket } from './Socket.ts'
+
+/*
+Manifest of socket-name → module loader. Produced by the resolver
+plugin from each `.ts` under src/server/sockets/. Each module has exactly one
+named export, a Socket whose `.name` was stamped in by the bundler
+rewrite. The dispatcher imports a module on first access and caches the
+resolved Socket against its name.
+*/
+export type SocketRoutes = Record<string, () => Promise<Record<string, Socket<unknown>>>>

package/src/lib/server/sockets/types/SocketServerFrame.ts

@@ -0,0 +1,15 @@
+/*
+Wire frame the server sends over the multiplexed socket connection.
+
+`msg` is keyed by socket name (not sub id) because one publish fans
+out to every client subscribed to the socket via Bun's native
+publish — the client demuxes against every local sub of that socket.
+`end` and `err` are per-sub because they're subscription-lifecycle
+events; `err.message` is the only thrown-value field forwarded so the
+wire stays JSON-safe and server-side stack traces never reach the
+client.
+*/
+export type SocketServerFrame =
+    | { type: 'msg'; socket: string; message: unknown }
+    | { type: 'end'; sub: string }
+    | { type: 'err'; sub: string; message: string }

package/src/lib/server/sse.ts

@@ -0,0 +1,47 @@
+/*
+Wraps an AsyncIterable<Frame> in a Response whose body is
+Server-Sent Events (text/event-stream) — each frame becomes one
+`data: <json>\n\n` event. Used inside an rpc handler to expose a
+generator over plain HTTP so EventSource (or `subscribe(fn.stream)(args)`
+on the client) can consume it frame-by-frame.
+
+  export const orderFeed = GET<Args>((args) =>
+      sse(async function* () {
+          for await (const order of db.watchOrders(args)) yield order
+      }())
+  )
+
+A 15s keepalive comment (`: keepalive\n\n`) is sent between frames so
+intermediaries (proxies, load balancers) don't drop an idle connection.
+Comments are ignored by EventSource per the spec, so they're invisible to
+consumers.
+
+Cancellation flows from the consumer through ReadableStream's `cancel`
+into `iter.return()` so the handler's `for await` exits via its normal
+control path. Errors are emitted as an `event: error` frame carrying only
+the message (full error logged server-side) before the stream closes;
+EventSource surfaces this via its `error` listener and `subscribe()`
+maps it to the entry's `error` field.
+*/
+import { NO_STORE } from '../shared/cacheControlValues.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { streamFromIterator } from './runtime/streamFromIterator.ts'
+
+const KEEPALIVE_INTERVAL_MS = 15000
+
+export function sse<Frame>(iterable: AsyncIterable<Frame>): TypedResponse<Frame> {
+    const body = streamFromIterator(iterable, {
+        encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
+        encodeError: (message) => `event: error\ndata: ${JSON.stringify({ message })}\n\n`,
+        keepaliveMs: KEEPALIVE_INTERVAL_MS,
+        keepalivePayload: ': keepalive\n\n',
+    })
+    return new Response(body, {
+        headers: {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': NO_STORE,
+            'X-Content-Type-Options': 'nosniff',
+            Connection: 'keep-alive',
+        },
+    }) as TypedResponse<Frame>
+}

package/src/lib/shared/activeCacheStore.ts

@@ -0,0 +1,20 @@
+import { cacheStoreSlot } from './cacheStoreSlot.ts'
+import { createCacheStore } from './createCacheStore.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Resolves the active CacheStore. The runtime is registered via
+`setCacheStoreResolver` from the server entry (request-scoped via ALS)
+or the client entry (module-level singleton). If no resolver is registered,
+a single fallback store is created lazily so isolated tests still work.
+*/
+export function activeCacheStore(): CacheStore {
+    const fromResolver = cacheStoreSlot.resolver?.()
+    if (fromResolver) {
+        return fromResolver
+    }
+    if (!cacheStoreSlot.fallback) {
+        cacheStoreSlot.fallback = createCacheStore()
+    }
+    return cacheStoreSlot.fallback
+}

package/src/lib/shared/buildRpcRequest.ts

@@ -0,0 +1,61 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+
+/*
+Builds the Request a verb helper uses to invoke its handler. Same shape on
+both sides (server defineVerb + client remoteProxy) so the cache key
+derivation and SSR snapshot round-trip identically. $rpc URLs are flat
+(no `:name` segments): GET/DELETE/HEAD serialise args onto the query
+string; POST/PUT/PATCH send them as application/json.
+
+`baseUrl` provides the origin needed by the Request constructor — on the
+server it's the inbound request's URL (so handlers reading `request.url` see
+the caller's host), in the browser it's window.location. `headers` lets the
+server pre-populate the synthetic Request with forwarded session headers;
+the client passes nothing.
+*/
+export function buildRpcRequest({
+    method,
+    url,
+    args,
+    baseUrl,
+    headers,
+}: {
+    method: HttpVerb
+    url: string
+    args: unknown
+    baseUrl: string
+    headers?: Headers
+}): Request {
+    const requestHeaders = headers ?? new Headers()
+    if (method === 'GET' || method === 'DELETE' || method === 'HEAD') {
+        const target = appendQuery(method, url, args)
+        return new Request(new URL(target, baseUrl).href, { method, headers: requestHeaders })
+    }
+    if (args === undefined) {
+        return new Request(new URL(url, baseUrl).href, { method, headers: requestHeaders })
+    }
+    requestHeaders.set('content-type', 'application/json')
+    return new Request(new URL(url, baseUrl).href, {
+        method,
+        headers: requestHeaders,
+        body: JSON.stringify(args),
+    })
+}
+
+function appendQuery(method: HttpVerb, url: string, args: unknown): string {
+    if (args === undefined) {
+        return url
+    }
+    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+        const got = Array.isArray(args) ? 'array' : typeof args
+        throw new Error(`[belte] ${method} ${url} args must be a plain object — got ${got}`)
+    }
+    const entries = Object.entries(args as Record<string, unknown>).filter(
+        ([, value]) => value !== undefined,
+    )
+    if (entries.length === 0) {
+        return url
+    }
+    const suffix = new URLSearchParams(entries as Array<[string, string]>).toString()
+    return suffix === '' ? url : `${url}?${suffix}`
+}

package/src/lib/shared/cacheControlValues.ts

@@ -0,0 +1,8 @@
+/*
+Cache-Control values used by belte's framework responses. Centralised so
+the framework's policy (no-store on errors and rpc dispatch helpers,
+private/no-cache on SSR HTML) lives in one place and can't drift between
+the server core and the respond helpers.
+*/
+export const NO_STORE = 'no-store'
+export const SSR_CACHE_CONTROL = 'private, no-cache'

package/src/lib/shared/cacheStoreSlot.ts

@@ -0,0 +1,16 @@
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Internal slot the runtime entries register their resolver into. The
+server entry installs an ALS-backed resolver (request-scoped); the
+client entry installs a module-singleton resolver. `fallback` is a
+single lazy store used only when no resolver is registered — keeps
+isolated tests working without forcing them to spin up the runtime.
+*/
+export const cacheStoreSlot: {
+    resolver: (() => CacheStore | undefined) | undefined
+    fallback: CacheStore | undefined
+} = {
+    resolver: undefined,
+    fallback: undefined,
+}

package/src/lib/shared/canonicalJson.ts

@@ -0,0 +1,24 @@
+/*
+Stable JSON stringify: object keys are sorted recursively so equivalent values
+produce identical strings regardless of insertion order. Non-JSON values
+(functions, symbols) are dropped the same way native JSON.stringify drops them.
+Used to derive deterministic cache keys from explicit-key overrides and from
+auto-keyed POST/PUT/PATCH bodies. Walks the value once using JSON.stringify's
+replacer so no intermediate copies are allocated per level.
+*/
+export function canonicalJson(value: unknown): string {
+    return JSON.stringify(value, sortedKeysReplacer)
+}
+
+function sortedKeysReplacer(_key: string, value: unknown): unknown {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return value
+    }
+    const record = value as Record<string, unknown>
+    const sortedKeys = Object.keys(record).sort()
+    const sorted: Record<string, unknown> = {}
+    for (const key of sortedKeys) {
+        sorted[key] = record[key]
+    }
+    return sorted
+}

package/src/lib/shared/commandNameForUrl.ts

@@ -0,0 +1,17 @@
+/*
+Derives the MCP tool name / CLI subcommand name from an rpc URL. Strips
+the framework's `/rpc/` mount and joins nested folder segments with `-`
+so `users/list.ts` (mounted at `/rpc/users/list`) becomes `users-list`
+across both surfaces. Folder prefixing prevents collisions when two
+files in different folders share the same stem (e.g. `users/list.ts`
+and `posts/list.ts`); `/` is not a valid character in MCP tool names or
+typical CLI subcommands, so the join uses `-`.
+*/
+const RPC_PREFIX = '/rpc/'
+
+export function commandNameForUrl(url: string): string {
+    const trimmed = url.startsWith(RPC_PREFIX)
+        ? url.slice(RPC_PREFIX.length)
+        : url.replace(/^\//, '')
+    return trimmed.replaceAll('/', '-')
+}

package/src/lib/shared/createCacheStore.ts

@@ -0,0 +1,42 @@
+import { createSubscriber } from 'svelte/reactivity'
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Returns a fresh cache store. On the server, every request gets its own
+store via the AsyncLocalStorage RequestStore. On the client, a single
+module-level store is created at startup and shared across the tab.
+
+Each key gets a lazily-created Svelte subscriber that lives for the
+lifetime of the store. Reading a key from a tracking scope
+($derived / $effect) subscribes that scope; invalidating the key dispatches
+an 'invalidate' event whose detail is a Set of affected keys so each
+listener's lookup is O(1). When the entry is later re-created the same
+subscriber is reused — no listener churn, no risk of duplicate registrations
+during entry eviction. Svelte tears down the underlying listener on its
+own when the last tracker stops reading.
+*/
+export function createCacheStore(): CacheStore {
+    const entries = new Map<string, CacheEntry>()
+    const events = new EventTarget()
+    const subscribers = new Map<string, () => void>()
+
+    function subscribe(key: string): void {
+        let registered = subscribers.get(key)
+        if (!registered) {
+            registered = createSubscriber((update) => {
+                const onInvalidate = (event: Event) => {
+                    if ((event as CustomEvent<Set<string>>).detail.has(key)) {
+                        update()
+                    }
+                }
+                events.addEventListener('invalidate', onInvalidate)
+                return () => events.removeEventListener('invalidate', onInvalidate)
+            })
+            subscribers.set(key, registered)
+        }
+        registered()
+    }
+
+    return { entries, events, subscribe }
+}

package/src/lib/shared/createPushIterator.ts

@@ -0,0 +1,77 @@
+/*
+Single-slot-mailbox AsyncIterator factory shared by the in-process
+socket fan-out (defineSocket) and the client-side ws proxy
+(socketProxy). Callers push values, signal end, or signal an error;
+the iterator drains a queue then awaits the next push. Cancellation
+runs the optional `onClose` so subscribers can drop their backref.
+*/
+
+type Slot<T> = { kind: 'value'; value: T } | { kind: 'end' } | { kind: 'error'; message: string }
+
+export type PushIterator<T> = AsyncIterator<T, void, undefined> & {
+    push(value: T): void
+    end(): void
+    error(message: string): void
+}
+
+export function createPushIterator<T>(onClose?: () => void): PushIterator<T> {
+    const buffer: Slot<T>[] = []
+    let waiter: ((slot: Slot<T>) => void) | undefined
+    let closed = false
+
+    function deliver(slot: Slot<T>): void {
+        if (closed) {
+            return
+        }
+        if (waiter) {
+            const wake = waiter
+            waiter = undefined
+            wake(slot)
+            return
+        }
+        buffer.push(slot)
+    }
+
+    function close(): void {
+        if (closed) {
+            return
+        }
+        closed = true
+        onClose?.()
+    }
+
+    return {
+        push(value) {
+            deliver({ kind: 'value', value })
+        },
+        end() {
+            deliver({ kind: 'end' })
+        },
+        error(message) {
+            deliver({ kind: 'error', message })
+        },
+        async next() {
+            if (closed) {
+                return { value: undefined, done: true }
+            }
+            const slot = buffer.shift() ?? (await new Promise<Slot<T>>((r) => (waiter = r)))
+            if (slot.kind === 'end') {
+                close()
+                return { value: undefined, done: true }
+            }
+            if (slot.kind === 'error') {
+                close()
+                throw new Error(slot.message)
+            }
+            return { value: slot.value, done: false }
+        },
+        async return() {
+            if (!closed) {
+                close()
+                waiter?.({ kind: 'end' })
+                waiter = undefined
+            }
+            return { value: undefined, done: true }
+        },
+    }
+}