@abide/abide 0.100.0 → 0.102.0

package/src/server/compressAnswer.ts

@@ -1,4 +1,4 @@
-// 38.30 — AN ANSWER, COMPRESSED WHOLE: a document, and a JSON value at least `COMPRESSION_FLOOR`
+// 38.29 — AN ANSWER, COMPRESSED WHOLE: a document, and a JSON value at least `COMPRESSION_FLOOR`
 // bytes long. Both are in hand before a byte goes out — `render` sends nothing until the page is
 // built (41.1), and a value is stringified once — so one compression is the whole answer, with its
 // length known, where a stream compressed as it arrived had to be flushed at every chunk.
@@ -6,8 +6,10 @@
 // WHAT EACH LANE SENDS BESIDE THE BYTES is here too, so the two cannot drift. A document names
 // `accept-encoding` in `vary` through `DOCUMENT_HEADERS`, which its `HEAD` and error answers carry as
 // well; a JSON answer names it here. Both say their length: `abide dev` relays a body chunk by chunk
-// from its worker (38.36), and a relayed body with no declared length goes out chunked.
-import { brotliCompressSync, constants } from 'node:zlib' // bun has gzip and zstd of its own, and no brotli
+// from its worker (38.35), and a relayed body with no declared length goes out chunked.
+// BUN'S GZIP parts from zlib's past ~130 KB, which only the off-loop lane reaches — so that lane takes
+// zlib's, the loop keeps bun's, and the two make the same bytes.
+import { brotliCompress, brotliCompressSync, constants, gzip } from 'node:zlib' // bun has no brotli, and no compression off the loop
 import {
     ENCODINGS,
     type Encoding,
@@ -17,13 +19,18 @@ import {
 // QUALITY 5, NOT 11. This runs per request, and the top brotli level is priced for a build that
 // runs once: on an 18 KB docs page 11 took 15,800 µs against 5's 150, for 15% fewer bytes. 5 is
 // already under gzip's size at twice gzip's 70 µs.
-const QUALITY = 5
+const BROTLI_OPTIONS = { params: { [constants.BROTLI_PARAM_QUALITY]: 5 } }
 
-// 38.69 — the bytes under which a JSON answer goes out as it is. Under it an answer saves tens of
+// 38.68 — the bytes under which a JSON answer goes out as it is. Under it an answer saves tens of
 // bytes that leave in the same packet anyway, for 3–8 µs of a ~57 µs request; at 8 KB the same CPU
 // saves seven kilobytes.
 const COMPRESSION_FLOOR = 1024
 
+// 38.95 — the bytes from which an answer is compressed off the event loop. Brotli 5 holds the loop
+// ~360 µs at 64 KB and ~7 ms at 700 KB — every other request and socket waits that long — where
+// the thread pool's hop adds ~20 µs to the answer it carries: 6% at 64 KB, 27% at 16 KB.
+const OFF_LOOP_FLOOR = 64 * 1024
+
 const ENCODER = new TextEncoder()
 
 function compressed(
@@ -31,24 +38,48 @@ function compressed(
     encoding: Encoding,
 ): Uint8Array<ArrayBuffer> {
     return encoding === 'br'
-        ? (brotliCompressSync(bytes, {
-              params: { [constants.BROTLI_PARAM_QUALITY]: QUALITY },
-          }) as Uint8Array<ArrayBuffer>)
+        ? (brotliCompressSync(bytes, BROTLI_OPTIONS) as Uint8Array<ArrayBuffer>)
         : Bun.gzipSync(bytes)
 }
 
+function compressedOffLoop(
+    bytes: Uint8Array<ArrayBuffer>,
+    encoding: Encoding,
+): Promise<Uint8Array<ArrayBuffer>> {
+    return new Promise((resolve, reject) => {
+        const settle = (error: Error | null, result: Uint8Array): void => {
+            if (error === null) resolve(result as Uint8Array<ArrayBuffer>)
+            else reject(error)
+        }
+        if (encoding === 'br') brotliCompress(bytes, BROTLI_OPTIONS, settle)
+        else gzip(bytes, settle)
+    })
+}
+
+function answered(
+    body: Uint8Array<ArrayBuffer>,
+    encoding: Encoding | undefined,
+    headers: Headers,
+    status: number,
+): Response {
+    if (encoding !== undefined) headers.set('content-encoding', encoding)
+    headers.set('content-length', String(body.byteLength))
+    return new Response(body, { status, headers })
+}
+
 /**
  * `answer` as the `Response` to `request`, in the encoding the request takes where it takes one.
  *
  * THE LANE IS THE BODY'S TYPE: a built document arrives as its bytes, and a JSON value as its text,
- * encoded once here and floored by its length.
+ * encoded once here and floored by its length. A `Promise` only where the compression runs off the
+ * loop, so an answer under that floor costs no await.
  */
 export function compressAnswer(
     answer: Uint8Array<ArrayBuffer> | string,
     request: Request,
     headers: Headers,
     status: number,
-): Response {
+): Response | Promise<Response> {
     const json = typeof answer === 'string'
     const bytes = json ? ENCODER.encode(answer) : answer
     const encoding =
@@ -59,8 +90,11 @@ export function compressAnswer(
                   ENCODINGS,
               )
     if (json) headers.append('vary', 'accept-encoding')
-    const body = encoding === undefined ? bytes : compressed(bytes, encoding)
-    if (encoding !== undefined) headers.set('content-encoding', encoding)
-    headers.set('content-length', String(body.byteLength))
-    return new Response(body, { status, headers })
+    if (encoding === undefined)
+        return answered(bytes, encoding, headers, status)
+    if (bytes.byteLength >= OFF_LOOP_FLOOR)
+        return compressedOffLoop(bytes, encoding).then((body) =>
+            answered(body, encoding, headers, status),
+        )
+    return answered(compressed(bytes, encoding), encoding, headers, status)
 }

package/src/server/config.ts

@@ -1,16 +1,17 @@
 // SECTION 27 — THE RESOLVED CONFIGURATION. One process-wide value (27.9) over three layers, the last
 // winning (27.2): what abide derives, what the app's `onConfig` defaulted, and the environment.
 //
-// A `reactive` BODY, so `config.invalidate` is the core's own trigger and re-runs all of it (27.5),
+// A `reactive` BODY, so `config.invalidate` is the core's own trigger and reruns all of it (27.5),
 // and a throw out of `onConfig` is the value's standing error, which a read throws (27.1).
 
 import { homedir } from 'node:os' // bun exposes no home directory of its own
+import { isRecord } from '#shared/isRecord.ts'
 import { numberFromText } from '#shared/numberFromText.ts'
 import { reactive } from '#shared/reactive/index.ts'
 import { validationError } from '#shared/refuse.ts'
 import { runSchema } from '#shared/Schema.ts'
 import { appDirectories } from './appDirectories.ts'
-import { type Env, HOOKS } from './hooks.ts'
+import { type Env, HOOKS, inOrder } from './hooks.ts'
 import { withoutTrailingSlash } from './withoutTrailingSlash.ts'
 
 /** The fields of an app's `package.json` 27.3 derives from. */
@@ -46,10 +47,6 @@ export interface Config {
     APP_NAME: string
     APP_VERSION: string
     APP_DATA_DIR: string
-    ABIDE_LOGS: boolean
-    ABIDE_OPENAPI: boolean
-    ABIDE_MCP: boolean
-    ABIDE_BRIDGE: boolean
 }
 
 /** The resolved configuration: abide's derived values, then `onConfig`'s defaults, then the env. */
@@ -57,24 +54,20 @@ export const config = reactive(resolve, { global: true })
 
 function resolve(): Config {
     const env: Env = { ...process.env }
-    const hooked = HOOKS.config
-    // 27.4 — SYNCHRONOUS BY CONTRACT; a promise handed back is a contract broken, not a value.
+    const hooked = inOrder(HOOKS.config)
     // 27.11 — handed what 27.3 derives under the environment, so a default can be built on
     // `APP_DATA_DIR` without deriving it a second time.
     const derivedValues = derived()
-    const defaults = hooked?.defaults?.({ ...derivedValues, ...env }) ?? {}
-    if (defaults instanceof Promise)
-        throw new Error(
-            'abide: onConfig returned a promise. ConfigDefaults is synchronous; read what the defaults need before registering them. RULEBOOK 27.4.',
-        )
-    const document: Record<string, unknown> = {
-        // 36.7 — CLOSED BY DEFAULT, and a boolean, so 27.8 reads the environment's spelling of one.
-        ABIDE_LOGS: false,
-        ABIDE_OPENAPI: false,
-        ABIDE_MCP: false,
-        ABIDE_BRIDGE: false,
-        ...derivedValues,
-        ...(defaults as Record<string, unknown>),
+    const document: Record<string, unknown> = { ...derivedValues }
+    // 27.6, 37.7 — EVERY `onConfig`'S DEFAULTS, merged over the ones before it.
+    for (const { defaults } of hooked) {
+        const given = defaults?.({ ...derivedValues, ...env }) ?? {}
+        // 27.4 — SYNCHRONOUS BY CONTRACT; a promise handed back is a contract broken, not a value.
+        if (given instanceof Promise)
+            throw new Error(
+                'abide: onConfig returned a promise. ConfigDefaults is synchronous; read what the defaults need before registering them. RULEBOOK 27.4.',
+            )
+        Object.assign(document, given as Record<string, unknown>)
     }
     // 27.8 — THE ENVIRONMENT, COERCED TO THE DEFAULT IT OVERRIDES; a value that will not coerce leaves
     // the default standing.
@@ -83,13 +76,16 @@ function resolve(): Config {
         const coerced = coerce(text, document[name])
         if (coerced !== undefined) document[name] = coerced
     }
-    // 27.7 — LAST, over the whole document.
-    const schema = hooked?.options?.schema
-    if (schema === undefined) return document as Config
-    const checked = runSchema(schema, document)
-    if (checked.issues !== null)
-        return validationError(checked.issues as never) as never
-    return checked.value as Config
+    // 27.7 — LAST, each over the whole document, and what each accepts merged back over it.
+    for (const { options } of hooked) {
+        const schema = options?.schema
+        if (schema === undefined) continue
+        const checked = runSchema(schema, document)
+        if (checked.issues !== null)
+            return validationError(checked.issues as never) as never
+        if (isRecord(checked.value)) Object.assign(document, checked.value)
+    }
+    return document as Config
 }
 
 function coerce(text: string, standing: unknown): unknown {
@@ -129,7 +125,7 @@ export function dataDirectory(name: string): string {
     return `${process.env.XDG_DATA_HOME ?? `${home}/.local/share`}/${name}`
 }
 
-// 28.5 — THE APP'S NAME IS `log`'s ROOT NAMESPACE, and the config is where the name is decided.
+// 28.4 — THE APP'S NAME IS `log`'s ROOT NAMESPACE, and the config is where the name is decided.
 // PEEKED, so a log line written inside an effect does not subscribe it to the configuration.
 export function derivedAppName(): string | undefined {
     const resolved = config.peek()

package/src/server/configFields.ts

@@ -1,8 +1,8 @@
-// 38.73 — THE FIELDS THE DESKTOP LAUNCHER'S START FORM ASKS FOR: the members of the `onConfig`
+// 38.72 — THE FIELDS THE DESKTOP LAUNCHER'S START FORM ASKS FOR: the members of the `onConfig`
 // schema's JSON Schema, probed as 20.11 probes a handler's, and the fields `onConfig`'s defaults
 // return where the schema has no document to read.
 
-import { HOOKS } from './hooks.ts'
+import { HOOKS, inOrder } from './hooks.ts'
 
 type Property = {
     type?: string | string[]
@@ -30,32 +30,38 @@ export type ConfigField = {
 export function configFields(
     env: Record<string, string | undefined>,
 ): ConfigField[] {
-    const hooked = HOOKS.config
-    let defaults: Record<string, unknown> = {}
-    try {
-        const given = hooked?.defaults?.({ ...env })
-        if (given !== null && typeof given === 'object')
-            defaults = given as Record<string, unknown>
-    } catch {}
-    const schema = hooked?.options?.schema as
-        | {
-              '~standard'?: {
-                  jsonSchema?: { input?: (options: unknown) => unknown }
+    // 27.6, 37.7 — EVERY `onConfig`, its defaults and its schema's fields merged in route order.
+    const defaults: Record<string, unknown> = {}
+    let declared: Record<string, Property> | undefined
+    const required = new Set<string>()
+    for (const { defaults: given, options } of inOrder(HOOKS.config)) {
+        try {
+            const answered = given?.({ ...env })
+            if (answered !== null && typeof answered === 'object')
+                Object.assign(defaults, answered)
+        } catch {}
+        const schema = options?.schema as
+            | {
+                  '~standard'?: {
+                      jsonSchema?: { input?: (options: unknown) => unknown }
+                  }
               }
-          }
-        | undefined
-    let document:
-        | { properties?: Record<string, Property>; required?: string[] }
-        | undefined
-    try {
-        document = schema?.['~standard']?.jsonSchema?.input?.({
-            target: 'draft-2020-12',
-        }) as typeof document
-    } catch {}
+            | undefined
+        let document:
+            | { properties?: Record<string, Property>; required?: string[] }
+            | undefined
+        try {
+            document = schema?.['~standard']?.jsonSchema?.input?.({
+                target: 'draft-2020-12',
+            }) as typeof document
+        } catch {}
+        if (document?.properties !== undefined)
+            declared = { ...declared, ...document.properties }
+        for (const name of document?.required ?? []) required.add(name)
+    }
     const properties: Record<string, Property> =
-        document?.properties ??
+        declared ??
         Object.fromEntries(Object.keys(defaults).map((name) => [name, {}]))
-    const required = new Set(document?.required ?? [])
     const fields: ConfigField[] = []
     for (const [name, property] of Object.entries(properties)) {
         const fallback = defaults[name] ?? property.default

package/src/server/createApp.ts

@@ -10,19 +10,19 @@ import { namedLogger } from '#shared/log.ts'
 import { compose } from '#shared/Middleware.ts'
 import { MOUNT, unmounted } from '#shared/mount.ts'
 import { RPC_SERVER } from '#shared/RPC_SERVER.ts'
-import {
-    type AppSources,
-    answerRequest,
-    type LoadedSources,
-} from './answerRequest.ts'
+import { servedTable } from './abideModules.ts'
+import { type AppSources, answerRequest } from './answerRequest.ts'
 import { Mux, type MuxConnection } from './answerSocket.ts'
+import { appDirectories } from './appDirectories.ts'
+import { holdsAbide } from './appTree.ts'
 import { buildDirectory } from './buildDirectory.ts'
 import { APP_PACKAGE, type AppPackage, config, packageUnder } from './config.ts'
 import { McpSurface } from './generatedSurfaces.ts'
-import { HOOKS, reportUnexpected } from './hooks.ts'
+import { HOOKS, inOrder, reportUnexpected, rootRungs } from './hooks.ts'
 import { installServer } from './installServer.ts'
 import { admitsMux, upgraded } from './muxUpgrade.ts'
 import { plainAnswer } from './plainAnswer.ts'
+import { realOrAsGiven } from './realOrAsGiven.ts'
 import {
     type AnsweringApp,
     applyWritten,
@@ -35,7 +35,7 @@ import {
 import { testBuild } from './testBuild.ts'
 import { traceResponse } from './trace.ts'
 
-// 28.9 — one line per request.
+// 28.8 — one line per request.
 const REQUEST_LOG = namedLogger('abide:request')
 
 /** The app object: what a host, a test or a script holds the app as. */
@@ -54,29 +54,16 @@ export interface App {
     [Symbol.asyncDispose](): Promise<void>
 }
 
-// 37.2 — the two shapes `default` may take.
-type OwnRoute =
-    | ((
-          request: Request,
-          server: Bun.Server<unknown> | undefined,
-      ) => Response | undefined | Promise<Response | undefined>)
-    | {
-          fetch: (
-              request: Request,
-              server: Bun.Server<unknown> | undefined,
-          ) => unknown
-      }
-
 /**
  * The app this process was started in, booted off what `abide build` left beside it.
  *
- * 42.1 — found where the CLI finds it (38.26), and booted off the build (38.28).
+ * 42.1 — found where the CLI finds it (38.25), and booted off the build (38.27).
  */
 export async function createApp(): Promise<App> {
     const root = appRoot(undefined)
     if (root === undefined)
         throw new Error(
-            `abide: createApp found no app. Looked for ui/ in ${process.cwd()} and in ${resolve('src')}.`,
+            `abide: createApp found no app. Looked for a .abide under ${resolve('src')}, or under ${process.cwd()} where it has no src.`,
         )
     // 42.16 — under `bun test` the app is built for its sources as they stand rather than read off
     // whatever `abide build` last left, which a test run would otherwise need first and could find
@@ -85,21 +72,34 @@ export async function createApp(): Promise<App> {
         process.env.NODE_ENV === 'test'
             ? await testBuild(root)
             : buildDirectory(root)
-    const { loadBuild } = await import('./serveBuild.ts')
+    const { loadBuild, serveBuild } = await import('./serveBuild.ts')
+    if (!(await serveBuild(root, out)))
+        throw new Error(
+            `abide: createApp found nothing under ${root} to build.`,
+        )
     return bootApp(originUnder(root), () => loadBuild({ root, out }))
 }
 
 /**
- * The directory `ui/` sits under, or `undefined` where none is found.
+ * The app's root — `--root`, else `src` where the working directory holds one, else the working
+ * directory — or `undefined` where it is no app's.
  *
- * 38.26 and 38.27 — `undefined` is a refusal and not a guess.
+ * 38.25 and 38.26 — `undefined` is a refusal and not a guess. An app's root is in a package — it or
+ * the directory above it holds the `package.json` (`appDirectories`) — and holds a `.abide`
+ * file; the package is asked first, so a command run from `/` answers at once rather than
+ * walking the disk.
+ *
+ * ITS REAL PATH, as the bundler and the resolver name every file under it: an app under `/tmp` is
+ * `/private/tmp` to both, and one spelling here is one fewer at every reader downstream.
  */
 export function appRoot(given: string | undefined): string | undefined {
-    if (given !== undefined) return resolve(given)
-    const here = process.cwd()
-    if (existsSync(`${here}/ui`)) return here
+    if (given !== undefined) return realOrAsGiven(resolve(given))
     const under = resolve('src')
-    return existsSync(`${under}/ui`) ? under : undefined
+    const root = realOrAsGiven(existsSync(under) ? under : process.cwd())
+    let packaged = false
+    for (const directory of appDirectories(root))
+        packaged ||= existsSync(`${directory}/package.json`)
+    return packaged && holdsAbide(root) ? root : undefined
 }
 
 /**
@@ -110,26 +110,26 @@ export function appRoot(given: string | undefined): string | undefined {
  * under.
  */
 export type AppOrigin = {
-    /** The import of `src/server/app.ts`, where the app has one. 37.1. */
-    hooks: (() => Promise<{ default?: OwnRoute }>) | undefined
+    /**
+     * Imports every module holding a `<script server>`, where the app has one. 37.1.
+     *
+     * Imported for what each CALLS: every hook it runs is filed by the time the import settles.
+     */
+    hooks: (() => Promise<unknown>) | undefined
     /** 27.3's name and version. */
     package: AppPackage
 }
 
-/** The path of the app's hooks module under its source root, where it has one. 37.1. */
-export function hooksModuleUnder(root: string): string | undefined {
-    const hooksModule = `${root}/server/app.ts`
-    return existsSync(hooksModule) ? hooksModule : undefined
-}
-
-/** The `AppOrigin` of an app on disk, found under its source root. */
+/**
+ * The `AppOrigin` of an app on disk: its package under `root`, and its server blocks, out of the
+ * compilation this process serves (`serveCompilation`) — the build's, or `abide dev`'s.
+ */
 export function originUnder(root: string): AppOrigin {
-    const hooksModule = hooksModuleUnder(root)
     return {
-        hooks:
-            hooksModule === undefined
-                ? undefined
-                : () => import(Bun.pathToFileURL(hooksModule).href),
+        hooks: async () => {
+            const table = await servedTable(root)
+            await Promise.all(table.servers.map((load) => load()))
+        },
         package: packageUnder(root),
     }
 }
@@ -143,15 +143,12 @@ export type BootedApp = App & { openMux(): Mux }
 /** An `App` booted over the sources `load` supplies, inside the app's `onStart` hooks. */
 export async function bootApp(
     origin: AppOrigin,
-    load: () => Promise<LoadedSources>,
+    load: () => Promise<AppSources>,
 ): Promise<BootedApp> {
     installServer()
-    // 37.1 — OPTIONAL, and imported for what it CALLS: every hook it runs is filed by the time the
-    // import settles.
-    const own =
-        origin.hooks === undefined
-            ? undefined
-            : ((await origin.hooks()).default ?? undefined)
+    // 37.1 — EVERY SERVER BLOCK, imported for what it CALLS: every hook it runs is filed by the
+    // time the import settles, which is before `onStart` is composed around the boot.
+    if (origin.hooks !== undefined) await origin.hooks()
 
     // 37.4 — THE BOOT, INSIDE `onStart`. 37.6 — a throw out of a hook or out of the boot rejects
     // `createApp`, and nothing is served.
@@ -159,8 +156,8 @@ export async function bootApp(
     // 42.2 — THE CONFIGURATION IS READ AS PART OF THE BOOT, so a configuration that does not resolve
     // is a boot that fails rather than a first request that does.
     APP_PACKAGE.current = origin.package
-    let sources: LoadedSources | undefined
-    await compose(HOOKS.starts, async () => {
+    let sources: AppSources | undefined
+    await compose(inOrder(HOOKS.starts), async () => {
         config.invalidate()
         await config
         sources = await load()
@@ -169,17 +166,16 @@ export async function bootApp(
         throw new Error(
             'abide: an onStart hook returned without calling start(), so the app never booted. RULEBOOK 37.4.',
         )
-    const booted: AppSources = {
-        ...sources,
-        own: own === undefined ? undefined : ownRoute(own),
-    }
+    const booted = sources
 
-    // 16.14, 37.3 — THE APP LANE'S ONION, composed once over the whole request path. 21.20 — the
-    // centre takes its own time back out of what `fetch` counts for the whole onion.
-    const answer = compose(HOOKS.rungs, async ({ request }) => {
+    // 16.14, 37.3 — THE APP LANE'S ONION, composed once over the whole request path: the root
+    // route's rungs, the ones below it running after routing (37.2, `answerRequest`). 21.20 — the
+    // center takes its own time back out of what `fetch` counts for the whole onion.
+    const rungs = rootRungs()
+    const answer = compose(rungs, async ({ request }) => {
         const began = performance.now()
         const answered = await answerRequest(booted, request)
-        if (HOOKS.rungs.length > 0) rungsTook(began - performance.now())
+        if (rungs.length > 0) rungsTook(began - performance.now())
         return answered
     })
 
@@ -213,14 +209,14 @@ export async function bootApp(
                     let answered: Response
                     try {
                         answered = await answer({ request })
-                        if (HOOKS.rungs.length > 0)
+                        if (rungs.length > 0)
                             rungsTook(performance.now() - started)
                     } catch (thrown) {
                         reportUnexpected(thrown)
                         answered = plainAnswer('internal server error', 500)
                     }
                     const stamped = stamp(answered)
-                    // 28.8 — a closed namespace does not pay for the line it would have written.
+                    // 28.7 — a closed namespace does not pay for the line it would have written.
                     if (REQUEST_LOG.enabled())
                         REQUEST_LOG.debug(
                             request.method,
@@ -289,7 +285,7 @@ export async function bootApp(
         // 16.42 — a stopped app answers no `raw` call made outside every request.
         if (RPC_SERVER.raw === answerRaw) RPC_SERVER.raw = null
         bound = undefined
-        await compose(HOOKS.stops, async () => {})(undefined)
+        await compose(inOrder(HOOKS.stops), async () => {})(undefined)
     }
 
     return {
@@ -416,13 +412,3 @@ function belowMount(request: Request): Request | Response {
     url.pathname = below
     return new Request(url, request)
 }
-
-function ownRoute(
-    own: OwnRoute,
-): (request: Request) => Promise<Response | undefined> {
-    const answer = typeof own === 'function' ? own : own.fetch.bind(own)
-    return async (request) => {
-        const answered = await answer(request, LISTENING.server)
-        return answered instanceof Response ? answered : undefined
-    }
-}