rcf-lite 0.0.1 → 0.7.1

package/src/server/index.js

@@ -0,0 +1,178 @@
+// HTTP + SSE server for the live-view surface. Wires the watch primitive
+// to the walker to the SSE hub: any change under `rcf/` triggers a full
+// re-walk (D4) and a `tree-update` broadcast (D12). Binds 127.0.0.1 only
+// (D11); EADDRINUSE is a hard failure (D10).
+//
+// Public surface:
+//   startServer({ projectRoot, port, host, log, heartbeatMs, watchImpl })
+//     -> Promise<{ url, port, close, hub, currentState }>
+// close() drains SSE with a `shutdown` event and releases the port. The
+// caller (bin/rcf-view.js) is responsible for the 2s force-exit budget
+// on top; the server itself does not `process.exit`.
+
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+
+import { LIVE_CLIENT_PATH, STYLE_CSS_PATH, VENDORED_MERMAID_PATH, renderModelToPage } from '../view/index.js';
+import { watch as defaultWatch } from '../watch/index.js';
+import { createRouter } from './routes.js';
+import { createSseHub } from './sse.js';
+
+/**
+ * @typedef {object} StartServerOptions
+ * @property {string} projectRoot
+ * @property {number} [port=4373]
+ * @property {string} [host='127.0.0.1']
+ * @property {number} [heartbeatMs=30000]
+ * @property {number} [debounceMs=50]
+ * @property {(line: string) => void} [log] - stderr sink
+ * @property {typeof defaultWatch} [watchImpl] - injectable watch primitive for tests
+ */
+
+/**
+ * @param {StartServerOptions} args
+ * @returns {Promise<{
+ *   url: string,
+ *   port: number,
+ *   host: string,
+ *   close: () => Promise<void>,
+ *   currentState: () => { version: number, fullPageHtml: string, contentHtml: string } | null,
+ *   sse: ReturnType<typeof createSseHub>,
+ *   rewalk: () => Promise<void>,
+ * }>}
+ */
+export async function startServer(args) {
+  const projectRoot = args.projectRoot;
+  const port = typeof args.port === 'number' ? args.port : 4373;
+  const host = typeof args.host === 'string' ? args.host : '127.0.0.1';
+  const heartbeatMs = typeof args.heartbeatMs === 'number' ? args.heartbeatMs : 30000;
+  const debounceMs = typeof args.debounceMs === 'number' ? args.debounceMs : 50;
+  const log = typeof args.log === 'function' ? args.log : () => {};
+  const watchImpl = typeof args.watchImpl === 'function' ? args.watchImpl : defaultWatch;
+
+  /** @type {{ version: number, fullPageHtml: string, contentHtml: string, errors: import('#core/errors').RcfError[] } | null} */
+  let state = null;
+  let version = 0;
+  let rewalkInFlight = null;
+  let closed = false;
+
+  const sse = createSseHub({ heartbeatMs, log });
+
+  async function rewalk() {
+    if (closed) return;
+    if (rewalkInFlight) {
+      // Coalesce concurrent walks. The trailing one will pick up the
+      // final on-disk state; a middle one adds nothing.
+      return rewalkInFlight;
+    }
+    rewalkInFlight = (async () => {
+      try {
+        const result = await renderModelToPage({ projectRoot });
+        if (closed) return;
+        version += 1;
+        state = {
+          version,
+          fullPageHtml: result.fullPageHtml,
+          contentHtml: result.contentHtml,
+          errors: result.errors,
+        };
+        sse.broadcast('tree-update', { version, contentHtml: result.contentHtml });
+        if (result.errors && result.errors.length > 0) {
+          sse.broadcast('walker-error', { errors: result.errors });
+        }
+      } catch (err) {
+        log(`[server] walker failed: ${/** @type {Error} */ (err).message}`);
+        sse.broadcast('walker-error', {
+          errors: [{ kind: 'ioFailure', message: /** @type {Error} */ (err).message }],
+        });
+      } finally {
+        rewalkInFlight = null;
+      }
+    })();
+    return rewalkInFlight;
+  }
+
+  // Initial walk before we bind, so the first HTTP GET / has content ready
+  // and the first SSE connect gets a real payload.
+  await rewalk();
+
+  const router = createRouter({
+    currentState: () => state,
+    sse,
+    stylePath: STYLE_CSS_PATH,
+    mermaidPath: VENDORED_MERMAID_PATH,
+    liveClientPath: LIVE_CLIENT_PATH,
+  });
+
+  const server = createServer(router);
+
+  // Watcher: any .json change under rcf/ triggers a re-walk. Debounced
+  // per D4. Non-JSON files are filtered in the primitive itself.
+  const watchDir = join(projectRoot, 'rcf');
+  const watcher = watchImpl({
+    paths: [watchDir],
+    onChange: () => { rewalk().catch(() => {}); },
+    debounceMs,
+    onError: (err) => { log(`[watch] ${err.message}`); },
+  });
+
+  // Bind. EADDRINUSE surfaces as a rejected Promise so the caller can
+  // print a clear message and exit 2 (D10). On bind failure we also tear
+  // down the watcher and close the (unbound) http.Server so the process
+  // has no lingering handles.
+  try {
+    await new Promise((resolve, reject) => {
+      function onError(err) {
+        server.off('listening', onListening);
+        reject(err);
+      }
+      function onListening() {
+        server.off('error', onError);
+        resolve();
+      }
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(port, host);
+    });
+  } catch (err) {
+    try { watcher.close(); } catch { /* swallow */ }
+    try { sse.close(); } catch { /* swallow */ }
+    try { server.close(); } catch { /* swallow */ }
+    throw err;
+  }
+
+  const boundPort = /** @type {import('node:net').AddressInfo} */ (server.address()).port;
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    try { watcher.close(); } catch { /* swallow */ }
+    await sse.drain('shutdown');
+    // Kick any lingering keep-alive sockets out first so `server.close()`
+    // resolves quickly. Node 18.2+ exposes both APIs.
+    try { server.closeIdleConnections?.(); } catch { /* swallow */ }
+    try { server.closeAllConnections?.(); } catch { /* swallow */ }
+    await new Promise((resolve) => {
+      let done = false;
+      server.close(() => { if (!done) { done = true; resolve(); } });
+      // Backstop: never let the promise hang beyond the bin's 2s budget.
+      const t = setTimeout(() => {
+        if (done) return;
+        done = true;
+        try { server.closeAllConnections?.(); } catch { /* swallow */ }
+        resolve();
+      }, 500);
+      if (typeof t.unref === 'function') t.unref();
+    });
+  }
+
+  return {
+    url: `http://${host}:${boundPort}/`,
+    port: boundPort,
+    host,
+    close,
+    currentState: () => state,
+    sse,
+    rewalk,
+  };
+}

package/src/server/routes.js

@@ -0,0 +1,110 @@
+// HTTP route table for the live-view server. Only five routes are served:
+// GET /              -> rendered page (text/html)
+// GET /events        -> SSE stream (text/event-stream)
+// GET /style.css     -> shipped stylesheet
+// GET /mermaid.min.js-> vendored mermaid runtime
+// GET /live-client.js-> phase 3.8 live client script
+// Everything else -> 404 text/plain.
+//
+// No CORS headers, no cache headers on static assets beyond what the
+// browser derives from same-origin/localhost trust (D5, D11).
+
+import { readFile, stat } from 'node:fs/promises';
+
+const MIME = {
+  html: 'text/html; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  js: 'application/javascript; charset=utf-8',
+  txt: 'text/plain; charset=utf-8',
+};
+
+/**
+ * @typedef {object} RouterDeps
+ * @property {() => { fullPageHtml: string, contentHtml: string, version: number } | null} currentState
+ * @property {ReturnType<typeof import('./sse.js').createSseHub>} sse
+ * @property {string} stylePath
+ * @property {string} mermaidPath
+ * @property {string} liveClientPath
+ */
+
+/**
+ * Create a request handler bound to the current state provider and the
+ * SSE hub. The returned function has signature `(req, res) -> void` and
+ * is ready to pass into `http.createServer`.
+ *
+ * @param {RouterDeps} deps
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => void}
+ */
+export function createRouter(deps) {
+  return function handle(req, res) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405, { 'content-type': MIME.txt, allow: 'GET, HEAD' });
+      res.end('method not allowed\n');
+      return;
+    }
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname;
+
+    if (path === '/' || path === '/index.html') {
+      const state = deps.currentState();
+      if (!state) {
+        res.writeHead(503, { 'content-type': MIME.txt });
+        res.end('view server initialising\n');
+        return;
+      }
+      res.writeHead(200, { 'content-type': MIME.html });
+      res.end(state.fullPageHtml);
+      return;
+    }
+    if (path === '/events') {
+      const state = deps.currentState();
+      const payload = state ? { version: state.version, contentHtml: state.contentHtml } : null;
+      deps.sse.handle(req, res, payload);
+      return;
+    }
+    if (path === '/style.css') {
+      serveFile(res, deps.stylePath, MIME.css).catch((err) => fail(res, err));
+      return;
+    }
+    if (path === '/mermaid.min.js') {
+      serveFile(res, deps.mermaidPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
+    if (path === '/live-client.js') {
+      serveFile(res, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
+
+    res.writeHead(404, { 'content-type': MIME.txt });
+    res.end('not found\n');
+  };
+}
+
+async function serveFile(res, path, contentType) {
+  let body;
+  let size;
+  try {
+    const [buf, s] = await Promise.all([readFile(path), stat(path)]);
+    body = buf;
+    size = s.size;
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+      res.writeHead(404, { 'content-type': MIME.txt });
+      res.end('not found\n');
+      return;
+    }
+    throw err;
+  }
+  res.writeHead(200, {
+    'content-type': contentType,
+    'content-length': String(size),
+  });
+  res.end(body);
+}
+
+function fail(res, err) {
+  try {
+    res.writeHead(500, { 'content-type': MIME.txt });
+    res.end(`internal error: ${err && err.message ? err.message : 'unknown'}\n`);
+  } catch { /* swallow */ }
+}

package/src/server/sse.js

@@ -0,0 +1,118 @@
+// SSE (Server-Sent Events) connection manager. Tracks the open long-lived
+// `/events` responses, broadcasts payload events to all of them, keeps a
+// heartbeat loop, and drains gracefully on server close (D16).
+//
+// D5: private surface between the server and its own browser client.
+// Neither payload shape nor route path is a stable contract; downstream
+// consumers (e.g. `rcf query`) get their own wire when the time comes.
+
+/**
+ * @typedef {Object} SseHubOptions
+ * @property {number} [heartbeatMs=30000] - heartbeat interval in ms
+ * @property {(msg: string) => void} [log] - optional stderr sink
+ */
+
+/**
+ * @param {SseHubOptions} [opts]
+ * @returns {{
+ *   handle: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, current: { version: number, contentHtml: string } | null) => void,
+ *   broadcast: (event: string, data: object) => void,
+ *   heartbeatOnce: () => void,
+ *   drain: (event?: string) => Promise<void>,
+ *   size: () => number,
+ *   close: () => void,
+ * }}
+ */
+export function createSseHub(opts = {}) {
+  const heartbeatMs = typeof opts.heartbeatMs === 'number' && opts.heartbeatMs > 0 ? opts.heartbeatMs : 30000;
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+  /** @type {Set<import('node:http').ServerResponse>} */
+  const clients = new Set();
+  let heartbeatTimer = null;
+  let closed = false;
+
+  function frame(event, data) {
+    const payload = typeof data === 'string' ? data : JSON.stringify(data ?? {});
+    return `event: ${event}\ndata: ${payload}\n\n`;
+  }
+
+  function writeTo(res, event, data) {
+    try {
+      res.write(frame(event, data));
+    } catch (err) {
+      log(`[sse] write failed: ${/** @type {Error} */ (err).message}`);
+      try { res.end(); } catch { /* swallow */ }
+      clients.delete(res);
+    }
+  }
+
+  function startHeartbeat() {
+    if (heartbeatTimer || closed) return;
+    heartbeatTimer = setInterval(() => {
+      if (clients.size === 0) return;
+      const ts = new Date().toISOString();
+      for (const res of clients) writeTo(res, 'heartbeat', { ts });
+    }, heartbeatMs);
+    if (typeof heartbeatTimer.unref === 'function') heartbeatTimer.unref();
+  }
+
+  function stopHeartbeat() {
+    if (!heartbeatTimer) return;
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+
+  return {
+    handle(req, res, current) {
+      if (closed) {
+        res.writeHead(503, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('server shutting down\n');
+        return;
+      }
+      res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache, no-transform',
+        'connection': 'keep-alive',
+        'x-accel-buffering': 'no',
+      });
+      // Prime the stream so proxies don't buffer the initial event.
+      try { res.write(': ok\n\n'); } catch { /* swallow */ }
+      clients.add(res);
+      req.on('close', () => {
+        clients.delete(res);
+      });
+      // First event on connect carries the current state so the client
+      // is in sync without a separate resume protocol (D12).
+      if (current) writeTo(res, 'tree-update', current);
+      startHeartbeat();
+    },
+    broadcast(event, data) {
+      if (closed) return;
+      for (const res of clients) writeTo(res, event, data);
+    },
+    heartbeatOnce() {
+      if (clients.size === 0) return;
+      const ts = new Date().toISOString();
+      for (const res of clients) writeTo(res, 'heartbeat', { ts });
+    },
+    async drain(event = 'shutdown') {
+      if (closed) return;
+      closed = true;
+      stopHeartbeat();
+      for (const res of clients) {
+        writeTo(res, event, {});
+        try { res.end(); } catch { /* swallow */ }
+      }
+      clients.clear();
+    },
+    size() { return clients.size; },
+    close() {
+      closed = true;
+      stopHeartbeat();
+      for (const res of clients) {
+        try { res.end(); } catch { /* swallow */ }
+      }
+      clients.clear();
+    },
+  };
+}