@briancray/belte 0.8.0 → 0.9.0

package/src/lib/server/runtime/createServer.ts

@@ -27,9 +27,9 @@ import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
 import { createRouteDispatcher } from './createRouteDispatcher.ts'
 import { disableIdleTimeoutForStream } from './disableIdleTimeoutForStream.ts'
-import { findOpenPort } from './findOpenPort.ts'
 import { globToPathSet } from './globToPathSet.ts'
 import { internalErrorResponse } from './internalErrorResponse.ts'
+import { listenOnOpenPort } from './listenOnOpenPort.ts'
 import { logBrowserOnlyRoutes } from './logBrowserOnlyRoutes.ts'
 import { parseIdleTimeout } from './parseIdleTimeout.ts'
 import { parsePort } from './parsePort.ts'
@@ -92,9 +92,9 @@ export async function createServer({
     distDir = `${process.cwd()}/dist`,
     publicDir = `${process.cwd()}/src/browser/public`,
     resourcesDir = `${process.cwd()}/src/mcp/resources`,
-    // No PORT set → scan for the first open port at/above 3000 rather than
-    // hardcoding 3000, so a second app boots cleanly instead of colliding.
-    port = parsePort(process.env.PORT) ?? findOpenPort(3000),
+    // A configured PORT is honored as-is; left undefined, the real listener
+    // scans upward from 3000 at bind time (see buildServer / listenOnOpenPort).
+    port = parsePort(process.env.PORT),
     /*
     Bun's per-connection idle timeout in seconds (its own default is 10).
     Surfaced for apps whose unary handlers legitimately compute longer than
@@ -310,137 +310,155 @@ export async function createServer({
     a busy socket doesn't iterate JS per subscriber per message.
     */
     const socketDispatcher = createSocketDispatcher(sockets)
-    // Server<unknown> pins Bun's WebSocketData generic so upgrade({ data: {} }) typechecks.
-    const server: Server<unknown> = Bun.serve({
-        port,
-        idleTimeout,
 
-        websocket: {
-            open(ws) {
-                socketDispatcher.open(ws)
-            },
-            message(ws, data) {
-                socketDispatcher.message(ws, data)
-            },
-            close(ws) {
-                socketDispatcher.close(ws)
+    /*
+    Bind the real server on `boundPort`. Only the port varies between scan
+    attempts, so the rest of the config lives inline and just the port is spread
+    in — passing the literal straight to Bun.serve keeps contextual typing of the
+    websocket handlers (and Server<unknown> pins Bun's WebSocketData generic so
+    upgrade({ data: {} }) typechecks).
+    */
+    const bindAt = (boundPort: number): Server<unknown> =>
+        Bun.serve({
+            port: boundPort,
+            idleTimeout,
+
+            websocket: {
+                open(ws) {
+                    socketDispatcher.open(ws)
+                },
+                message(ws, data) {
+                    socketDispatcher.message(ws, data)
+                },
+                close(ws) {
+                    socketDispatcher.close(ws)
+                },
             },
-        },
 
-        routes,
+            routes,
 
-        async fetch(req, bunServer) {
-            const url = new URL(req.url)
-            /*
-            Identity probe — answered directly, ahead of any app.handle middleware,
-            so the bundle's connect screen can confirm a URL really is a belte
-            server (and which app) before pointing the desktop window at it. It
-            must stay reachable even when the app guards everything behind auth,
-            hence the early return that bypasses dispatchRequest.
-            */
-            if (url.pathname === IDENTITY_PATH) {
-                return Response.json(
-                    {
-                        belte: true,
-                        name: appInfo?.name ?? cliName,
-                        version: appInfo?.version ?? '0.0.0',
-                    },
-                    { headers: { 'Cache-Control': NO_STORE } },
-                )
-            }
-            if (url.pathname === SOCKETS_PATH) {
-                if (bunServer.upgrade(req, { data: {} })) {
-                    return undefined as unknown as Response
+            async fetch(req, bunServer) {
+                const url = new URL(req.url)
+                /*
+                Identity probe — answered directly, ahead of any app.handle middleware,
+                so the bundle's connect screen can confirm a URL really is a belte
+                server (and which app) before pointing the desktop window at it. It
+                must stay reachable even when the app guards everything behind auth,
+                hence the early return that bypasses dispatchRequest.
+                */
+                if (url.pathname === IDENTITY_PATH) {
+                    return Response.json(
+                        {
+                            belte: true,
+                            name: appInfo?.name ?? cliName,
+                            version: appInfo?.version ?? '0.0.0',
+                        },
+                        { headers: { 'Cache-Control': NO_STORE } },
+                    )
                 }
-                return new Response('Upgrade failed', { status: 400 })
-            }
-            /*
-            HTTP face of a socket (`/__belte/sockets/<name>`) — tail over
-            SSE / JSON and publish — for the CLI and MCP. Runs through
-            dispatchRequest so app.handle auth applies, like the rpc paths.
-            The socket name may contain `/` (nested files), so it's the
-            whole remaining pathname, percent-decoded.
-            */
-            if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
-                const name = decodeURIComponent(url.pathname.slice(SOCKETS_REST_PREFIX.length))
-                return dispatchRequest(req, {}, async () => socketDispatcher.rest(req, name))
-            }
-            if (url.pathname === MCP_PATH && mcp) {
-                return dispatchRequest(req, {}, async () => mcp.handle(req))
-            }
-            if (url.pathname === CLI_PATH) {
-                return dispatchRequest(req, {}, async () => handleCliInstall(req, cliName))
-            }
-            if (url.pathname.startsWith(CLI_DOWNLOAD_PREFIX)) {
-                const platform = url.pathname.slice(CLI_DOWNLOAD_PREFIX.length)
-                return dispatchRequest(req, {}, async () =>
-                    handleCliDownload(req, platform, cliName, cliCwd),
-                )
-            }
-            if (url.pathname === OPENAPI_PATH) {
-                return dispatchRequest(req, {}, async () => {
-                    await ensureRegistriesLoaded()
-                    const spec = buildOpenApiSpec({
-                        title: appInfo?.name ?? cliName,
-                        version: appInfo?.version ?? '0.0.0',
-                    })
-                    return Response.json(spec, { headers: { 'Cache-Control': NO_STORE } })
-                })
-            }
-            /*
-            Static assets sidestep ALS + the per-request CacheStore + the
-            app.handle middleware: they have no need for cache() and the
-            allocation overhead matters on a cold page load that pulls
-            dozens of chunks. The global server.error() handler still
-            catches anything that goes wrong inside serveStaticAsset.
-            */
-            if (url.pathname.startsWith('/_app/')) {
-                if (!logRequests) {
-                    return serveStaticAsset(req, url)
+                if (url.pathname === SOCKETS_PATH) {
+                    if (bunServer.upgrade(req, { data: {} })) {
+                        return undefined as unknown as Response
+                    }
+                    return new Response('Upgrade failed', { status: 400 })
                 }
-                const start = Bun.nanoseconds()
-                const response = await serveStaticAsset(req, url)
-                const ms = (Bun.nanoseconds() - start) / 1e6
-                log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
-                return response
-            }
-            /*
-            Files under public/ are served at the site root, sidestepping
-            ALS + middleware like the /_app/ assets do. A miss returns
-            undefined so the request falls through to the 404 / middleware
-            path below.
-            */
-            const publicResponse = await servePublicAsset(req, url)
-            if (publicResponse) {
-                if (logRequests) {
-                    log.request(
-                        req.method,
-                        `${url.pathname}${url.search}`,
-                        publicResponse.status,
-                        0,
+                /*
+                HTTP face of a socket (`/__belte/sockets/<name>`) — tail over
+                SSE / JSON and publish — for the CLI and MCP. Runs through
+                dispatchRequest so app.handle auth applies, like the rpc paths.
+                The socket name may contain `/` (nested files), so it's the
+                whole remaining pathname, percent-decoded.
+                */
+                if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
+                    const name = decodeURIComponent(url.pathname.slice(SOCKETS_REST_PREFIX.length))
+                    return dispatchRequest(req, {}, async () => socketDispatcher.rest(req, name))
+                }
+                if (url.pathname === MCP_PATH && mcp) {
+                    return dispatchRequest(req, {}, async () => mcp.handle(req))
+                }
+                if (url.pathname === CLI_PATH) {
+                    return dispatchRequest(req, {}, async () => handleCliInstall(req, cliName))
+                }
+                if (url.pathname.startsWith(CLI_DOWNLOAD_PREFIX)) {
+                    const platform = url.pathname.slice(CLI_DOWNLOAD_PREFIX.length)
+                    return dispatchRequest(req, {}, async () =>
+                        handleCliDownload(req, platform, cliName, cliCwd),
                     )
                 }
-                return publicResponse
-            }
-            /*
-            Unknown routes still run through dispatchRequest so user-defined
-            app.handle middleware can rewrite the request, serve a custom
-            404, or branch on the URL. The inner handler returns the
-            framework's default 404 when nothing intervenes.
-            */
-            return dispatchRequest(req, {}, async () => {
-                return new Response('Not Found', {
-                    status: 404,
-                    headers: { 'Cache-Control': NO_STORE },
+                if (url.pathname === OPENAPI_PATH) {
+                    return dispatchRequest(req, {}, async () => {
+                        await ensureRegistriesLoaded()
+                        const spec = buildOpenApiSpec({
+                            title: appInfo?.name ?? cliName,
+                            version: appInfo?.version ?? '0.0.0',
+                        })
+                        return Response.json(spec, { headers: { 'Cache-Control': NO_STORE } })
+                    })
+                }
+                /*
+                Static assets sidestep ALS + the per-request CacheStore + the
+                app.handle middleware: they have no need for cache() and the
+                allocation overhead matters on a cold page load that pulls
+                dozens of chunks. The global server.error() handler still
+                catches anything that goes wrong inside serveStaticAsset.
+                */
+                if (url.pathname.startsWith('/_app/')) {
+                    if (!logRequests) {
+                        return serveStaticAsset(req, url)
+                    }
+                    const start = Bun.nanoseconds()
+                    const response = await serveStaticAsset(req, url)
+                    const ms = (Bun.nanoseconds() - start) / 1e6
+                    log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
+                    return response
+                }
+                /*
+                Files under public/ are served at the site root, sidestepping
+                ALS + middleware like the /_app/ assets do. A miss returns
+                undefined so the request falls through to the 404 / middleware
+                path below.
+                */
+                const publicResponse = await servePublicAsset(req, url)
+                if (publicResponse) {
+                    if (logRequests) {
+                        log.request(
+                            req.method,
+                            `${url.pathname}${url.search}`,
+                            publicResponse.status,
+                            0,
+                        )
+                    }
+                    return publicResponse
+                }
+                /*
+                Unknown routes still run through dispatchRequest so user-defined
+                app.handle middleware can rewrite the request, serve a custom
+                404, or branch on the URL. The inner handler returns the
+                framework's default 404 when nothing intervenes.
+                */
+                return dispatchRequest(req, {}, async () => {
+                    return new Response('Not Found', {
+                        status: 404,
+                        headers: { 'Cache-Control': NO_STORE },
+                    })
                 })
-            })
-        },
+            },
+
+            error(err) {
+                log.error(err)
+                return internalErrorResponse(err)
+            },
+        })
 
-        error(err) {
-            log.error(err)
-            return internalErrorResponse(err)
-        },
-    })
+    /*
+    A configured PORT binds that exact port — a collision surfaces loudly rather
+    than silently moving, since something connecting to the app needs a known
+    address. With none set, scan upward from 3000 binding the real listener, so
+    whichever server wins the port keeps it (no probe-release gap to lose it in,
+    which used to crash boot on EADDRINUSE instead of stepping to the next port).
+    */
+    const server: Server<unknown> =
+        port === undefined ? listenOnOpenPort(bindAt, 3000) : bindAt(port)
 
     /*
     Publishes the live server through `belte/server` before invoking the

package/src/lib/server/runtime/listenOnOpenPort.ts

@@ -0,0 +1,36 @@
+import type { Server } from 'bun'
+
+// Ports tried upward from `start` before giving up and letting the kernel assign one.
+const SCAN_RANGE = 100
+
+/*
+Binds the real server, scanning upward from `start` for the first free port.
+The listener that wins a port is the one that keeps it: unlike probing a
+throwaway server and releasing it before the real bind, this leaves no window
+for the chosen port to be stolen in between — the gap that crashed boot on
+EADDRINUSE instead of stepping to the next port. `bindAt` does the actual
+Bun.serve; only an in-use port is retried, any other failure propagates. After
+SCAN_RANGE occupied ports it binds port 0 so the kernel assigns any free port.
+*/
+export function listenOnOpenPort(
+    bindAt: (port: number) => Server<unknown>,
+    start: number,
+): Server<unknown> {
+    for (let port = start; port < start + SCAN_RANGE; port++) {
+        try {
+            return bindAt(port)
+        } catch (error) {
+            if (!isAddressInUse(error)) {
+                throw error
+            }
+            // port in use — try the next one up
+        }
+    }
+    // every candidate was taken; bind to 0 so the kernel picks a free port
+    return bindAt(0)
+}
+
+// Bun reports a taken port as an Error carrying code 'EADDRINUSE'.
+function isAddressInUse(error: unknown): boolean {
+    return error instanceof Error && (error as { code?: string }).code === 'EADDRINUSE'
+}

package/src/lib/shared/clearLastConnection.ts

@@ -0,0 +1,7 @@
+import { rm } from 'node:fs/promises'
+import { lastConnectionPath } from './lastConnectionPath.ts'
+
+// Forgets the saved connection (the `/disconnect` reset). Missing file is a no-op.
+export async function clearLastConnection(programName: string): Promise<void> {
+    await rm(lastConnectionPath(programName), { force: true })
+}

package/src/lib/shared/lastConnectionPath.ts

@@ -0,0 +1,7 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+
+// Path to the per-program last-connection record, beside the data-dir `.env`.
+export function lastConnectionPath(programName: string): string {
+    return join(appDataDir(programName), 'last-connection.json')
+}

package/src/lib/shared/readLastConnection.ts

@@ -0,0 +1,18 @@
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+/*
+Reads the saved connection intent, or undefined when none is recorded or the file
+is unreadable/corrupt — callers treat undefined as "nothing to resume".
+*/
+export async function readLastConnection(programName: string): Promise<LastConnection | undefined> {
+    const file = Bun.file(lastConnectionPath(programName))
+    if (!(await file.exists())) {
+        return undefined
+    }
+    try {
+        return (await file.json()) as LastConnection
+    } catch {
+        return undefined
+    }
+}

package/src/lib/shared/runningAsStandaloneBinary.ts

@@ -0,0 +1,13 @@
+/*
+True when this code runs inside a `bun build --compile` standalone executable
+(the bundle's embedded server, or an install-tarball server binary) rather than
+under the `bun` CLI. Bun mounts a compiled binary's embedded modules under a
+synthetic root — `/$bunfs/…` on posix, `…~BUN…` on Windows — so `Bun.main`
+carries that marker only in a standalone binary; under `bun dev`/`bun start`
+it's a real on-disk path. Used to scope the bundle's data-dir/binary-dir `.env`
+loading to the shipped app, so `bun dev`/`bun start` keep to their project-local
+CWD `.env` alone.
+*/
+export function runningAsStandaloneBinary(): boolean {
+    return Bun.main.includes('$bunfs') || Bun.main.includes('~BUN')
+}

package/src/lib/shared/types/LastConnection.ts

@@ -0,0 +1,9 @@
+/*
+The launcher/CLI-owned record of the last connection, kept in the data dir so it
+survives relaunch and is readable before any window or session opens. It records
+the *intent*, not a concrete embedded URL — an embedded server picks a fresh port
+each launch, so only `{ kind: 'embedded' }` is durable; a remote connection keeps
+its url. resolveLaunchTarget / resolveCliTarget read it; /connect and /start write
+it; /disconnect clears it.
+*/
+export type LastConnection = { kind: 'embedded' } | { kind: 'url'; url: string }

package/src/lib/shared/writeLastConnection.ts

@@ -0,0 +1,13 @@
+import { mkdir } from 'node:fs/promises'
+import { appDataDir } from './appDataDir.ts'
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+// Persists the connection intent, creating the data dir on first write.
+export async function writeLastConnection(
+    programName: string,
+    value: LastConnection,
+): Promise<void> {
+    await mkdir(appDataDir(programName), { recursive: true })
+    await Bun.write(lastConnectionPath(programName), JSON.stringify(value))
+}

package/src/serverEntry.ts

@@ -29,17 +29,23 @@ import { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
 import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
+import { runningAsStandaloneBinary } from './lib/shared/runningAsStandaloneBinary.ts'
 import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
 
 /*
 Resolve config into process.env before anything reads it (createServer reads
-PORT, app code reads Bun.env.*). Data-dir first so the user's saved config wins
-over the binary-dir shipped default; both back-fill only what the shell or Bun's
-CWD `.env` didn't already set. A bundle launched via `open` has cwd `/`, so the
-data-dir `.env` is how it gets its config at all.
+PORT, app code reads Bun.env.*). Standalone-only: data-dir first so the user's
+saved config wins over the binary-dir shipped default; both back-fill only what
+the shell didn't already set. A bundle launched via `open` has cwd `/`, so the
+data-dir `.env` is how it gets its config at all. Under `bun dev`/`bun start`
+these bundle layers don't apply — the project's own CWD `.env` (Bun-autoloaded)
+is the config — so loading them would let a stray data-dir `PORT` defeat dev's
+port scan.
 */
-await loadEnvFromDataDir(cliProgramName)
-await loadEnvFromBinaryDir()
+if (runningAsStandaloneBinary()) {
+    await loadEnvFromDataDir(cliProgramName)
+    await loadEnvFromBinaryDir()
+}
 
 // In a bundle, tie this server's life to the launcher's (no-op standalone).
 exitWithParent()