@abide/abide 0.57.1 → 0.100.0

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

@@ -1,104 +0,0 @@
-import { abideLog } from '../../shared/abideLog.ts'
-import { logTapSlot } from '../../shared/logTapSlot.ts'
-import { requestScopeSlot } from '../../shared/requestScopeSlot.ts'
-import { socketTapSlot } from '../../shared/socketTapSlot.ts'
-import type { LogRecord } from '../../shared/types/LogRecord.ts'
-import { buildCacheSnapshot } from './buildCacheSnapshot.ts'
-import { buildInFlightSnapshot } from './buildInFlightSnapshot.ts'
-import { buildInspectorSurface } from './buildInspectorSurface.ts'
-import { inFlightRequests } from './inFlightRequests.ts'
-import { ensureRegistriesLoaded } from './registryManifests.ts'
-import type { InspectorContext } from './types/InspectorContext.ts'
-
-/* The request handler `@abide/inspector` returns — serves its UI + data routes. */
-type InspectorHandler = (request: Request, url: URL) => Promise<Response>
-
-/* Shapes a published socket frame as a log record so the inspector's one feed
-   carries it like any other event — on the `socket` channel, tied to the active
-   trace when the publish happened inside a request (e.g. an RPC broadcasting). */
-function socketFrameRecord(frame: { socket: string; message: unknown }): LogRecord {
-    const scope = requestScopeSlot.resolver?.()
-    return {
-        ts: Date.now(),
-        level: 'info',
-        channel: 'socket',
-        msg: frame.socket,
-        data: frame.message,
-        trace: scope?.trace.traceId,
-        elapsedMs: scope?.elapsedMs,
-        method: scope?.method,
-        path: scope?.path,
-    }
-}
-
-/*
-Non-literal so Bun's bundler can't fold the optional package into a compiled
-binary: the import stays external and resolves only at runtime, only when the
-package is actually installed.
-*/
-const INSPECTOR_PACKAGE = '@abide/inspector'
-
-/*
-Activates the opt-in inspector when ABIDE_ENABLE_INSPECTOR=true. The flag is the
-activation switch; the package is installed explicitly (`bun add -d
-@abide/inspector`) — core never installs anything. Returns the package's request
-handler for createServer to route, or undefined when the flag is off or the
-package isn't present (with a one-line install hint in that case).
-
-The inspector exposes all traffic and the whole machine surface, so it's gated
-behind the operator's explicit flag and announces itself loudly on mount —
-enable it only in trusted/dev environments (mirrors warnUnguardedMcp).
-*/
-export async function maybeMountInspector(app: {
-    name: string
-    version: string
-}): Promise<InspectorHandler | undefined> {
-    if (process.env.ABIDE_ENABLE_INSPECTOR !== 'true') {
-        return undefined
-    }
-    const imported = (await import(INSPECTOR_PACKAGE).catch(() => undefined)) as
-        | { mountInspector: (context: InspectorContext) => InspectorHandler }
-        | undefined
-    if (!imported) {
-        abideLog.warn(
-            `ABIDE_ENABLE_INSPECTOR=true but ${INSPECTOR_PACKAGE} isn't installed — run \`bun add -d ${INSPECTOR_PACKAGE}\``,
-        )
-        return undefined
-    }
-    /* Arm in-flight tracking now the inspector is mounting: runWithRequestScope
-       fills this Set per request, kept process-wide (the events tap teardown is
-       per-connection; the Set outlives any single feed). */
-    inFlightRequests.tracked = new Set()
-    const context: InspectorContext = {
-        app,
-        loadSurface: async () => {
-            await ensureRegistriesLoaded()
-            return buildInspectorSurface()
-        },
-        cacheSnapshot: buildCacheSnapshot,
-        inFlightSnapshot: buildInFlightSnapshot,
-        /*
-        One process-wide tap each for the log and socket chokepoints; the
-        inspector owns both and fans out to its readers. Socket frames arrive
-        shaped as `socket`-channel records, so the inspector sees a single
-        uniform event stream.
-        */
-        onRecord: (listener: (record: LogRecord) => void) => {
-            const onFrame = (frame: { socket: string; message: unknown }) =>
-                listener(socketFrameRecord(frame))
-            logTapSlot.tap = listener
-            socketTapSlot.tap = onFrame
-            return () => {
-                if (logTapSlot.tap === listener) {
-                    logTapSlot.tap = undefined
-                }
-                if (socketTapSlot.tap === onFrame) {
-                    socketTapSlot.tap = undefined
-                }
-            }
-        },
-    }
-    const handler = imported.mountInspector(context)
-    abideLog.warn('inspector enabled — exposes all traffic and the full surface; trusted use only')
-    return handler
-}

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

@@ -1,14 +0,0 @@
-/*
-Derives the MIME type from a URL pathname using Bun.file().type, which
-operates on the file extension synchronously without touching the disk. The
-Bun.file ref here is never read from — it exists only to reuse Bun's
-extension-to-MIME table. Cache by extension so repeat hits for the same
-chunk type (.js / .css / .map / .svg / …) skip the BunFile allocation.
-*/
-const mimeByExtension = new Map<string, string>()
-
-export function mimeForExtension(pathname: string): string {
-    const dot = pathname.lastIndexOf('.')
-    const extension = dot === -1 ? '' : pathname.slice(dot)
-    return mimeByExtension.getOrInsertComputed(extension, () => Bun.file(pathname).type)
-}

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

@@ -1,15 +0,0 @@
-/*
-Internal holder for the in-process page-render dispatch. createServer sets this
-once at boot, closing over the app's route resolver + render pipeline, so the
-public `render()` can turn a route URL into the same Response the HTTP fetch
-handler would — a page render, without a socket hop. Empty until boot: `render()`
-throws on access before the slot is set (mirroring serverSlot / server()). The
-closure runs the matched page handler directly under runWithRequestScope — like
-dispatchRpcInProcess for rpcs — so it skips app.handle middleware and wire
-finalization (gzip); it is the page analogue of the in-process rpc seam.
-*/
-export const pageRenderSlot: {
-    render: ((request: Request, url: URL) => Promise<Response>) | undefined
-} = {
-    render: undefined,
-}

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

@@ -1,15 +0,0 @@
-import { withBaseUrl } from '../../shared/withBaseUrl.ts'
-import type { RequestStore } from './types/RequestStore.ts'
-
-/*
-The browser-space URL `page.url` publishes for a request: store.url with the
-mount base re-applied, matching what window.location shows under a proxy
-mount, so an active-state compare against url() output hydrates identically.
-store.url itself stays app-space (base-stripped by the proxy) for routing and
-error-prefix matching. Memoized on the store so repeated page-proxy reads
-share one URL.
-*/
-export function pageUrlFromStore(store: RequestStore): URL {
-    store.pageUrl ??= withBaseUrl(store.url)
-    return store.pageUrl
-}

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

@@ -1,10 +0,0 @@
-import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
-
-/*
-Parses ABIDE_IDLE_TIMEOUT into Bun's per-connection idle timeout in seconds.
-Bun accepts 0–255 (0 disables the timeout); returns undefined for missing,
-empty, or out-of-range/non-integer input so the caller keeps its default.
-*/
-export function parseIdleTimeout(value: string | undefined): number | undefined {
-    return parseBoundedEnvInt(value, 0, 255)
-}

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

@@ -1,11 +0,0 @@
-import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
-
-/*
-Parses a PORT env value into a usable TCP port (0–65535), returning undefined
-for missing, empty, or out-of-range/non-integer input so the caller can fall
-back to a default. A bare Number() would turn '' into 0 (a random
-kernel-assigned port) and 'abc' into NaN, both silently wrong.
-*/
-export function parsePort(value: string | undefined): number | undefined {
-    return parseBoundedEnvInt(value, 0, 65535)
-}

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

@@ -1,15 +0,0 @@
-// AsyncLocalStorage is canonical via node:async_hooks — Bun has no separate API
-import { AsyncLocalStorage } from 'node:async_hooks'
-
-/*
-The server's dedicated render-path store (ADR-0033 D1). Backs `CURRENT_PATH.current` during an
-SSR pass with the COMPOSED path as the store value, pushed by `.run(compose(base, segment), build)`
-at each nesting site (route → layout → row → branch → child ordinal). Unlike a mutable slot restored
-in `finally`, `run`'s value is inherited by every async continuation spawned inside it — so a render
-body resuming after an `await` still reads ITS OWN path, and sibling rows/children (continuations of
-the enclosing render body) read the enclosing render's path. Per-request isolation falls out for free
-(each route render is its own `run` tree), which is why this subsumes the path half of the request
-store. Reads outside any `run` fail open to `''` (a detached scope then takes the counter fallback).
-Server-only, kept out of `lib/ui` so the browser bundle never drags in `node:async_hooks`.
-*/
-export const pathStore = new AsyncLocalStorage<string>()

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

@@ -1,66 +0,0 @@
-import type { PromptRoutes } from '../prompts/types/PromptRoutes.ts'
-import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
-import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
-
-/*
-Process-wide slot for the rpc + sockets + prompts manifests. createServer
-assigns once at boot (right after the route table is built); the MCP
-server, the OpenAPI emitter, and prompt enumeration read it on first
-request so they can lazy-import every module and walk the
-rpc/socket/prompt registries.
-
-The slot pattern (mirrors getActiveServer) lets the framework-generated
-McpServer bind to the manifests at module scope while the loaders stay
-lazy until the first enumeration request.
-*/
-type RegistryManifests = {
-    rpc: RemoteRoutes
-    sockets: SocketRoutes
-    prompts: PromptRoutes
-}
-
-let manifests: RegistryManifests | undefined
-let loading: Promise<void> | undefined
-
-export function setRegistryManifests(value: RegistryManifests): void {
-    manifests = value
-    loading = undefined
-}
-
-/*
-On first call, eagerly imports every rpc + socket + prompt module so
-defineRpc / defineSocket / definePrompt fire and populate the
-registries. Idempotent — repeat calls reuse the same in-flight promise,
-so concurrent first requests (e.g. /openapi.json + an MCP tools/list)
-trigger exactly one load instead of racing to fire the full import set
-each. Eager loading is acceptable here because enumeration (MCP
-tool/resource/prompt lists, the OpenAPI document) fundamentally requires
-the full surface; the alternative of per-call lazy loading produces flaky
-first-call latency.
-*/
-export function ensureRegistriesLoaded(): Promise<void> {
-    if (!manifests) {
-        return Promise.resolve()
-    }
-    if (!loading) {
-        const { rpc, sockets, prompts } = manifests
-        loading = Promise.all([
-            ...Object.values(rpc).map((loader) => loader()),
-            ...Object.values(sockets).map((loader) => loader()),
-            ...Object.values(prompts).map((loader) => loader()),
-        ])
-            .then(() => undefined)
-            /*
-            Clear the memo on failure so a transient import error (a
-            module that throws at load, fixed by the next rebuild)
-            doesn't poison every later enumeration request for the
-            process lifetime. The rejection still propagates to this
-            caller; the reset only affects subsequent calls.
-            */
-            .catch((error) => {
-                loading = undefined
-                throw error
-            })
-    }
-    return loading
-}

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

@@ -1,15 +0,0 @@
-// AsyncLocalStorage is canonical via node:async_hooks — Bun has no separate API
-import { AsyncLocalStorage } from 'node:async_hooks'
-import type { PendingAsyncCells } from '../../shared/types/PendingAsyncCells.ts'
-
-/*
-The server's per-RENDER async-cell barrier store (ADR-0037 Phase 2). Backs `cellBarrierBacking` with
-a fresh pending-cells list pushed by `isolateCellBarrier` around a hoisted concurrent child render.
-Unlike the per-request `pendingAsyncCells` (one list a whole request shares), `run`'s value is
-inherited by the child render's own async continuations — so a child that suspends on its script
-await or its `$$settleAsyncCells` barrier keeps reading ITS list, and two sibling renders in flight
-at once never splice each other's cells. `getStore()` is `undefined` outside any isolated render, so
-the page's own cells fall through to the request list. Server-only, kept out of `lib/ui` so the
-browser bundle never drags in `node:async_hooks`. Mirrors `pathStore` (ADR-0033 D1).
-*/
-export const renderCellBarrierStore = new AsyncLocalStorage<PendingAsyncCells>()

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

@@ -1,5 +0,0 @@
-// AsyncLocalStorage is canonical via node:async_hooks — Bun has no separate API
-import { AsyncLocalStorage } from 'node:async_hooks'
-import type { RequestStore } from './types/RequestStore.ts'
-
-export const requestContext = new AsyncLocalStorage<RequestStore>()

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

@@ -1,25 +0,0 @@
-import type { PageSnapshot } from '../../shared/types/PageSnapshot.ts'
-import { pageUrlFromStore } from './pageUrlFromStore.ts'
-import { requestContext } from './requestContext.ts'
-
-/*
-The server's page resolver: the `page` proxy reads route/params/url off the
-ALS request store, so layout-scoped components see the live match during SSR
-without a module singleton leaking across concurrent or streaming renders.
-route/params land just before render; url is set at the request boundary, so
-404/error renders still get a correct page.url. Registered by serverEntry at
-boot and mirrored by bootTestServer; undefined outside a request scope falls
-through to activePage's empty fallback.
-*/
-export function resolvePageSnapshot(): PageSnapshot | undefined {
-    const store = requestContext.getStore()
-    if (!store) {
-        return undefined
-    }
-    return {
-        route: store.route ?? '',
-        params: store.params ?? {},
-        url: pageUrlFromStore(store),
-        navigating: false,
-    }
-}

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

@@ -1,18 +0,0 @@
-/*
-Serves one compile-time-embedded asset: a gzip-capable client gets the stored
-bytes as-is, anyone else gets them decompressed on the fly. Shared by the
-`_app` and public/ asset servers so the decompress fallback lives once.
-*/
-export function respondWithEmbeddedAsset(
-    compressed: Uint8Array<ArrayBuffer>,
-    wantsGzip: boolean,
-    headers: { base: HeadersInit; gzip: HeadersInit },
-): Response {
-    if (wantsGzip) {
-        return new Response(compressed, { headers: headers.gzip })
-    }
-    /* gunzipSync's Buffer is freshly allocated over a plain ArrayBuffer; @types/bun widens it to ArrayBufferLike, which BodyInit rejects. */
-    return new Response(Bun.gunzipSync(compressed) as Uint8Array<ArrayBuffer>, {
-        headers: headers.base,
-    })
-}

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

@@ -1,165 +0,0 @@
-import { abideLog } from '../../shared/abideLog.ts'
-import { createCacheStore } from '../../shared/createCacheStore.ts'
-import { createTraceContext } from '../../shared/createTraceContext.ts'
-import { formatTraceparent } from '../../shared/formatTraceparent.ts'
-import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
-import { logClosingRecord } from '../../shared/logClosingRecord.ts'
-import type { AppModule } from '../AppModule.ts'
-import { inFlightRequests } from './inFlightRequests.ts'
-import { internalErrorResponse } from './internalErrorResponse.ts'
-import { requestContext } from './requestContext.ts'
-import type { RequestStore } from './types/RequestStore.ts'
-
-/*
-Establishes the per-request scope and runs `body` inside it: a fresh
-CacheStore, the request's trace position and start time, and request metadata
-published through the AsyncLocalStorage RequestStore (so cache(), request()/
-server(), trace(), and log prefixes resolve without threading args), the
-app's handleError — or the framework's 500 fallback — on a thrown body, and
-optional request logging. The single seam every dynamic route crosses;
-extracted from createServer so the scope, error, and logging behaviour is
-exercisable through this interface without booting a Bun server.
-*/
-export function runWithRequestScope(
-    req: Request,
-    /* `url` skips the WHATWG re-parse when the caller already parsed it (the fetch fallback). */
-    options: { app?: AppModule; logRequests: boolean; url?: URL },
-    body: (store: RequestStore) => Promise<Response>,
-): Promise<Response> {
-    const url = options.url ?? new URL(req.url)
-    const store: RequestStore = {
-        url,
-        req,
-        cache: createCacheStore(),
-        pendingAsyncCells: { promises: [] },
-        resolvedCells: { entries: [] },
-        streamedCells: { entries: [] },
-        socketTails: { entries: [] },
-        docSnapshots: { entries: [] },
-        trace: createTraceContext(req.headers.get('traceparent')),
-        start: Bun.nanoseconds(),
-    }
-    return requestContext.run(store, async () => {
-        /* Register the live handler for the inspector's in-flight view; the Set is
-           absent (a no-op) unless the inspector mounted. Removed once the handler
-           settles — its compute is done even if a streamed body keeps piping. */
-        inFlightRequests.tracked?.add(store)
-        let response: Response
-        try {
-            response = await body(store)
-        } catch (error) {
-            if (options.app?.handleError) {
-                response = await options.app.handleError(error, req)
-            } else {
-                abideLog.error(error)
-                response = internalErrorResponse(error)
-            }
-        } finally {
-            inFlightRequests.tracked?.delete(store)
-        }
-        /*
-        Flush any cookies the handler set onto the outgoing response. Only when
-        a jar was materialized (cookies() was called) and only via append, so a
-        Set-Cookie the handler already placed on the response init survives.
-        */
-        if (store.cookies) {
-            const setCookies = store.cookies.toSetCookieHeaders()
-            if (setCookies.length > 0) {
-                try {
-                    setCookies.forEach((header) => {
-                        response.headers.append('set-cookie', header)
-                    })
-                } catch {
-                    /* A passthrough Response (proxied fetch) carries immutable headers;
-                       rebuild it with a mutable copy so the cookies still ship rather
-                       than the append throwing and 500ing the successful response. */
-                    response = new Response(response.body, response)
-                    setCookies.forEach((header) => {
-                        response.headers.append('set-cookie', header)
-                    })
-                }
-            }
-        }
-        /*
-        Server-Timing is always-on (identical dev/build): `total` is what's
-        knowable at header time — for streamed responses the settled total
-        belongs to the closing log record — and the `traceparent` entry is the
-        one header browsers expose to page JS, so RUM tooling links the
-        frontend to this trace. Guarded: a passthrough Response (proxied
-        fetch) carries immutable headers.
-        */
-        const headerMs = (Bun.nanoseconds() - store.start) / 1e6
-        const stats = store.cache.stats
-        const cacheEntry =
-            stats.hits + stats.misses + stats.coalesced > 0
-                ? `, cache;desc="hits=${stats.hits} misses=${stats.misses} coalesced=${stats.coalesced}"`
-                : ''
-        try {
-            response.headers.set(
-                'server-timing',
-                `total;dur=${headerMs.toFixed(1)}, traceparent;desc="${formatTraceparent(store.trace)}"${cacheEntry}`,
-            )
-        } catch {
-            /* Immutable headers — skip; the closing log record still reports. */
-        }
-        if (!options.logRequests) {
-            return response
-        }
-        /*
-        The closing record logs at settle so its elapsed IS the total. Buffered
-        responses settle here; streaming bodies (SSE/JSONL) settle when the
-        stream ends — re-entered into the request scope because stream
-        callbacks don't inherit the ALS context.
-        */
-        let settled = false
-        const emitClose = () => {
-            if (settled) {
-                return
-            }
-            settled = true
-            requestContext.run(store, () => {
-                const ms = (Bun.nanoseconds() - store.start) / 1e6
-                /* Copy freezes the tallies at settle — the live object keeps counting if late reads land. */
-                logClosingRecord(req.method, `${url.pathname}${url.search}`, response.status, ms, {
-                    ...store.cache.stats,
-                })
-            })
-        }
-        /* Reuse the dispatch pipeline's single S2 classification when it stashed
-           one; callers that don't (mcp, the fetch fallback, tests) classify here. */
-        const streaming = store.responseStreaming ?? isStreamingResponse(response)
-        if (response.body && streaming) {
-            /*
-            A hand-pumped wrap rather than a TransformStream: streams typically
-            end by client disconnect (an SSE tab closing), which cancels the
-            readable without ever flushing a transform — Bun also skips the
-            transformer's cancel hook — so only this readable's own close/error/
-            cancel paths see every termination.
-            */
-            const reader = response.body.getReader()
-            const monitored = new ReadableStream({
-                async pull(controller) {
-                    try {
-                        const { done, value } = await reader.read()
-                        if (done) {
-                            emitClose()
-                            controller.close()
-                            return
-                        }
-                        controller.enqueue(value)
-                    } catch (error) {
-                        emitClose()
-                        controller.error(error)
-                    }
-                },
-                cancel(reason) {
-                    emitClose()
-                    return reader.cancel(reason)
-                },
-            })
-            return new Response(monitored, response)
-        }
-        emitClose()
-        return response
-    })
-}

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

@@ -1,31 +0,0 @@
-import { snapshotShippable } from '../../shared/snapshotShippable.ts'
-import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
-import type { CacheStore } from '../../shared/types/CacheStore.ts'
-import { snapshotEntryFromCache } from './snapshotEntryFromCache.ts'
-
-/*
-Snapshots the request-scoped cache for SSR at a single instant: every entry
-(any method) called inline and settled by now, serialized to a wire-safe
-CacheSnapshotEntry the client seeds its store from — so an inline POST hydrates
-warm rather than re-firing after render. Unsettled entries and producers/stream
-cells (no wire request) are skipped; a body that can't ship (binary / streaming /
-rejected) drops out via snapshotEntryFromCache.
-
-Snapshots concurrently — the awaits are immediate (entries are already settled), but
-their body reads run in parallel. Never blocks on an unsettled entry.
-
-WHEN it's called decides what it sees. createUiPageRenderer calls it at render-return
-for `__SSR__` — that catches only top-level `await` reads (render blocked on them). A
-`{#await cache()}` read does NOT appear: its expression is a thunk renderToStream runs
-lazily, so its entry is created mid-stream, after this snapshot. The renderer snapshots
-AGAIN once the stream has drained (entries then exist and are settled) and seeds those
-over the wire — see its post-stream `__abideResolve` pass. So for a streaming page the
-render-return snapshot is typically empty; the warm cache arrives over the stream.
-*/
-export async function serializeCacheSnapshot(store: CacheStore): Promise<CacheSnapshotEntry[]> {
-    const settled = Array.from(store.entries.values()).filter(snapshotShippable)
-    const snapshots = await Promise.all(
-        settled.map((entry) => snapshotEntryFromCache(store, entry)),
-    )
-    return snapshots.filter((snapshot): snapshot is CacheSnapshotEntry => snapshot !== undefined)
-}

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

@@ -1,13 +0,0 @@
-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

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