@jxsuite/server 7.0.0 → 8.0.0

package/src/project-server.ts

@@ -1,8 +1,8 @@
 /**
- * Shared project server factory. Generalizes the chromium variant's ad-hoc in-process Bun.serve
- * into one createProjectServer() used by the chromium desktop launcher and the Electron hub.
+ * The desktop hub's per-window project server (`createProjectServer`).
  *
- * It serves three surfaces from a single loopback-bound Bun.serve:
+ * It serves three surfaces from a single loopback-bound server (`serve.ts`, which is `node:http` in
+ * the packaged app and `Bun.serve` under Bun):
  *
  * - The studio shell + canvas iframe doc + iframe bundle, under a non-colliding studio namespace (so
  *   a project's own asset tree never collides);
@@ -25,12 +25,13 @@
  */
 
 import { resolve, sep } from "node:path";
-import type { ServerWebSocket } from "bun";
+import { serve } from "#serve";
+import type { ServeServer, ServeSocket } from "./serve.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
 import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
-import { resolveNpmPath } from "./server.ts";
+import { resolveNpmPath } from "./npm-path.ts";
 import type { ImportApiOptions } from "./import-api.ts";
 import {
   decodeAndNormalizePath,
@@ -44,6 +45,7 @@ import { createLoopbackAuthorizer, OAUTH_CALLBACK_PATH } from "./oauth-loopback.
 import type { LoopbackAuthorizer } from "./oauth-loopback.ts";
 import type { FsEventBatch } from "./sse.ts";
 import type { JsonPrimitive, JsonValue } from "@jxsuite/schema/types";
+import { bundleToString } from "@jxsuite/compiler/bundler";
 
 /**
  * What a handler answers, sent as the reply frame's `result`: anything `JSON.stringify` encodes,
@@ -98,7 +100,7 @@ export interface CreateProjectServerOptions {
 }
 
 export interface ProjectServerHandle {
-  server: ReturnType<typeof Bun.serve>;
+  server: ServeServer<{ winId: string | null }>;
   url: string;
   wsUrl: string;
   rpcToken: string;
@@ -129,7 +131,9 @@ export interface ProjectServerHandle {
  * @param options See {@link CreateProjectServerOptions}.
  * @returns A handle with the bound url/wsUrl, the rpcToken, the canvas iframe URL, and stop().
  */
-export function createProjectServer(options: CreateProjectServerOptions): ProjectServerHandle {
+export async function createProjectServer(
+  options: CreateProjectServerOptions,
+): Promise<ProjectServerHandle> {
   const {
     resolveSession,
     studioDir,
@@ -147,9 +151,9 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
   /* Live shell sockets, so the server can speak first (see ProjectServerHandle.push). Membership is
      the socket's whole lifetime — added on open, dropped on close — so a push after a window is
      gone reaches nobody rather than throwing. */
-  const sockets = new Set<ServerWebSocket<{ winId: string | null }>>();
+  const sockets = new Set<ServeSocket<{ winId: string | null }>>();
 
-  const server = Bun.serve<{ winId: string | null }>({
+  const server = await serve<{ winId: string | null }>({
     hostname,
     port,
     // Keep SSE/AI streams alive (mirrors the dev server's generous idle timeout).
@@ -327,14 +331,10 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
       if (resolved) {
         if (!bundleCache.has(resolved)) {
           try {
-            const result = await Bun.build({
-              entrypoints: [resolved],
-              format: "esm",
-              minify: false,
-            });
-            if (result.success && result.outputs.length > 0) {
-              bundleCache.set(resolved, await result.outputs[0]!.text());
-            }
+            bundleCache.set(
+              resolved,
+              await bundleToString(resolved, { minify: false, target: "browser" }),
+            );
           } catch (error) {
             console.error("Bundle failed for", resolved, error);
           }

package/src/refactor/apply.ts

@@ -19,6 +19,7 @@ import { refactorMounts } from "./mounts.ts";
 import type { RefChange } from "./refs.ts";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+import { scanFiles } from "../fs-glob.ts";
 
 export interface FileChange {
   path: string;
@@ -117,7 +118,7 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
   let tagFilesChanged = 0;
   let tagRefsUpdated = 0;
 
-  for await (const match of documentGlob(opts.registry).scan({ cwd: opts.root, dot: false })) {
+  for await (const match of scanFiles(documentGlob(opts.registry), opts.root)) {
     if (skipScanPath(match)) {
       continue;
     }

package/src/refactor/scan.ts

@@ -61,13 +61,13 @@ export function skipScanPath(match: string): boolean {
   );
 }
 
-/** Build the recursive glob covering JSON plus every registered document/content extension. */
-export function documentGlob(registry: FormatRegistry): Bun.Glob {
+/** The recursive glob pattern covering JSON plus every registered document/content extension. */
+export function documentGlob(registry: FormatRegistry): string {
   const exts = new Set(["json"]);
   for (const ext of registry.documentExtensions()) {
     exts.add(ext.replace(/^\./, ""));
   }
-  return new Bun.Glob(`**/*.{${[...exts].join(",")}}`);
+  return `**/*.{${[...exts].join(",")}}`;
 }
 
 /**

package/src/resolve.ts

@@ -360,15 +360,10 @@ export async function handleResolve(
         return new Response(`$src "${$src}" escapes the project root`, { status: 403 });
       }
     } else {
-      // Npm/bare specifier — use createRequire from project root, fall back to server package
+      // Npm/bare specifier — the project's own install, never the server's (a class package is an
+      // Extension of the project, specs/extensions.md §3, and the build resolves it the same way).
       const projectRoot = activeProjectRoot || root;
-      const projRequire = createRequire(resolve(projectRoot, "package.json"));
-      try {
-        moduleAbsPath = projRequire.resolve($src);
-      } catch {
-        const serverRequire = createRequire(import.meta.url);
-        moduleAbsPath = serverRequire.resolve($src);
-      }
+      moduleAbsPath = createRequire(resolve(projectRoot, "package.json")).resolve($src);
       trustedResolution = true;
     }
   } catch (error) {

package/src/serve.bun.ts

@@ -0,0 +1,50 @@
+/**
+ * `serve()` under Bun: `Bun.serve`, adapted to `serve.ts`'s shape. Selected by the `bun` condition
+ * of `#serve`, so only a Bun process ever loads this file.
+ *
+ * @docs studio/desktop
+ */
+import type { Server } from "bun";
+import type { ServeOptions, ServeServer } from "./serve.ts";
+
+export type * from "./serve.ts";
+
+/** Bun's `Server`, seen through the surface `serve.ts` declares. */
+function adapt<Data>(server: Server<Data>): ServeServer<Data> {
+  /* SAFETY: Bun declares `upgrade`'s options as a rest tuple conditional on `Data`, which an
+     unresolved type parameter never selects; for every `Data` either branch takes this object. */
+  const upgradeSocket = server.upgrade.bind(server) as (
+    req: Request,
+    options: { data: Data; headers?: HeadersInit },
+  ) => boolean;
+  return {
+    get port() {
+      return Number(server.url.port);
+    },
+    get url() {
+      return server.url;
+    },
+    upgrade: (req, { data, headers }) =>
+      upgradeSocket(req, headers === undefined ? { data } : { data, headers: { ...headers } }),
+    stop: (closeActiveConnections) => server.stop(closeActiveConnections),
+  };
+}
+
+/** Start a server and resolve once it is listening (which, under Bun, is already). */
+export async function serve<Data = undefined>(
+  options: ServeOptions<Data>,
+): Promise<ServeServer<Data>> {
+  const { fetch: handle, websocket, ...rest } = options;
+  let adapted: ServeServer<Data> | null = null;
+  const server = Bun.serve<Data>({
+    ...rest,
+    fetch: (req, bunServer) => handle(req, (adapted ??= adapt(bunServer))),
+    websocket: {
+      close: (ws, code, reason) => websocket?.close?.(ws, code, reason),
+      message: (ws, message) => websocket?.message?.(ws, message),
+      open: (ws) => websocket?.open?.(ws),
+    },
+  });
+  adapted ??= adapt(server);
+  return adapted;
+}

package/src/serve.node.ts

@@ -0,0 +1,311 @@
+/**
+ * `serve()` on `node:http` and `ws`: the default of `#serve` (`serve.ts`), so every runtime that is
+ * not Bun gets it, and the packaged desktop backend runs on it (specs/desktop.md §7.1).
+ *
+ * The work is the conversion at both edges. A request becomes a Fetch `Request` whose `signal`
+ * aborts when the client goes away (the AI and import routes cancel upstream work on it), and a
+ * `Response` body is streamed chunk by chunk with backpressure, never buffered, because SSE and AI
+ * streams are open-ended. An upgrade request reaches the same `fetch` handler, which accepts it
+ * with `server.upgrade()` as it would under Bun, or answers it with an ordinary `Response`.
+ *
+ * `tests/serve-node.test.ts` imports this file directly, so it runs under `bun test` as well.
+ *
+ * @docs studio/desktop
+ */
+import { createServer } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+import { WebSocketServer } from "ws";
+import type { RawData, WebSocket } from "ws";
+import type { ServeOptions, ServeServer, ServeSocket } from "./serve.ts";
+
+export type * from "./serve.ts";
+
+/** What an upgrade request carries until the handler accepts or answers it. */
+interface PendingUpgrade {
+  nodeReq: IncomingMessage;
+  socket: Duplex;
+  head: Buffer;
+  taken: boolean;
+}
+
+/** The `Sec-WebSocket-Protocol` an accepted upgrade echoes, read by `handleProtocols`. */
+const echoedProtocol = new WeakMap<IncomingMessage, string>();
+
+const BODYLESS_METHODS = new Set(["GET", "HEAD"]);
+
+/**
+ * The request body as `node:http` delivers it.
+ *
+ * @yields {Uint8Array} Each chunk of the body, in order
+ */
+async function* chunksOf(nodeReq: IncomingMessage): AsyncGenerator<Uint8Array> {
+  /* SAFETY: an `IncomingMessage` with no encoding set yields its body as Buffers; anything else is
+     skipped by the check below. */
+  for await (const chunk of nodeReq as AsyncIterable<unknown>) {
+    if (chunk instanceof Uint8Array) {
+      yield chunk;
+    }
+  }
+}
+
+/**
+ * The URL of a request, as `Bun.serve` reports it: the Host's origin followed by the target's path.
+ *
+ * The target is never resolved against the origin as a relative reference. `//home/me/site.json` is
+ * how the Studio asks for a file under an absolute project root, and as a reference it is
+ * scheme-relative: `new URL()` reads `home` as the host and drops it from the path, so every
+ * component and image of such a project answered 404 from the desktop backend. An absolute-form
+ * target (`http://other/x`) keeps only its path and query, as Bun keeps them.
+ */
+export function requestUrl(target: string | undefined, origin: string): URL {
+  const path = target ?? "/";
+  if (path.startsWith("/")) {
+    return new URL(`${origin}${path}`);
+  }
+  const absolute = new URL(path, origin);
+  return new URL(`${origin}${absolute.pathname}${absolute.search}`);
+}
+
+/** The `Request` for a Node request, with a signal that aborts when the client disconnects. */
+function toRequest(nodeReq: IncomingMessage, origin: string, signal?: AbortSignal): Request {
+  const headers = new Headers();
+  for (let i = 0; i < nodeReq.rawHeaders.length; i += 2) {
+    headers.append(nodeReq.rawHeaders[i]!, nodeReq.rawHeaders[i + 1]!);
+  }
+  const { host } = nodeReq.headers;
+  const url = requestUrl(nodeReq.url, host ? `http://${host}` : origin);
+  const method = nodeReq.method ?? "GET";
+  const init: RequestInit & { duplex?: "half" } = { headers, method };
+  if (signal) {
+    init.signal = signal;
+  }
+  if (!BODYLESS_METHODS.has(method)) {
+    const source = chunksOf(nodeReq);
+    init.body = new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        const next = await source.next();
+        if (next.done === true) {
+          controller.close();
+        } else {
+          controller.enqueue(next.value);
+        }
+      },
+    });
+    init.duplex = "half";
+  }
+  return new Request(url, init);
+}
+
+/** Resolve when `res` can take more, or has closed and never will. */
+function drained(res: ServerResponse): Promise<void> {
+  return new Promise((resolve) => {
+    const done = (): void => {
+      res.off("drain", done);
+      res.off("close", done);
+      resolve();
+    };
+    res.on("drain", done);
+    res.on("close", done);
+  });
+}
+
+/** Write `response` to `res`, streaming its body and stopping when the client goes away. */
+async function writeResponse(
+  response: Response,
+  res: ServerResponse,
+  method: string,
+): Promise<void> {
+  const headers: Record<string, string | string[]> = {};
+  for (const [key, value] of response.headers) {
+    if (key !== "set-cookie") {
+      headers[key] = value;
+    }
+  }
+  const cookies = response.headers.getSetCookie();
+  if (cookies.length > 0) {
+    headers["set-cookie"] = cookies;
+  }
+  res.writeHead(response.status, response.statusText, headers);
+  if (!response.body || method === "HEAD") {
+    res.end();
+    return;
+  }
+  const reader = response.body.getReader();
+  const cancel = (): void => {
+    void reader.cancel().catch(() => {});
+  };
+  res.once("close", cancel);
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done || res.destroyed) {
+        break;
+      }
+      // `flushHeaders` is implied by the first write; each chunk goes out as it arrives.
+      if (!res.write(value)) {
+        await drained(res);
+      }
+    }
+  } catch {
+    // The body's producer failed or was cancelled; what was sent is all the client gets.
+  } finally {
+    res.off("close", cancel);
+    res.end();
+  }
+}
+
+/** Answer an upgrade request the handler refused (or never accepted) with a plain HTTP response. */
+async function rejectUpgrade(socket: Duplex, response: Response): Promise<void> {
+  const body = Buffer.from(await response.arrayBuffer());
+  const lines = [`HTTP/1.1 ${response.status} ${response.statusText || "Error"}`];
+  for (const [key, value] of response.headers) {
+    lines.push(`${key}: ${value}`);
+  }
+  lines.push(`content-length: ${body.length}`, "connection: close", "", "");
+  const head = Buffer.from(lines.join("\r\n"));
+  socket.end(Buffer.concat([head, body]));
+}
+
+/** A frame as the handler receives it: text as a string, binary as one Buffer. */
+function frameOf(data: RawData, isBinary: boolean): string | Buffer {
+  const bytes = Array.isArray(data)
+    ? Buffer.concat(data)
+    : Buffer.isBuffer(data)
+      ? data
+      : Buffer.from(data);
+  return isBinary ? bytes : bytes.toString("utf8");
+}
+
+/** Start a server and resolve once it is listening. */
+export async function serve<Data = undefined>(
+  options: ServeOptions<Data>,
+): Promise<ServeServer<Data>> {
+  const hostname = options.hostname ?? "0.0.0.0";
+  const handler = options.websocket;
+  const pending = new WeakMap<Request, PendingUpgrade>();
+  const sockets = new Set<WebSocket>();
+  const wss = new WebSocketServer({
+    handleProtocols: (_protocols, nodeReq) => echoedProtocol.get(nodeReq) ?? false,
+    noServer: true,
+  });
+
+  const http = createServer();
+  if (options.idleTimeout !== undefined) {
+    http.setTimeout(options.idleTimeout * 1000, (socket) => socket.destroy());
+  }
+
+  let origin = "";
+  let url = new URL("http://localhost/");
+
+  const server: ServeServer<Data> = {
+    get port() {
+      return Number(url.port);
+    },
+    get url() {
+      return url;
+    },
+    upgrade(req, { data, headers }) {
+      const upgrade = pending.get(req);
+      if (!upgrade || upgrade.taken) {
+        return false;
+      }
+      upgrade.taken = true;
+      const protocol = headers?.["Sec-WebSocket-Protocol"];
+      if (protocol !== undefined) {
+        echoedProtocol.set(upgrade.nodeReq, protocol);
+      }
+      wss.handleUpgrade(upgrade.nodeReq, upgrade.socket, upgrade.head, (ws) => {
+        sockets.add(ws);
+        const socket: ServeSocket<Data> = {
+          data,
+          send: (message) => ws.send(message),
+          close: (code, reason) => ws.close(code, reason),
+        };
+        ws.on("message", (raw, isBinary) => {
+          void handler?.message?.(socket, frameOf(raw, isBinary));
+        });
+        ws.on("close", (code, reason) => {
+          sockets.delete(ws);
+          handler?.close?.(socket, code, reason.toString("utf8"));
+        });
+        handler?.open?.(socket);
+      });
+      return true;
+    },
+    stop(closeActiveConnections) {
+      return new Promise<void>((resolve) => {
+        http.close(() => resolve());
+        if (closeActiveConnections) {
+          http.closeAllConnections();
+          for (const ws of sockets) {
+            ws.terminate();
+          }
+        }
+      });
+    },
+  };
+
+  http.on("request", (nodeReq, res) => {
+    const controller = new AbortController();
+    res.once("close", () => {
+      if (!res.writableFinished) {
+        controller.abort();
+      }
+    });
+    const method = nodeReq.method ?? "GET";
+    void (async () => {
+      let response: Response | undefined;
+      try {
+        response = await options.fetch(toRequest(nodeReq, origin, controller.signal), server);
+      } catch (error) {
+        console.error("[serve]", error);
+        response = new Response("Internal Server Error", { status: 500 });
+      }
+      await writeResponse(
+        response ?? new Response("Internal Server Error", { status: 500 }),
+        res,
+        method,
+      );
+    })();
+  });
+
+  http.on("upgrade", (nodeReq, socket, head) => {
+    const req = toRequest(nodeReq, origin);
+    const upgrade: PendingUpgrade = { head, nodeReq, socket, taken: false };
+    pending.set(req, upgrade);
+    void (async () => {
+      let response: Response | undefined;
+      try {
+        response = await options.fetch(req, server);
+      } catch (error) {
+        console.error("[serve]", error);
+        response = new Response("Internal Server Error", { status: 500 });
+      }
+      if (!upgrade.taken) {
+        await rejectUpgrade(socket, response ?? new Response("Upgrade failed", { status: 400 }));
+      }
+    })();
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    http.once("error", reject);
+    http.listen(options.port ?? 0, hostname, () => {
+      http.off("error", reject);
+      resolve();
+    });
+  });
+  const address = http.address();
+  /* SAFETY: a TCP listener's `address()` is an `AddressInfo`; it is a string only for a pipe or a
+     Unix socket, which this function never binds. */
+  const { port } = address as { port: number };
+  const host =
+    hostname === "0.0.0.0" || hostname === "::"
+      ? "localhost"
+      : hostname.includes(":")
+        ? `[${hostname}]`
+        : hostname;
+  origin = `http://${host}:${port}`;
+  url = new URL(`${origin}/`);
+  return server;
+}

package/src/serve.ts

@@ -0,0 +1,67 @@
+/**
+ * The HTTP + WebSocket server surface the backend's servers are written against.
+ *
+ * It is the part of `Bun.serve` they use and nothing more: a Fetch-API handler that may upgrade, a
+ * bound port and URL, `stop()`, an idle timeout, and a socket's `data`, `send` and `close`. Two
+ * implementations answer it, selected at resolution time by the `#serve` import's conditions
+ * (Node's conditional exports): `serve.bun.ts` passes through to `Bun.serve` under Bun, and
+ * `serve.node.ts` is `node:http` plus `ws` everywhere else, which is the packaged desktop backend
+ * (specs/desktop.md §7.1). A bundle built for Node therefore contains no Bun code at all.
+ *
+ * `serve()` resolves once the server is listening, because Node binds asynchronously: a port read
+ * straight after `listen()` is not there yet.
+ *
+ * @docs studio/desktop
+ */
+
+/** One upgraded WebSocket connection, carrying the `data` its upgrade attached. */
+export interface ServeSocket<Data> {
+  readonly data: Data;
+  /** Send a text frame (a string) or a binary frame (bytes). A closed socket drops the frame. */
+  send: (message: string | Uint8Array) => void;
+  close: (code?: number, reason?: string) => void;
+}
+
+/** Headers an upgrade may add to its 101 response. */
+export interface UpgradeHeaders {
+  "Sec-WebSocket-Protocol"?: string;
+}
+
+/** The running server, as a fetch handler sees it and as its owner stops it. */
+export interface ServeServer<Data> {
+  readonly port: number;
+  /** The origin the server answers on, with a trailing `/` path. */
+  readonly url: URL;
+  /**
+   * Accept a WebSocket upgrade for `req`, attaching `data` to the socket. True when the upgrade was
+   * taken, in which case the handler returns `undefined`.
+   *
+   * The 101 response's only negotiable header is the subprotocol the server echoes (RFC 6455
+   * §4.2.2), so that is the only one this accepts. Under Bun the `ws` package is Bun's own shim,
+   * which emits no `headers` event, so a wider set could not be honoured on both runtimes.
+   */
+  upgrade: (req: Request, options: { data: Data; headers?: UpgradeHeaders }) => boolean;
+  /** Stop listening; with `closeActiveConnections`, also drop open requests and sockets. */
+  stop: (closeActiveConnections?: boolean) => Promise<void>;
+}
+
+/** Callbacks for upgraded sockets. A text frame arrives as a string, a binary one as a Buffer. */
+export interface ServeWebSocketHandler<Data> {
+  open?: (ws: ServeSocket<Data>) => void;
+  message?: (ws: ServeSocket<Data>, message: string | Buffer) => void | Promise<void>;
+  close?: (ws: ServeSocket<Data>, code: number, reason: string) => void;
+}
+
+export interface ServeOptions<Data> {
+  /** Interface to bind; `0.0.0.0` when absent. */
+  hostname?: string;
+  /** Port to bind; `0` picks a free one. */
+  port?: number;
+  /** Seconds a connection may sit without traffic before it is closed. */
+  idleTimeout?: number;
+  fetch: (
+    req: Request,
+    server: ServeServer<Data>,
+  ) => Response | undefined | Promise<Response | undefined>;
+  websocket?: ServeWebSocketHandler<Data>;
+}