@abide/abide 0.123.2 → 0.124.0

package/src/server/answerRpc.ts

@@ -1,21 +1,15 @@
-// 16.2 — A HANDLER, ANSWERED OVER HTTP. The call is the in-process one (`#shared/rpc.ts`), made in a
-// request's own scope (11.32), and what this module adds is the transport either side of it: the
-// args off the request, and the answer onto a response.
+// 16.2 — A HANDLER, ANSWERED OVER HTTP. The call is `invokeHandler`'s, made in a request's own scope
+// (11.32), and what this module adds is the transport either side of it: the args off the request,
+// and the answer onto a response.
 //
-// WIRE-ONLY, per 16.13: the `Origin` gate on a mutation, `maxBodySize`, the `crossOrigin` preflight,
-// and 19.7's coercion of the text a URL carried.
+// WIRE-ONLY, per 16.13: `maxBodySize`, the `crossOrigin` preflight, and the text a URL or a form
+// carried the args as.
 
-import type { CopyOptions } from '#shared/CopyOptions.ts'
 import { type Failed, isFailed } from '#shared/Failed.ts'
-import { GLOBAL_GETS } from '#shared/GLOBAL_GETS.ts'
 import { isRecord } from '#shared/isRecord.ts'
-import type { JsonValue } from '#shared/JsonValue.ts'
 import { mounted as underMount } from '#shared/mount.ts'
-import type { Gated } from '#shared/reactive/argsContract.ts'
-import { deadlineOf, heldGenerationOf } from '#shared/reactive/index.ts'
-import type { Defaults } from '#shared/reactive/parameterDefaults.ts'
+import { deadlineOf } from '#shared/reactive/producer.ts'
 import { notFound, refuse } from '#shared/refuse.ts'
-import type { HeldToAnnotation, Method, Rpc } from '#shared/rpc.ts'
 import { RPC_SERVER } from '#shared/RPC_SERVER.ts'
 import { argsInURL } from '#shared/rpcRequest.ts'
 import { VERSION_HEADER } from '#shared/VERSION_HEADER.ts'
@@ -27,196 +21,24 @@ import {
     type ErrorPages,
     handlerHeaders,
 } from './answerFailure.ts'
-import { followAsEvents } from './answerSocket.ts'
 import { answerValue, namesEtag, sseHeaders } from './answerValue.ts'
-import { argsFor } from './argsFor.ts'
-import { callerOf } from './callerOf.ts'
-import {
-    argsDocumentOf,
-    coerceArgs,
-    collapsed,
-    type Document,
-} from './coerceArgs.ts'
+import { collapsed } from './argsContract.ts'
 import { positiveSetting } from './config.ts'
-import {
-    allows,
-    closedTo,
-    crossingOrigin,
-    crossingRefusal,
-} from './crossingOrigin.ts'
-import { failureOf, type LaneRung, rungsOver } from './hooks.ts'
+import { allows, crossingOrigin } from './crossingOrigin.ts'
+import { failureOf } from './hooks.ts'
+import { type Invocation, invokeHandler, originGate } from './invokeHandler.ts'
+import type { Mounted } from './mountHandlers.ts'
 import { OFFLINE_STALE } from './OFFLINE_STALE.ts'
 import { prefers } from './prefers.ts'
-import {
-    currentRequestScope,
-    rungsTook,
-    timed,
-    unreap,
-    writtenStatus,
-} from './requestScope.ts'
-import { type Outcome, outcomeOf, takeSeed } from './seedBuffer.ts'
+import { currentRequestScope, unreap, writtenStatus } from './requestScope.ts'
+import type { Outcome } from './seedBuffer.ts'
 import { versionOf } from './versionOf.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
-    /**
-     * The args' JSON Schema, probed once at mount.
-     *
-     * 19.7, 20.11 — a third-party schema converts itself on every probe.
-     */
-    argsDocument: Document | 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'],
-            argsDocument: undefined,
-        },
-    ]
-}
-
 // 16.58 — the environment's `timeout`, for every call a handler that names none makes.
 export function environmentTimeout(): number | undefined {
     return positiveSetting('ABIDE_RPC_TIMEOUT', undefined)
 }
 
-/**
- * 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']
-        const declared = argsDocumentOf(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)
-        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,
-            argsDocument: declared ?? (mount.args as Document | undefined),
-        })
-    }
-    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}`
-}
-
 /**
  * The `Response` to a call of `found` made over http, `params` being what its route matched.
  *
@@ -240,89 +62,46 @@ export async function answerRpc(
         return origin !== null && allows(found.handler.crossOrigin, origin)
             ? preflight(found, origin, request)
             : answered(notFound({ path: pathname, method: request.method }))
-    // 16.50 — a `HEAD` is the `GET`'s answer, which the server sends without its body.
-    const head = request.method === 'HEAD'
-    const handler = found.handler
     const inUrl = argsInURL(found.method)
     const form = isForm(request)
-    const crossing = crossingOrigin(origin, url)
-    const closed = closedTo(handler.crossOrigin, crossing)
     // 21.19 — the origin the answer admits, where the handler declared it may read.
-    const admitted = closed ? null : crossing
-    // 16.13 — A MUTATION FROM ANOTHER ORIGIN IS REFUSED unless the handler declared it may come.
-    if (closed && !inUrl)
-        return answered(crossingRefusal(crossing, found.method))
-    const raw = await argsOf(request, url, inUrl, form, handler.maxBodySize)
+    const admitted = originGate(
+        found.handler,
+        crossingOrigin(origin, url),
+        false,
+    )
+    if (isFailed(admitted)) return answered(admitted)
+    const raw = await argsOf(
+        request,
+        url,
+        inUrl,
+        form,
+        found.handler.maxBodySize,
+    )
     if (isFailed(raw)) return answered(raw)
-    const sent = withParameters(raw, params, inUrl || form, found)
-    if (isFailed(sent)) return answered(sent)
-    let args: unknown
-    try {
-        // A URL's and a form's args are text, and the query tells a bare name from `name=` (19.7).
-        args = argsFor(found, sent, inUrl ? url.search : form ? '' : undefined)
-    } catch (refused) {
-        if (isFailed(refused)) return answered(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).
-    // 16.51 — a `HEAD` leaves the seed for the `GET` it stands in front of.
-    const caller = head ? undefined : callerOf()
-    const seeded =
-        caller === undefined ? undefined : takeSeed(caller, handler, args)
-    // 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
-    // The entry as the run left it, which the answer reads too.
-    const entry = key === undefined ? undefined : global?.at(key)
-    const cached =
-        heldAt !== undefined &&
-        entry === held &&
-        heldGenerationOf(held) === heldAt
+    // A URL's and a form's args are text, and the query tells a bare name from `name=` (19.7).
+    // 16.50 — a `HEAD` is the `GET`'s answer, which the server sends without its body; 16.51 — and
+    // it leaves the seed for the `GET` it stands in front of.
+    const invoked = await invokeHandler(
+        found,
+        raw,
+        inUrl ? url.search : form ? '' : undefined,
+        params,
+        request.method !== 'HEAD',
+    )
+    if (isFailed(invoked)) return answered(invoked)
+    const outcome = invoked.outcome
     // 16.38 — A MUTATION A DOCUMENT MADE — a form posted with no script — is answered as a navigation.
     if (!inUrl && prefers(request, 'text/html', 'application/json'))
         return navigated(outcome, request, pathname, pages)
-    const answer = await answerOutcome(
-        outcome,
-        request,
-        found,
-        args,
-        key,
-        entry,
-        offline,
-    )
+    const answer = await answerOutcome(invoked, request, found, offline)
     // A `Response` the handler built is its own — but the origin answer below is laid over it, so it
     // varies on `Origin` too (21.7), which `handlerHeaders` never reached.
     if (outcome.settled && outcome.value instanceof Response) {
         answer.headers.append('vary', 'origin')
         return admitting(answer, admitted)
     }
-    // 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. A stream's time is to its first
-    // chunk, which the answer's head waited for.
-    const took = outcome.duration ?? performance.now() - started
-    const run =
-        seeded !== undefined
-            ? 'Seeded'
-            : cached
-              ? 'Cached'
-              : outcome.duration === undefined
-                ? 'Started'
-                : 'Direct'
-    // 21.20 — what the rungs took is theirs, and the handler's own body is what `Direct` reports.
-    const handled = run === 'Direct' ? timing?.handled : undefined
-    if (handled !== undefined) rungsTook(took - handled)
-    timed(timing, run, handled ?? took)
+    invoked.timed()
     return admitting(answer, admitted)
 }
 
@@ -344,15 +123,12 @@ function admitting(answer: Response, admitted: string | null): Response {
 }
 
 async function answerOutcome(
-    outcome: Outcome,
+    invoked: Invocation,
     request: Request,
     found: Mounted,
-    args: unknown,
-    key: string | undefined,
-    entry: unknown,
     offline: boolean,
 ): Promise<Response> {
-    const handler = found.handler
+    const { outcome, entry } = invoked
     if (!outcome.settled) return answered(failureOf(outcome.error))
     const value = outcome.value
     // The `global` value the answer came from, or `undefined` for one built per request. 18.22 — or
@@ -379,7 +155,8 @@ async function answerOutcome(
     const etag = serving !== undefined ? `"${versionOf(serving)}"` : undefined
     if (etag !== undefined) {
         headers.set(VERSION_HEADER, etag)
-        RPC_SERVER.served?.(handler, serving, key as string)
+        for (const followers of RPC_SERVER.following)
+            followers.served(found.handler, serving, invoked.key as string)
     }
     // 21.22 — A `GET` THE DEVICE KEEPS, where the worker is there to keep it: a value, not a
     // refusal (16.40) nor a stream with no end to keep (16.32) — a generator's, or the lines a
@@ -413,17 +190,19 @@ async function answerOutcome(
     // 18.20 — A READER ASKING FOR AN EVENT STREAM IS FOLLOWED, rather than answered once: the value,
     // then each change, from the version its `Last-Event-ID` names. A handler that streams answers
     // its own chunks as it always has (16.45).
+    const followers = currentRequestScope()?.app?.followers
     if (
         etag !== undefined &&
+        followers !== undefined &&
         !streams(outcome.value) &&
         prefers(request, 'text/event-stream', 'application/json')
     ) {
         const events = handlerHeaders()
         sseHeaders(events)
         return new Response(
-            followAsEvents(
+            followers.events(
                 found,
-                args,
+                invoked.args,
                 versionInEtag(request.headers.get('last-event-id')),
             ),
             { status: 200, headers: events },
@@ -478,39 +257,6 @@ async function argsOf(
     return parsed
 }
 
-/**
- * The args a request sent, with the parameters its route matched laid in.
- *
- * 16.65 — the path's, whatever the method. 16.66 — a parameter the query or the body names as
- * well is refused rather than one of the two chosen. A JSON body's members are typed already, so the
- * path's text is coerced to the declared types before it joins them (19.7); text args are coerced
- * with the rest of the text.
- */
-function withParameters(
-    sent: unknown,
-    params: Record<string, string | string[]>,
-    text: boolean,
-    found: Mounted,
-): unknown | Failed<'HttpError', undefined> {
-    let none = true
-    for (const name in params) {
-        none = false
-        if (isRecord(sent) && name in sent)
-            return refuse(
-                400,
-                `The parameter '${name}' is in the path and in the request as well.`,
-            )
-    }
-    if (none) return sent
-    const fromPath = text
-        ? params
-        : (coerceArgs(params, found.argsDocument, '') as Record<
-              string,
-              unknown
-          >)
-    return isRecord(sent) ? { ...sent, ...fromPath } : { ...fromPath }
-}
-
 /**
  * The request's body, received whole, under the ceiling `maxBodySize` sets, or
  * `ABIDE_MAX_REQUEST_BODY_SIZE` where it is unset, or a 413 refusal past it.