feat(discovery): add standalone bootstrap server

Author: marcus-pousette

docs/BENCHMARKS.md

@@ -306,6 +306,9 @@ This is the benchmark to use when you want a direct before/after comparison betw
 Use `benchmark:sync:bootstrap` when you want to isolate the one-time discovery
 layer from the steady-state sync path.
 
+The benchmark target can be a standalone bootstrap server such as
+`@treecrdt/discovery-server-node`, not just a colocated sync-server route.
+
 It measures:
 
 - `resolveSamplesMs`: `GET /resolve-doc?docId=...`

examples/playground/README.md

@@ -3,6 +3,7 @@
 A small, self-contained demo that exercises the `@treecrdt/wa-sqlite` adapter inside a Vite + React + Tailwind UI. It runs the TreeCRDT SQLite extension in wa-sqlite and lets you insert, move, and delete nodes in an expandable tree while watching the underlying operation log.
 
 ## Features
+
 - Insert children under any node, reorder siblings (up/down), move nodes back to the root, or delete them (root is protected).
 - Collapsible tree with per-node controls and a composer form to target any parent.
 - Live CRDT operation log with lamport/counter metadata.
@@ -11,6 +12,7 @@ A small, self-contained demo that exercises the `@treecrdt/wa-sqlite` adapter in
 - Optional auth/ACL demo (COSE_Sign1 + CWT subtree capabilities) with invite links, per-op signatures, and a pending-op inspector.
 
 ## Running locally
+
 ```bash
 pnpm install --filter @treecrdt/playground
 pnpm -C examples/playground dev
@@ -27,14 +29,16 @@ pnpm build
 pnpm sync-server:postgres:db:start
 # Start the TreeCRDT sync server on ws://localhost:8787 using that Postgres DB.
 pnpm sync-server:postgres:local
+# Start the standalone bootstrap server on http://localhost:8788.
+pnpm discovery-server:local
 # Start the playground UI.
 pnpm -C examples/playground dev
 ```
 
 Then in the playground:
 
 - Open the `Connections` panel
-- Paste `ws://localhost:8787` into `Remote sync server`
+- Paste `http://localhost:8788` into `Remote sync / bootstrap`
 - Leave mode as `Hybrid`, or switch to `Remote server` if you want to disable local tab sync
 
 ## Public sync server
@@ -49,6 +53,9 @@ The playground will call `/resolve-doc` once, cache the returned websocket
 attachment, and then connect directly to the resolved `wss://.../sync`
 endpoint.
 
+If you want to skip bootstrap entirely, you can still paste a direct websocket
+endpoint such as `ws://localhost:8787`.
+
 `pnpm sync-server:postgres:db:start` starts a disposable local Postgres at:
 
 ```bash
@@ -95,6 +102,7 @@ pnpm --filter @treecrdt/wa-sqlite-vendor rebuild
 The example does not depend on the npm `wa-sqlite` package; it consumes the repo's git submodule build directly via the copy step above.
 
 ## Building / deploying to GitHub Pages
+
 ```bash
 pnpm -C examples/playground build     # outputs to dist/
 pnpm -C examples/playground deploy    # pushes dist/ via gh-pages

examples/playground/src/playground/components/PeersPanel.tsx

@@ -1,44 +1,44 @@
-import React from "react";
-import { MdCheckCircle, MdCloudOff, MdCloudQueue, MdErrorOutline, MdSync } from "react-icons/md";
+import React from 'react';
+import { MdCheckCircle, MdCloudOff, MdCloudQueue, MdErrorOutline, MdSync } from 'react-icons/md';
 
-import { PLAYGROUND_PUBLIC_DISCOVERY_URL } from "../constants";
-import type { PeerInfo, RemoteSyncStatus, SyncTransportMode } from "../types";
+import { PLAYGROUND_PUBLIC_DISCOVERY_URL } from '../constants';
+import type { PeerInfo, RemoteSyncStatus, SyncTransportMode } from '../types';
 
 function formatPeerId(id: string): string {
-  if (id.startsWith("remote:")) return `remote(${id.slice("remote:".length)})`;
+  if (id.startsWith('remote:')) return `remote(${id.slice('remote:'.length)})`;
   return id.length > 18 ? `${id.slice(0, 8)}…${id.slice(-6)}` : id;
 }
 
 function transportModeButtonClass(active: boolean): string {
   return active
-    ? "border-accent bg-accent/15 text-white"
-    : "border-slate-700 bg-slate-900/70 text-slate-300 hover:border-slate-500 hover:text-white";
+    ? 'border-accent bg-accent/15 text-white'
+    : 'border-slate-700 bg-slate-900/70 text-slate-300 hover:border-slate-500 hover:text-white';
 }
 
 function remoteStatusTone(status: RemoteSyncStatus): string {
   switch (status.state) {
-    case "connected":
-      return "border-emerald-500/40 bg-emerald-500/10 text-emerald-100";
-    case "connecting":
-      return "border-sky-500/40 bg-sky-500/10 text-sky-100";
-    case "disabled":
-      return "border-slate-700 bg-slate-900/70 text-slate-400";
-    case "missing_url":
-      return "border-amber-500/30 bg-amber-500/10 text-amber-100";
-    case "invalid":
-    case "error":
-      return "border-rose-500/40 bg-rose-500/10 text-rose-100";
+    case 'connected':
+      return 'border-emerald-500/40 bg-emerald-500/10 text-emerald-100';
+    case 'connecting':
+      return 'border-sky-500/40 bg-sky-500/10 text-sky-100';
+    case 'disabled':
+      return 'border-slate-700 bg-slate-900/70 text-slate-400';
+    case 'missing_url':
+      return 'border-amber-500/30 bg-amber-500/10 text-amber-100';
+    case 'invalid':
+    case 'error':
+      return 'border-rose-500/40 bg-rose-500/10 text-rose-100';
   }
 }
 
 function RemoteStatusIcon({ status }: { status: RemoteSyncStatus }) {
-  if (status.state === "connected") {
+  if (status.state === 'connected') {
     return <MdCheckCircle className="text-[14px]" />;
   }
-  if (status.state === "connecting") {
+  if (status.state === 'connecting') {
     return <MdSync className="text-[14px]" />;
   }
-  if (status.state === "disabled") {
+  if (status.state === 'disabled') {
     return <MdCloudOff className="text-[14px]" />;
   }
   return <MdErrorOutline className="text-[14px]" />;
@@ -63,7 +63,7 @@ export function PeersPanel({
   remoteSyncStatus: RemoteSyncStatus;
   peers: PeerInfo[];
 }) {
-  const requiresRemoteUrl = syncTransportMode !== "local";
+  const requiresRemoteUrl = syncTransportMode !== 'local';
   const hasRemoteUrl = syncServerUrl.trim().length > 0;
 
   return (
@@ -73,74 +73,86 @@ export function PeersPanel({
     >
       <div className="flex flex-wrap items-start justify-between gap-3">
         <div>
-          <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">Connections</div>
+          <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">
+            Connections
+          </div>
           <div className="mt-1 max-w-xl text-[11px] text-slate-400">
-            Choose how this tab syncs. Local tabs use `BroadcastChannel`. Remote transport can use either a direct
-            websocket sync endpoint or an HTTP bootstrap endpoint.
+            Choose how this tab syncs. Local tabs use `BroadcastChannel`. Remote transport can use
+            either a direct websocket sync endpoint or a separate HTTP bootstrap endpoint.
           </div>
         </div>
         <button
           className={`flex h-8 items-center gap-2 rounded-lg border px-3 text-[11px] font-semibold transition ${
             online
-              ? "border-slate-700 bg-slate-800/70 text-slate-200 hover:border-accent hover:text-white"
-              : "border-amber-500/60 bg-amber-500/10 text-amber-100 hover:border-amber-400"
+              ? 'border-slate-700 bg-slate-800/70 text-slate-200 hover:border-accent hover:text-white'
+              : 'border-amber-500/60 bg-amber-500/10 text-amber-100 hover:border-amber-400'
           }`}
           onClick={() => setOnline((v) => !v)}
           type="button"
-          title={online ? "Pause sync activity" : "Resume sync activity"}
+          title={online ? 'Pause sync activity' : 'Resume sync activity'}
         >
-          {online ? <MdCloudQueue className="text-[16px]" /> : <MdCloudOff className="text-[16px]" />}
-          <span>{online ? "Sync enabled" : "Sync paused"}</span>
+          {online ? (
+            <MdCloudQueue className="text-[16px]" />
+          ) : (
+            <MdCloudOff className="text-[16px]" />
+          )}
+          <span>{online ? 'Sync enabled' : 'Sync paused'}</span>
         </button>
       </div>
 
       <div className="mt-3 rounded-lg border border-slate-800/70 bg-slate-950/30 p-2">
-        <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">Transport</div>
+        <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">
+          Transport
+        </div>
         <div className="mt-2 flex flex-wrap gap-2">
           <button
             type="button"
-            className={`rounded-md border px-3 py-1.5 text-[11px] font-semibold transition ${transportModeButtonClass(syncTransportMode === "local")}`}
-            onClick={() => setSyncTransportMode("local")}
+            className={`rounded-md border px-3 py-1.5 text-[11px] font-semibold transition ${transportModeButtonClass(syncTransportMode === 'local')}`}
+            onClick={() => setSyncTransportMode('local')}
           >
             Local tabs
           </button>
           <button
             type="button"
-            className={`rounded-md border px-3 py-1.5 text-[11px] font-semibold transition ${transportModeButtonClass(syncTransportMode === "remote")}`}
-            onClick={() => setSyncTransportMode("remote")}
+            className={`rounded-md border px-3 py-1.5 text-[11px] font-semibold transition ${transportModeButtonClass(syncTransportMode === 'remote')}`}
+            onClick={() => setSyncTransportMode('remote')}
           >
             Remote server
           </button>
           <button
             type="button"
-            className={`rounded-md border px-3 py-1.5 text-[11px] font-semibold transition ${transportModeButtonClass(syncTransportMode === "hybrid")}`}
-            onClick={() => setSyncTransportMode("hybrid")}
+            className={`rounded-md border px-3 py-1.5 text-[11px] font-semibold transition ${transportModeButtonClass(syncTransportMode === 'hybrid')}`}
+            onClick={() => setSyncTransportMode('hybrid')}
           >
             Hybrid
           </button>
         </div>
         <div className="mt-2 text-[11px] text-slate-500">
-          {syncTransportMode === "local" && "Only same-origin tabs in this browser will sync."}
-          {syncTransportMode === "remote" && "Only the configured websocket sync server will be used."}
-          {syncTransportMode === "hybrid" && "Use both same-origin tabs and the configured websocket sync server."}
+          {syncTransportMode === 'local' && 'Only same-origin tabs in this browser will sync.'}
+          {syncTransportMode === 'remote' &&
+            'Only the configured remote websocket or bootstrap endpoint will be used.'}
+          {syncTransportMode === 'hybrid' &&
+            'Use both same-origin tabs and the configured remote websocket or bootstrap endpoint.'}
         </div>
       </div>
 
       <div className="mt-3 rounded-lg border border-slate-800/70 bg-slate-950/30 p-2">
         <div className="flex items-center justify-between gap-2">
-          <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">Remote sync server</div>
+          <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">
+            Remote sync / bootstrap
+          </div>
           <div
             className={`inline-flex items-center gap-1.5 rounded-full border px-2 py-1 text-[10px] font-semibold ${remoteStatusTone(remoteSyncStatus)}`}
             title={remoteSyncStatus.detail}
           >
             <RemoteStatusIcon status={remoteSyncStatus} />
             <span>
-              {remoteSyncStatus.state === "connected" && "Connected"}
-              {remoteSyncStatus.state === "connecting" && "Connecting"}
-              {remoteSyncStatus.state === "disabled" && "Inactive"}
-              {remoteSyncStatus.state === "missing_url" && "Missing URL"}
-              {remoteSyncStatus.state === "invalid" && "Invalid URL"}
-              {remoteSyncStatus.state === "error" && "Unreachable"}
+              {remoteSyncStatus.state === 'connected' && 'Connected'}
+              {remoteSyncStatus.state === 'connecting' && 'Connecting'}
+              {remoteSyncStatus.state === 'disabled' && 'Inactive'}
+              {remoteSyncStatus.state === 'missing_url' && 'Missing URL'}
+              {remoteSyncStatus.state === 'invalid' && 'Invalid URL'}
+              {remoteSyncStatus.state === 'error' && 'Unreachable'}
             </span>
           </div>
         </div>
@@ -151,20 +163,20 @@ export function PeersPanel({
             onChange={(event) => {
               const next = event.target.value;
               setSyncServerUrl(next);
-              if (syncTransportMode === "local" && next.trim().length > 0) {
-                setSyncTransportMode("hybrid");
+              if (syncTransportMode === 'local' && next.trim().length > 0) {
+                setSyncTransportMode('hybrid');
               }
             }}
-            placeholder={`${PLAYGROUND_PUBLIC_DISCOVERY_URL} or ws://localhost:8787/sync`}
+            placeholder={`${PLAYGROUND_PUBLIC_DISCOVERY_URL} or ws://localhost:8787`}
             spellCheck={false}
           />
           <button
             type="button"
             className="rounded-md border border-slate-700 px-2 py-1.5 text-[11px] font-semibold text-slate-300 transition hover:border-slate-500 hover:text-white"
             onClick={() => {
               setSyncServerUrl(PLAYGROUND_PUBLIC_DISCOVERY_URL);
-              if (syncTransportMode === "local") {
-                setSyncTransportMode("hybrid");
+              if (syncTransportMode === 'local') {
+                setSyncTransportMode('hybrid');
               }
             }}
             title="Use the public emhub.net bootstrap endpoint"
@@ -174,7 +186,7 @@ export function PeersPanel({
           <button
             type="button"
             className="rounded-md border border-slate-700 px-2 py-1.5 text-[11px] font-semibold text-slate-300 transition hover:border-slate-500 hover:text-white disabled:opacity-50"
-            onClick={() => setSyncServerUrl("")}
+            onClick={() => setSyncServerUrl('')}
             disabled={syncServerUrl.trim().length === 0}
             title="Clear remote sync server URL"
           >
@@ -189,14 +201,18 @@ export function PeersPanel({
 
       <div className="mt-3 rounded-lg border border-slate-800/70 bg-slate-950/30 p-2">
         <div className="flex items-center justify-between gap-2">
-          <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">Connected peers</div>
+          <div className="text-[10px] font-semibold uppercase tracking-wide text-slate-400">
+            Connected peers
+          </div>
           <div className="text-[10px] text-slate-500">{peers.length}</div>
         </div>
         <div className="mt-2 max-h-32 overflow-auto pr-1">
           {peers.map((p) => (
             <div key={p.id} className="flex items-center justify-between gap-2 py-1">
               <span className="font-mono text-slate-200">{formatPeerId(p.id)}</span>
-              <span className="text-[10px] text-slate-500">{Math.max(0, Date.now() - p.lastSeen)}ms</span>
+              <span className="text-[10px] text-slate-500">
+                {Math.max(0, Date.now() - p.lastSeen)}ms
+              </span>
             </div>
           ))}
           {peers.length === 0 && (

package.json

@@ -50,6 +50,8 @@
     "benchmark:web": "pnpm -C packages/treecrdt-wa-sqlite/e2e run bench",
     "test": "pnpm run test:browser && pnpm run test:native-node",
     "playground": "pnpm --filter @treecrdt/playground dev",
+    "discovery-server": "pnpm --filter @treecrdt/discovery-server-node dev",
+    "discovery-server:local": "TREECRDT_DISCOVERY_PUBLIC_HTTP_BASE_URL=http://localhost:8788 TREECRDT_DISCOVERY_PUBLIC_WS_BASE_URL=ws://localhost:8787 pnpm --filter @treecrdt/discovery-server-node dev",
     "sync-server:postgres:setup": "pnpm --filter @treecrdt/postgres-napi... --filter @treecrdt/sync-server-postgres-node... run build",
     "sync-server:postgres": "pnpm --filter @treecrdt/sync-server-postgres-node dev",
     "sync-server:postgres:local": "node scripts/run-sync-server-postgres-local.mjs",

packages/discovery-server-node/README.md

@@ -0,0 +1,37 @@
+# TreeCRDT Discovery Server (Node)
+
+Small standalone HTTP bootstrap service for `resolveDoc`.
+
+It is intentionally separate from the websocket sync server:
+
+- discovery/bootstrap happens once at connect time
+- clients cache the returned attachment plan
+- steady-state sync then talks directly to the resolved `ws://` or `wss://` endpoint
+
+## Run locally
+
+From the repo root:
+
+```sh
+pnpm discovery-server:local
+```
+
+This starts a bootstrap server on `http://localhost:8788` that advertises:
+
+- bootstrap base: `http://localhost:8788`
+- sync websocket base: `ws://localhost:8787`
+
+## Environment
+
+- `HOST` (default: `0.0.0.0`)
+- `PORT` (default: `8788`)
+- `TREECRDT_DISCOVERY_RESOLVE_PATH` (default: `/resolve-doc`)
+- `TREECRDT_DISCOVERY_PUBLIC_HTTP_BASE_URL` (optional absolute HTTP base URL advertised to clients)
+- `TREECRDT_DISCOVERY_PUBLIC_WS_BASE_URL` (optional absolute websocket base URL advertised to clients)
+- `TREECRDT_DISCOVERY_CACHE_TTL_MS` (default: `3600000`)
+
+## Endpoints
+
+- `GET /health`
+- `GET /status`
+- `GET /resolve-doc?docId=YOUR_DOC_ID`

packages/discovery-server-node/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@treecrdt/discovery-server-node",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "pnpm --filter @treecrdt/discovery-server-node^... run build && tsx src/cli.ts",
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm -C ../discovery run build && pnpm run build && vitest run"
+  },
+  "dependencies": {
+    "@treecrdt/discovery": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.25",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.0"
+  }
+}