@abide/abide 0.123.3 → 0.124.1

package/src/server/faceOf.ts

@@ -34,7 +34,7 @@ export type Lane = { bundling: boolean; browser: boolean }
 export type Face = { path: string; namespace: string }
 
 /**
- * What an import asks of a file, by its spelling: its text (`?text`), a component's stylesheet
+ * What an import asks of a file, by its spelling: its text (`.abide-text`), a component's stylesheet
  * (`?style`), the module it compiles to (`?component`), its browser module (`?client`), its server
  * module (`?server`), a `.abide` named bare, or a module that may be a handler file.
  */

package/src/server/generatedSurfaces.ts

@@ -22,12 +22,13 @@ import { parseRoutePattern, type Segment } from '#shared/routePattern.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 
 import { answered } from './answerFailure.ts'
-import { bodyWithin, type Mounted } from './answerRpc.ts'
+import { bodyWithin } from './answerRpc.ts'
 import type { ToolAnswer, ToolDefinition } from './assistant.ts'
 import { appIdentity } from './config.ts'
 import { crossingOrigin, crossingRefusal } from './crossingOrigin.ts'
 import { IMAGE_TYPES } from './IMAGE_TYPES.ts'
 import { MCP_PROTOCOL_VERSION } from './MCP_PROTOCOL_VERSION.ts'
+import type { Mounted } from './mountHandlers.ts'
 import { type Listed, surfaceOf } from './surfaceOf.ts'
 
 const OPENAPI_LOG = namedLogger('abide:openapi')

package/src/server/handlerFileMount.ts

@@ -1,4 +1,4 @@
-import type { Mount } from './answerRpc.ts'
+import type { Mount } from './mountHandlers.ts'
 
 /**
  * The row of a handler file (16.73): its default, answered at the route the file is placed at and

package/src/server/index.ts

@@ -51,7 +51,7 @@ export type { ConfigField } from './configFields.ts'
 export { type App, createApp } from './createApp.ts'
 // 41.28's run-time half: an emitted component reads it on either side of its setup, and one whose
 // setup made a call answers as a page does. Not an app's name.
-export { callsInRender } from './deferredBuilds.ts'
+export { callsInRender } from './PageRender.ts'
 // 19.9's run-time half: what the module a handler is loaded through calls to hold it to the schema
 // its annotation derives (15.8). Not an app's name.
 export { derivedArgs } from './argsContract.ts'

package/src/server/installServer.ts

@@ -2,9 +2,9 @@
 // whichever server module a process happened to import — a compiler or a test that reaches one of
 // them for a function is not made a server by it. Called where a server is entered: `bootApp`,
 // `abide run`, and `@abide/abide/server`, which an app imports to be one. Filling the same functions again
-// changes nothing, so each entry calls it. Three are filled elsewhere: `SCOPING.provider` at
-// `requestScope.ts`'s import (its comment says why), `RPC_SERVER.raw` per boot, and
-// `LISTENING.timeout` by the dev worker alone.
+// changes nothing, so each entry calls it. Four are filled elsewhere: `SCOPING.provider` at
+// `requestScope.ts`'s import (its comment says why), `RPC_SERVER.raw` per boot,
+// `RPC_SERVER.following` by each app's followers, and `LISTENING.timeout` by the dev worker alone.
 
 import { COOKIES } from '#shared/cookies.ts'
 import { CSP } from '#shared/csp.ts'
@@ -15,12 +15,11 @@ import { PRINCIPAL } from '#shared/principal.ts'
 import { RPC_SERVER } from '#shared/RPC_SERVER.ts'
 import { UNEXPECTED } from '#shared/UNEXPECTED.ts'
 
-import { reachedInRender } from './answerRequest.ts'
 import { environmentTimeout } from './answerRpc.ts'
-import { broadcast, feedFromServed, swept } from './answerSocket.ts'
 import { configuredMount, derivedAppName } from './config.ts'
 import { cspRung, nonce } from './csp.ts'
 import { handOnError } from './hooks.ts'
+import { recordInRender } from './PageRender.ts'
 import { SERVER_PRINCIPAL } from './principal.ts'
 import { reportHealth } from './reportHealth.ts'
 import { handlerTook, request, requestCookies } from './requestScope.ts'
@@ -40,9 +39,6 @@ export function installServer(): void {
     // 16.11 — the request a handler's rung is handed.
     RPC_SERVER.request = request
     RPC_SERVER.timeout = environmentTimeout
-    RPC_SERVER.reached = reachedInRender
-    RPC_SERVER.broadcast = broadcast
-    RPC_SERVER.swept = swept
-    RPC_SERVER.served = feedFromServed
+    RPC_SERVER.reached = recordInRender
     RPC_SERVER.handled = handlerTook
 }

package/src/server/invokeHandler.ts

@@ -0,0 +1,230 @@
+// 16.2 — ONE HANDLER, CALLED FOR ONE CALLER, whichever lane the call came over. What a call over
+// http and a subscription over the mux both owe the handler is decided here — the origin gate
+// (16.13, 18.2), the args contract (19.7, 19.9), the rungs a follow is held to (18.8, 18.26), the
+// seed a render left (41.13) and the `global` entry the answer came from (21.15) — and what a lane
+// adds is the decoding of what it was sent and the encoding of what it answers.
+//
+// THE IN-PROCESS CALL is `#shared/rpc.ts`'s, which a browser bundle reaches too, so it cannot be
+// this module's; a call over a lane is that call, made in the request's scope.
+
+import { type Failed, isFailed } from '#shared/Failed.ts'
+import { GLOBAL_GETS } from '#shared/GLOBAL_GETS.ts'
+import { compose } from '#shared/Middleware.ts'
+import { heldGenerationOf } from '#shared/reactive/producer.ts'
+import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
+
+import { argsFor } from './argsContract.ts'
+import { closedTo, crossingRefusal } from './crossingOrigin.ts'
+import type { FollowedHandler, Mounted } from './mountHandlers.ts'
+import { takeSeeded } from './PageRender.ts'
+import { currentRequestScope, rungsTook, timed } from './requestScope.ts'
+import { type Outcome, outcomeOf } from './seedBuffer.ts'
+
+/**
+ * What the origin gate makes of a call from `crossing`: the refusal it is answered with, or the
+ * origin its answer admits — `null` for the app's own, and for a read another origin may make but
+ * not read (21.19).
+ *
+ * 16.13 — A MUTATION FROM ANOTHER ORIGIN IS REFUSED, and 18.2 — a subscription, unless the handler
+ * declared it may come. 16.24, 36.2 — the same gate and the same own origin for every lane.
+ */
+export function originGate(
+    handler: Mounted['handler'],
+    crossing: string | null,
+    following: boolean,
+): Failed<'HttpError', undefined> | string | null {
+    if (!closedTo(handler.crossOrigin, crossing)) return crossing
+    if (following) return crossingRefusal(crossing, 'subscription')
+    return argsInURL(handler.method)
+        ? null
+        : crossingRefusal(crossing, handler.method)
+}
+
+/** Which run answered a call, as 21.15's `server-timing` names it. */
+type Run = 'Seeded' | 'Cached' | 'Started' | 'Direct'
+
+/**
+ * A handler's call, made: how it ended, the args it was held to, and the `global` entry it was
+ * answered from.
+ */
+export class Invocation {
+    readonly outcome: Outcome
+    readonly args: unknown
+    /** The entry key of a `global` value, or `undefined` for one built per request. */
+    readonly key: string | undefined
+    /** The `global` entry as the run left it, which the answer reads too. */
+    readonly entry: unknown
+    readonly run: Run
+    readonly started: number
+
+    constructor(
+        outcome: Outcome,
+        args: unknown,
+        key: string | undefined,
+        entry: unknown,
+        run: Run,
+        started: number,
+    ) {
+        this.outcome = outcome
+        this.args = args
+        this.key = key
+        this.entry = entry
+        this.run = run
+        this.started = started
+    }
+
+    /**
+     * 21.15 — HOW LONG THE HANDLER TOOK, AND WHICH RUN THIS IS, for the network panel: the row
+     * already names the handler, so the metric names the run. Read once the answer's head is built,
+     * so a stream's time is to its first chunk.
+     */
+    timed(): void {
+        const timing = currentRequestScope()?.timing
+        const took = this.outcome.duration ?? performance.now() - this.started
+        // 21.20 — what the rungs took is theirs, and the handler's own body is what `Direct` reports.
+        const handled = this.run === 'Direct' ? timing?.handled : undefined
+        if (handled !== undefined) rungsTook(took - handled)
+        timed(timing, this.run, handled ?? took)
+    }
+}
+
+/**
+ * Calls `mounted`'s handler with what a lane decoded: `given` its args, `text` the query a URL or
+ * a form carried them as (19.7), `params` what its route matched.
+ *
+ * Answers the refusal its args were refused with, or the call made. `seeds` is whether a seed a
+ * page's render left may answer it (41.7) — 16.51, a `HEAD` leaves it for the `GET` it stands in
+ * front of.
+ */
+export async function invokeHandler(
+    mounted: Mounted,
+    given: unknown,
+    text: string | undefined,
+    params: Record<string, string | string[]>,
+    seeds: boolean,
+): Promise<Invocation | Failed<string, unknown>> {
+    const handler = mounted.handler
+    let args: unknown
+    try {
+        args = argsFor(handler, given, text, params)
+    } catch (refused) {
+        if (isFailed(refused)) return refused
+        throw refused
+    }
+    // 41.7 — the call a hydrating page makes for what its render already reached is answered from
+    // that, and the handler is not run again (41.13).
+    const seeded = seeds ? takeSeeded(handler, args) : undefined
+    // The entry key of a `global` value, taken once for every read of it below.
+    const global = GLOBAL_GETS.get(handler)
+    const key = global?.key(args)
+    // 21.15 — A `global` PRODUCTION ALREADY HELD, and not loading, answers without a run: a run
+    // this call started moves the generation, and one it joined was loading when it came.
+    const held =
+        seeded === undefined && key !== undefined ? global?.at(key) : undefined
+    const heldAt = held === undefined ? undefined : heldGenerationOf(held)
+    const timing = currentRequestScope()?.timing
+    if (timing !== undefined) timing.answering = handler
+    const started = performance.now()
+    const outcome =
+        seeded === undefined ? await outcomeOf(handler(args)) : await seeded
+    const entry = key === undefined ? undefined : global?.at(key)
+    const run: Run =
+        seeded !== undefined
+            ? 'Seeded'
+            : heldAt !== undefined &&
+                entry === held &&
+                heldGenerationOf(held) === heldAt
+              ? 'Cached'
+              : outcome.duration === undefined
+                ? 'Started'
+                : 'Direct'
+    return new Invocation(outcome, args, key, entry, run, started)
+}
+
+/**
+ * The args a subscription to `mounted` follows, held to its contract as a `GET` over http is
+ * (18.3) — or a throw of the refusal, the origin gate's included (18.2).
+ */
+export function followedArgs(
+    mounted: FollowedHandler,
+    given: unknown,
+    crossing: string | null,
+): unknown {
+    const gate = originGate(mounted.handler, crossing, true)
+    if (isFailed(gate)) throw gate
+    return argsFor(mounted.handler, given, undefined)
+}
+
+/**
+ * Whether a subscription to `mounted` with `args` is fed its productions, asked over `upgrade`, the
+ * request the connection opened with — settled where nothing guards it.
+ *
+ * 18.8 — A GUARDED `GET`'s RUNGS RUN ONCE, as the subscription opens: one they admit is fed the
+ * value, and one they refuse is sent its triggers alone. 18.26 — AND THE MIDDLEWARE ITS FILE'S
+ * ROUTE FILED, over the request a `GET` of it would be: one a rung answers in the handler's place is
+ * not fed, as an http call it answered would never reach the handler.
+ */
+export function admitsFollower(
+    mounted: FollowedHandler,
+    args: unknown,
+    upgrade: Request,
+): boolean | Promise<boolean> {
+    // No route rungs, no turn: a guarded `GET`'s rungs start in this frame's own run.
+    if (mounted.rungs.length === 0)
+        return mounted.handler.guarded ? handlerAdmits(mounted, args) : true
+    return throughRoute(mounted, args, upgrade)
+}
+
+async function throughRoute(
+    mounted: FollowedHandler,
+    args: unknown,
+    upgrade: Request,
+): Promise<boolean> {
+    if (!(await routeAdmits(mounted, args, upgrade))) return false
+    return !mounted.handler.guarded || handlerAdmits(mounted, args)
+}
+
+/** Whether the handler's own rungs let a call with `args` through. 18.8. */
+function handlerAdmits(
+    mounted: FollowedHandler,
+    args: unknown,
+): Promise<boolean> {
+    return Promise.resolve(
+        mounted.handler(args as never) as PromiseLike<unknown>,
+    ).then(
+        () => true,
+        () => false,
+    )
+}
+
+/**
+ * Whether the rungs over `mounted`'s route let a `GET` of it with `args` through, asked over the
+ * upgrade's own request at the handler's address. 18.26.
+ */
+async function routeAdmits(
+    mounted: FollowedHandler,
+    args: unknown,
+    upgrade: Request,
+): Promise<boolean> {
+    const asked = rpcRequest(
+        'GET',
+        mounted.address,
+        args as Record<string, unknown> | undefined,
+    )
+    const request = new Request(new URL(asked.url, upgrade.url), {
+        headers: upgrade.headers,
+        signal: upgrade.signal,
+    })
+    // REACHED BY A FLAG, not by the answer's identity: a rung that wraps or re-heads what `next`
+    // answered still let the call through, and a shared answer would carry every rung's headers.
+    let reached = false
+    try {
+        const answered = await compose(mounted.rungs, async () => {
+            reached = true
+            return new Response(null, { status: 204 })
+        })({ request })
+        return reached && answered.ok
+    } catch {
+        return false
+    }
+}

package/src/server/mountHandlers.ts

@@ -0,0 +1,184 @@
+// 16.2 — THE MOUNTED HANDLERS: the table the build writes, each row's handler imported at boot and
+// keyed by its method and address, with the rungs its route filed over it.
+
+import type { CopyOptions } from '#shared/CopyOptions.ts'
+import type { JsonValue } from '#shared/JsonValue.ts'
+import { mounted as underMount } from '#shared/mount.ts'
+import type { Gated, HeldToAnnotation } from '#shared/reactive/argsContract.ts'
+import type { Defaults } from '#shared/reactive/parameterDefaults.ts'
+import type { Method, Rpc } from '#shared/rpc.ts'
+
+import { answered } from './answerFailure.ts'
+import { derivedArgs } from './argsContract.ts'
+import { type LaneRung, rungsOver } from './hooks.ts'
+
+/**
+ * One row of the handler table the build writes into the server's table (`SERVER_TABLE`): where a
+ * handler answers, and its module.
+ *
+ * The module is relative to the app's root, which both commands that serve already know.
+ */
+export type Mount = {
+    address: string
+    method: Method
+    source: string
+    /** The handler file's name, or the private handler's binding. */
+    name: string
+    /** What the source's module exports it as: `default` for a handler file. */
+    export: string
+    /** The route its hooks are filed at, which its rungs are read over (37.1, 16.72). */
+    scope: string
+    /** 23.26 — each matcher its address names, to the anchored source its row is ranked with. */
+    matchers: Record<string, string>
+    /** Whether it is a private handler, listed nowhere (16.71). */
+    private: boolean
+    /** Whether a browser is handed a wrapper for it. 20.4. */
+    ui: boolean
+    /** Whether the command line lists it — the shell's listing and completion, never whether `call` reaches it. 20.3, 38.62. */
+    cli: boolean
+    /**
+     * Whether MCP lists it where its runtime `clients` does not say.
+     *
+     * 16.37 — false for a handler typed as returning a `Response`, which only the build can tell.
+     */
+    mcp: boolean
+    /** Its `description`, where the declaration writes one as a literal the build can read. */
+    description: string | undefined
+    /**
+     * What a `GET`'s value declares that the browser's copy behaves by, or `undefined`.
+     *
+     * 18.4 — set where its declaration names any of it.
+     */
+    copy: CopyOptions | undefined
+    /**
+     * The defaults the handler's parameter writes, for the browser's copy to key by.
+     *
+     * 11.29 — the server reads its own off the handler.
+     */
+    defaults: Defaults | undefined
+    /** The JSON Schema the handler's args annotation derives, where it takes a record. 19.9. */
+    args: JsonValue | undefined
+    /** The JSON Schema of what it answers, where its type says one. 19.21. */
+    result: JsonValue | undefined
+}
+
+/**
+ * A row of the table the build wrote, with the import of the module its handler is declared in —
+ * the handler file itself, or a private handler's `.abide` server module, the one the route table
+ * loads too, so a page and a call reach one handler.
+ */
+export type MountRow = Mount & { load: () => Promise<Record<string, unknown>> }
+
+/** A handler's row, mounted: the handler imported and its args schema probed. */
+export type Mounted = Mount & {
+    /**
+     * The rungs filed over `scope`, read once at mount (16.14) — what an http call and a socket
+     * subscription to it both pass through (37.2, 18.26).
+     */
+    rungs: LaneRung[]
+    handler: Rpc<unknown, unknown> & Gated<unknown> & HeldToAnnotation
+}
+
+/**
+ * What following a handler reads of its row: where it answers, the rungs its route filed, the
+ * handler, and the `tags` its copy carries. 18.3, 18.8, 18.26.
+ */
+export type FollowedHandler = Pick<
+    Mounted,
+    'address' | 'rungs' | 'handler' | 'copy'
+>
+
+/**
+ * The `GET` a browser follows at each address among `handlers` — one it is handed a wrapper for
+ * (20.4) — or `undefined`.
+ */
+export function followedIn(
+    handlers: Map<string, Mounted>,
+): (address: string) => FollowedHandler | undefined {
+    return (address) => {
+        const found = handlers.get(handlerKey('GET', address))
+        return found?.ui === true ? found : undefined
+    }
+}
+
+/**
+ * The row of a handler abide mounts itself, keyed as `answerRpc` looks one up.
+ *
+ * Built on the core's `declare` with no generated surface (20.1) — the app's tree never names it.
+ */
+export function mountedOwn(
+    address: string,
+    name: string,
+    handler: object,
+): [string, Mounted] {
+    // 16.10 — READ WHEN IT IS REPORTED, where a mounted handler's is stamped at boot: the mount is
+    // the configuration's, and nothing boots this handler.
+    Object.defineProperty(handler, 'address', {
+        get: () => underMount(address),
+    })
+    return [
+        address,
+        {
+            address,
+            method: 'GET',
+            // The root's rungs run before routing (37.3), and nothing is filed below a route
+            // of abide's own.
+            rungs: [],
+            source: '',
+            name,
+            export: name,
+            scope: '/',
+            matchers: {},
+            private: false,
+            ui: false,
+            cli: false,
+            mcp: false,
+            description: undefined,
+            copy: undefined,
+            defaults: undefined,
+            args: undefined,
+            result: undefined,
+            handler: handler as Mounted['handler'],
+        },
+    ]
+}
+
+/**
+ * The table's handlers, imported and keyed by method and address.
+ *
+ * Imported through each row's own loader, which the route table shares, so a page rendering on the
+ * server and a call over the wire reach one module and so one handler. AT BOOT rather than on the
+ * first call, because a page's render reaches a handler through the page's own import and has to
+ * know its address before anything has called it over the wire.
+ */
+export async function mountHandlers(
+    table: MountRow[],
+): Promise<{ handlers: Map<string, Mounted> }> {
+    const modules = await Promise.all(table.map((mount) => mount.load()))
+    const handlers = new Map<string, Mounted>()
+    for (let at = 0; at < table.length; at += 1) {
+        const mount = table[at] as Mount
+        const exported = (modules[at] as Record<string, unknown>)[mount.export]
+        const handler = exported as Mounted['handler']
+        // 16.9, 16.10 — the address `rpc.url` and `rpc.raw` build on, under the mount — and what a
+        // page's render turns a call it made into the browser's request by (41.20).
+        handler.address = underMount(mount.address)
+        // 19.9 — the schema the build derived off its annotation, for a handler whose module did not
+        // file it on load: a bundled executable's faces carry no `derivedArgs` call.
+        if (mount.args !== undefined) derivedArgs(handler, mount.args)
+        handlers.set(handlerKey(mount.method, mount.address), {
+            ...mount,
+            // 37.1, 16.72 — the route its file's hooks are filed at, which the build read off
+            // where the file answers (23.19's mount for a package's), never its place on disk.
+            // 37.14 — a handler's lane answers a refusal as Problem Details (15.1).
+            rungs: rungsOver(mount.scope, answered),
+            handler,
+        })
+    }
+    return { handlers }
+}
+
+/** What a handler is keyed by among the mounted: its method and its route. 19.1. */
+export function handlerKey(method: string, address: string): string {
+    return `${method} ${address}`
+}