@abide/abide 0.58.0 → 0.100.0

package/src/server/serveDev.ts

@@ -0,0 +1,499 @@
+// 38.4 — `abide dev`: the project, watched, with the app kept up across every save. What is here
+// is the LISTENER and nothing else (38.15): the socket is bound once in this process and survives
+// every reload, so a browser holding a connection open meets a server that is still there when
+// the app behind it has been thrown away and rebuilt.
+//
+// 18.1 — THE APP'S MUX IS HELD HERE TOO, and its frames relayed: the browser's web socket is bound
+// in this process, tagged with a connection id, and the app's mux answers each frame through it.
+// A reload closes these with the reload client's, and a follower reconnects naming the version it
+// holds (18.9), so the rebuilt app sends it only what moved.
+//
+// THE COMPILE IS HERE AND THE APP IS THERE. The compiler stays loaded in this process across every
+// reload, where a compiler imported into each new app cost 4.5 s a save against the 80 ms the
+// compile takes — and the clause asks for the APP to be in the child, which the compiler is not.
+//
+// 38.16 — A RELOAD IS A NEW PROCESS, not a module cache to invalidate. An app leaves things behind
+// that no invalidation reaches — a timer, a `share`, a module that ran once, and bun's own memory of
+// a file it failed to find — and a process is the one boundary that takes all of them with it. Every live socket is force-closed with it, which
+// is also the whole of the reload protocol: the reload client reconnects and reloads, so nothing
+// here has a message to send.
+
+import { watch } from 'node:fs' // bun exposes no file watcher of its own
+import {
+    type AppChecker,
+    compileApp,
+    openChecker,
+} from '#compiler/compileApp.ts'
+import { formatDiagnosis } from '#compiler/formatDiagnosis.ts'
+import { DEV_ADDRESS } from '#shared/ADDRESSES.ts'
+import { DEFAULT_PORT } from './DEFAULT_PORT.ts'
+import type { Ask, FromWorker, ToWorker } from './devWorker.ts'
+import { upgraded } from './muxUpgrade.ts'
+import { plainAnswer } from './plainAnswer.ts'
+import { SETTLE_MILLISECONDS } from './SETTLE_MILLISECONDS.ts'
+import { VIRTUAL_DIRECTORY } from './VIRTUAL_DIRECTORY.ts'
+
+/** What `abide dev` serves, and where. */
+export type DevOptions = {
+    /** The app's source root — the directory `ui/` sits under, and the tree that is watched. */
+    root: string
+    port?: number | undefined
+}
+
+// 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 app that exists (38.25) — 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.36).
+type InFlight = Omit<Ask, 'id' | 'method' | 'url'> & {
+    // 16.22 — the request bun handed the listener, which is the one its idle timeout is raised on.
+    request: Request
+    settle: (response: Response) => void
+    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 app's process, spoken to in its own protocol.
+type DevWorker = {
+    postMessage(message: ToWorker): void
+    terminate(): void
+}
+
+type Compiled = { modules: Map<string, string>; failure: string }
+
+const LAST_DEV_PORT = 3099
+
+// 37.3 — the answers the worker said `admitsMux`, which the listener upgrades on.
+const ADMITTED = new WeakSet<Response>()
+
+// An app-mux socket's data: the id the worker knows its connection by, and what `Mux.connect` reads
+// off the upgrade. `undefined` on the reload client's.
+type Carried =
+    | { connection: number; url: string; headers: [string, string][] }
+    | undefined
+
+/**
+ * `abide dev`'s listener, compiling the app here and serving it from a child process.
+ *
+ * The child is replaced on every save; the listener's bound socket outlives it.
+ */
+export async function serveDev(
+    options: DevOptions,
+): Promise<Bun.Server<undefined>> {
+    const inFlight = new Map<number, InFlight>()
+    // Every socket this listener holds: the reload client's, with no data, and the app mux's, carrying
+    // the connection id the worker knows it by.
+    const sockets = new Set<Bun.ServerWebSocket<Carried>>()
+    const muxed = new Map<number, Bun.ServerWebSocket<Carried>>()
+    let nextConnection = 0
+    let worker: DevWorker | undefined
+    let ready = false
+    let nextId = 0
+    // ASKED BEFORE THERE IS ANYONE TO ASK. A replacement terminates the worker and the next one
+    // does not exist until its compile finishes, so a request arriving in that window has
+    // nowhere to go — posted to the terminated worker it is never answered, and the reader's
+    // tab hangs until they give up. It waits here instead.
+    const queued: InFlight[] = []
+
+    // ONE COMPILE AT A TIME, and the worker is started from the LAST one. A save landing while a
+    // compile runs marks it stale rather than starting a second: two in flight each started a
+    // worker, the one finishing second overwrote the first without terminating it, and where the
+    // older compile finished last it was the one that served.
+    let compiling: Promise<void> | undefined
+    let stale = false
+
+    // THE CHECKER IS KEPT ACROSS SAVES, and what the watcher saw move since the last compile is
+    // what it is told (`AppChecker.saw`). On the docs app a save reached the next answer in 182 ms
+    // opening a checker per compile and 86 ms keeping one; kept, it re-reads only what moved.
+    let checker: AppChecker | undefined
+
+    async function reopen(): Promise<void> {
+        let compiled: Compiled
+        do {
+            stale = false
+            compiled = await compile()
+        } while (stale)
+        compiling = undefined
+        open(compiled)
+    }
+
+    // A compile that threw is sent IN rather than thrown here: 38.4 keeps the app up, so what a
+    // failure changes is what the worker serves.
+    //
+    // A THROW DROPS THE CHECKER. Most are an author's typo, but the checker's own process dying is
+    // one too, and a session nobody can tell apart from a dead one is not one to keep.
+    async function compile(): Promise<Compiled> {
+        try {
+            if (checker !== undefined && !checker.current())
+                await closeChecker()
+            checker ??= await openChecker(options.root)
+            const compiled = await compileApp(
+                options.root,
+                `${options.root}/${VIRTUAL_DIRECTORY}`,
+                checker,
+            )
+            // 14 and 32.14 — what the compiler has to say, on every compile.
+            for (const warning of compiled.warnings)
+                console.warn(formatDiagnosis(warning, process.cwd()))
+            return { modules: compiled.modules, failure: '' }
+        } catch (thrown) {
+            await closeChecker()
+            const failure =
+                thrown instanceof Error ? thrown.message : String(thrown)
+            console.error(`abide dev: ${failure}`)
+            return { modules: new Map(), failure }
+        }
+    }
+
+    async function closeChecker(): Promise<void> {
+        const closing = checker
+        checker = undefined
+        try {
+            await closing?.close()
+        } catch {
+            // Already gone, which is what closing it was for.
+        }
+    }
+
+    // The worker, compiled and answering.
+    function open({ modules, failure }: Compiled): void {
+        // 38.15 — A PROCESS, NOT A THREAD, for the header's reason: bun remembers a file it failed
+        // to find for the life of the process, and a thread inherits the miss.
+        //
+        // THE ENVIRONMENT AS IT STANDS, `NODE_ENV` included (36.3): the child is handed what this
+        // process holds now rather than what it started with. `advanced` carries an `ArrayBuffer`.
+        const child = Bun.spawn(
+            [
+                'bun',
+                Bun.fileURLToPath(new URL('./devWorker.ts', import.meta.url)),
+            ],
+            {
+                env: process.env as Record<string, string>,
+                stdio: ['inherit', 'inherit', 'inherit'],
+                serialization: 'advanced',
+                ipc(message: FromWorker) {
+                    if (message.kind === 'ready') ready = true
+                    else if (message.kind === 'socket-send')
+                        muxed.get(message.connection)?.send(message.text)
+                    else if (message.kind === 'timeout') {
+                        const asked = inFlight.get(message.id)?.request
+                        if (asked !== undefined)
+                            server.timeout(asked, message.seconds)
+                    } else answer(started, message)
+                },
+                // 38.42 — AN APP THAT EXITS ON ITS OWN is replaced, and says so: a listener still
+                // forwarding to it leaves every tab hanging.
+                onExit() {
+                    if (worker !== started) return
+                    console.error(
+                        'abide dev: the app exited, so it was restarted',
+                    )
+                    endInFlight(false, 'abide dev: the app exited')
+                    replace()
+                },
+            },
+        )
+        const started: DevWorker = {
+            // A message to a process already gone is one nobody would answer; its exit says so.
+            postMessage(message) {
+                if (!child.killed && child.exitCode === null)
+                    child.send(message)
+            },
+            terminate() {
+                child.kill()
+            },
+        }
+        worker = started
+        started.postMessage({
+            kind: 'start',
+            root: options.root,
+            modules,
+            failure,
+        })
+        // The worker holds every request behind its own compile, so what waited here only had
+        // to wait for one to EXIST.
+        const waiting = queued.splice(0)
+        for (const again of waiting) forward(again)
+    }
+
+    // WHAT AN APP THAT IS GONE WAS HOLDING. A request whose head has not gone out is re-asked of the
+    // replacement (38.25), or answered where the app ended itself — the request in hand may be what
+    // ended it (38.42). 38.38 — one whose head has gone out cannot be answered again, and ends as
+    // `abide start`'s does.
+    function endInFlight(reask: boolean, why: string): 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.16 — THE REPLACEMENT. The old worker is terminated, every socket it could still be
+    // answering is force-closed, and the new one is opened. The order matters: a socket closed
+    // after the new worker is up is a reload client that reconnects to a server still compiling.
+    //
+    // 38.25 — A REQUEST IN FLIGHT IS RE-ASKED rather than failed. Failing it serves a reader a
+    // network error for asking while somebody saved, and during a regeneration of a whole docs
+    // tree that is every request; re-asked, they wait and get the app the source now says.
+    function replace(): void {
+        ready = false
+        worker?.terminate()
+        worker = undefined
+        for (const socket of sockets) socket.terminate()
+        sockets.clear()
+        muxed.clear()
+        endInFlight(true, 'abide dev replaced the app mid-response')
+        if (compiling !== undefined) stale = true
+        else compiling = reopen()
+    }
+
+    compiling = reopen()
+    await compiling
+
+    // 38.4 — THE PROJECT, WATCHED. One recursive watcher over the source root: the pages, the
+    // shell, the stylesheets and `ui/public` are all under it, and every one of them is something
+    // the worker read at boot.
+    //
+    // IT IS NOT UNREFFED. It holds the process open, which is what a command that IS a server
+    // wants: the only ways out of `abide dev` are a signal and a throw, exactly as for
+    // `abide start`.
+    let settling: ReturnType<typeof setTimeout> | undefined
+    watch(options.root, { recursive: true }, (_event, filename) => {
+        checker?.saw(
+            filename === null ? undefined : `${options.root}/${filename}`,
+        )
+        if (settling !== undefined) clearTimeout(settling)
+        settling = setTimeout(replace, SETTLE_MILLISECONDS)
+    })
+
+    // A REQUEST AS A MESSAGE. `Request` does not survive a structured clone, so what crosses is
+    // the four things the worker rebuilds one from — and the request's body is collected here, which
+    // is what lets it be asked again of a replacement (38.25). The answer's body streams (38.36).
+    //
+    // COLLECTED ONCE, HERE, rather than inside `forward`: a body can only be read off a
+    // `Request` once, and a re-asked request is the second read that is not there.
+    async function ask(request: Request): Promise<Response> {
+        const body = request.body === null ? null : await request.arrayBuffer()
+        return await new Promise<Response>((resolve) => {
+            forward({
+                request,
+                headers: identityOnly(request.headers),
+                body,
+                settle: resolve,
+                stream: null,
+                pulled: null,
+                failed: null,
+            })
+        })
+    }
+
+    // 38.39 — ASKED WITHOUT `accept-encoding`, so the app answers uncompressed. A failure after the
+    // head is shown as markup appended to the stream (`pull` in the worker), 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
+    }
+
+    // 38.36, 38.37 — 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 answer(
+        from: DevWorker,
+        message: Exclude<
+            FromWorker,
+            { kind: 'ready' | 'socket-send' | 'timeout' }
+        >,
+    ): void {
+        const waiting = inFlight.get(message.id)
+        if (waiting === undefined) return
+        const { id } = message
+        if (message.kind === 'head') {
+            if (message.empty || message.whole !== undefined) {
+                inFlight.delete(id)
+                const answered = new Response(message.whole ?? null, {
+                    status: message.status,
+                    statusText: message.statusText,
+                    headers: message.headers,
+                })
+                // The admission has no body, so an admitted answer is always settled here.
+                if (message.admitted) ADMITTED.add(answered)
+                waiting.settle(answered)
+                return
+            }
+            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
+                            from.postMessage({ kind: 'pull', id })
+                        })
+                    },
+                    cancel() {
+                        inFlight.delete(id)
+                        from.postMessage({ kind: 'cancel', id })
+                    },
+                },
+                { highWaterMark: 0 },
+            )
+            waiting.settle(
+                new Response(body, {
+                    status: message.status,
+                    statusText: message.statusText,
+                    headers: message.headers,
+                }),
+            )
+            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(id)
+            stream.close()
+        } else waiting.failed = message.message
+        pulled?.()
+    }
+
+    // NOT TRANSFERRED. Handing the buffer over detaches it here, and a request re-asked of the
+    // replacement worker would post a body that is no longer there.
+    function forward(waiting: InFlight): void {
+        if (worker === undefined) {
+            queued.push(waiting)
+            return
+        }
+        nextId += 1
+        const id = nextId
+        inFlight.set(id, waiting)
+        worker.postMessage({
+            kind: 'request',
+            id,
+            method: waiting.request.method,
+            url: waiting.request.url,
+            headers: waiting.headers,
+            body: waiting.body,
+        })
+    }
+
+    // THE CHECKER GOES WITH THE COMMAND. It is a process of its own, and an app with no tsconfig
+    // holds a temporary project on disk for as long as it is open. The signal is raised again once
+    // it is closed, so the command still ends the way that signal ends a process.
+    for (const signal of ['SIGINT', 'SIGTERM'] as const)
+        process.once(signal, () => {
+            void closeChecker().finally(() => process.kill(process.pid, signal))
+        })
+
+    const listen = (port: number | undefined) =>
+        Bun.serve<Carried>({
+            ...(port === undefined ? {} : { port }),
+            // 16.54, as `App.listen` lifts it: the worker behind this is where the ceiling is read.
+            maxRequestBodySize: Number.MAX_SAFE_INTEGER,
+            async fetch(request, listening) {
+                const asked = new URL(request.url).pathname
+                // THE MUX STANDS UNDER THE MOUNT, which is the app's configuration and so the worker's to
+                // read: every upgrade but the reload client's is asked of it, and the worker says
+                // whether it is the mux's (`muxUpgrade`) — a status alone is not, since any rung at any
+                // address can answer one.
+                const mux =
+                    asked !== DEV_ADDRESS &&
+                    request.headers.get('upgrade') === 'websocket'
+                if (!mux && asked !== DEV_ADDRESS) return ask(request)
+                // 37.3 — THE MUX'S UPGRADE IS ASKED OF THE APP FIRST, whose lane runs in the worker.
+                if (mux && ready) {
+                    const answered = await ask(request)
+                    if (!ADMITTED.has(answered)) return answered
+                }
+                // NOT WHILE THE APP IS COMPILING. The reload client and the browser's mux both read a
+                // refusal as "still rebuilding" and retry, which is what keeps a reload from racing
+                // the worker it is meant to show.
+                if (!ready) return plainAnswer('rebuilding', 503)
+                let data: Carried
+                if (mux) {
+                    nextConnection += 1
+                    data = {
+                        connection: nextConnection,
+                        url: request.url,
+                        headers: [...request.headers.entries()],
+                    }
+                }
+                return upgraded(listening, request, data)
+            },
+            websocket: {
+                open(socket) {
+                    // A RELOAD LANDED between the upgrade and this open: the worker it was meant for is
+                    // gone and the next one would never hear of it, so it is closed and retried instead.
+                    if (!ready) {
+                        socket.terminate()
+                        return
+                    }
+                    sockets.add(socket)
+                    const carried = socket.data
+                    if (carried === undefined) return
+                    muxed.set(carried.connection, socket)
+                    worker?.postMessage({ kind: 'socket-open', ...carried })
+                },
+                close(socket) {
+                    sockets.delete(socket)
+                    const carried = socket.data
+                    if (carried === undefined) return
+                    // A socket a reload terminated is the old worker's, and the new one never knew it.
+                    if (muxed.delete(carried.connection))
+                        worker?.postMessage({
+                            kind: 'socket-close',
+                            connection: carried.connection,
+                        })
+                },
+                // The reload client says nothing; an app socket's frames go to the mux in the worker.
+                message(socket, text) {
+                    const carried = socket.data
+                    if (carried === undefined) return
+                    worker?.postMessage({
+                        kind: 'socket-message',
+                        connection: carried.connection,
+                        text: String(text),
+                    })
+                },
+            },
+        })
+
+    // 38.65 — A PORT SOMEONE NAMED IS THE PORT, and one taken is the failure. `Bun.serve` given
+    // none reads `PORT` itself.
+    const server =
+        options.port !== undefined || process.env.PORT
+            ? listen(options.port)
+            : listenOnFirstFree(listen)
+    return server as unknown as Bun.Server<undefined>
+}
+
+// 38.64 — NAMED BY NOBODY, the first free port from 3000. A port taken is the next one tried, and
+// any other failure is the failure.
+function listenOnFirstFree<Listener>(
+    listen: (port: number) => Listener,
+): Listener {
+    for (let port = DEFAULT_PORT; ; port += 1)
+        try {
+            return listen(port)
+        } catch (thrown) {
+            if (
+                (thrown as { code?: unknown }).code !== 'EADDRINUSE' ||
+                port === LAST_DEV_PORT
+            )
+                throw thrown
+        }
+}