@treecrdt/discovery-server-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cybersemics Institute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/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`

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import { startDiscoveryServer } from './server.js';
+function clientHostForBindHost(host) {
+    const trimmed = host.trim();
+    if (trimmed === '0.0.0.0' || trimmed === '::' || trimmed === '[::]') {
+        return 'localhost';
+    }
+    return trimmed;
+}
+function parseBooleanEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw || raw.trim().length === 0)
+        return fallback;
+    const normalized = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    throw new Error(`${name} must be a boolean (true/false), got: ${raw}`);
+}
+function readPackageVersion() {
+    try {
+        const packageJsonUrl = new URL('../package.json', import.meta.url);
+        const parsed = JSON.parse(fs.readFileSync(packageJsonUrl, 'utf8'));
+        return typeof parsed.version === 'string' && parsed.version.trim().length > 0
+            ? parsed.version.trim()
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function main() {
+    const host = process.env.HOST ?? '0.0.0.0';
+    const port = Number(process.env.PORT ?? '8788');
+    const resolveDocPath = process.env.TREECRDT_DISCOVERY_RESOLVE_PATH?.trim() || undefined;
+    const publicHttpBaseUrl = process.env.TREECRDT_DISCOVERY_PUBLIC_HTTP_BASE_URL?.trim() || undefined;
+    const publicWebSocketBaseUrl = process.env.TREECRDT_DISCOVERY_PUBLIC_WS_BASE_URL?.trim() || undefined;
+    const cacheTtlMs = Number(process.env.TREECRDT_DISCOVERY_CACHE_TTL_MS ?? String(60 * 60 * 1000));
+    const packageVersion = readPackageVersion();
+    const gitSha = process.env.TREECRDT_DISCOVERY_GIT_SHA?.trim() || undefined;
+    const gitDirty = parseBooleanEnv('TREECRDT_DISCOVERY_GIT_DIRTY', false);
+    const startedAt = new Date().toISOString();
+    if (!Number.isFinite(port) || port <= 0)
+        throw new Error(`invalid PORT: ${process.env.PORT}`);
+    if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0) {
+        throw new Error('invalid TREECRDT_DISCOVERY_CACHE_TTL_MS');
+    }
+    const handle = await startDiscoveryServer({
+        host,
+        port,
+        resolveDocPath,
+        publicHttpBaseUrl,
+        publicWebSocketBaseUrl,
+        cacheTtlMs,
+        packageVersion,
+        gitSha,
+        gitDirty,
+        startedAt,
+    });
+    const clientHost = clientHostForBindHost(handle.host);
+    console.log(`TreeCRDT discovery server listening on ${handle.host}:${handle.port}`);
+    console.log(`- bind: http://${handle.host}:${handle.port}`);
+    console.log(`- health: http://${clientHost}:${handle.port}/health`);
+    console.log(`- status: http://${clientHost}:${handle.port}/status`);
+    console.log(`- resolve: http://${clientHost}:${handle.port}${resolveDocPath ?? '/resolve-doc'}?docId=YOUR_DOC_ID`);
+    if (publicHttpBaseUrl || publicWebSocketBaseUrl) {
+        console.log(`- advertised endpoints: ${publicHttpBaseUrl ?? '(derived from request)'} / ${publicWebSocketBaseUrl ?? '(derived from request)'}`);
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './server.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './server.js';

package/dist/server.d.ts

@@ -0,0 +1,43 @@
+import http from 'node:http';
+import type { ResolveDocRequest, ResolveDocResponse } from '@treecrdt/discovery';
+type Awaitable<T> = T | Promise<T>;
+export type DiscoveryServerResolveContext = {
+    req: http.IncomingMessage;
+    url: URL;
+};
+export type DiscoveryServerResolveHandler = (request: ResolveDocRequest, ctx: DiscoveryServerResolveContext) => Awaitable<ResolveDocResponse>;
+export type DiscoveryServerHealthResult = {
+    ok: true;
+    body?: string;
+    contentType?: string;
+} | {
+    ok: false;
+    statusCode?: number;
+    body?: string;
+    contentType?: string;
+};
+export type DiscoveryServerOptions = {
+    host?: string;
+    port?: number;
+    healthPath?: string;
+    statusPath?: string;
+    resolveDocPath?: string;
+    publicHttpBaseUrl?: string;
+    publicWebSocketBaseUrl?: string;
+    cacheTtlMs?: number;
+    resolveDoc?: DiscoveryServerResolveHandler;
+    healthCheck?: () => Awaitable<DiscoveryServerHealthResult>;
+    statusInfo?: () => Awaitable<Record<string, unknown>>;
+    packageName?: string;
+    packageVersion?: string;
+    gitSha?: string;
+    gitDirty?: boolean;
+    startedAt?: string;
+};
+export type DiscoveryServerHandle = {
+    host: string;
+    port: number;
+    close: () => Promise<void>;
+};
+export declare function startDiscoveryServer(opts?: DiscoveryServerOptions): Promise<DiscoveryServerHandle>;
+export {};

package/dist/server.js

@@ -0,0 +1,229 @@
+import http from 'node:http';
+function normalizeOptionalAbsoluteUrl(name, value, allowedProtocols) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`${name} must be a valid absolute URL`);
+    }
+    if (!allowedProtocols.includes(url.protocol)) {
+        throw new Error(`${name} must use ${allowedProtocols.join(', ')}`);
+    }
+    return url.toString().replace(/\/$/, '');
+}
+function normalizePath(name, value, fallback) {
+    const trimmed = value?.trim() || fallback;
+    if (!trimmed.startsWith('/'))
+        throw new Error(`${name} must start with "/"`);
+    return trimmed;
+}
+function firstForwardedHeader(value) {
+    if (Array.isArray(value))
+        value = value[0];
+    if (!value)
+        return undefined;
+    const first = value.split(',')[0]?.trim();
+    return first && first.length > 0 ? first : undefined;
+}
+function derivePublicBaseUrl(req, fallbackProtocol) {
+    const host = firstForwardedHeader(req.headers['x-forwarded-host']) ?? req.headers.host ?? 'localhost';
+    const forwardedProto = firstForwardedHeader(req.headers['x-forwarded-proto']);
+    const protocol = forwardedProto && forwardedProto.length > 0
+        ? fallbackProtocol === 'ws'
+            ? forwardedProto === 'https'
+                ? 'wss'
+                : 'ws'
+            : forwardedProto
+        : fallbackProtocol;
+    return `${protocol}://${host}`.replace(/\/$/, '');
+}
+function buildDefaultResolveDocHandler(opts) {
+    return async (request, ctx) => {
+        const publicHttpBaseUrl = opts.publicHttpBaseUrl ?? derivePublicBaseUrl(ctx.req, 'http');
+        const publicWebSocketBaseUrl = opts.publicWebSocketBaseUrl ?? derivePublicBaseUrl(ctx.req, 'ws');
+        return {
+            docId: request.docId,
+            plan: {
+                topology: 'relay',
+                attachments: [
+                    {
+                        protocol: 'websocket',
+                        role: 'preferred',
+                        url: `${publicWebSocketBaseUrl}/sync`,
+                    },
+                    {
+                        protocol: 'https',
+                        role: 'bootstrap',
+                        url: publicHttpBaseUrl,
+                    },
+                ],
+                cacheTtlMs: opts.cacheTtlMs,
+            },
+        };
+    };
+}
+export async function startDiscoveryServer(opts = {}) {
+    const host = opts.host ?? '0.0.0.0';
+    const port = Number(opts.port ?? 8788);
+    const healthPath = normalizePath('healthPath', opts.healthPath, '/health');
+    const statusPath = normalizePath('statusPath', opts.statusPath, '/status');
+    const resolveDocPath = normalizePath('resolveDocPath', opts.resolveDocPath, '/resolve-doc');
+    const publicHttpBaseUrl = normalizeOptionalAbsoluteUrl('publicHttpBaseUrl', opts.publicHttpBaseUrl, ['http:', 'https:']);
+    const publicWebSocketBaseUrl = normalizeOptionalAbsoluteUrl('publicWebSocketBaseUrl', opts.publicWebSocketBaseUrl, ['ws:', 'wss:', 'http:', 'https:']);
+    const cacheTtlMs = opts.cacheTtlMs == null ? 60 * 60 * 1000 : Number(opts.cacheTtlMs);
+    const packageName = opts.packageName?.trim() || '@treecrdt/discovery-server-node';
+    const packageVersion = opts.packageVersion?.trim() || undefined;
+    const gitSha = opts.gitSha?.trim() || undefined;
+    const gitDirty = Boolean(opts.gitDirty);
+    const startedAt = opts.startedAt?.trim() || new Date().toISOString();
+    const startedAtMs = Date.parse(startedAt);
+    if (!Number.isFinite(port) || port < 0)
+        throw new Error(`invalid port: ${opts.port}`);
+    if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0) {
+        throw new Error(`invalid cacheTtlMs: ${opts.cacheTtlMs}`);
+    }
+    const resolveDoc = opts.resolveDoc ??
+        buildDefaultResolveDocHandler({
+            publicHttpBaseUrl,
+            publicWebSocketBaseUrl,
+            cacheTtlMs,
+        });
+    const discoveryCorsHeaders = {
+        'access-control-allow-origin': '*',
+        'access-control-allow-methods': 'GET,OPTIONS',
+        'access-control-allow-headers': 'content-type,authorization',
+    };
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        if (url.pathname === healthPath) {
+            void (async () => {
+                try {
+                    const result = (await opts.healthCheck?.()) ?? { ok: true };
+                    if (result.ok) {
+                        res.writeHead(200, { 'content-type': result.contentType ?? 'text/plain' });
+                        res.end(result.body ?? 'ok');
+                        return;
+                    }
+                    const requestedStatusCode = result.statusCode;
+                    const statusCode = typeof requestedStatusCode === 'number' &&
+                        Number.isInteger(requestedStatusCode) &&
+                        requestedStatusCode >= 400 &&
+                        requestedStatusCode <= 599
+                        ? requestedStatusCode
+                        : 503;
+                    res.writeHead(statusCode, { 'content-type': result.contentType ?? 'text/plain' });
+                    res.end(result.body ?? 'not ready');
+                }
+                catch {
+                    res.writeHead(503, { 'content-type': 'text/plain' });
+                    res.end('not ready');
+                }
+            })();
+            return;
+        }
+        if (url.pathname === statusPath) {
+            void (async () => {
+                try {
+                    const status = {
+                        ok: true,
+                        service: packageName,
+                        version: packageVersion ?? null,
+                        gitSha: gitSha ?? null,
+                        gitDirty,
+                        buildRef: gitSha ? `${gitSha}${gitDirty ? '-dirty' : ''}` : null,
+                        startedAt,
+                        uptimeMs: Number.isFinite(startedAtMs) ? Math.max(0, Date.now() - startedAtMs) : null,
+                        resolveDocPath,
+                        publicHttpBaseUrl: publicHttpBaseUrl ?? null,
+                        publicWebSocketBaseUrl: publicWebSocketBaseUrl ?? null,
+                        cacheTtlMs,
+                        ...((await opts.statusInfo?.()) ?? {}),
+                    };
+                    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+                    res.end(JSON.stringify(status));
+                }
+                catch {
+                    res.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
+                    res.end(JSON.stringify({ ok: false, error: 'status unavailable' }));
+                }
+            })();
+            return;
+        }
+        if (url.pathname === resolveDocPath) {
+            void (async () => {
+                try {
+                    if (req.method === 'OPTIONS') {
+                        res.writeHead(204, discoveryCorsHeaders);
+                        res.end();
+                        return;
+                    }
+                    if (req.method && req.method !== 'GET') {
+                        res.writeHead(405, {
+                            'content-type': 'application/json; charset=utf-8',
+                            ...discoveryCorsHeaders,
+                        });
+                        res.end(JSON.stringify({ ok: false, error: 'method not allowed' }));
+                        return;
+                    }
+                    const docId = url.searchParams.get('docId')?.trim();
+                    if (!docId) {
+                        res.writeHead(400, {
+                            'content-type': 'application/json; charset=utf-8',
+                            ...discoveryCorsHeaders,
+                        });
+                        res.end(JSON.stringify({ ok: false, error: 'missing docId' }));
+                        return;
+                    }
+                    const response = await resolveDoc({ docId }, { req, url });
+                    res.writeHead(200, {
+                        'content-type': 'application/json; charset=utf-8',
+                        ...discoveryCorsHeaders,
+                    });
+                    res.end(JSON.stringify(response));
+                }
+                catch {
+                    res.writeHead(500, {
+                        'content-type': 'application/json; charset=utf-8',
+                        ...discoveryCorsHeaders,
+                    });
+                    res.end(JSON.stringify({ ok: false, error: 'resolve failed' }));
+                }
+            })();
+            return;
+        }
+        res.writeHead(404, { 'content-type': 'text/plain' });
+        res.end('not found');
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('failed to start discovery server');
+    }
+    return {
+        host: address.address,
+        port: address.port,
+        close: async () => {
+            await new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@treecrdt/discovery-server-node",
+  "version": "0.1.0",
+  "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"
+  ],
+  "dependencies": {
+    "@treecrdt/discovery": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.25",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cybersemics/treecrdt.git",
+    "directory": "packages/discovery-server-node"
+  },
+  "bugs": {
+    "url": "https://github.com/cybersemics/treecrdt/issues"
+  },
+  "homepage": "https://github.com/cybersemics/treecrdt#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+
+import { startDiscoveryServer } from './server.js';
+
+function clientHostForBindHost(host: string): string {
+  const trimmed = host.trim();
+  if (trimmed === '0.0.0.0' || trimmed === '::' || trimmed === '[::]') {
+    return 'localhost';
+  }
+  return trimmed;
+}
+
+function parseBooleanEnv(name: string, fallback: boolean): boolean {
+  const raw = process.env[name];
+  if (!raw || raw.trim().length === 0) return fallback;
+  const normalized = raw.trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  throw new Error(`${name} must be a boolean (true/false), got: ${raw}`);
+}
+
+function readPackageVersion(): string | undefined {
+  try {
+    const packageJsonUrl = new URL('../package.json', import.meta.url);
+    const parsed = JSON.parse(fs.readFileSync(packageJsonUrl, 'utf8')) as { version?: unknown };
+    return typeof parsed.version === 'string' && parsed.version.trim().length > 0
+      ? parsed.version.trim()
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function main() {
+  const host = process.env.HOST ?? '0.0.0.0';
+  const port = Number(process.env.PORT ?? '8788');
+  const resolveDocPath = process.env.TREECRDT_DISCOVERY_RESOLVE_PATH?.trim() || undefined;
+  const publicHttpBaseUrl =
+    process.env.TREECRDT_DISCOVERY_PUBLIC_HTTP_BASE_URL?.trim() || undefined;
+  const publicWebSocketBaseUrl =
+    process.env.TREECRDT_DISCOVERY_PUBLIC_WS_BASE_URL?.trim() || undefined;
+  const cacheTtlMs = Number(process.env.TREECRDT_DISCOVERY_CACHE_TTL_MS ?? String(60 * 60 * 1000));
+  const packageVersion = readPackageVersion();
+  const gitSha = process.env.TREECRDT_DISCOVERY_GIT_SHA?.trim() || undefined;
+  const gitDirty = parseBooleanEnv('TREECRDT_DISCOVERY_GIT_DIRTY', false);
+  const startedAt = new Date().toISOString();
+
+  if (!Number.isFinite(port) || port <= 0) throw new Error(`invalid PORT: ${process.env.PORT}`);
+  if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0) {
+    throw new Error('invalid TREECRDT_DISCOVERY_CACHE_TTL_MS');
+  }
+
+  const handle = await startDiscoveryServer({
+    host,
+    port,
+    resolveDocPath,
+    publicHttpBaseUrl,
+    publicWebSocketBaseUrl,
+    cacheTtlMs,
+    packageVersion,
+    gitSha,
+    gitDirty,
+    startedAt,
+  });
+  const clientHost = clientHostForBindHost(handle.host);
+  console.log(`TreeCRDT discovery server listening on ${handle.host}:${handle.port}`);
+  console.log(`- bind: http://${handle.host}:${handle.port}`);
+  console.log(`- health: http://${clientHost}:${handle.port}/health`);
+  console.log(`- status: http://${clientHost}:${handle.port}/status`);
+  console.log(
+    `- resolve: http://${clientHost}:${handle.port}${resolveDocPath ?? '/resolve-doc'}?docId=YOUR_DOC_ID`,
+  );
+  if (publicHttpBaseUrl || publicWebSocketBaseUrl) {
+    console.log(
+      `- advertised endpoints: ${publicHttpBaseUrl ?? '(derived from request)'} / ${
+        publicWebSocketBaseUrl ?? '(derived from request)'
+      }`,
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/src/index.ts

@@ -0,0 +1 @@
+export * from './server.js';

package/src/server.ts

@@ -0,0 +1,310 @@
+import http from 'node:http';
+
+import type { ResolveDocRequest, ResolveDocResponse } from '@treecrdt/discovery';
+
+type Awaitable<T> = T | Promise<T>;
+
+export type DiscoveryServerResolveContext = {
+  req: http.IncomingMessage;
+  url: URL;
+};
+
+export type DiscoveryServerResolveHandler = (
+  request: ResolveDocRequest,
+  ctx: DiscoveryServerResolveContext,
+) => Awaitable<ResolveDocResponse>;
+
+export type DiscoveryServerHealthResult =
+  | {
+      ok: true;
+      body?: string;
+      contentType?: string;
+    }
+  | {
+      ok: false;
+      statusCode?: number;
+      body?: string;
+      contentType?: string;
+    };
+
+export type DiscoveryServerOptions = {
+  host?: string;
+  port?: number;
+  healthPath?: string;
+  statusPath?: string;
+  resolveDocPath?: string;
+  publicHttpBaseUrl?: string;
+  publicWebSocketBaseUrl?: string;
+  cacheTtlMs?: number;
+  resolveDoc?: DiscoveryServerResolveHandler;
+  healthCheck?: () => Awaitable<DiscoveryServerHealthResult>;
+  statusInfo?: () => Awaitable<Record<string, unknown>>;
+  packageName?: string;
+  packageVersion?: string;
+  gitSha?: string;
+  gitDirty?: boolean;
+  startedAt?: string;
+};
+
+export type DiscoveryServerHandle = {
+  host: string;
+  port: number;
+  close: () => Promise<void>;
+};
+
+function normalizeOptionalAbsoluteUrl(
+  name: string,
+  value: string | undefined,
+  allowedProtocols: readonly string[],
+): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new Error(`${name} must be a valid absolute URL`);
+  }
+  if (!allowedProtocols.includes(url.protocol)) {
+    throw new Error(`${name} must use ${allowedProtocols.join(', ')}`);
+  }
+  return url.toString().replace(/\/$/, '');
+}
+
+function normalizePath(name: string, value: string | undefined, fallback: string): string {
+  const trimmed = value?.trim() || fallback;
+  if (!trimmed.startsWith('/')) throw new Error(`${name} must start with "/"`);
+  return trimmed;
+}
+
+function firstForwardedHeader(value: string | string[] | undefined): string | undefined {
+  if (Array.isArray(value)) value = value[0];
+  if (!value) return undefined;
+  const first = value.split(',')[0]?.trim();
+  return first && first.length > 0 ? first : undefined;
+}
+
+function derivePublicBaseUrl(req: http.IncomingMessage, fallbackProtocol: 'http' | 'ws'): string {
+  const host =
+    firstForwardedHeader(req.headers['x-forwarded-host']) ?? req.headers.host ?? 'localhost';
+  const forwardedProto = firstForwardedHeader(req.headers['x-forwarded-proto']);
+  const protocol =
+    forwardedProto && forwardedProto.length > 0
+      ? fallbackProtocol === 'ws'
+        ? forwardedProto === 'https'
+          ? 'wss'
+          : 'ws'
+        : forwardedProto
+      : fallbackProtocol;
+  return `${protocol}://${host}`.replace(/\/$/, '');
+}
+
+function buildDefaultResolveDocHandler(opts: {
+  publicHttpBaseUrl?: string;
+  publicWebSocketBaseUrl?: string;
+  cacheTtlMs: number;
+}): DiscoveryServerResolveHandler {
+  return async (request, ctx) => {
+    const publicHttpBaseUrl = opts.publicHttpBaseUrl ?? derivePublicBaseUrl(ctx.req, 'http');
+    const publicWebSocketBaseUrl =
+      opts.publicWebSocketBaseUrl ?? derivePublicBaseUrl(ctx.req, 'ws');
+    return {
+      docId: request.docId,
+      plan: {
+        topology: 'relay',
+        attachments: [
+          {
+            protocol: 'websocket',
+            role: 'preferred',
+            url: `${publicWebSocketBaseUrl}/sync`,
+          },
+          {
+            protocol: 'https',
+            role: 'bootstrap',
+            url: publicHttpBaseUrl,
+          },
+        ],
+        cacheTtlMs: opts.cacheTtlMs,
+      },
+    };
+  };
+}
+
+export async function startDiscoveryServer(
+  opts: DiscoveryServerOptions = {},
+): Promise<DiscoveryServerHandle> {
+  const host = opts.host ?? '0.0.0.0';
+  const port = Number(opts.port ?? 8788);
+  const healthPath = normalizePath('healthPath', opts.healthPath, '/health');
+  const statusPath = normalizePath('statusPath', opts.statusPath, '/status');
+  const resolveDocPath = normalizePath('resolveDocPath', opts.resolveDocPath, '/resolve-doc');
+  const publicHttpBaseUrl = normalizeOptionalAbsoluteUrl(
+    'publicHttpBaseUrl',
+    opts.publicHttpBaseUrl,
+    ['http:', 'https:'],
+  );
+  const publicWebSocketBaseUrl = normalizeOptionalAbsoluteUrl(
+    'publicWebSocketBaseUrl',
+    opts.publicWebSocketBaseUrl,
+    ['ws:', 'wss:', 'http:', 'https:'],
+  );
+  const cacheTtlMs = opts.cacheTtlMs == null ? 60 * 60 * 1000 : Number(opts.cacheTtlMs);
+  const packageName = opts.packageName?.trim() || '@treecrdt/discovery-server-node';
+  const packageVersion = opts.packageVersion?.trim() || undefined;
+  const gitSha = opts.gitSha?.trim() || undefined;
+  const gitDirty = Boolean(opts.gitDirty);
+  const startedAt = opts.startedAt?.trim() || new Date().toISOString();
+  const startedAtMs = Date.parse(startedAt);
+
+  if (!Number.isFinite(port) || port < 0) throw new Error(`invalid port: ${opts.port}`);
+  if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0) {
+    throw new Error(`invalid cacheTtlMs: ${opts.cacheTtlMs}`);
+  }
+
+  const resolveDoc =
+    opts.resolveDoc ??
+    buildDefaultResolveDocHandler({
+      publicHttpBaseUrl,
+      publicWebSocketBaseUrl,
+      cacheTtlMs,
+    });
+  const discoveryCorsHeaders = {
+    'access-control-allow-origin': '*',
+    'access-control-allow-methods': 'GET,OPTIONS',
+    'access-control-allow-headers': 'content-type,authorization',
+  };
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+
+    if (url.pathname === healthPath) {
+      void (async () => {
+        try {
+          const result = (await opts.healthCheck?.()) ?? { ok: true as const };
+          if (result.ok) {
+            res.writeHead(200, { 'content-type': result.contentType ?? 'text/plain' });
+            res.end(result.body ?? 'ok');
+            return;
+          }
+          const requestedStatusCode = result.statusCode;
+          const statusCode =
+            typeof requestedStatusCode === 'number' &&
+            Number.isInteger(requestedStatusCode) &&
+            requestedStatusCode >= 400 &&
+            requestedStatusCode <= 599
+              ? requestedStatusCode
+              : 503;
+          res.writeHead(statusCode, { 'content-type': result.contentType ?? 'text/plain' });
+          res.end(result.body ?? 'not ready');
+        } catch {
+          res.writeHead(503, { 'content-type': 'text/plain' });
+          res.end('not ready');
+        }
+      })();
+      return;
+    }
+
+    if (url.pathname === statusPath) {
+      void (async () => {
+        try {
+          const status = {
+            ok: true,
+            service: packageName,
+            version: packageVersion ?? null,
+            gitSha: gitSha ?? null,
+            gitDirty,
+            buildRef: gitSha ? `${gitSha}${gitDirty ? '-dirty' : ''}` : null,
+            startedAt,
+            uptimeMs: Number.isFinite(startedAtMs) ? Math.max(0, Date.now() - startedAtMs) : null,
+            resolveDocPath,
+            publicHttpBaseUrl: publicHttpBaseUrl ?? null,
+            publicWebSocketBaseUrl: publicWebSocketBaseUrl ?? null,
+            cacheTtlMs,
+            ...((await opts.statusInfo?.()) ?? {}),
+          };
+          res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+          res.end(JSON.stringify(status));
+        } catch {
+          res.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
+          res.end(JSON.stringify({ ok: false, error: 'status unavailable' }));
+        }
+      })();
+      return;
+    }
+
+    if (url.pathname === resolveDocPath) {
+      void (async () => {
+        try {
+          if (req.method === 'OPTIONS') {
+            res.writeHead(204, discoveryCorsHeaders);
+            res.end();
+            return;
+          }
+          if (req.method && req.method !== 'GET') {
+            res.writeHead(405, {
+              'content-type': 'application/json; charset=utf-8',
+              ...discoveryCorsHeaders,
+            });
+            res.end(JSON.stringify({ ok: false, error: 'method not allowed' }));
+            return;
+          }
+          const docId = url.searchParams.get('docId')?.trim();
+          if (!docId) {
+            res.writeHead(400, {
+              'content-type': 'application/json; charset=utf-8',
+              ...discoveryCorsHeaders,
+            });
+            res.end(JSON.stringify({ ok: false, error: 'missing docId' }));
+            return;
+          }
+          const response = await resolveDoc({ docId }, { req, url });
+          res.writeHead(200, {
+            'content-type': 'application/json; charset=utf-8',
+            ...discoveryCorsHeaders,
+          });
+          res.end(JSON.stringify(response));
+        } catch {
+          res.writeHead(500, {
+            'content-type': 'application/json; charset=utf-8',
+            ...discoveryCorsHeaders,
+          });
+          res.end(JSON.stringify({ ok: false, error: 'resolve failed' }));
+        }
+      })();
+      return;
+    }
+
+    res.writeHead(404, { 'content-type': 'text/plain' });
+    res.end('not found');
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve();
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('failed to start discovery server');
+  }
+
+  return {
+    host: address.address,
+    port: address.port,
+    close: async () => {
+      await new Promise<void>((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+      });
+    },
+  };
+}