@abide/abide 0.57.1 → 0.100.0

package/src/server/requestScope.ts

@@ -0,0 +1,435 @@
+// THE REQUEST SCOPE. What 11.32 files a value under on a server, what 22.1's ambients read, and
+// what `App.run` opens (42.7). One `AsyncLocalStorage`, because a request
+// is carried across every `await` its handlers and bodies make, and an ambient read after one has
+// to find the request it was made for.
+//
+// IMPORTING THIS MODULE IS WHAT MAKES A SERVER FILE VALUES. It fills the reactive core's provider
+// slot (`#shared/reactive/scoping.ts`), so from here on a `reactive` built outside a request is a
+// forwarder to one instance per request (`scoped.ts`). Everything that answers a request imports
+// it, and it is imported before any app module is, which is what makes an app's module-level
+// values forwarders rather than process-wide.
+
+import { AsyncLocalStorage } from 'node:async_hooks' // bun implements AsyncLocalStorage and has no context-carrying api of its own
+import { Cookies } from '#shared/cookies.ts'
+import type { Principal } from '#shared/principal.ts'
+import { SCOPING, type Scope } from '#shared/reactive/scoping.ts'
+import type { RpcRequest } from '#shared/rpcRequest.ts'
+import type { McpSurface } from './generatedSurfaces.ts'
+
+/** The three framings a stream is answered in. 17.6. */
+export type Framing = 'jsonl' | 'sse' | 'bytes'
+
+/** What one request, or one `App.run`, carries across every `await` its work makes. */
+export type RequestScope = Scope & {
+    /**
+     * What still answers this request: the opener, and a streamed body for as long as it streams.
+     *
+     * 12.5 — the scope is torn down when this reaches zero (`releaseScope`). A page is rendered
+     * whole before its answer goes out, but a stream goes on reading in the scope after `fetch`
+     * has returned, so it holds the scope until it closes.
+     */
+    holds: number
+    /** The framing a helper fixed for a streaming answer, or `undefined` to negotiate it. 17.6. */
+    framing: Framing | 'html' | 'json' | undefined
+    /** Which browser is calling, once read or minted in this request. 26.5. */
+    caller: string | undefined
+    /** This request's one resolve of the principal. 26.14. */
+    principal: Promise<Principal> | undefined
+    /**
+     * The longest `timeout` any handler that ran in this request asked for, in seconds.
+     *
+     * 16.23 — and `Infinity` for one that is never reaped (16.57).
+     */
+    timeout: number
+    /** This response's nonce, minted by the `csp` rung or on the first ask. 29.3. */
+    nonce: string | undefined
+    /** This request's cookie jar, built on the first ask. 22.2. */
+    cookies: Cookies | undefined
+    /** Whether an answer has taken what was written through `response` (`applyWritten`). */
+    applied: boolean
+    /** This scope's trace, built on the first ask (`trace.ts`). 24.1. */
+    trace: { id: string; span: string; flags: string } | undefined
+    /** `undefined` where the scope was opened without one — 42.8's scope, which 22.1 throws in. */
+    request: Request | undefined
+    /**
+     * The app that opened this scope: the `App.fetch` `RPC_SERVER.raw` answers through, and its MCP
+     * surface.
+     *
+     * 42.12 — ITS OWN APP, where two are held in one process: not whichever was built last.
+     */
+    app: AnsweringApp | undefined
+    /**
+     * The request the listener was handed, before a mount or a rung made another.
+     *
+     * 16.22 — bun raises the idle timeout only on the one it received itself.
+     */
+    received: Request | undefined
+    /** What a write through `response` is collected onto, for whoever answers to apply. 22.9. */
+    response: { status: number; headers: Headers }
+    /**
+     * The page this scope is rendering, which its calls report into.
+     *
+     * 41.13, 41.20 — `undefined` in every scope but a page's.
+     */
+    page: PageRender | undefined
+    /**
+     * What the answer's `server-timing` carries, gathered until the head goes out.
+     *
+     * 21.15, 21.20, 24.6.
+     */
+    timing: {
+        entries: string[]
+        /** The time rungs took, apart from what they wrapped; `undefined` where none ran. 21.20. */
+        middleware: number | undefined
+        /**
+         * The handler this request is answering; `handled` is its own body's time inside its rungs.
+         */
+        answering: object | undefined
+        handled: number | undefined
+    }
+}
+
+/**
+ * A page's render, as its calls see it: the seed sink and the requests the browser will make.
+ *
+ * The seed buffer's sink for this caller (41.13), and the requests the browser will make for the
+ * calls, for the early-call script (41.20). ON THE SCOPE because that is the only thing a call made
+ * deep in a page's setup can find it through when requests interleave — `RPC_SERVER.reached` is
+ * one slot for every request in flight.
+ */
+export type PageRender = {
+    seed: (rpc: object, args: unknown, reached: unknown) => boolean
+    calls: PageCall[]
+}
+
+/** An app as the scopes it opens hold it: what answers a request in it, and its MCP surface. */
+export type AnsweringApp = {
+    answer: (request: Request) => Promise<Response>
+    mcp: McpSurface
+    /**
+     * What this app's answers still hold past their request, each as what ends it: a streamed body
+     * still being written, a seed entry and its timer. 42.11 — `App.stop` ends every one.
+     */
+    held: Set<() => void>
+}
+
+/**
+ * One call a page's render made: the request the browser will make for it, and what it reached —
+ * read once the markup is built, for whether it was painted settled (41.25).
+ */
+export type PageCall = { request: RpcRequest; reached: unknown }
+
+// `undefined` IS A STORE, not the absence of one: a value built outside every request runs its body
+// under it (`Cell.scope`), rather than under whichever request scheduled the drain.
+const STORAGE = new AsyncLocalStorage<RequestScope | undefined>()
+
+// AT IMPORT, unlike every slot `installServer` fills: `reactive` decides at CONSTRUCTION whether a
+// value is filed per request (11.32), and a server module builds values as it loads — the
+// principal's document here, an app's handlers ahead of `bootApp` in a compiled entry. Anything
+// that can enter a scope imports this module, so none is built before the provider is in.
+SCOPING.provider = {
+    current: (): Scope | undefined => STORAGE.getStore(),
+    run: (scope, body, given) =>
+        STORAGE.run(scope as RequestScope | undefined, body, given),
+}
+
+/**
+ * A fresh request scope, for an opener that enters it more than once (`inOpenScope`).
+ *
+ * 18.16 — a connection to the socket mux, whose every frame is answered in the scope its upgrade
+ * opened; the opener releases it (`releaseScope`) when the connection closes, 18.17.
+ */
+export function scopeFor(
+    given: Request | undefined,
+    received: Request | undefined,
+    app: RequestScope['app'],
+): RequestScope {
+    return {
+        instances: new Map(),
+        stops: [],
+        holds: 1,
+        page: undefined,
+        trace: undefined,
+        cookies: undefined,
+        nonce: undefined,
+        framing: undefined,
+        timeout: 0,
+        caller: undefined,
+        principal: undefined,
+        applied: false,
+        request: given,
+        received,
+        app,
+        response: { status: 200, headers: new Headers() },
+        timing: {
+            entries: [],
+            middleware: undefined,
+            answering: undefined,
+            handled: undefined,
+        },
+    }
+}
+
+/** Runs `body` in a fresh request scope and returns what it returned. 42.7. */
+export function inScope<Result>(
+    given: Request | undefined,
+    body: () => Result,
+): Result {
+    return STORAGE.run(scopeFor(given, given, undefined), body)
+}
+
+/** Runs `body` in `scope`, which `scopeFor` opened, and returns what it returned. */
+export function inOpenScope<Result>(
+    scope: RequestScope,
+    body: () => Result,
+): Result {
+    return STORAGE.run(scope, body)
+}
+
+/**
+ * `inScope`, releasing the scope once `body` has settled.
+ *
+ * 12.5 — the watches `body` opened stop once it is done; a body still streaming holds the scope
+ * until that closes (`holdScope`).
+ */
+export function inReleasedScope<Result>(
+    given: Request | undefined,
+    body: () => Promise<Result>,
+    app: RequestScope['app'] = undefined,
+    received: Request | undefined = given,
+): Promise<Result> {
+    const scope = scopeFor(given, received, app)
+    return STORAGE.run(scope, async () => {
+        try {
+            return await body()
+        } finally {
+            releaseScope(scope)
+        }
+    })
+}
+
+/**
+ * Holds the current request's scope open for an answer that outlives `fetch`; answers the release.
+ *
+ * 12.5 — A STREAMED BODY. Released once, when it closes, errors or its reader hangs up. Outside
+ * every scope there is nothing to hold, and the release does nothing.
+ */
+export function holdScope(): () => void {
+    const scope = STORAGE.getStore()
+    if (scope === undefined) return () => {}
+    scope.holds += 1
+    let released = false
+    return () => {
+        if (released) return
+        released = true
+        releaseScope(scope)
+    }
+}
+
+/**
+ * Files `end` with the app answering the current scope, for `App.stop` to run; answers the unfiling.
+ *
+ * 42.11 — whatever outlives its request is the app's to end when it stops. Outside an app's scope
+ * there is no stop to end it, and the unfiling does nothing.
+ */
+export function heldByApp(end: () => void): () => void {
+    const held = STORAGE.getStore()?.app?.held
+    if (held === undefined) return () => {}
+    held.add(end)
+    return () => {
+        held.delete(end)
+    }
+}
+
+/**
+ * Lets go of one hold on `scope`; the last one tears it down.
+ *
+ * 12.5 — TEARDOWN STOPS EVERY `watch` OPENED IN IT, and their disposers run. Called by whatever
+ * opened the scope to answer something — a request (`App.fetch`) or `App.run` — once that is
+ * answered. A scope nothing releases lives as long as its process: the one `abide run` imports a
+ * script in, whose watches are the script's to keep.
+ */
+export function releaseScope(scope: RequestScope): void {
+    scope.holds -= 1
+    if (scope.holds > 0) return
+    const stops = scope.stops
+    for (let at = 0; at < stops.length; at += 1) (stops[at] as () => void)()
+    stops.length = 0
+}
+
+/**
+ * Makes `given` the current scope's request, for a rung that handed `next` one of its own.
+ *
+ * 37.3 — A RUNG MAY HAND `next` A REQUEST OF ITS OWN, and it is served in the scope `App.fetch`
+ * opened rather than a second one (42.6), so `request` reads it from here on.
+ */
+export function adoptRequest(given: Request): void {
+    ;(STORAGE.getStore() as RequestScope).request = given
+}
+
+/**
+ * What `App.listen` bound, and how a call raises the idle timeout on the received request.
+ *
+ * 42.9 — the server is for `server` to hand back. 16.22 — the timeout is raised on the server
+ * bound here, or where the listener is in another process (`abide dev`), by a message to it.
+ */
+export const LISTENING: {
+    server: Bun.Server<unknown> | undefined
+    timeout: (received: Request, seconds: number) => void
+} = {
+    server: undefined,
+    timeout: (received, seconds) =>
+        LISTENING.server?.timeout(received, seconds),
+}
+
+/**
+ * Sets what the calls a render makes report into, on the request's own scope.
+ *
+ * 41.13 — set before the render runs: a page's render passes one, and an error page's none. The
+ * render is awaited where the request is answered, so it runs in that scope throughout (42.6).
+ */
+export function beginRender(page: PageRender | undefined): void {
+    ;(STORAGE.getStore() as RequestScope).page = page
+}
+
+/** The scope a request or `App.run` opened, or `undefined` outside every one. */
+export function currentRequestScope(): RequestScope | undefined {
+    return STORAGE.getStore()
+}
+
+/** The current request's scope; throws, naming `name()`, outside a request. 22.1. */
+export function within(name: string): RequestScope {
+    const scope = STORAGE.getStore()
+    if (scope?.request === undefined)
+        throw new Error(
+            `abide: ${name}() was called outside a request, and it reads the request being served. RULEBOOK 22.1.`,
+        )
+    return scope
+}
+
+// 22.2, 22.8 — THE REQUEST'S JAR, whose writes are collected onto the response being built.
+export function requestCookies(): Cookies {
+    const scope = within('cookies')
+    scope.cookies ??= new Cookies(
+        scope.request?.headers.get('cookie') ?? '',
+        (serialized) => {
+            refuseUnanswered(scope, 'cookies().set')
+            scope.response.headers.append('set-cookie', serialized)
+        },
+        false,
+    )
+    return scope.cookies
+}
+
+/**
+ * Throws where nothing written now can reach an answer.
+ *
+ * 22.10 — ONCE THE HEADERS ARE OUT (`applyWritten`), and from the start on a connection to the
+ * socket mux, whose headers went out with the upgrade: a write collected there is never sent.
+ */
+function refuseUnanswered(scope: RequestScope, name: string): void {
+    if (scope.applied)
+        throw new Error(
+            `abide: ${name} was called after the response headers went out — or on a socket connection, whose headers went out with the upgrade — so what it writes cannot reach the browser. RULEBOOK 22.10.`,
+        )
+}
+
+/**
+ * Lays what was written through `response` onto `headers`, once; returns the written status.
+ *
+ * 21.10, 22.9 — over whatever the answer carried, and a `set-cookie` appended rather than
+ * replacing the one before it. ONCE, at `App.fetch`'s exit — the moment the head goes out, which
+ * is what `applied` tells 26.21.
+ */
+export function applyWritten(headers: Headers): number {
+    const scope = STORAGE.getStore()
+    if (scope === undefined || scope.applied) return 200
+    scope.applied = true
+    for (const [name, value] of scope.response.headers)
+        if (name === 'set-cookie') headers.append(name, value)
+        else headers.set(name, value)
+    return scope.response.status
+}
+
+/**
+ * The status written through `response`, or 200 where nothing wrote one.
+ *
+ * 22.9 — for a lane that builds its answer at it. The headers are laid over the answer once, at
+ * `App.fetch`'s exit (`applyWritten`).
+ */
+export function writtenStatus(): number {
+    return STORAGE.getStore()?.response.status ?? 200
+}
+
+/** The request being served. 22.1. */
+export function request(): Request {
+    return within('request').request as Request
+}
+
+// 21.20 — only the handler being answered: one it calls in process reports into the same scope.
+export function handlerTook(rpc: object, duration: number): void {
+    const timing = STORAGE.getStore()?.timing
+    if (timing?.answering === rpc && timing.handled === undefined)
+        timing.handled = duration
+}
+
+/**
+ * Adds `duration` to the time spent in rungs.
+ *
+ * 21.20 — or takes it back out where it was the centre's.
+ */
+export function rungsTook(duration: number): void {
+    const timing = STORAGE.getStore()?.timing
+    if (timing !== undefined)
+        timing.middleware = (timing.middleware ?? 0) + duration
+}
+
+/** Adds one `server-timing` metric to the answer `timing` belongs to. 21.15, 24.6. */
+export function timed(
+    timing: RequestScope['timing'] | undefined,
+    name: string,
+    duration: number,
+): void {
+    timing?.entries.push(metric(name, duration))
+}
+
+function metric(name: string, duration: number): string {
+    return `${name};dur=${duration.toFixed(1)}`
+}
+
+/**
+ * The answer's `server-timing` header, in the order it was gathered; `undefined` for none.
+ *
+ * 21.15, 21.20, 24.6.
+ */
+export function serverTiming(): string | undefined {
+    const timing = STORAGE.getStore()?.timing
+    if (timing === undefined) return undefined
+    const entries =
+        timing.middleware === undefined
+            ? timing.entries
+            : [...timing.entries, metric('Middleware', timing.middleware)]
+    return entries.length === 0 ? undefined : entries.join(', ')
+}
+
+/** The response being built for the request being served. 22.1, 22.9. */
+export function response(): { status: number; headers: Headers } {
+    const scope = within('response')
+    refuseUnanswered(scope, 'response()')
+    return scope.response
+}
+
+/**
+ * The listening server.
+ *
+ * 22.1, 42.9 — inside a request and with nothing bound — `App.fetch` on an app nobody called
+ * `listen` on — there is no server to hand back, and that is a throw too.
+ */
+export function server<WebSocketData = unknown>(): Bun.Server<WebSocketData> {
+    within('server')
+    if (LISTENING.server === undefined)
+        throw new Error(
+            'abide: server() was called in an app with no socket bound. App.listen is what binds one. RULEBOOK 42.9.',
+        )
+    return LISTENING.server as Bun.Server<WebSocketData>
+}

package/src/server/responseHelpers.ts

@@ -0,0 +1,75 @@
+// SECTION 17 — THE RESPONSE HELPERS. Each is a write through `response` and hands back what it was
+// given, so a handler returns the helper's call and its value type is unchanged: `page` names the
+// document's type (17.2), `json` the serialization (17.9), `redirect` the status and the address
+// (17.3), and the three stream helpers the framing (17.6) that nothing then negotiates past (17.7).
+
+import { type Framing, response, within } from './requestScope.ts'
+
+/**
+ * What a stream helper frames: an iterable, an async iterable or a stream of values.
+ *
+ * 17.1.
+ */
+export type Values<T> = Iterable<T> | AsyncIterable<T> | ReadableStream<T>
+
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308
+
+/**
+ * Marks the answer as an HTML document and returns `body` unchanged.
+ *
+ * 17.2 — a rendered document: what `render` produced, not a render.
+ */
+export function page<
+    Body extends string | Uint8Array | Values<Uint8Array | string>,
+>(body: Body): Body {
+    response().headers.set('content-type', 'text/html; charset=utf-8')
+    within('page').framing = 'html'
+    return body
+}
+
+/**
+ * Fixes the answer as JSON and returns `value` unchanged.
+ *
+ * 17.9, 17.10 — the serialization a bare return gets, with nothing negotiated past it and an
+ * `undefined` sent as `null` rather than as 204.
+ */
+export function json<T>(value: T): T {
+    within('json').framing = 'json'
+    return value
+}
+
+/**
+ * Sets the response's redirect status and `location`, and returns `undefined`.
+ *
+ * 17.3.
+ */
+export function redirect(to: string, status: RedirectStatus = 302): undefined {
+    const written = response()
+    written.status = status
+    written.headers.set('location', to)
+    return undefined
+}
+
+function fixed<T>(framing: Framing, values: T): T {
+    within(framing).framing = framing
+    return values
+}
+
+/**
+ * Fixes the answer's framing to JSON lines and returns `values` unchanged.
+ *
+ * 17.6.
+ */
+export function jsonl<T>(values: Values<T>): Values<T> {
+    return fixed('jsonl', values)
+}
+
+/** Fixes the answer's framing to server-sent events and returns `values` unchanged. 17.6. */
+export function sse<T>(values: Values<T>): Values<T> {
+    return fixed('sse', values)
+}
+
+/** Fixes the answer's framing to raw bytes and returns `values` unchanged. 17.6. */
+export function bytes(values: Values<Uint8Array>): Values<Uint8Array> {
+    return fixed('bytes', values)
+}

package/src/server/runCompiled.ts

@@ -0,0 +1,44 @@
+// 38.51 — A COMPILED APP'S COMMAND LINE: `abide`'s list (`commands.ts`), over the app the executable
+// holds rather than one on disk, and spoken under the name it was started by — a `--platforms` build
+// is `ledger-linux-x64`, and that is what a reader types.
+
+import { type Host, runCommands } from './commands.ts'
+import { type AppOrigin, bootApp } from './createApp.ts'
+import { type BuildParts, builtSources, serveApp } from './serveBuild.ts'
+
+export async function runCompiled(
+    origin: AppOrigin,
+    parts: BuildParts,
+    // 38.57 — every specifier a script `run` may import out of the executable: abide's own entries
+    // and the app's handler modules, each to the module it holds.
+    specifiers: Record<string, () => Promise<Record<string, unknown>>>,
+): Promise<void> {
+    // REGISTERED AT START AND LOADED ON FIRST IMPORT: a handler module a script never names never
+    // runs its top level, as it would not under `abide run`.
+    Bun.plugin({
+        name: 'abide:compiled-specifiers',
+        setup(build) {
+            for (const [name, load] of Object.entries(specifiers))
+                build.module(name, async () => ({
+                    exports: await load(),
+                    loader: 'object',
+                }))
+        },
+    })
+    const host: Host = {
+        name: process.execPath.slice(process.execPath.lastIndexOf('/') + 1),
+        handlers: async () => parts.handlers,
+        appPackage: () => origin.package,
+        boot: () => bootApp(origin, () => builtSources(parts)),
+        // 38.50.
+        serve: ({ values: { port } }) =>
+            serveApp(
+                origin,
+                () => builtSources(parts),
+                port === undefined ? undefined : Number(port),
+            ),
+        source: undefined,
+    }
+    const code = await runCommands(host, Bun.argv.slice(2))
+    if (code !== undefined) process.exit(code)
+}