@abide/abide 0.123.3 → 0.124.0

package/src/server/answerRequest.ts

@@ -16,10 +16,7 @@ import {
 } from '#shared/ADDRESSES.ts'
 import { decodedOrKept } from '#shared/decodedOrKept.ts'
 import { isFailed } from '#shared/Failed.ts'
-import { HandlerRoute } from '#shared/HandlerRoute.ts'
 import { health } from '#shared/health.ts'
-import { KEEP_HEADER } from '#shared/KEEP_HEADER.ts'
-import { KEEP_OPENED } from '#shared/KEEP_OPENED.ts'
 import { matchOf, type Params, partsOf } from '#shared/matchRoute.ts'
 import { compose } from '#shared/Middleware.ts'
 import { mounted } from '#shared/mount.ts'
@@ -27,35 +24,31 @@ import { NAVIGATION_HEADER } from '#shared/NAVIGATION_HEADER.ts'
 import { notFound as refusedNotFound, refuse } from '#shared/refuse.ts'
 import { arrive } from '#shared/route.ts'
 import type { Segment } from '#shared/routePattern.ts'
-import type { Method, Rpc } from '#shared/rpc.ts'
-import { rpcRequest } from '#shared/rpcRequest.ts'
+import type { Method } from '#shared/rpc.ts'
 
 import { answerFailure, laneFailure } from './answerFailure.ts'
-import { answerRpc, type Mounted, mountedOwn } from './answerRpc.ts'
+import { answerRpc } from './answerRpc.ts'
 import { answerBlobTagged, answerValue } from './answerValue.ts'
 import { answerBridge } from './bridgeRelay.ts'
-import { callerOrMint } from './callerOf.ts'
 import { compressAnswer } from './compressAnswer.ts'
-import { noteCallInRender } from './deferredBuilds.ts'
 import { DOCUMENT_HEADERS } from './DOCUMENT_HEADERS.ts'
 import { answerMcp, openApi } from './generatedSurfaces.ts'
 import { failureOf, type LaneRung } from './hooks.ts'
+import { type Mounted, mountedOwn } from './mountHandlers.ts'
 import { muxAdmission } from './muxUpgrade.ts'
 import { OFFLINE_STALE } from './OFFLINE_STALE.ts'
+import { beginPageRender } from './PageRender.ts'
 import { plainAnswer } from './plainAnswer.ts'
 import { PRINCIPAL_MOUNT } from './principal.ts'
 import { boundPage, type Component, renderDocument } from './render.ts'
 import {
     adoptRequest,
     type AnsweringApp,
-    beginRender,
     currentRequestScope,
-    type PageRender,
     type RequestScope,
     within,
     writtenStatus,
 } from './requestScope.ts'
-import { callsOnly, seedFor } from './seedBuffer.ts'
 
 // One row of the server's table the compiler writes (`SERVER_TABLE`). The loader is a dynamic import
 // so a page's markup is off the boot path until an address asks for it, which is the same reason
@@ -146,9 +139,6 @@ export type AppSources = {
     explained: ((thrown: unknown) => Response) | undefined
 }
 
-// 41.29 — the seed sink of a render no page hydrates: every call is left to run when it is made.
-const SEEDS_NOTHING: PageRender['seed'] = () => false
-
 // 35.19 — what fetch calls a navigation request's destinations, and a script's `fetch`.
 const PAGE_DESTINATIONS = new Set([
     'document',
@@ -336,9 +326,6 @@ async function answerMatched(
     // minted for a request that never becomes a page.
     if (request.method === 'HEAD')
         return new Response(null, { status: writtenStatus(), headers })
-    // 26.5 — the caller the seed buffer is keyed by, minted where the browser carries none: the same
-    // one `principal.caller` reads for the rest of the request.
-    const caller = callerOrMint()
     // 23.1 — WHERE THIS PAGE IS, for its setup to read, in the request's own instances (11.32).
     // 16.10 — AT THE ADDRESS IT IS SERVED AT, which is the one the browser's router arrives at: the
     // request reached here with the mount taken off, and a page reading `route.url()` on both sides
@@ -347,23 +334,8 @@ async function answerMatched(
     at.pathname = mounted(at.pathname)
     arrive(at.href, page.pattern, params)
     // 11.32 — the page renders in a scope of its own, so what its values hold is this request's —
-    // and 41.13, every call it makes is left for the browser's own call to be answered from.
-    // 41.29 — BUT NOT A PAGE A SCRIPT FETCHED, which nothing hydrates: its entries would answer the
-    // next call this caller makes with what the render saw, a sign-in since included — save the one
-    // the worker fetched for the navigation it answers, which is the page that hydrates (45.23).
-    const keep = request.headers.get(KEEP_HEADER)
-    const hydrated =
-        keep === KEEP_OPENED ||
-        request.headers.get('sec-fetch-dest') !== 'empty'
-    // 41.30 — SAVE ONE THE WORKER KEEPS, whose early calls are what a later open of it starts.
-    beginRender({
-        seed: hydrated
-            ? seedFor(caller)
-            : keep !== null
-              ? callsOnly()
-              : SEEDS_NOTHING,
-        calls: [],
-    })
+    // and 41.13, every call it makes is recorded into its render.
+    beginPageRender(request)
     // 41.1, 35.2 — THE DOCUMENT IS THE BUILT PAGE, read whole before there is a `Response` to commit a
     // status to: a refusal the page read, or a throw, is answered by the nearest error page at its own
     // status rather than as a 200 the stream then abandons.
@@ -411,42 +383,6 @@ const SURFACES = new Map<
     [BRIDGE_ADDRESS, (_app, request) => answerBridge(request)],
 ])
 
-// Each handler's route, compiled once rather than per render that calls it — as its `Rpc` keeps its
-// own; compiled again only where it was mounted at another address since.
-const ROUTE_OF = new WeakMap<object, HandlerRoute>()
-
-// What a call made in a page's render reports into: the seed buffer (41.13), and — where the handler
-// is mounted — the request the browser will make for it, for the early-call script (41.20). Once per
-// render, as the browser's `Rpc` makes it once, and the seed buffer is what says which is the once.
-export function reachedInRender(
-    rpc: object,
-    args: unknown,
-    reached: unknown,
-): void {
-    const page = currentRequestScope()?.page
-    if (page === undefined) return
-    noteCallInRender()
-    if (!page.seed(rpc, args, reached)) return
-    // 16.10 — the address the browser's own call is made at, stamped under the mount by
-    // `mountHandlers` — and `undefined` on a handler nothing mounted.
-    const { address, method } = rpc as Rpc<unknown, unknown>
-    if (address === undefined) return
-    let route = ROUTE_OF.get(rpc)
-    if (route?.address !== address) {
-        route = new HandlerRoute(address)
-        ROUTE_OF.set(rpc, route)
-    }
-    page.calls.push({
-        request: rpcRequest(
-            method,
-            route,
-            args as Record<string, unknown> | undefined,
-        ),
-        reached,
-        painted: undefined,
-    })
-}
-
 /**
  * The server's table the compiler writes (`SERVER_TABLE`): the routes and the error pages.
  *

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, HeldToAnnotation } 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 { 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,184 +21,24 @@ import {
     type ErrorPages,
     handlerHeaders,
 } from './answerFailure.ts'
-import { followAsEvents } from './answerSocket.ts'
 import { answerValue, namesEtag, sseHeaders } from './answerValue.ts'
-import { argsFor, collapsed, derivedArgs } from './argsContract.ts'
-import { callerOf } from './callerOf.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 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'],
-        },
-    ]
-}
-
 // 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']
-        // 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}`
-}
-
 /**
  * The `Response` to a call of `found` made over http, `params` being what its route matched.
  *
@@ -228,92 +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)
-    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(
-            handler,
-            raw,
-            inUrl ? url.search : form ? '' : undefined,
-            params,
-        )
-    } 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)
 }
 
@@ -335,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
@@ -370,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
@@ -404,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 },