@abide/abide 0.101.0 → 0.103.0

package/src/server/answerRpc.ts

@@ -30,7 +30,12 @@ import { followAsEvents } from './answerSocket.ts'
 import { answerValue, namesEtag, sseHeaders } from './answerValue.ts'
 import { argsFor } from './argsFor.ts'
 import { callerOf } from './callerOf.ts'
-import { argsDocumentOf, collapsed, type Document } from './coerceArgs.ts'
+import {
+    argsDocumentOf,
+    coerceArgs,
+    collapsed,
+    type Document,
+} from './coerceArgs.ts'
 import { positiveSetting } from './config.ts'
 import {
     allows,
@@ -38,7 +43,7 @@ import {
     crossingOrigin,
     crossingRefusal,
 } from './crossingOrigin.ts'
-import { failureOf } from './hooks.ts'
+import { type AppRung, failureOf, rungsOver } from './hooks.ts'
 import { prefers } from './prefers.ts'
 import {
     currentRequestScope,
@@ -51,7 +56,8 @@ import { type Outcome, outcomeOf, takeSeed } from './seedBuffer.ts'
 import { versionOf } from './versionOf.ts'
 
 /**
- * One row of the table the build writes to `<out>/rpc.ts`: where a handler answers, and its module.
+ * 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.
  */
@@ -59,10 +65,17 @@ 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
+    /** 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.63. */
+    /** 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.
@@ -88,9 +101,20 @@ export type Mount = {
     args: 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 & {
-    method: Method
+    /**
+     * 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: AppRung[]
     handler: Rpc<unknown, unknown> & Gated<unknown>
     /**
      * The args' JSON Schema, probed once at mount.
@@ -127,8 +151,14 @@ export function mountedOwn(
         {
             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: '/',
+            private: false,
             ui: false,
             cli: false,
             mcp: false,
@@ -149,32 +179,31 @@ export function environmentTimeout(): number | undefined {
 }
 
 /**
- * The table's handlers, imported and keyed by address.
+ * The table's handlers, imported and keyed by method and address.
  *
- * Imported from the SOURCE tree, 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.
+ * 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: Mount[],
-    moduleOf: (source: string) => Promise<Record<string, unknown>>,
+    table: MountRow[],
 ): Promise<{ handlers: Map<string, Mounted> }> {
-    const modules = await Promise.all(
-        table.map((mount) => moduleOf(mount.source)),
-    )
+    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.name]
+        const exported = (modules[at] as Record<string, unknown>)[mount.export]
         const handler = exported as Rpc<unknown, unknown> & Gated<unknown>
         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(mount.address, {
+        handlers.set(handlerKey(mount.method, mount.address), {
             ...mount,
-            method: mount.method,
+            // 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.
+            rungs: rungsOver(mount.scope),
             handler,
             argsDocument: declared ?? (mount.args as Document | undefined),
             wireArgs: declared === undefined ? mount.args : undefined,
@@ -183,30 +212,34 @@ export async function mountHandlers(
     return { handlers }
 }
 
-/** The `Response` to a handler call made over http. */
+/** 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.
+ *
+ * `found` answers the request's method — or, for an `OPTIONS`, the method its preflight asks
+ * about: which handler a request reaches is the route table's to say (19.20).
+ */
 export async function answerRpc(
-    handlers: Map<string, Mounted>,
+    found: Mounted,
+    params: Record<string, string | string[]>,
     url: URL,
     request: Request,
     // 16.38 — what paints a refusal for a request that came as a navigation.
     pages: ErrorPages,
 ): Promise<Response> {
     const pathname = url.pathname
-    const found = handlers.get(pathname)
     const origin = request.headers.get('origin')
     // 16.24 — THE PREFLIGHT, answered by abide where the handler declared `crossOrigin`.
-    if (
-        found !== undefined &&
-        request.method === 'OPTIONS' &&
-        origin !== null &&
-        allows(found.handler.crossOrigin, origin)
-    )
-        return preflight(found, origin, request)
+    if (request.method === 'OPTIONS')
+        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'
-    // 15.7 — no handler at this address AND this method is one refusal, not two.
-    if (found === undefined || found.method !== (head ? 'GET' : request.method))
-        return answered(notFound({ path: pathname, method: request.method }))
     const handler = found.handler
     const inUrl = argsInURL(found.method)
     const form = isForm(request)
@@ -226,10 +259,12 @@ export async function answerRpc(
         return answered(overCeiling(ceiling))
     const raw = await argsOf(request, url, inUrl, form, ceiling)
     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, raw, inUrl ? url.search : form ? '' : undefined)
+        args = argsFor(found, sent, inUrl ? url.search : form ? '' : undefined)
     } catch (refused) {
         if (isFailed(refused)) return answered(refused)
         throw refused
@@ -436,6 +471,39 @@ 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 read up to `ceiling`, as a `Response`, or a 413 refusal past it.
  *
@@ -487,6 +555,12 @@ function preflight(found: Mounted, origin: string, request: Request): Response {
  * 16.57 — `Infinity` is never reaped, which bun spells 0; any finite bound is capped at the 255
  * seconds bun's idle timeout can hold.
  *
+ * FOUR SECONDS PAST THE TIMEOUT, NOT AT IT: a load that goes its timeout is refused at that moment,
+ * and a stream's refusal is a frame written then (16.68). bun's sockets check an idle timeout on a
+ * tick four seconds wide, so an idle timeout of the same second — or one past it — fired anywhere in
+ * the tick before it and reaped the connection ahead of the frame, one stream in two under `abide
+ * dev`. Four is the tick, so the refusal always goes out first.
+ *
  * ON THE REQUEST THE LISTENER RECEIVED, never the one being answered: under a mount, or past a
  * rung that handed `next` its own, that is a copy, and bun's `timeout` does nothing for a request
  * it was not handed itself.
@@ -496,7 +570,7 @@ export function raiseTimeout(milliseconds: number): void {
     const received = scope?.received
     if (scope === undefined || received === undefined) return
     const seconds = Number.isFinite(milliseconds)
-        ? Math.min(255, Math.ceil(milliseconds / 1000))
+        ? Math.min(255, Math.ceil(milliseconds / 1000) + 4)
         : Number.POSITIVE_INFINITY
     if (seconds <= scope.timeout) return
     scope.timeout = seconds

package/src/server/answerSocket.ts

@@ -10,18 +10,20 @@
 // built per request, since a trigger names args rather than a value. A `global` value is also fed its productions, a guarded one only to a
 // subscription its rungs admitted when it opened (18.8) — they run once, in the connection's request.
 
-import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
 import { type Problem, problemOf } from '#shared/Failed.ts'
 import { GLOBAL_GETS } from '#shared/GLOBAL_GETS.ts'
 import { namedLogger } from '#shared/log.ts'
+import { compose } from '#shared/Middleware.ts'
+import { unmounted } from '#shared/mount.ts'
+import type { BrowserFrame, ServerFrame } from '#shared/muxFrames.ts'
 import { FOLLOWED } from '#shared/reactive/FOLLOWED.ts'
 import { servedCellOf } from '#shared/reactive/index.ts'
 import { matchesPattern } from '#shared/reactive/matchesPattern.ts'
 import { PATCH_SINKS } from '#shared/reactive/PATCH_SINKS.ts'
 import { unowned } from '#shared/reactive/watch.ts'
 import { refuse } from '#shared/refuse.ts'
-import type { BrowserFrame, ServerFrame } from '#shared/muxFrames.ts'
-import type { Mounted } from './answerRpc.ts'
+import { rpcRequest } from '#shared/rpcRequest.ts'
+import { handlerKey, type Mounted } from './answerRpc.ts'
 import { argsFor } from './argsFor.ts'
 import { closedTo, crossingOrigin, crossingRefusal } from './crossingOrigin.ts'
 import { failureOf } from './hooks.ts'
@@ -38,7 +40,7 @@ import { patchesSince, versionOf } from './versionOf.ts'
  * The far end of one connection to the mux, which its frames are written to.
  *
  * Bun's socket under `abide start`, and under `abide dev` a stand-in that posts each frame to the
- * listener holding the real one (38.15).
+ * listener holding the real one (38.14).
  */
 export type Peer = {
     send(text: string): unknown
@@ -141,10 +143,10 @@ export function feedFromServed(
  * Only where that entry is not the one it is fed from already.
  */
 function attach(rpc: Mounted['handler'], follower: Follower): unknown {
-    const serving =
-        rpc.guarded && !follower.admitted
-            ? undefined
-            : GLOBAL_GETS.get(rpc)?.at(follower.key)
+    // 18.8, 18.26 — what its own rungs or its route's refused is sent its triggers alone.
+    const serving = !follower.admitted
+        ? undefined
+        : GLOBAL_GETS.get(rpc)?.at(follower.key)
     if (serving === follower.serving) return serving
     follower.stopFeed?.()
     // A version is one entry's count, so what it was sent of another says nothing about this one.
@@ -250,8 +252,8 @@ export class MuxConnection {
             return
         }
         const id = frame.id ?? 0
-        // THE ADDRESS FROM `/__abide` ON, which is what both tables are keyed by: a browser names
-        // it as its wrapper resolved it, which is a whole URL, or a path under the app's mount.
+        // THE ADDRESS BELOW THE MOUNT, which is what the handlers are keyed by: a browser names it
+        // as its wrapper resolved it, which is a whole URL, or a path under the app's mount.
         const address = addressIn(frame.address ?? '')
         const subscriptions = this.subscriptions
         if (frame.op === 'unsub') {
@@ -260,7 +262,9 @@ export class MuxConnection {
             return
         }
         const handler =
-            frame.op === 'sub' ? this.mux.handlers.get(address) : undefined
+            frame.op === 'sub'
+                ? this.mux.handlers.get(handlerKey('GET', address))
+                : undefined
         const followed = handler?.ui ? handler : undefined
         if (followed === undefined) {
             send(this.peer, {
@@ -295,16 +299,24 @@ export class MuxConnection {
             // 18.8 — A GUARDED `GET`'s RUNGS RUN ONCE, as the subscription opens, in this
             // connection's request: one they admit is fed the value, and one they refuse is sent its
             // triggers alone.
-            let admitted = !followed.handler.guarded
+            // 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.
+            const routed = followed.rungs.length > 0
+            let admitted = !followed.handler.guarded && !routed
             if (!admitted) {
                 subscriptions.get(id)?.()
                 subscriptions.set(id, pending)
-                admitted = await Promise.resolve(
-                    followed.handler(args as never) as PromiseLike<unknown>,
-                ).then(
-                    () => true,
-                    () => false,
-                )
+                // No route rungs, no turn: a guarded `GET`'s rungs start in this frame's own run.
+                admitted =
+                    !routed || (await routeAdmits(this.scope, followed, args))
+                if (admitted && followed.handler.guarded)
+                    admitted = await Promise.resolve(
+                        followed.handler(args as never) as PromiseLike<unknown>,
+                    ).then(
+                        () => true,
+                        () => false,
+                    )
                 if (subscriptions.get(id) !== pending) return
             }
             follow(this, id, followed, args, frame.version, admitted)
@@ -315,6 +327,39 @@ export class MuxConnection {
     }
 }
 
+/**
+ * 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(
+    scope: RequestScope,
+    mounted: Mounted,
+    args: unknown,
+): Promise<boolean> {
+    const upgrade = scope.request as Request
+    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
+    }
+}
+
 /**
  * Follows a handler for `id`: its triggers always, its value where `global` and unguarded.
  *
@@ -564,8 +609,8 @@ function sendAll(serving: unknown, fed: Iterable<Follower>): void {
 }
 
 function addressIn(named: string): string {
-    const at = named.indexOf(ABIDE_ADDRESS)
-    return at === -1 ? named : named.slice(at)
+    const path = URL.parse(named)?.pathname ?? named
+    return unmounted(path) ?? path
 }
 
 /**

package/src/server/answerValue.ts

@@ -3,6 +3,8 @@
 // (16.35), a document where `page` named one (17.2), a stream — a streaming handler's chunks, or
 // `Values` a handler returned — framed one chunk per pull (16.32, 16.44–16.47).
 
+import { isFailed, problemOf } from '#shared/Failed.ts'
+import { refusalFrame } from '#shared/framing.ts'
 import { compressAnswer } from './compressAnswer.ts'
 import { prefers } from './prefers.ts'
 import {
@@ -158,7 +160,7 @@ export function linesType(request: Request): string {
         : 'application/jsonl'
 }
 
-/** A stream answered at a framing already decided — a handler's, and `log.records` (36.7). */
+/** A stream answered at a framing already decided — a handler's. */
 export function framed(
     chunks: AsyncIterator<unknown>,
     framing: Framing,
@@ -185,7 +187,7 @@ export function framed(
  * was reading in its scope.
  *
  * AN EVENT STREAM OPENS ON A COMMENT: a streamed answer's head goes out with its first byte, so a
- * stream with nothing yet to say — an empty `log.records` — held its reader's headers until it did.
+ * stream with nothing yet to say held its reader's headers until it did.
  *
  * `first` is a result already pulled — the one a framing was decided from — and is sent ahead of
  * the rest.
@@ -230,7 +232,20 @@ export function bodyOf(
                     next = await chunks.next()
                 } catch (thrown) {
                     if (ended) return
-                    controller.error(thrown)
+                    // 16.68 — A REFUSAL AFTER THE STATUS WAS SENT is the stream's last frame, so the
+                    // reader refuses with it rather than reading a dropped connection. Bytes carry no
+                    // framing to hold one, and anything else is not a refusal to send.
+                    if (framing !== 'bytes' && isFailed(thrown)) {
+                        controller.enqueue(
+                            ENCODER.encode(
+                                refusalFrame(
+                                    problemOf(thrown),
+                                    framing === 'sse' ? 'data: ' : '',
+                                ),
+                            ),
+                        )
+                        controller.close()
+                    } else controller.error(thrown)
                     release()
                     return
                 }
@@ -314,12 +329,10 @@ export function answerBlobTagged(
             })
         }
     }
-    // A RANGE DECLINED — `If-Range` naming another version, or one this does not parse. Bun.serve
-    // ranges a file-backed 200 body on its own and reads no `If-Range` when it does, so the file, or
-    // its `stream()`, would go out 206 anyway; piped, the body is no longer one it can see is a file.
-    const body =
-        range === null ? blob : blob.stream().pipeThrough(new TransformStream())
-    return new Response(body, { status, headers })
+    // A RANGE DECLINED — `If-Range` naming another version, or one this does not parse — goes out
+    // whole as the blob itself: Bun.serve ranges a file-backed body on its own, but declines exactly
+    // these, so a file still leaves from disk.
+    return new Response(blob, { status, headers })
 }
 
 /**

package/src/server/appDirectories.ts

@@ -1,7 +1,7 @@
 /**
  * The directories an app's own files stand in: `root`, and the one above it.
  *
- * `root` is the directory `ui/` sits under — `src/` — and the one above it is the package beside
+ * `root` is the app's root — `src/` — and the one above it is the package beside
  * it. The app's `package.json` and `bunfig.toml` are found in the first that has one.
  */
 export function appDirectories(root: string): string[] {

package/src/server/appPlugins.ts

@@ -3,7 +3,7 @@ import { appDirectories } from './appDirectories.ts'
 /**
  * The app's own bundler plugins, loaded from `bunfig.toml`'s `[serve.static] plugins`.
  *
- * 38.44 — declared where bun already has an app declare them, the key `bun-plugin-tailwind`
+ * 38.43 — declared where bun already has an app declare them, the key `bun-plugin-tailwind`
  * documents. `Bun.build` reads no bunfig, so both client builds read this one — in
  * `appDirectories`, as `config` finds the app's `package.json`.
  */