@abide/abide 0.102.0 → 0.104.0

package/src/server/abideModules.ts

@@ -7,8 +7,8 @@
 // WHICH FACE AN IMPORT GETS IS SPELLED ON ITS SPECIFIER (`MODULE_QUERIES`), because bun hands a plugin
 // no import attributes: a compiled module asks for `?component`, a browser module for its own
 // `?style`, a text import for `?text`. A `.abide` named bare is a module abide did not compile
-// asking — on a server that is the bound face 34.16 states, beside every name the module exports,
-// and in a browser the component module itself.
+// asking — on a server that is the bound face 34.16 states, and in a browser the component module
+// itself.
 //
 // THE TABLES — the route, error and handler tables, and in a browser the router's table and the
 // entry — are the build's own modules, served from `__abide` below the root, where no app writes.
@@ -17,13 +17,16 @@
 // that registered one, so a second app booted in the same process — a test's — adds its compilation
 // to this one rather than registering a plugin nobody asks.
 
-import { dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
+import { basename, dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
+import { SERVER_SPECIFIER } from '#shared/SPECIFIERS.ts'
 import type { ServerTable } from './answerRequest.ts'
 import type { MountRow } from './answerRpc.ts'
 import { installSourceMaps, type SourceMaps } from './installSourceMaps.ts'
 import {
     CLIENT_QUERY,
     COMPONENT_QUERY,
+    HANDLER_FACE,
+    HANDLER_SUFFIX,
     STYLE_QUERY,
     TEXT_QUERY,
 } from './MODULE_QUERIES.ts'
@@ -51,8 +54,18 @@ export type CompiledFile = {
 export type Compilation = {
     /** Every `.abide` compiled, by its path below the root. */
     files: Record<string, CompiledFile>
+    /**
+     * Every handler file, by its path below the root: the route its hooks are filed at (37.1), and
+     * the module a browser is handed in its place (16.74), `''` where the browser is handed none.
+     */
+    handlers: Record<string, HandlerFace>
     /** The build's own modules, by name below `__abide`. */
     tables: Record<string, string>
+    /**
+     * 23.19 — every directory a file mounts, by its path below the root, to the position its files
+     * take: what the browser's fence reads a mounted file's place by (16.29).
+     */
+    mounted: Record<string, string>
 }
 
 // A VIRTUAL FACE'S PATH: its file's, with a suffix that is not a query. Both registries key a module
@@ -68,29 +81,40 @@ export const COMPONENT_NAMESPACE = 'abide-component'
 /** The namespaces a file's text and a component's stylesheet are loaded in. */
 export const TEXT_NAMESPACE = 'abide-text'
 export const STYLE_NAMESPACE = 'abide-style'
+const RELATIVE_OR_SUBPATH = /^(?:\.\.?\/|#)/
 
-/** What the plugin answers from: a compiled file or a table by absolute path. */
-type Served = {
-    file: (path: string) => CompiledFile | undefined
-    table: (path: string) => string | undefined
-}
+/** One handler file, as `Compilation.handlers` holds it. */
+type HandlerFace = { scope: string; client: string }
 
 /** The plugin serving `compilation`'s files and tables, for one bundle. */
 export function abideModules(
     root: string,
     compilation: Compilation,
 ): Bun.BunPlugin {
-    const files = new Map<string, CompiledFile>()
-    const tables = new Map<string, string>()
-    addCompilation(realOrAsGiven(root), compilation, files, tables)
-    return modulesPlugin({
-        file: (path) => files.get(path),
-        table: (path) => tables.get(path),
-    })
+    const held: Held = {
+        files: new Map(),
+        handlers: new Map(),
+        tables: new Map(),
+    }
+    addCompilation(realOrAsGiven(root), compilation, held)
+    return modulesPlugin(held)
+}
+
+/**
+ * A compilation as the plugin keys it, and answers from: a compiled file, a handler file or a table
+ * by absolute path.
+ */
+type Held = {
+    files: Map<string, CompiledFile>
+    handlers: Map<string, HandlerFace>
+    tables: Map<string, string>
 }
 
-const RUNTIME_FILES = new Map<string, CompiledFile>()
-const RUNTIME_TABLES = new Map<string, string>()
+const RUNTIME: Held = {
+    files: new Map(),
+    handlers: new Map(),
+    tables: new Map(),
+}
 let registered = false
 
 /**
@@ -99,16 +123,37 @@ let registered = false
  */
 export function serveCompilation(root: string, compilation: Compilation): void {
     const real = realOrAsGiven(root)
-    addCompilation(real, compilation, RUNTIME_FILES, RUNTIME_TABLES)
+    const handlerFiles = addCompilation(real, compilation, RUNTIME)
     installSourceMaps(serverMapsOf(compilation, real), real)
+    if (handlerFiles.length !== 0) Bun.plugin(handlerFilesPlugin(handlerFiles))
     if (registered) return
     registered = true
-    Bun.plugin(
-        modulesPlugin({
-            file: (path) => RUNTIME_FILES.get(path),
-            table: (path) => RUNTIME_TABLES.get(path),
-        }),
-    )
+    Bun.plugin(modulesPlugin(RUNTIME))
+}
+
+// 16.2 — A HANDLER FILE LOADED AT ITS OWN PATH RE-EXPORTS ITS FACE, so every spelling of its import
+// is the module the server mounted. The runtime asks `onResolve` only for a specifier with an
+// extension, while `onLoad` is asked by the path the file resolved to, however it was spelled. One
+// plugin per compilation because the filter is fixed at registration, and the runtime's `onLoad`
+// cannot fall through, so the filter names the handler files and nothing else. The face it names
+// is resolved by `modulesPlugin`, registered once.
+function handlerFilesPlugin(paths: string[]): Bun.BunPlugin {
+    return {
+        name: 'abide-handler-files',
+        setup(build) {
+            build.onLoad(
+                {
+                    filter: new RegExp(
+                        `^(?:${paths.map(RegExp.escape).join('|')})$`,
+                    ),
+                },
+                (args) => ({
+                    contents: `export { default } from ${JSON.stringify(`${args.path}${HANDLER_SUFFIX}`)}\n`,
+                    loader: 'js',
+                }),
+            )
+        },
+    }
 }
 
 /** What the server's table exports: its routes and error pages, server blocks and handlers. */
@@ -143,17 +188,24 @@ export function serverMapsOf(
     return maps
 }
 
+/** Adds `compilation` to `held`, and answers its handler files' absolute paths. */
 function addCompilation(
     root: string,
     compilation: Compilation,
-    files: Map<string, CompiledFile>,
-    tables: Map<string, string>,
-): void {
+    held: Held,
+): string[] {
     // RESOLVED, not joined: a dependency's file is keyed above the root (`../node_modules/…`).
     for (const [relative, compiled] of Object.entries(compilation.files))
-        files.set(resolve(root, relative), compiled)
+        held.files.set(resolve(root, relative), compiled)
+    const handlerFiles: string[] = []
+    for (const [relative, face] of Object.entries(compilation.handlers)) {
+        const path = resolve(root, relative)
+        held.handlers.set(path, face)
+        handlerFiles.push(path)
+    }
     for (const [name, text] of Object.entries(compilation.tables))
-        tables.set(`${root}/${VIRTUAL_DIRECTORY}/${name}`, text)
+        held.tables.set(`${root}/${VIRTUAL_DIRECTORY}/${name}`, text)
+    return handlerFiles
 }
 
 // `Bun.resolveSync` asks EVERY abide plugin's `onResolve` again — this one's, and the runtime's, which
@@ -178,7 +230,7 @@ export function resolvedFile(specifier: string, from: string): string {
     }
 }
 
-function modulesPlugin(served: Served): Bun.BunPlugin {
+function modulesPlugin(served: Held): Bun.BunPlugin {
     return {
         name: 'abide-modules',
         setup(build) {
@@ -264,12 +316,54 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
                         dirname(pathOf(args.importer)),
                         args.path,
                     )
-                    return served.table(path) === undefined
+                    return served.tables.get(path) === undefined
                         ? undefined
                         : { path, namespace: 'abide-table' }
                 },
             )
 
+            // A HANDLER FILE IS FOUND BY WHERE ITS IMPORT RESOLVES, however the import spells it, and
+            // only from the app's own modules: a package's never names one, and asking bun again for
+            // each of a package's relative imports is a resolve per module of the bundle. THE FILTER
+            // IS THE HANDLER FILES' NAMES: a hook matching every relative import costs the bundle
+            // abide's own `sideEffects`, and the barrel's rest — the validator, the csp — moved into
+            // the chunk every page loads (38.94). ONLY IN A BUNDLE: the runtime finds a handler file
+            // by the path it loads at (`handlerFilesPlugin`), which costs no resolve per import.
+            // Each handler file's name without `.ts` — what an import of one ends in.
+            const stems = new Set<string>()
+            if (bundling)
+                for (const path of served.handlers.keys())
+                    stems.add(basename(path, '.ts'))
+            if (stems.size !== 0)
+                build.onResolve(
+                    {
+                        filter: new RegExp(
+                            `(?:^|/)(?:${[...stems].map(RegExp.escape).join('|')})(?:\\.ts)?$`,
+                        ),
+                    },
+                    (args) => {
+                        if (resolving || !RELATIVE_OR_SUBPATH.test(args.path))
+                            return undefined
+                        const importer = pathOf(args.importer)
+                        if (importer.includes('/node_modules/'))
+                            return undefined
+                        let path: string
+                        try {
+                            path = resolved(args.path, args.importer)
+                        } catch {
+                            return undefined
+                        }
+                        const face = served.handlers.get(path)
+                        if (face === undefined) return undefined
+                        // 20.4 — a handler the browser is handed no wrapper for is no import of its.
+                        if (inBrowser(args.importer) && face.client === '')
+                            throw new Error(
+                                `abide: ${pathOf(args.importer)} imports ${args.path}, whose handler withholds itself from the browser (\`clients: { ui: false }\`). Call it from a <script server>, or let the browser have it. RULEBOOK 20.4.`,
+                            )
+                        return { path: `${path}${HANDLER_SUFFIX}` }
+                    },
+                )
+
             // A RELATIVE SPECIFIER A FACE IMPORTS AT RUN TIME is resolved from the file the face
             // stands for: bun's runtime reads one from an importer in a namespace as no path at
             // all. A bare one it resolves itself. Registered after every face, so a `.abide` is
@@ -277,12 +371,18 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
             // and where a hook matching every relative import in a package costs the bundle that
             // package's `sideEffects`: a two-page app grew by 12 KB, the validator one page never
             // calls moved into the chunk both pages load.
-            if (!bundling)
+            if (!bundling) {
+                // A face `handlerFilesPlugin` re-exports, named by its absolute path, which no file
+                // is at.
+                build.onResolve({ filter: HANDLER_FACE }, (args) => ({
+                    path: args.path,
+                }))
                 build.onResolve({ filter: /^\.\.?\// }, (args) =>
                     resolving || pathOf(args.importer) === args.importer
                         ? undefined
                         : { path: resolved(args.path, args.importer) },
                 )
+            }
 
             build.onLoad(
                 { filter: /\.abide$/, namespace: componentNamespace },
@@ -294,6 +394,22 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
                     }
                 },
             )
+            // 16.74, 37.1 — A HANDLER FILE: the browser's is its wrapper, and the server's is the file
+            // as written, between the two calls that file its hooks at its route — on its first
+            // line, so every line of the file stays where its frames name it. ITS FACE is its path
+            // with a suffix, in bun's own namespace — so what it imports, relative, `#` or bare,
+            // resolves from its directory as the file's own imports do. A namespace of abide's own
+            // had bun resolve a bare one from the working directory: a second abide, run from `/`.
+            build.onLoad({ filter: HANDLER_FACE }, async (args) => {
+                const path = args.path.slice(0, -HANDLER_SUFFIX.length)
+                const face = served.handlers.get(path) as HandlerFace
+                if (browser) return { contents: face.client, loader: 'js' }
+                const text = await Bun.file(path).text()
+                return {
+                    contents: `import { fileRoute as __fileRoute } from '${SERVER_SPECIFIER}';__fileRoute(${JSON.stringify(face.scope)});${text}\n;__fileRoute(undefined)\n`,
+                    loader: 'ts',
+                }
+            })
             build.onLoad(
                 { filter: /.*/, namespace: 'abide-client' },
                 (args) => ({
@@ -307,10 +423,7 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
             build.onLoad({ filter: /.*/, namespace: 'abide-bound' }, (args) => {
                 const path = args.path.slice(0, -BOUND.length)
                 return {
-                    contents: boundModule(
-                        path,
-                        compiledAt(served, path).server,
-                    ),
+                    contents: boundModule(path),
                     loader: 'js',
                 }
             })
@@ -339,7 +452,7 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
             build.onLoad(
                 { filter: /.*/, namespace: 'abide-table' },
                 (args) => ({
-                    contents: served.table(args.path) ?? '',
+                    contents: served.tables.get(args.path) ?? '',
                     loader: 'ts',
                 }),
             )
@@ -355,8 +468,8 @@ function pathOf(importer: string): string {
 
 // THE PATH BUN NAMES A FILE BY HAS ITS LINKS RESOLVED, and so has the root a compilation is served
 // under (`serveCompilation`).
-function compiledAt(served: Served, path: string): CompiledFile {
-    const compiled = served.file(path)
+function compiledAt(served: Held, path: string): CompiledFile {
+    const compiled = served.files.get(path)
     if (compiled === undefined)
         throw new Error(
             `abide: ${path} is imported, and no compile of this app reached it.`,
@@ -364,22 +477,12 @@ function compiledAt(served: Served, path: string): CompiledFile {
     return compiled
 }
 
-const SCANNER = new Bun.Transpiler({ loader: 'ts' })
-
 // 34.16 — BOUND, NOT RAW. The compiled module is a function of accessors answering its markup (33.4);
 // what an app's own module calls is a function of plain props answering a `Component` (35.4), which
-// `render` invokes with nothing. Every name the module exports rides beside it: a `<script module>`'s,
-// and the handlers a `<script server>` declares (34.23).
-//
-// NAMED RATHER THAN `export *`: the server blocks load side by side at boot, and a star export
-// through a module still loading found none of its names.
-function boundModule(path: string, server: string): string {
-    const specifier = JSON.stringify(path)
-    const names: string[] = []
-    for (const name of SCANNER.scan(server).exports)
-        if (name !== 'default') names.push(name)
-    return `import component from ${specifier}
-${names.length === 0 ? '' : `export { ${names.join(', ')} } from ${specifier}\n`}export default (props = {}) => {
+// `render` invokes with nothing. The component is the module's one export (34.17).
+function boundModule(path: string): string {
+    return `import component from ${JSON.stringify(path)}
+export default (props = {}) => {
     const accessors = {}
     for (const key in props) {
         const value = props[key]

package/src/server/answerRequest.ts

@@ -13,6 +13,7 @@ import {
     HEALTH_ADDRESS,
     MCP_ADDRESS,
     OPENAPI_ADDRESS,
+    PRIVATE_HANDLERS_ADDRESS,
 } from '#shared/ADDRESSES.ts'
 import { APP_META } from '#shared/APP_META.ts'
 import { DEBUG_META } from '#shared/DEBUG_META.ts'
@@ -102,7 +103,7 @@ type Ranked = RankedError & {
 /**
  * One route of the app: the page at it, and the handler answering each method there.
  *
- * 19.1 — one file per method per route, so a route is a row and a method is a column, and 19.21's
+ * 19.1 — one file per method per route, so a route is a row and a method is a column, and 19.20's
  * "the most specific route answering the method" is a walk down the rows asking each column.
  */
 type RouteRow = {
@@ -196,7 +197,11 @@ export async function answerRequest(
     // 37.3 — THE MUX'S UPGRADE PASSES THE APP LANE as every request does (`muxUpgrade`).
     const admitted = muxAdmission(asked, request, app)
     if (admitted !== undefined) return admitted
-    if (asked.startsWith(`${ABIDE_ADDRESS}/`)) {
+    // 16.70 — a private handler is answered by the route table, below abide's own namespace.
+    if (
+        asked.startsWith(`${ABIDE_ADDRESS}/`) &&
+        !asked.startsWith(`${PRIVATE_HANDLERS_ADDRESS}/`)
+    ) {
         const answer = app.framework(asked, request)
         if (answer === undefined) return notFound()
         return readsOnly(request) ? answer : methodRefused(app, asked, READS)
@@ -222,7 +227,7 @@ export async function answerRequest(
             refuse(400, 'The address is not a valid path.'),
         )
 
-    // 19.21 — THE MOST SPECIFIC ROUTE ANSWERING THE METHOD, an `OPTIONS` asking about the method
+    // 19.20 — THE MOST SPECIFIC ROUTE ANSWERING THE METHOD, an `OPTIONS` asking about the method
     // its preflight names (16.24). A route that matches and answers some other method is held, so
     // an address nothing answers the method at is a 405 naming what is answered there (15.17).
     const preflight = request.method === 'OPTIONS'
@@ -271,7 +276,7 @@ export async function answerRequest(
     // above it, the root's having run already, and an error in it reaches that route's `onError`.
     const scope = currentRequestScope() as RequestScope
     scope.route =
-        found.handler === undefined ? found.route.pattern : found.handler.route
+        found.handler === undefined ? found.route.pattern : found.handler.scope
     scope.params = found.params
     const answer = found.route.answers.get(
         found.handler ?? (found.route.page as Ranked),

package/src/server/answerRpc.ts

@@ -16,7 +16,6 @@ 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 { notFound, refuse } from '#shared/refuse.ts'
-import { routeOf } from '#shared/routePattern.ts'
 import type { Method, Rpc } from '#shared/rpc.ts'
 import { argsInURL } from '#shared/rpcRequest.ts'
 import { VERSION_HEADER } from '#shared/VERSION_HEADER.ts'
@@ -66,7 +65,14 @@ 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.62. */
@@ -97,18 +103,15 @@ export type Mount = {
 
 /**
  * A row of the table the build wrote, with the import of the module its handler is declared in —
- * the file's server module, the one the route table loads too, so a page and a call reach one
- * handler.
+ * 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 route of the file declaring it, which its hooks are filed at (37.1, 37.2). */
-    route: string
     /**
-     * The rungs filed over `route`, read once at mount (16.14) — what an http call and a socket
+     * 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[]
@@ -148,12 +151,14 @@ export function mountedOwn(
         {
             address,
             method: 'GET',
-            route: '/',
             // 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,
@@ -188,20 +193,17 @@ export async function mountHandlers(
     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)
-        // 23.19 — the route its address answers below, which is its mount's for a package's file,
-        // never the file's place on disk.
-        const route = routeOf(mount.address)
         handlers.set(handlerKey(mount.method, mount.address), {
             ...mount,
-            method: mount.method,
-            route,
-            rungs: rungsOver(route),
+            // 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,
@@ -219,7 +221,7 @@ export function handlerKey(method: string, address: string): string {
  * 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.21).
+ * about: which handler a request reaches is the route table's to say (19.20).
  */
 export async function answerRpc(
     found: Mounted,