@jxsuite/server 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
+    "@jxsuite/collab": "^0.2.0",
     "@jxsuite/compiler": "^0.35.0",
     "@jxsuite/create": "^0.36.0",
     "@jxsuite/import": "^0.35.1",

package/src/collab.ts

@@ -0,0 +1,250 @@
+/**
+ * Collab.ts — the dev server's realtime co-editing endpoint (`/__studio/collab`): the reference
+ * implementation of the Jx collab wire contract, built on `@jxsuite/collab/room`.
+ *
+ * Rooms are keyed by server-root-relative path; a room's Y.Text source seeds from the file on disk
+ * and writes back (debounced) so every non-collab consumer — preview, live reload, plain editors —
+ * keeps working off the real file. Genuinely external file changes (not our own write-back echo)
+ * bump the doc's epoch and reset subscribers, per the contract. No persistence beyond the files
+ * themselves: this is deliberately a reference implementation.
+ */
+
+import { resolve } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { colorForKey } from "@jxsuite/collab/awareness-types";
+import { createCollabHost } from "@jxsuite/collab/room";
+import { assertAccessible } from "./studio-api";
+import type { ServerWebSocket, WebSocketHandler } from "bun";
+import type { HostConnection } from "@jxsuite/collab/room";
+
+const WRITE_BACK_DEBOUNCE_MS = 800;
+const EMPTY_ROOM_GRACE_MS = 30_000;
+
+const BINARY_EXTENSIONS = new Set([
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "avif",
+  "ico",
+  "bmp",
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "eot",
+  "mp3",
+  "mp4",
+  "webm",
+  "wav",
+  "ogg",
+  "pdf",
+  "zip",
+  "gz",
+]);
+
+function isBinaryPath(path: string): boolean {
+  const dot = path.lastIndexOf(".");
+  return dot !== -1 && BINARY_EXTENSIONS.has(path.slice(dot + 1).toLowerCase());
+}
+
+export interface CollabSocketData {
+  connection: HostConnection | null;
+}
+
+export interface CollabRegistry {
+  /**
+   * Handle a request to /__studio/collab: WebSocket upgrades become collab connections; a plain GET
+   * answers the capability probe. Returns undefined when the upgrade was accepted (Bun sends the
+   * 101 itself).
+   */
+  handleRequest: (
+    req: Request,
+    server: { upgrade: (req: Request, opts: { data: CollabSocketData }) => boolean },
+  ) => Response | undefined;
+  /** Bun.serve websocket handlers backing the upgraded connections. */
+  websocket: WebSocketHandler<CollabSocketData>;
+  /** Watcher hook: a file changed on disk (absolute path). Echoes of our write-back are ignored. */
+  handleExternalChange: (absPath: string) => void;
+  /** Flush pending write-backs and tear everything down. */
+  stop: () => Promise<void>;
+}
+
+export function createCollabRegistry(opts: {
+  absRoot: string;
+  activeProjectRoot: () => string | null;
+}): CollabRegistry {
+  const { absRoot } = opts;
+  let connectionCounter = 0;
+  let stopped = false;
+
+  const writeTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  const destroyTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** Content we last wrote (or are about to write) per path — the watcher-echo signature. */
+  const lastWritten = new Map<string, string>();
+
+  const absPathFor = (relPath: string): string => {
+    const abs = resolve(absRoot, relPath);
+    assertAccessible(abs, absRoot, opts.activeProjectRoot());
+    return abs;
+  };
+
+  const relPathFor = (absPath: string): string => {
+    const rel = absPath.startsWith(absRoot)
+      ? absPath.slice(absRoot.length).replace(/^\/+/, "")
+      : absPath;
+    return rel.replaceAll("\\", "/");
+  };
+
+  const persist = async (path: string): Promise<void> => {
+    const source = host.sourceOf(path);
+    if (source === null) {
+      return;
+    }
+    if (lastWritten.get(path) === source) {
+      return;
+    }
+    lastWritten.set(path, source);
+    try {
+      await writeFile(absPathFor(path), source, "utf8");
+    } catch {
+      // Disk write failures leave the room live; the next change retries.
+    }
+  };
+
+  const host = createCollabHost({
+    loadSource: async (path) => {
+      try {
+        return await readFile(absPathFor(path), "utf8");
+      } catch {
+        return null;
+      }
+    },
+    onEmpty: (path) => {
+      const existing = destroyTimers.get(path);
+      if (existing) {
+        clearTimeout(existing);
+      }
+      destroyTimers.set(
+        path,
+        setTimeout(() => {
+          destroyTimers.delete(path);
+          void persist(path).then(() => host.destroyRoomIfEmpty(path));
+        }, EMPTY_ROOM_GRACE_MS),
+      );
+    },
+    onFlush: (path) => {
+      const timer = writeTimers.get(path);
+      if (timer) {
+        clearTimeout(timer);
+        writeTimers.delete(path);
+      }
+      return persist(path);
+    },
+    onSourceChange: (path) => {
+      const existing = writeTimers.get(path);
+      if (existing) {
+        clearTimeout(existing);
+      }
+      writeTimers.set(
+        path,
+        setTimeout(() => {
+          writeTimers.delete(path);
+          void persist(path);
+        }, WRITE_BACK_DEBOUNCE_MS),
+      );
+    },
+    rejectPath: (path) => {
+      if (isBinaryPath(path)) {
+        return "binary-file";
+      }
+      try {
+        absPathFor(path);
+        return null;
+      } catch {
+        return "content-not-loaded";
+      }
+    },
+  });
+
+  return {
+    handleExternalChange(absPath) {
+      const path = relPathFor(absPath);
+      if (host.subscriberCount(path) === 0 && host.sourceOf(path) === null) {
+        return;
+      }
+      void (async () => {
+        let content: string | null = null;
+        try {
+          content = await readFile(absPathFor(path), "utf8");
+        } catch {
+          content = null;
+        }
+        // Our own write-back (or a no-op save) is not an external change.
+        if (
+          content !== null &&
+          (content === lastWritten.get(path) || content === host.sourceOf(path))
+        ) {
+          return;
+        }
+        host.resetDoc(path);
+      })();
+    },
+
+    handleRequest(req, server) {
+      if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+        const upgraded = server.upgrade(req, { data: { connection: null } });
+        return upgraded ? undefined : new Response("Upgrade failed", { status: 400 });
+      }
+      return Response.json({ collab: true, version: 1 });
+    },
+
+    async stop() {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      for (const timer of writeTimers.values()) {
+        clearTimeout(timer);
+      }
+      for (const timer of destroyTimers.values()) {
+        clearTimeout(timer);
+      }
+      const flushes: Promise<void>[] = [];
+      for (const path of writeTimers.keys()) {
+        flushes.push(persist(path));
+      }
+      writeTimers.clear();
+      destroyTimers.clear();
+      await Promise.all(flushes);
+      host.destroy();
+    },
+
+    websocket: {
+      close(ws: ServerWebSocket<CollabSocketData>) {
+        ws.data.connection?.close();
+        ws.data.connection = null;
+      },
+      message(ws: ServerWebSocket<CollabSocketData>, message: string | Buffer) {
+        if (typeof message === "string") {
+          return;
+        }
+        ws.data.connection?.handleMessage(new Uint8Array(message));
+      },
+      open(ws: ServerWebSocket<CollabSocketData>) {
+        connectionCounter += 1;
+        const login = `local-${connectionCounter}`;
+        ws.data.connection = host.connect(
+          {
+            close: () => ws.close(),
+            send: (data) => {
+              ws.send(data);
+            },
+          },
+          { color: colorForKey(login), login, permission: "write" },
+        );
+      },
+    },
+  };
+}

package/src/server.ts

@@ -15,6 +15,7 @@
 
 import { join, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
+import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleResolve, handleServerFunction } from "./resolve.ts";
 import { assertAccessible, handleStudioApi } from "./studio-api.ts";
@@ -204,10 +205,12 @@ export async function createDevServer(options: {
   // ─── File watcher + SSE ─────────────────────────────────────────────────────
 
   let handleSSE = null;
+  let fsWatcher: ReturnType<typeof createWatcher>["watcher"] | null = null;
   if (watch !== false) {
     const watchOpts = typeof watch === "object" ? watch : {};
     const watcher = createWatcher(absRoot, builds, watchOpts);
     ({ handleSSE } = watcher);
+    fsWatcher = watcher.watcher;
   }
 
   // Bundle cache for npm packages (bare specifier → bundled JS)
@@ -224,10 +227,24 @@ export async function createDevServer(options: {
   // Active studio project root (set via /__studio/activate, used for static file fallback)
   let activeProjectRoot: string | null = null;
 
+  // ─── Realtime co-editing (/__studio/collab) ─────────────────────────────────
+
+  // Created unconditionally (it is inert until an upgrade) so Bun.serve always has real
+  // Websocket handlers; the route below is what gates the capability on enableStudio.
+  const collabRegistry = createCollabRegistry({
+    absRoot,
+    activeProjectRoot: () => activeProjectRoot,
+  });
+  if (enableStudio && fsWatcher) {
+    fsWatcher.on("change", (changedPath: string) => {
+      collabRegistry.handleExternalChange(resolve(absRoot, changedPath));
+    });
+  }
+
   // ─── HTTP server ────────────────────────────────────────────────────────────
 
   const server = Bun.serve({
-    async fetch(req) {
+    async fetch(req, bunServer) {
       const url = new URL(req.url);
       let path = decodeURIComponent(url.pathname);
       if (path.endsWith("/")) {
@@ -253,6 +270,11 @@ export async function createDevServer(options: {
 
       // Studio filesystem API
       if (enableStudio && path.startsWith("/__studio/")) {
+        // Realtime co-editing: WebSocket upgrade or capability probe
+        if (path === "/__studio/collab") {
+          return collabRegistry.handleRequest(req, bunServer);
+        }
+
         // Activate project — tells the server which project root to use for static file fallback
         if (path === "/__studio/activate" && req.method === "POST") {
           const body = (await req.json()) as { root?: string };
@@ -380,6 +402,7 @@ export async function createDevServer(options: {
     // Keep SSE connections alive — heartbeats are every 15 s, and AI streaming can take
     // 30+ s. The default 10 s idleTimeout kills them prematurely.
     idleTimeout: 120,
+    websocket: collabRegistry.websocket,
   });
 
   console.log(`\n@jxsuite/server listening on http://localhost:${server.port}`);