@briancray/belte 0.1.0

package/src/lib/shared/createRemoteFunction.ts

@@ -0,0 +1,89 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import type { RawRemoteFunction } from '../server/rpc/types/RawRemoteFunction.ts'
+import type { RemoteFunction } from '../server/rpc/types/RemoteFunction.ts'
+import { decodeResponse } from './decodeResponse.ts'
+import { keyForRemoteCall } from './keyForRemoteCall.ts'
+import { recordRemoteMeta } from './recordRemoteMeta.ts'
+import { subscribableFromResponse } from './subscribableFromResponse.ts'
+import type { ClientFlags } from './types/ClientFlags.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Assembles the public RemoteFunction shape used identically by the
+server-side defineVerb (in-process handler invocation) and the
+client-side remoteProxy (network fetch). Centralising the wiring here
+keeps the call/raw/stream/fetch semantics — including WeakMap meta
+recording, Content-Type decode, and Subscribable derivation — in one
+place so the two halves can't drift.
+
+- `buildRequest(args)` synthesizes the Request a meta reader (cache()) or
+  the client invoke needs. Server uses the inbound request's URL as the
+  base; client uses window.location. The result is memoised inside the
+  per-call `getRequest` thunk so the Request is built at most once per
+  call regardless of how many readers pull on it.
+- `invoke(args, getRequest)` actually runs the call: server defineVerb
+  runs the handler and ignores `getRequest`; client remoteProxy calls
+  `fetch(getRequest())`. The thunk lets the server skip the Request
+  allocation entirely on the SSR hot path — the only consumer that ever
+  forces it is cache(), via the meta thunk recorded below.
+- `parseArgsForFetch` is optional and only set by the server, so the
+  framework's router can call `.fetch(inboundRequest)` and have the
+  handler receive parsed args. Client `remoteProxy.fetch` just
+  forwards the request through invoke().
+*/
+export function createRemoteFunction<Args, Return>(opts: {
+    method: HttpVerb
+    url: string
+    clients: ClientFlags
+    buildRequest: (args: Args | undefined) => Request
+    invoke: (args: Args | undefined, getRequest: () => Request) => Promise<Response>
+    parseArgsForFetch?: (request: Request) => Promise<Args | undefined>
+}): RemoteFunction<Args, Return> {
+    const { method, url, clients, buildRequest, invoke, parseArgsForFetch } = opts
+
+    /*
+    Dispatch is the one-stop entry for both the plain call (no prebuilt
+    Request) and the fetch path (router hands us the inbound Request as
+    `prebuilt`). The `getRequest` thunk lazily synthesizes — or
+    short-circuits to the prebuilt one — and caches the result so the
+    client invoke + the cache meta reader share a single Request.
+    */
+    function dispatch(args: Args | undefined, prebuilt?: Request): Promise<Response> {
+        let cached = prebuilt
+        function getRequest(): Request {
+            return cached ?? (cached = buildRequest(args))
+        }
+        const promise = invoke(args, getRequest)
+        recordRemoteMeta(promise, getRequest)
+        return promise
+    }
+
+    function rawCall(args: Args): Promise<Response> {
+        return dispatch(args)
+    }
+    rawCall.method = method
+    rawCall.url = url
+    const raw = rawCall as RawRemoteFunction<Args>
+
+    function callable(args: Args): Promise<Return> {
+        return raw(args).then(decodeResponse) as Promise<Return>
+    }
+    callable.method = method
+    callable.url = url
+    callable.clients = clients
+    callable.raw = raw
+    callable.stream = (args?: Args): Subscribable<Return> => {
+        return subscribableFromResponse(keyForRemoteCall(method, url, args), () =>
+            raw(args as Args),
+        )
+    }
+    callable.fetch = parseArgsForFetch
+        ? async (request: Request): Promise<Response> => {
+              const args = await parseArgsForFetch(request)
+              return dispatch(args, request)
+          }
+        : (request: Request): Promise<Response> => {
+              return dispatch(undefined, request)
+          }
+    return callable as RemoteFunction<Args, Return>
+}

package/src/lib/shared/decodeResponse.ts

@@ -0,0 +1,47 @@
+import { HttpError } from '../server/HttpError.ts'
+import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+
+/*
+Decodes a Response into the natural body value based on Content-Type:
+  application/json (or `*\/+json`) → parsed JSON
+  text/*                           → string
+  204 No Content / empty body      → undefined
+  everything else                  → Blob
+
+Non-2xx responses throw HttpError so the happy path never has to check
+`.ok` — error handling moves into try/catch (or unhandled exception
+propagation), and the success path types as Promise<Return> cleanly.
+
+Streaming Content-Types (SSE / JSONL / NDJSON) throw a clear error
+rather than silently doing the wrong thing: response.text() would hang
+forever on a never-ending body and response.json() would fail mid-parse.
+The error points callers at the right tools — `subscribe(fn.stream)(args)`
+for a shared reactive view, or `fn.stream(args)` directly for a fresh
+per-call AsyncIterable — both of which know how to consume the body
+frame-by-frame.
+
+Callers that need headers, streaming, or per-status branching should use
+the `.raw(args)` escape hatch on the remote function instead — that
+returns the underlying Response untouched.
+*/
+export async function decodeResponse(response: Response): Promise<unknown> {
+    if (!response.ok) {
+        throw new HttpError(response)
+    }
+    if (response.status === 204) {
+        return undefined
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        throw new Error(
+            `[belte] response at ${response.url} is a stream (${contentType}) — use subscribe(fn.stream)(args) for a reactive view, or fn.stream(args) for per-call iteration, instead of awaiting the bare call or cache()`,
+        )
+    }
+    if (contentType.includes('json')) {
+        return response.json()
+    }
+    if (contentType.startsWith('text/')) {
+        return response.text()
+    }
+    return response.blob()
+}

package/src/lib/shared/detectTarget.ts

@@ -0,0 +1,27 @@
+import type { CompileTarget } from '../server/runtime/types/CompileTarget.ts'
+
+/*
+Picks the Bun compile target matching the current host. Throws if the
+platform/arch pair isn't one of the supported Bun standalone targets — the
+CLI's `--target` flag is the escape hatch for cross-compilation.
+*/
+const HOST_TO_TARGET: Record<string, CompileTarget> = {
+    'darwin-arm64': 'bun-darwin-arm64',
+    'darwin-x64': 'bun-darwin-x64',
+    'linux-arm64': 'bun-linux-arm64',
+    'linux-x64': 'bun-linux-x64',
+    'win32-x64': 'bun-windows-x64',
+}
+
+export function detectTarget(
+    platform: NodeJS.Platform = process.platform,
+    arch: NodeJS.Architecture = process.arch,
+): CompileTarget {
+    const target = HOST_TO_TARGET[`${platform}-${arch}`]
+    if (!target) {
+        throw new Error(
+            `[belte] unsupported host platform ${platform}/${arch}. Pass --target=<bun-...> explicitly.`,
+        )
+    }
+    return target
+}

package/src/lib/shared/findExportCallSite.ts

@@ -0,0 +1,479 @@
+/*
+Scans a module source character-by-character — skipping strings,
+templates, comments, and TypeScript generics — for an
+`export const <name> = <IDENT>(...)` binding the caller cares about.
+On a match returns the identifier text, the export name, and the byte
+ranges of the call's open and close parens; the $rpc and $sockets
+rewriters splice their runtime bindings into those ranges.
+
+The scanner enforces a single matching export per module: a second match
+throws `singleExportError` so each $rpc / $sockets file is required to
+declare exactly one remote function / socket.
+
+A regex pass would be tidier but it can't tell a `GET` mention inside a
+docstring or template literal from the real call, and it can't follow
+nested generics like `GET<Map<K, V>>(`.
+*/
+
+export type ExportCallSite = {
+    ident: string
+    exportName: string
+    callStart: number
+    parenStart: number
+    parenEnd: number
+}
+
+export function findExportCallSite(
+    source: string,
+    matchIdent: (ident: string) => boolean,
+    singleExportError: string,
+): ExportCallSite | undefined {
+    let found: ExportCallSite | undefined
+    const len = source.length
+    let i = 0
+    while (i < len) {
+        const c = source[i]
+        const next = source[i + 1]
+        if (c === '/' && next === '/') {
+            const newline = source.indexOf('\n', i + 2)
+            i = newline === -1 ? len : newline + 1
+            continue
+        }
+        if (c === '/' && next === '*') {
+            const end = source.indexOf('*/', i + 2)
+            i = end === -1 ? len : end + 2
+            continue
+        }
+        if (c === '/' && isRegexContext(source, i)) {
+            i = skipRegex(source, i + 1)
+            continue
+        }
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (isIdentStart(c) && !isIdentPart(source[i - 1])) {
+            let j = i + 1
+            while (j < len && isIdentPart(source[j])) {
+                j++
+            }
+            const ident = source.slice(i, j)
+            if (matchIdent(ident)) {
+                const tail = matchCallTail(source, j)
+                if (tail !== undefined) {
+                    const exportName = detectExportName(source, i)
+                    if (exportName !== undefined) {
+                        if (found !== undefined) {
+                            throw new Error(singleExportError)
+                        }
+                        const parenEnd = findCallEnd(source, tail)
+                        if (parenEnd === undefined) {
+                            throw new Error(`[belte] unmatched \`(\` after \`${ident}\` identifier`)
+                        }
+                        found = {
+                            ident,
+                            exportName,
+                            callStart: i,
+                            parenStart: tail,
+                            parenEnd,
+                        }
+                        i = parenEnd + 1
+                        continue
+                    }
+                }
+            }
+            i = j
+            continue
+        }
+        i++
+    }
+    return found
+}
+
+function skipString(source: string, start: number, quote: string): number {
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === quote) {
+            return i + 1
+        }
+        if (c === '\n') {
+            return i
+        }
+        i++
+    }
+    return source.length
+}
+
+function skipTemplate(source: string, start: number): number {
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === '`') {
+            return i + 1
+        }
+        if (c === '$' && source[i + 1] === '{') {
+            i = skipTemplateExpression(source, i + 2)
+            continue
+        }
+        i++
+    }
+    return source.length
+}
+
+function skipTemplateExpression(source: string, start: number): number {
+    let depth = 1
+    let i = start
+    while (i < source.length && depth > 0) {
+        const c = source[i]
+        if (c === '{') {
+            depth++
+            i++
+            continue
+        }
+        if (c === '}') {
+            depth--
+            i++
+            continue
+        }
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (c === '/' && source[i + 1] === '/') {
+            const newline = source.indexOf('\n', i + 2)
+            i = newline === -1 ? source.length : newline + 1
+            continue
+        }
+        if (c === '/' && source[i + 1] === '*') {
+            const end = source.indexOf('*/', i + 2)
+            i = end === -1 ? source.length : end + 2
+            continue
+        }
+        if (c === '/' && isRegexContext(source, i)) {
+            i = skipRegex(source, i + 1)
+            continue
+        }
+        i++
+    }
+    return i
+}
+
+function matchCallTail(source: string, after: number): number | undefined {
+    let j = after
+    while (j < source.length && isWhitespace(source[j])) {
+        j++
+    }
+    if (source[j] === '<') {
+        const closed = skipGenerics(source, j)
+        if (closed === undefined) {
+            return undefined
+        }
+        j = closed
+        while (j < source.length && isWhitespace(source[j])) {
+            j++
+        }
+    }
+    return source[j] === '(' ? j : undefined
+}
+
+/*
+Returns the index immediately after the matching `>` for a generic
+argument list starting at `start`. TypeScript type literals inside the
+generic (`<{ a: string; b: number }>`, function types `<() => X>`,
+tuples `<[A, B]>`, etc.) bring their own paired brackets and
+semicolons, so track depth across `<>`, `()`, `{}`, and `[]` and only
+count a closing `>` when every other bracket is balanced.
+Arrow-function `=>` is treated as a single token so the `>` doesn't
+prematurely close the generic.
+*/
+function skipGenerics(source: string, start: number): number | undefined {
+    let angleDepth = 0
+    let parenDepth = 0
+    let braceDepth = 0
+    let bracketDepth = 0
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (c === '<') {
+            angleDepth++
+        } else if (c === '>') {
+            const isArrow = source[i - 1] === '='
+            if (!isArrow && parenDepth === 0 && braceDepth === 0 && bracketDepth === 0) {
+                angleDepth--
+                if (angleDepth === 0) {
+                    return i + 1
+                }
+            }
+        } else if (c === '(') {
+            parenDepth++
+        } else if (c === ')') {
+            parenDepth--
+        } else if (c === '{') {
+            braceDepth++
+        } else if (c === '}') {
+            braceDepth--
+        } else if (c === '[') {
+            bracketDepth++
+        } else if (c === ']') {
+            bracketDepth--
+        }
+        i++
+    }
+    return undefined
+}
+
+/*
+Walks the call body, skipping strings/templates/comments and respecting
+nested `()` so brackets inside object literals or nested calls don't
+throw the depth count.
+*/
+function findCallEnd(source: string, parenStart: number): number | undefined {
+    let depth = 1
+    let i = parenStart + 1
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '"' || c === "'") {
+            i = skipString(source, i + 1, c)
+            continue
+        }
+        if (c === '`') {
+            i = skipTemplate(source, i + 1)
+            continue
+        }
+        if (c === '/' && source[i + 1] === '/') {
+            const newline = source.indexOf('\n', i + 2)
+            i = newline === -1 ? source.length : newline + 1
+            continue
+        }
+        if (c === '/' && source[i + 1] === '*') {
+            const end = source.indexOf('*/', i + 2)
+            i = end === -1 ? source.length : end + 2
+            continue
+        }
+        if (c === '/' && isRegexContext(source, i)) {
+            i = skipRegex(source, i + 1)
+            continue
+        }
+        if (c === '(') {
+            depth++
+        } else if (c === ')') {
+            depth--
+            if (depth === 0) {
+                return i
+            }
+        }
+        i++
+    }
+    return undefined
+}
+
+/*
+Looks backwards from a `<IDENT>(` callStart to confirm it was bound by
+`export const <name> = ...`. Returns the identifier in `<name>` if so,
+undefined otherwise — used to skip mentions of an identifier that
+isn't the module's declared export.
+*/
+function detectExportName(source: string, callStart: number): string | undefined {
+    let i = callStart - 1
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (source[i] !== '=') {
+        return undefined
+    }
+    i--
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    const nameEnd = i + 1
+    while (i >= 0 && isIdentPart(source[i])) {
+        i--
+    }
+    const nameStart = i + 1
+    if (nameStart === nameEnd) {
+        return undefined
+    }
+    const name = source.slice(nameStart, nameEnd)
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (!matchesBackwards(source, i, 'const')) {
+        return undefined
+    }
+    i -= 'const'.length
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (!matchesBackwards(source, i, 'export')) {
+        return undefined
+    }
+    return name
+}
+
+function matchesBackwards(source: string, end: number, keyword: string): boolean {
+    const start = end - keyword.length + 1
+    if (start < 0) {
+        return false
+    }
+    if (source.slice(start, end + 1) !== keyword) {
+        return false
+    }
+    return start === 0 || !isIdentPart(source[start - 1])
+}
+
+function isIdentStart(c: string | undefined): boolean {
+    if (c === undefined) {
+        return false
+    }
+    return (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c === '_' || c === '$'
+}
+
+function isIdentPart(c: string | undefined): boolean {
+    if (c === undefined) {
+        return false
+    }
+    return isIdentStart(c) || (c >= '0' && c <= '9')
+}
+
+function isWhitespace(c: string | undefined): boolean {
+    return c === ' ' || c === '\t' || c === '\n' || c === '\r'
+}
+
+/*
+A `/` starts a regex literal when the prior expression context expects an
+expression rather than a value — after an open delimiter, operator, or
+expression-prefix keyword (return, typeof, instanceof, in, of, delete,
+void, await, yield, new, throw, case, do). Otherwise `/` is division.
+Without this disambiguation a regex like `/^\//` reads as `/` (division),
+then `^`, `\`, `/`, `/` — and the final `//` pair fakes a line comment
+that swallows the rest of the line, eating any `)` that closes the
+enclosing call.
+*/
+const REGEX_PREFIX_KEYWORDS = new Set([
+    'return',
+    'typeof',
+    'instanceof',
+    'in',
+    'of',
+    'delete',
+    'void',
+    'await',
+    'yield',
+    'new',
+    'throw',
+    'case',
+    'do',
+])
+
+const REGEX_PUNCTUATION = new Set([
+    '(',
+    '[',
+    '{',
+    ',',
+    ';',
+    ':',
+    '?',
+    '!',
+    '&',
+    '|',
+    '^',
+    '~',
+    '+',
+    '-',
+    '*',
+    '%',
+    '<',
+    '>',
+    '=',
+    '/',
+])
+
+function isRegexContext(source: string, slashIndex: number): boolean {
+    let i = slashIndex - 1
+    while (i >= 0 && isWhitespace(source[i])) {
+        i--
+    }
+    if (i < 0) {
+        return true
+    }
+    const prev = source[i] as string
+    if (REGEX_PUNCTUATION.has(prev)) {
+        return true
+    }
+    if (isIdentPart(prev)) {
+        let start = i
+        while (start > 0 && isIdentPart(source[start - 1])) {
+            start--
+        }
+        return REGEX_PREFIX_KEYWORDS.has(source.slice(start, i + 1))
+    }
+    return false
+}
+
+/*
+Walks past a regex literal body, respecting character classes (`[...]`
+where `/` is literal) and backslash escapes, then consumes trailing
+flag identifiers. Returns the index immediately after the regex. An
+unterminated regex (newline before closing `/`) returns the newline
+position so the outer scanner can resume normally on the next line.
+*/
+function skipRegex(source: string, start: number): number {
+    let i = start
+    let inClass = false
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === '\n') {
+            return i
+        }
+        if (inClass) {
+            if (c === ']') {
+                inClass = false
+            }
+            i++
+            continue
+        }
+        if (c === '[') {
+            inClass = true
+            i++
+            continue
+        }
+        if (c === '/') {
+            let j = i + 1
+            while (j < source.length && isIdentPart(source[j])) {
+                j++
+            }
+            return j
+        }
+        i++
+    }
+    return source.length
+}

package/src/lib/shared/forwardHeaders.ts

@@ -0,0 +1,28 @@
+/*
+Headers belte forwards from an inbound HTTP/MCP request onto every
+synthesized in-process rpc Request — cookies + bearer auth + the four
+forwarding hints proxies set when terminating TLS in front of the app.
+defineVerb uses this when an SSR pass calls a verb in-process; the MCP
+dispatcher uses it when piping a tool invocation through verb.fetch.
+
+Centralised so both call sites can't drift on which headers are
+considered "auth/identity" context.
+*/
+export const FORWARDED_HEADERS = [
+    'cookie',
+    'authorization',
+    'x-forwarded-for',
+    'x-forwarded-proto',
+    'x-forwarded-host',
+]
+
+export function forwardHeaders(source: Headers): Headers {
+    const headers = new Headers()
+    for (const name of FORWARDED_HEADERS) {
+        const value = source.get(name)
+        if (value) {
+            headers.set(name, value)
+        }
+    }
+    return headers
+}

package/src/lib/shared/getRemoteMeta.ts

@@ -0,0 +1,5 @@
+import { remoteMetaStore } from './remoteMetaStore.ts'
+
+export function getRemoteMeta(promise: Promise<unknown>): Request | undefined {
+    return remoteMetaStore.get(promise)?.()
+}

package/src/lib/shared/isDebugEnabled.ts

@@ -0,0 +1,23 @@
+/*
+Matches the conventions of the `debug` npm package.
+DEBUG="belte"   → enables "belte"
+DEBUG="belte:*" → enables "belte" and "belte:anything"
+DEBUG="*"       → enables everything
+DEBUG="a,belte" → comma-separated list
+*/
+export function isDebugEnabled(name: string, env: string | undefined = process.env.DEBUG): boolean {
+    if (!env) {
+        return false
+    }
+    return env.split(',').some((raw) => {
+        const pattern = raw.trim()
+        if (pattern === '*') {
+            return true
+        }
+        if (pattern.endsWith(':*')) {
+            const prefix = pattern.slice(0, -2)
+            return name === prefix || name.startsWith(`${prefix}:`)
+        }
+        return pattern === name
+    })
+}