@abide/abide 0.103.0 → 0.105.0

package/src/server/responseRelay.ts

@@ -0,0 +1,389 @@
+// 38.14, 38.35, 38.36 — ONE RESPONSE, ANSWERED IN ONE PROCESS AND SENT FROM ANOTHER. `abide dev`'s
+// listener holds the connection and its worker holds the app, so a request crosses as a message and
+// its answer comes back as a head and then a chunk per pull. Both halves of that protocol are here —
+// `serveOver` is the worker's, `askOver` the listener's — over a channel neither half knows the kind
+// of, so the protocol is read in one file and runs in one test process (`responseRelay.test.ts`).
+// What `serveDev` and `devWorker` keep is the processes and the sockets.
+
+import { plainAnswer } from './plainAnswer.ts'
+
+/** One direction of the line between the halves: bun's IPC in `abide dev`, a pair of queues in a test. */
+export type Channel<Message> = { postMessage(message: Message): void }
+
+/** A request as it crosses to the worker: its id, and what the worker rebuilds it from. */
+export type Ask = {
+    id: number
+    method: string
+    url: string
+    headers: [string, string][]
+    body: ArrayBuffer | null
+}
+
+/** What the listener's half sends: a request, and a pull or cancel of its body. */
+export type ToRelay =
+    | ({ kind: 'request' } & Ask)
+    | { kind: 'pull'; id: number }
+    | { kind: 'cancel'; id: number }
+
+/** What the worker's half sends: a request's idle timeout raised, and its head, each chunk, and its end. */
+export type FromRelay =
+    | { kind: 'timeout'; id: number; seconds: number }
+    | {
+          kind: 'head'
+          id: number
+          status: number
+          statusText: string
+          headers: [string, string][]
+          empty: boolean
+          /** 37.3 — whether the listener upgrades this request to the mux (`admitsMux`). */
+          admitted: boolean
+          /** A body whose length the answer declared, sent with its head rather than pulled. */
+          whole: ArrayBuffer | undefined
+      }
+    | { kind: 'chunk'; id: number; bytes: ArrayBuffer }
+    | { kind: 'end'; id: number }
+    | { kind: 'fail'; id: number; message: string }
+
+// A status whose response has no body to send, which `Response` refuses to be built with one.
+const BODILESS = new Set([101, 204, 205, 304])
+
+/** A throw, as the text a reader is shown: its stack where it has one. */
+export function describe(thrown: unknown): string {
+    return thrown instanceof Error
+        ? (thrown.stack ?? thrown.message)
+        : String(thrown)
+}
+
+/**
+ * The worker's half: answers each request the listener sends with `fetch`, and its body a chunk per
+ * pull. `take` is handed every `ToRelay` message; `timeout` raises a request's idle timeout where the
+ * listener holds its connection (16.22); `hangUpAll` aborts every request still being answered.
+ */
+export function serveOver(
+    channel: Channel<FromRelay>,
+    answering: {
+        fetch(request: Request): Promise<Response>
+        /** 37.3 — whether the answer admits the request to the mux. */
+        admits(request: Request, response: Response): boolean
+        /** The answer to a throw out of `fetch`, which is an answer and not a dropped message. */
+        failed(why: string): Response
+        /** What a failure in the middle of an html body is shown as, appended to it. */
+        failureMarkup(why: string): string
+    },
+) {
+    // 38.96 — EACH REQUEST'S SIGNAL, by request id, until its answer ends: the listener holds the
+    // connection, so a hang-up reaches the worker as a `cancel` rather than through bun.
+    const hangUps = new Map<number, AbortController>()
+    // Each answer whose head has gone out, by request id: what its chunks are read from, and whether a
+    // failure in the middle can still be shown as markup.
+    const bodies = new Map<
+        number,
+        { reader: ReadableStreamDefaultReader<Uint8Array>; html: boolean }
+    >()
+    // 16.22 — each request built here, known by the ask it was built from.
+    const asks = new WeakMap<Request, number>()
+
+    const ended = (id: number): void => {
+        hangUps.delete(id)
+        bodies.delete(id)
+    }
+
+    /**
+     * Answers one request, sending back its head and holding its body for pulls.
+     *
+     * A THROW BEFORE THE HEAD IS AN ANSWER, not a dropped message. The listener is waiting on a head
+     * for this id and nothing else will send one, so an escape left the reader's tab hanging until
+     * they gave up.
+     */
+    async function answer(ask: Ask): Promise<void> {
+        const hangUp = new AbortController()
+        hangUps.set(ask.id, hangUp)
+        const request = new Request(ask.url, {
+            method: ask.method,
+            headers: ask.headers,
+            body: ask.body,
+            signal: hangUp.signal,
+        })
+        asks.set(request, ask.id)
+        let response: Response
+        try {
+            response = await answering.fetch(request)
+        } catch (thrown) {
+            response = answering.failed(describe(thrown))
+        }
+        const body = BODILESS.has(response.status) ? null : response.body
+        // A DECLARED LENGTH IS A BODY ALREADY WHOLE, and it crosses with its head: re-streamed through
+        // the listener, bun meets a first read that has to wait on the worker and answers it chunked,
+        // dropping the length the app declared.
+        const whole =
+            body !== null && response.headers.has('content-length')
+                ? await response.arrayBuffer()
+                : undefined
+        channel.postMessage({
+            kind: 'head',
+            id: ask.id,
+            status: response.status,
+            statusText: response.statusText,
+            headers: [...response.headers.entries()],
+            empty: body === null,
+            admitted: answering.admits(request, response),
+            whole,
+        })
+        if (body === null || whole !== undefined) {
+            ended(ask.id)
+            return
+        }
+        bodies.set(ask.id, {
+            reader: body.getReader(),
+            html: (response.headers.get('content-type') ?? '').startsWith(
+                'text/html',
+            ),
+        })
+    }
+
+    /**
+     * Sends the next chunk of an answer's body, or its end.
+     *
+     * ONE CHUNK PER ASK. A throw in the middle ends the stream in an error, as `abide start` does —
+     * and where the answer is html a handler streams, what broke goes out as markup first, a reader
+     * shown a blank tab otherwise being told nothing. A page is never here: it is built whole (41.1).
+     */
+    async function pull(id: number): Promise<void> {
+        const reading = bodies.get(id)
+        if (reading === undefined) return
+        try {
+            const { done, value } = await reading.reader.read()
+            if (done) {
+                ended(id)
+                channel.postMessage({ kind: 'end', id })
+                return
+            }
+            // THE VIEW'S OWN BYTES. A chunk may be a view on a buffer its producer still owns — a
+            // compressor's `Buffer` is a slice of a shared pool, and `Buffer#slice` copies nothing —
+            // so sending `value.buffer` sent the whole pool.
+            const bytes = new Uint8Array(value).buffer as ArrayBuffer
+            channel.postMessage({ kind: 'chunk', id, bytes })
+        } catch (thrown) {
+            ended(id)
+            const why = describe(thrown)
+            if (reading.html)
+                channel.postMessage({
+                    kind: 'chunk',
+                    id,
+                    bytes: new TextEncoder().encode(
+                        answering.failureMarkup(why),
+                    ).buffer as ArrayBuffer,
+                })
+            channel.postMessage({ kind: 'fail', id, message: why })
+        }
+    }
+
+    return {
+        take(message: ToRelay): Promise<void> | undefined {
+            if (message.kind === 'request') return answer(message)
+            if (message.kind === 'pull') return pull(message.id)
+            const reading = bodies.get(message.id)
+            hangUps.get(message.id)?.abort()
+            ended(message.id)
+            return reading?.reader.cancel()
+        },
+        timeout(request: Request, seconds: number): void {
+            const id = asks.get(request)
+            if (id !== undefined)
+                channel.postMessage({ kind: 'timeout', id, seconds })
+        },
+        hangUpAll(): void {
+            for (const hangUp of hangUps.values()) hangUp.abort()
+        },
+    }
+}
+
+// A request in flight: the request itself — because a worker replaced before it answered answers
+// nothing, and the ask has to be put to the one that exists (38.24) — the channel it was asked over,
+// and, once its head has come back, the stream the body is fed into and the pull waiting on the
+// worker's next chunk (38.35).
+type InFlight = {
+    // 16.22 — the request bun handed the listener, which is the one its idle timeout is raised on.
+    request: Request
+    headers: [string, string][]
+    body: ArrayBuffer | null
+    settle: (response: Response) => void
+    asked: Channel<ToRelay> | undefined
+    stream: ReadableStreamDefaultController<Uint8Array> | null
+    pulled: (() => void) | null
+    // A failure the worker sent behind a chunk still queued, raised on the pull after it — raising it
+    // at once would discard the chunk, which is the markup saying what broke.
+    failed: string | null
+}
+
+/**
+ * The listener's half: asks each request of the worker on its channel, and settles it with the
+ * response the worker's head and chunks describe. `take` is handed every `FromRelay` message;
+ * `replace` points it at a worker's channel — there is none until the first — or at none while one
+ * compiles; `endAll` ends what the worker that is gone was answering.
+ */
+export function askOver(
+    raiseTimeout: (request: Request, seconds: number) => void,
+) {
+    let channel: Channel<ToRelay> | undefined
+    const inFlight = new Map<number, InFlight>()
+    // ASKED BEFORE THERE IS ANYONE TO ASK. A replacement ends the worker and the next one does not
+    // exist until its compile finishes, so a request arriving in that window waits here.
+    const queued: InFlight[] = []
+    // 37.3 — the answers the worker said `admitsMux`, which the listener upgrades on.
+    const admitted = new WeakSet<Response>()
+    let nextId = 0
+
+    // NOT TRANSFERRED. Handing the buffer over detaches it here, and a request re-asked of the
+    // replacement would post a body that is no longer there.
+    function forward(waiting: InFlight): void {
+        if (channel === undefined) {
+            queued.push(waiting)
+            return
+        }
+        nextId += 1
+        const id = nextId
+        waiting.asked = channel
+        inFlight.set(id, waiting)
+        channel.postMessage({
+            kind: 'request',
+            id,
+            method: waiting.request.method,
+            url: waiting.request.url,
+            headers: waiting.headers,
+            body: waiting.body,
+        })
+    }
+
+    // 38.35, 38.36 — THE HEAD SETTLES THE RESPONSE, and its body pulls one chunk from the worker per
+    // read the connection makes: a high-water mark of 0 asks for nothing ahead of the reader.
+    function settleHead(
+        id: number,
+        waiting: InFlight,
+        head: Extract<FromRelay, { kind: 'head' }>,
+    ): void {
+        const init = {
+            status: head.status,
+            statusText: head.statusText,
+            headers: head.headers,
+        }
+        if (head.empty || head.whole !== undefined) {
+            inFlight.delete(id)
+            const answered = new Response(head.whole ?? null, init)
+            // The admission has no body, so an admitted answer is always settled here.
+            if (head.admitted) admitted.add(answered)
+            waiting.settle(answered)
+            return
+        }
+        const asked = waiting.asked
+        const body = new ReadableStream<Uint8Array>(
+            {
+                start(controller) {
+                    waiting.stream = controller
+                },
+                pull(controller) {
+                    if (waiting.failed !== null) {
+                        inFlight.delete(id)
+                        controller.error(new Error(waiting.failed))
+                        return
+                    }
+                    return new Promise<void>((done) => {
+                        waiting.pulled = done
+                        asked?.postMessage({ kind: 'pull', id })
+                    })
+                },
+                cancel() {
+                    inFlight.delete(id)
+                    asked?.postMessage({ kind: 'cancel', id })
+                },
+            },
+            { highWaterMark: 0 },
+        )
+        waiting.settle(new Response(body, init))
+    }
+
+    return {
+        /**
+         * The worker's answer to `request`.
+         *
+         * A REQUEST AS A MESSAGE. `Request` does not survive a structured clone, so what crosses is
+         * what the worker rebuilds one from — and the body is collected ONCE, HERE, which is what lets
+         * it be asked again of a replacement (38.24): a body can only be read off a `Request` once.
+         */
+        async ask(request: Request): Promise<Response> {
+            const body =
+                request.body === null ? null : await request.arrayBuffer()
+            return await new Promise<Response>((settle) => {
+                forward({
+                    request,
+                    headers: identityOnly(request.headers),
+                    body,
+                    settle,
+                    asked: undefined,
+                    stream: null,
+                    pulled: null,
+                    failed: null,
+                })
+            })
+        },
+        /** Whether the worker admitted this answer's request to the mux. 37.3. */
+        admitted(response: Response): boolean {
+            return admitted.has(response)
+        },
+        take(message: FromRelay): void {
+            const waiting = inFlight.get(message.id)
+            if (waiting === undefined) return
+            if (message.kind === 'timeout') {
+                raiseTimeout(waiting.request, message.seconds)
+                return
+            }
+            if (message.kind === 'head') {
+                settleHead(message.id, waiting, message)
+                return
+            }
+            const stream = waiting.stream
+            const pulled = waiting.pulled
+            waiting.pulled = null
+            if (stream === null) return
+            if (message.kind === 'chunk')
+                stream.enqueue(new Uint8Array(message.bytes))
+            else if (message.kind === 'end') {
+                inFlight.delete(message.id)
+                stream.close()
+            } else waiting.failed = message.message
+            pulled?.()
+        },
+        /** Asks the worker on `next` from now on — every request that waited for one included. */
+        replace(next: Channel<ToRelay> | undefined): void {
+            channel = next
+            if (next === undefined) return
+            for (const again of queued.splice(0)) forward(again)
+        },
+        /**
+         * Ends what a worker that is gone was answering. A request whose head has not gone out is
+         * asked again of the next (38.24) where `reask`, and answered 500 where not — the request in
+         * hand may be what ended the app (38.41). 38.37 — one whose head has gone out cannot be
+         * answered again, and ends as `abide start`'s does.
+         */
+        endAll(why: string, reask: boolean): void {
+            for (const held of inFlight.values()) {
+                if (held.stream !== null) {
+                    held.stream.error(new Error(why))
+                    held.pulled?.()
+                } else if (reask) queued.push(held)
+                else held.settle(plainAnswer(why, 500))
+            }
+            inFlight.clear()
+        },
+    }
+}
+
+// 38.38 — ASKED WITHOUT `accept-encoding`, so the app answers uncompressed. A failure after the head
+// is shown as markup appended to the stream, and markup appended to a compressed stream is a stream
+// no browser can decode. Localhost buys nothing from the bytes saved.
+function identityOnly(headers: Headers): [string, string][] {
+    const kept: [string, string][] = []
+    for (const [name, value] of headers)
+        if (name !== 'accept-encoding') kept.push([name, value])
+    return kept
+}

package/src/server/runCompiled.ts

@@ -3,8 +3,8 @@
 // is `ledger-linux-x64`, and that is what a reader types.
 
 import { type Host, runCommands } from './commands.ts'
-import { type AppOrigin, bootApp } from './createApp.ts'
-import { type BuildParts, builtSources, serveApp } from './serveBuild.ts'
+import { type AppHandle, type AppOrigin, bootApp } from './createApp.ts'
+import { type BuildParts, builtSources } from './serveBuild.ts'
 
 export async function runCompiled(
     origin: AppOrigin,
@@ -25,18 +25,15 @@ export async function runCompiled(
                 }))
         },
     })
+    // 38.49 — THE APP IT HOLDS, whatever the flags say.
+    const app: AppHandle = {
+        package: origin.package,
+        handlers: async () => parts.handlers,
+        boot: async () => bootApp(origin, () => builtSources(parts)),
+    }
     const host: Host = {
         name: process.execPath.slice(process.execPath.lastIndexOf('/') + 1),
-        handlers: async () => parts.handlers,
-        appPackage: () => origin.package,
-        boot: () => bootApp(origin, () => builtSources(parts)),
-        // 38.49.
-        serve: ({ values: { port } }) =>
-            serveApp(
-                origin,
-                () => builtSources(parts),
-                port === undefined ? undefined : Number(port),
-            ),
+        app: () => app,
         source: undefined,
     }
     const code = await runCommands(host, Bun.argv.slice(2))

package/src/server/runDesktop.ts

@@ -22,12 +22,11 @@ import {
     sendTyped,
     stringOf,
 } from './appKit.ts'
-import { APP_PACKAGE, configuredMount, dataDirectory } from './config.ts'
+import { configuredMount, dataDirectory } from './config.ts'
 import { configFields } from './configFields.ts'
-import { type App, type AppOrigin, bootApp } from './createApp.ts'
+import { type App, type AppOrigin, bootEntered, enterApp } from './createApp.ts'
 import { executableName } from './executableName.ts'
 import { HOOKS, inOrder, reportUnexpected } from './hooks.ts'
-import { installServer } from './installServer.ts'
 import { launcherOf } from './launcherOptions.ts'
 import { type Launch, launcherPage } from './launcherPage.ts'
 import { installMenu, menuBar, type NativeItem } from './nativeMenu.ts'
@@ -84,11 +83,9 @@ async function launch(
     load: () => ReturnType<typeof builtSources>,
     { launch: launchModule, document, icon, accent }: Desktop,
 ): Promise<void> {
-    installServer()
-    APP_PACKAGE.current = origin.package
-    // 37.1 — imported for what it files, so the start form reads `onConfig` and the launcher's
-    // `onLauncher` is filed.
-    await origin.hooks?.()
+    // 37.1 — ENTERED ONCE, before the window: the start form reads `onConfig` and the launcher's
+    // `onLauncher` is filed. Every start after it boots in what this entered (`bootEntered`).
+    await enterApp(origin)
     // 38.85 — a launcher page that fails to load leaves the built-in page, with its defaults.
     const launchPage = await launchModule?.().catch((thrown: unknown) => {
         reportUnexpected(thrown)
@@ -228,7 +225,7 @@ async function launch(
             else process.env[name] = value
         let app: App
         try {
-            app = await bootApp(origin, load)
+            app = await bootEntered(load)
         } catch (thrown) {
             failure = refused('start', thrown)
             return failure

package/src/server/serveBuild.ts

@@ -6,7 +6,6 @@
 // what it found, so the addresses the server answers and the addresses the client router knows
 // are two readings of one walk rather than two walks that have to agree (30.8).
 
-import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
 import {
     type Compilation,
     serveCompilation,
@@ -24,15 +23,10 @@ import {
     MANIFEST,
     PUBLIC_DIRECTORY,
 } from './CLIENT_BUILD.ts'
-import { type App, type AppOrigin, bootApp } from './createApp.ts'
-import { stopOnSignalOrFault } from './faultPolicy.ts'
+import { bundleServer, type ServedFile } from './clientBundle.ts'
 import type { Manifest } from './manifestOf.ts'
 import { namesUnder } from './namesUnder.ts'
-import {
-    ENCODINGS,
-    type Encoding,
-    negotiateEncoding,
-} from './negotiateEncoding.ts'
+import { ENCODINGS } from './negotiateEncoding.ts'
 import { runBuild } from './runBuild.ts'
 
 /**
@@ -49,23 +43,6 @@ export type BuildParts = Omit<SourceParts, 'client' | 'explained'> & {
     client: Map<string, string>
 }
 
-/**
- * The app booted (`bootApp`) and listening, stopped on a signal or an unawaited fault.
- *
- * Listening on `LISTENING.server`, for the caller to say where.
- */
-export async function serveApp(
-    origin: AppOrigin,
-    load: () => Promise<AppSources>,
-    port: number | undefined,
-): Promise<App> {
-    const app = await bootApp(origin, load)
-    await app.listen(port === undefined ? {} : { port })
-    // ONCE SERVING, and not before: a boot that fails is 37.6's to fail hard.
-    stopOnSignalOrFault(app)
-    return app
-}
-
 /**
  * Serves the compilation `abide build` kept in `out` to this process's imports; `false` where there
  * is none, because the app under `root` holds nothing to build.
@@ -128,62 +105,38 @@ export function pathsUnder(directory: string): Map<string, string> {
 
 /** The sources an `App` is booted over, out of the parts `abide build` produced. */
 export function builtSources(parts: BuildParts): Promise<AppSources> {
-    // THE BUNDLE, ENUMERATED RATHER THAN RESOLVED. A request names a file in this set or it names
-    // nothing — there is no path to normalize, so `..` is not a case that has to be got right,
-    // and what is servable is exactly what the build produced.
-    //
     // THE PRECOMPRESSED COPIES ARE NOT ADDRESSES OF THEIR OWN. They are the same file in another
     // encoding (38.5), so they are found under the name they encode and served as that name.
     const suffixes = Object.values(ENCODING_SUFFIX) as string[]
-    const assets = new Map<string, Encoding[]>()
-    for (const name of parts.client.keys()) {
+    const files = new Map<string, ServedFile>()
+    for (const [name, path] of parts.client) {
         if (suffixes.some((suffix) => name.endsWith(suffix))) continue
-        const encodings: Encoding[] = []
-        for (const encoding of ENCODINGS)
-            if (parts.client.has(name + ENCODING_SUFFIX[encoding]))
-                encodings.push(encoding)
-        assets.set(name, encodings)
-    }
-
-    const framework = (
-        pathname: string,
-        request: Request,
-    ): Response | undefined => {
-        if (!pathname.startsWith(`${CLIENT_ADDRESS}/`)) return undefined
-        const name = pathname.slice(CLIENT_ADDRESS.length + 1)
-        const encodings = assets.get(name)
-        if (encodings === undefined) return undefined
-        // THE TYPE IS THE NAME'S, not the path's: a compiled app's path carries a hash the
-        // bundler put before the extension, and a `.br`'s extension names nothing.
-        const type = Bun.file(name).type
-        // 21.5 — EVERY NAME IN THE BUNDLE CARRIES A HASH OF ITS BYTES, the entry's too (38.5),
-        // so a name never answers two different files and a year is safe for all of them. A
-        // deploy is new names in a new document, never new bytes at an old address.
-        const headers: Record<string, string> = {
-            'cache-control': 'public, max-age=31536000, immutable',
-            'content-type': type,
-            vary: 'accept-encoding',
+        const encoded: ServedFile['encoded'] = {}
+        for (const encoding of ENCODINGS) {
+            const copy = parts.client.get(name + ENCODING_SUFFIX[encoding])
+            if (copy !== undefined) encoded[encoding] = () => Bun.file(copy)
         }
-        // 38.29 — the precompressed copy where the request takes its encoding.
-        const encoding = negotiateEncoding(
-            request.headers.get('accept-encoding'),
-            encodings,
-        )
-        if (encoding === undefined)
-            return new Response(Bun.file(parts.client.get(name) as string), {
-                headers,
-            })
-        headers['content-encoding'] = encoding
-        return new Response(
-            Bun.file(
-                parts.client.get(name + ENCODING_SUFFIX[encoding]) as string,
-            ),
-            { headers },
-        )
+        files.set(name, {
+            // THE TYPE IS THE NAME'S, not the path's: a compiled app's path carries a hash the
+            // bundler put before the extension, and a `.br`'s extension names nothing.
+            type: Bun.file(name).type,
+            body: () => Bun.file(path),
+            encoded,
+        })
     }
     return appSources({
         ...parts,
         explained: undefined,
-        client: { manifest: parts.manifest, head: '', framework },
+        client: {
+            manifest: parts.manifest,
+            head: '',
+            // 21.5 — EVERY NAME IN THE BUNDLE CARRIES A HASH OF ITS BYTES, the entry's too (38.5), so
+            // a name never answers two different files and a year is safe for all of them. A deploy
+            // is new names in a new document, never new bytes at an old address.
+            framework: bundleServer(
+                files,
+                'public, max-age=31536000, immutable',
+            ),
+        },
     })
 }