@abide/abide 0.105.1 → 0.106.0

package/src/server/commands.ts

@@ -21,7 +21,7 @@ import { shell } from './shell.ts'
 import { withoutTrailingSlash } from './withoutTrailingSlash.ts'
 
 /** What a command is handed: the words after the flags, the command's own first, and the flags. */
-export type Given = ReturnType<typeof parsed>
+export type Given = ReturnType<typeof parseFlags>
 
 type Command = (given: Given) => Promise<number | undefined>
 
@@ -42,6 +42,8 @@ type SourceCommands = Record<
 export type Host = {
     /** What usage and every message speak as: `abide`, or the name the executable was run by. */
     name: string
+    /** What `--version` prints: abide's own, or the compiled app's. 38.115. */
+    version: string
     /**
      * The app the invocation means, found once off its flags (38.25): every command that serves,
      * boots, lists or announces it derives from this one handle.
@@ -60,26 +62,70 @@ export async function runCommands(
     host: Host,
     argv: string[],
 ): Promise<number | undefined> {
+    const commands = commandsOf(host)
     // 38.2 — EVERYTHING AFTER THE FILE IS THE SCRIPT'S, flags included, so `run` is taken before the
     // parser sees an argument it does not know.
-    const given: Given =
+    const given =
         argv[0] === 'run' ? { positionals: argv, values: {} } : parsed(argv)
+    // 38.113 — a flag the parser refuses is one line and the usage, never the parser's stack.
+    if (typeof given === 'string') {
+        console.error(`${host.name}: ${given}\n\n${usage(host, commands)}`)
+        return 1
+    }
     const command = given.positionals[0]
-    const commands = commandsOf(host)
     if (command === 'help' || given.values.help) {
         console.log(usage(host, commands))
         return 0
     }
+    if (given.values.version) {
+        console.log(host.version)
+        return 0
+    }
     if (command === undefined)
         return await shellOn(host, host.app(given), given)
-    for (const [name, , body] of commands)
-        if (name.split(' ')[0] === command) return await body(given)
+    let nearest: string | undefined
+    let nearestDistance = NEAREST_COMMAND_DISTANCE + 1
+    for (const [name, , body] of commands) {
+        const word = name.split(' ')[0] as string
+        if (word === command) return await body(given)
+        const distance = editDistance(word, command)
+        if (distance < nearestDistance) {
+            nearest = word
+            nearestDistance = distance
+        }
+    }
+    // 38.114 — a near miss is named, and the usage is left for a word nothing is near.
     console.error(
-        `${host.name}: unknown command '${command}'\n\n${usage(host, commands)}`,
+        nearest === undefined
+            ? `${host.name}: unknown command '${command}'\n\n${usage(host, commands)}`
+            : `${host.name}: unknown command '${command}' — did you mean \`${host.name} ${nearest}\`?`,
     )
     return 1
 }
 
+// Two edits covers a dropped, doubled or swapped letter; three reaches unrelated words.
+const NEAREST_COMMAND_DISTANCE = 2
+
+/** The Levenshtein distance between two words: the fewest insertions, deletions and substitutions. */
+function editDistance(from: string, to: string): number {
+    let previous: number[] = []
+    for (let column = 0; column <= to.length; column++) previous.push(column)
+    for (let row = 1; row <= from.length; row++) {
+        const current = [row]
+        for (let column = 1; column <= to.length; column++)
+            current.push(
+                Math.min(
+                    (previous[column] as number) + 1,
+                    (current[column - 1] as number) + 1,
+                    (previous[column - 1] as number) +
+                        (from[row - 1] === to[column - 1] ? 0 : 1),
+                ),
+            )
+        previous = current
+    }
+    return previous[to.length] as number
+}
+
 // A command, and whether it is one of `SourceCommands` — which a host without them still answers
 // (38.51), and does not list (38.52).
 type Row = [usage: string, meaning: string, run: Command, sourced: boolean]
@@ -190,8 +236,10 @@ function usage(host: Host, commands: Row[]): string {
             text += `  ${command.padEnd(width)}  ${meaning}\n`
     if (!sourced)
         return `${text}
-  --port  the listen port the app is served on
-  --url   the running app the shell, call, watch, openapi and mcp talk to
+  --port     the listen port the app is served on
+  --url      the running app the shell, call, watch, openapi and mcp talk to
+  --method   the method call sends, where the handler answers more than one
+  --version  the version of this executable's app
 `
     text += `
   --root       the app's source directory, where its pages sit —
@@ -202,11 +250,26 @@ function usage(host: Host, commands: Row[]): string {
   --url        the running app the shell, call, watch, openapi and mcp talk to
   --target     the platform compile builds for — linux-x64, darwin-arm64, windows-x64…
   --platforms  several of them, comma-separated, one executable each
+  --method     the method call sends, where the handler answers more than one
+  --version    the version of abide
 `
     return text
 }
 
+/** The words and flags `argv` holds, or the parser's refusal of a flag, as one line. */
 function parsed(argv: string[]) {
+    try {
+        return parseFlags(argv)
+    } catch (thrown) {
+        const { code, message } = thrown as { code?: string; message: string }
+        if (!code?.startsWith('ERR_PARSE_ARGS_')) throw thrown
+        // Bun's message goes on to advise `--`, which no command here reads.
+        const refusal = message.split('. ')[0] as string
+        return `${refusal[0]?.toLowerCase()}${refusal.slice(1)}`
+    }
+}
+
+function parseFlags(argv: string[]) {
     return parseArgs({
         args: argv,
         options: {
@@ -225,6 +288,7 @@ function parsed(argv: string[]) {
             platforms: { type: 'string' },
             json: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
         },
         allowPositionals: true,
     })
@@ -361,7 +425,6 @@ async function run(
     return undefined
 }
 
-/** `call`: one call to one handler on a running app. 38.8. */
 /** `watch <address> [args]`: a `GET`'s value and each patch, as its event stream sends them (38.69). */
 async function watch(host: Host, given: Given): Promise<number> {
     const {
@@ -380,6 +443,7 @@ async function watch(host: Host, given: Given): Promise<number> {
     })
 }
 
+/** `call`: one call to one handler on a running app. 38.8. */
 async function call(host: Host, app: AppHandle, given: Given): Promise<number> {
     const {
         positionals: [, address, ...args],

package/src/server/createApp.ts

@@ -17,11 +17,17 @@ import { Mux, type MuxConnection } from './answerSocket.ts'
 import { appDirectories } from './appDirectories.ts'
 import { holdsApp } from './appTree.ts'
 import { buildDirectory } from './buildDirectory.ts'
-import { APP_PACKAGE, type AppPackage, config, packageUnder } from './config.ts'
+import {
+    APP_PACKAGE,
+    type AppPackage,
+    config,
+    packageUnder,
+    positiveSetting,
+} from './config.ts'
 import { McpSurface } from './generatedSurfaces.ts'
 import { HOOKS, inOrder, reportUnexpected, rootRungs } from './hooks.ts'
 import { installServer } from './installServer.ts'
-import { admitsMux, upgraded } from './muxUpgrade.ts'
+import { admitsMux, muxSocketOptions, upgraded } from './muxUpgrade.ts'
 import { plainAnswer } from './plainAnswer.ts'
 import { realOrAsGiven } from './realOrAsGiven.ts'
 import {
@@ -39,6 +45,11 @@ import { traceResponse } from './trace.ts'
 // 28.8 — one line per request.
 const REQUEST_LOG = namedLogger('abide:request')
 
+// 42.18 — HALF OF `docker stop`'s TEN-SECOND GRACE, the shortest a common supervisor gives before its
+// `SIGKILL`: the other half is `onStop`'s, so the teardown runs before the kill rather than being cut
+// by it.
+const STOP_TIMEOUT = 5000
+
 /** The app object: what a host, a test or a script holds the app as. */
 export interface App {
     fetch(request: Request): Promise<Response>
@@ -360,11 +371,33 @@ export async function bootEntered(
         // stream ended, which a listener's stop otherwise waits on for as long as it streams.
         mux?.closeAll(1001, 'the app is stopping')
         endHeld()
-        await bound?.stop()
-        if (inFlight > 0)
-            await new Promise<void>((done) => {
-                drained = done
-            })
+        const drain = (async () => {
+            await bound?.stop()
+            if (inFlight > 0)
+                await new Promise<void>((done) => {
+                    drained = done
+                })
+            return true
+        })()
+        // 42.17, 42.18 — THE DRAIN HAS A DEADLINE: past it, every connection still answering is
+        // closed and `onStop` runs without waiting on the rest. A request `App.fetch` was handed with
+        // no socket bound has no connection to close, and is only no longer waited on.
+        let deadline: ReturnType<typeof setTimeout> | undefined
+        const finished = await Promise.race([
+            drain,
+            new Promise<false>((done) => {
+                deadline = setTimeout(
+                    () => done(false),
+                    // setTimeout reads anything past a signed 32-bit count as 1 ms.
+                    Math.min(
+                        positiveSetting('ABIDE_STOP_TIMEOUT', STOP_TIMEOUT),
+                        2 ** 31 - 1,
+                    ),
+                )
+            }),
+        ])
+        clearTimeout(deadline)
+        if (!finished) await bound?.stop(true)
         // What the requests drained here left behind them.
         endHeld()
         if (LISTENING.server === bound) LISTENING.server = undefined
@@ -409,6 +442,7 @@ export async function bootEntered(
                         : answered
                 },
                 websocket: {
+                    ...muxSocketOptions(),
                     open(socket) {
                         socket.data.connection = opened.connect(
                             socket.data.request,

package/src/server/devWorker.ts

@@ -37,7 +37,7 @@ import {
 import { type BootedApp, bootApp, originUnder } from './createApp.ts'
 import { keepServing } from './faultPolicy.ts'
 import { type Manifest, NO_MANIFEST } from './manifestOf.ts'
-import { admitsMux } from './muxUpgrade.ts'
+import { admitsMux, muxSocketOptions } from './muxUpgrade.ts'
 import { LISTENING } from './requestScope.ts'
 import {
     describe,
@@ -82,7 +82,7 @@ export type ToWorker =
  * Out: ready, a frame the mux sends a browser, and what answers a request (`FromRelay`).
  */
 export type FromWorker =
-    | { kind: 'ready' }
+    | { kind: 'ready'; muxOptions: ReturnType<typeof muxSocketOptions> }
     | { kind: 'socket-send'; connection: number; text: string }
     | FromRelay
 
@@ -151,7 +151,7 @@ async function receive(message: ToWorker): Promise<void> {
     if (message.kind === 'start') {
         opening = open(message)
         await opening
-        toListener({ kind: 'ready' })
+        toListener({ kind: 'ready', muxOptions: muxSocketOptions() })
         return
     }
     if (

package/src/server/generatedSurfaces.ts

@@ -19,7 +19,7 @@ import { type Reactive, reactive } from '#shared/reactive/index.ts'
 import { parseRoutePattern } from '#shared/routePattern.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 import { answered } from './answerFailure.ts'
-import type { Mounted } from './answerRpc.ts'
+import { bodyWithin, type Mounted } from './answerRpc.ts'
 import type { ToolDefinition } from './assistant.ts'
 import { appIdentity } from './config.ts'
 import { crossingOrigin, crossingRefusal } from './crossingOrigin.ts'
@@ -97,7 +97,13 @@ function openApiOf(handlers: Map<string, Mounted>): {
             responses: {
                 '200': {
                     description: 'The value.',
-                    content: { 'application/json': {} },
+                    // 20.15 — what the handler answers, where its type says (19.21).
+                    content: {
+                        'application/json':
+                            each.result === undefined
+                                ? {}
+                                : { schema: each.result },
+                    },
                 },
                 '204': { description: 'Nothing to say.' },
                 default: {
@@ -214,7 +220,6 @@ export function openApi(
 
 const published = new WeakMap<Map<string, Mounted>, Reactive<Published[]>>()
 
-
 type JsonRpc = {
     jsonrpc: '2.0'
     id?: number | string | null
@@ -276,6 +281,17 @@ export class McpSurface {
                 name: tool.name,
                 description: tool.description ?? '',
                 inputSchema: tool.schema ?? { type: 'object' },
+                // 20.14 — what the method promises: a `GET` is safe, and a `GET`, a `PUT` and a
+                // `DELETE` idempotent. Any other write may destroy, and nothing says it does not.
+                annotations: {
+                    readOnlyHint: tool.method === 'GET',
+                    destructiveHint: tool.method !== 'GET',
+                    idempotentHint:
+                        tool.method === 'GET' ||
+                        tool.method === 'PUT' ||
+                        tool.method === 'DELETE',
+                },
+                outputSchema: structured(tool) ? tool.result : undefined,
             })
         }
         return listing
@@ -350,6 +366,12 @@ export class McpSurface {
                 return {
                     result: {
                         content: [{ type: 'text', text }],
+                        // 20.16 — the same value as structured content, where the tool declares
+                        // its shape; a refusal is not that value.
+                        structuredContent:
+                            failed || !structured(tool)
+                                ? undefined
+                                : JSON.parse(text),
                         isError: failed,
                     },
                 }
@@ -360,6 +382,14 @@ export class McpSurface {
     }
 }
 
+/**
+ * Whether a tool declares an `outputSchema`: MCP's structured content is an object, so only a
+ * result schema that is one. 20.16.
+ */
+function structured(tool: Listed): boolean {
+    return (tool.result as { type?: unknown } | undefined)?.type === 'object'
+}
+
 /**
  * Answers one MCP JSON-RPC request over `surface`, or `undefined` where it publishes nothing.
  *
@@ -377,9 +407,12 @@ export async function answerMcp(
     // with the caller's own cookies, and a `text/plain` body is sent cross-origin with no preflight.
     const crossing = crossingOrigin(request.headers.get('origin'), request.url)
     if (crossing !== null) return answered(crossingRefusal(crossing, 'POST'))
+    // 16.78 — under the environment's body ceiling, as a handler's body is.
+    const body = await bodyWithin(request, undefined)
+    if (isFailed(body)) return answered(body)
     let message: JsonRpc
     try {
-        message = (await request.json()) as JsonRpc
+        message = (await body.json()) as JsonRpc
     } catch {
         return {
             jsonrpc: '2.0',

package/src/server/muxUpgrade.ts

@@ -10,6 +10,7 @@
 
 import { SOCKET_ADDRESS } from '#shared/ADDRESSES.ts'
 import { unmounted } from '#shared/mount.ts'
+import { positiveSetting } from './config.ts'
 import { plainAnswer } from './plainAnswer.ts'
 
 const MUX_ADMITTED = 204
@@ -70,3 +71,49 @@ export function upgraded<Data>(
         ? undefined
         : plainAnswer('expected a websocket', 400)
 }
+
+/**
+ * The limits a listener holds every connection to the mux to, `App.listen`'s and `abide dev`'s alike —
+ * read off the resolved configuration, which `abide dev`'s worker reports to its listener.
+ *
+ * 18.28 — A FRAME IN past `ABIDE_MAX_SOCKET_MESSAGE_SIZE`, a mebibyte unless set: a frame names an
+ * address and its args, which a `GET` carries in its URL. 18.29 — A CONNECTION IDLE is pinged, and
+ * closed where two minutes pass with nothing back. 18.30 — WHAT IS SENT is buffered to bun's 16 MiB,
+ * past which `send` drops it and the mux closes the peer (`SocketPeer`).
+ */
+export function muxSocketOptions(): {
+    maxPayloadLength: number
+    idleTimeout: number
+    sendPings: boolean
+    backpressureLimit: number
+} {
+    return {
+        maxPayloadLength: positiveSetting(
+            'ABIDE_MAX_SOCKET_MESSAGE_SIZE',
+            1024 * 1024,
+        ),
+        idleTimeout: 120,
+        sendPings: true,
+        backpressureLimit: 16 * 1024 * 1024,
+    }
+}
+
+/**
+ * Sends `text` to `socket`, and closes it where bun dropped the frame rather than sending or buffering it.
+ *
+ * 18.30 — A FOLLOWER THAT MISSED A FRAME stands at a version the next one does not build on, so the
+ * peer is closed rather than written past: the browser reconnects naming the version it holds (18.9)
+ * and is sent what stands. No buffer of our own — what bun buffers is the bound.
+ */
+export function sendOrClose(
+    socket:
+        | {
+              send(text: string): unknown
+              close(code: number, reason: string): unknown
+          }
+        | undefined,
+    text: string,
+): void {
+    if (socket?.send(text) === 0)
+        socket.close(1013, 'the connection fell behind')
+}

package/src/server/preload.ts

@@ -8,6 +8,17 @@
 import { appRoot, servedBuild } from './createApp.ts'
 
 const root = appRoot(undefined)
-// A run from a directory that holds no app — a workspace's root — preloads nothing.
+// A run from a directory that holds no app preloads nothing — nor from a workspace's root, whose
+// packages' `.abide` files are each their own app's rather than one app laid out across them.
 // Fresh whatever `NODE_ENV` says: `bun test` sets it only where nothing else has.
-if (root !== undefined) await servedBuild(root, true)
+if (root !== undefined && !(await isWorkspaceRoot(root)))
+    await servedBuild(root, true)
+
+async function isWorkspaceRoot(directory: string): Promise<boolean> {
+    const manifest = Bun.file(`${directory}/package.json`)
+    if (!(await manifest.exists())) return false
+    const json = (await manifest.json()) as { workspaces?: unknown }
+    return json.workspaces !== undefined
+}
+
+export { type Mounted, mount } from './testMount.ts'

package/src/server/render.ts

@@ -76,7 +76,10 @@ export async function composePage(
         if (at < layouts.length)
             levelProps.children = (): string => {
                 const below = levels[at + 1] as Rendered
-                if (below.head !== '') heads.push(below.head)
+                // THE SLOT IS TAKEN BEFORE THE HEAD IS READ: reading it builds the level, which
+                // pushes the heads deeper still, and the tree's order is what the merge keys on.
+                const slot = heads.push('') - 1
+                heads[slot] = below.head
                 return below.body
             }
         const level = (

package/src/server/runCompiled.ts

@@ -33,6 +33,7 @@ export async function runCompiled(
     }
     const host: Host = {
         name: process.execPath.slice(process.execPath.lastIndexOf('/') + 1),
+        version: origin.package.version ?? '0.0.0',
         app: () => app,
         source: undefined,
     }

package/src/server/seedBuffer.ts

@@ -31,7 +31,12 @@ import {
     streamingOrSettled,
 } from '#shared/reactive/index.ts'
 import { positiveSetting } from './config.ts'
-import { heldByApp, type PageRender } from './requestScope.ts'
+import {
+    currentRequestScope,
+    heldByApp,
+    type PageRender,
+    releaseScope,
+} from './requestScope.ts'
 
 const HYDRATE_LOG = namedLogger('abide:hydrate')
 
@@ -64,6 +69,10 @@ type Entry = {
     release: () => void
     // 42.11 — unfiles the entry from the app whose render left it, which drops it when it stops.
     unhold: () => void
+    // 41.13 — lets the render's scope go, which the entry holds while what it reached is in flight.
+    letGo: () => void
+    // Whether a call took it, which then answers from what the render reached until that settles.
+    taken: boolean
 }
 
 // INDEXED BY THE THREE THINGS 41.18 MATCHES ON — caller, handler, args key — so a call finds its entry
@@ -103,6 +112,22 @@ export function seedFor(caller: string): PageRender['seed'] {
             timer: undefined,
             release: NOTHING_HELD,
             unhold: NOTHING_HELD,
+            letGo: NOTHING_HELD,
+            taken: false,
+        }
+        // 41.13 — THE RENDER'S SCOPE IS HELD WHILE WHAT IT REACHED IS IN FLIGHT: the page is answered
+        // before a slow value lands, and letting the scope go stops that value's run — a stream the
+        // browser's call would join then never closes. Let go once it settles, a stream at its close.
+        const scope = currentRequestScope()
+        if (scope !== undefined && isReactive(reached)) {
+            scope.holds += 1
+            let held = true
+            entry.letGo = () => {
+                if (!held) return
+                held = false
+                releaseScope(scope)
+            }
+            Promise.resolve(reached).then(entry.letGo, entry.letGo)
         }
         const bound = positiveSetting(
             'ABIDE_MAX_STREAM_BUFFER_SIZE',
@@ -208,6 +233,9 @@ export function takeSeed(
     }
     const entry = entries[0]
     if (entry === undefined) return undefined
+    entry.taken = true
+    // And no longer than the call that took it: a stream that never closes ends with its reader.
+    currentRequestScope()?.stops.push(entry.letGo)
     drop(caller, entry)
     // READ AS WELL AS SWEPT: a timer can fire late, and an entry past its life answers nothing.
     if (entry.expires <= Date.now()) {
@@ -244,6 +272,8 @@ function drop(caller: string, entry: Entry): void {
     clearTimeout(entry.timer)
     entry.release()
     entry.unhold()
+    // Nothing will answer from an entry no call took, so its run need not finish.
+    if (!entry.taken) entry.letGo()
     const byRpc = BUFFER.get(caller)
     const byKey = byRpc?.get(entry.rpc)
     const entries = byKey?.get(entry.key)