@weborigami/origami 0.6.14 → 0.6.16

package/main.js

@@ -1,6 +1,9 @@
 export { default as documentObject } from "./src/common/documentObject.js";
 export * from "./src/common/serialize.js";
+export { default as debugParent } from "./src/dev/debug2/debugParent.js";
+export { default as debugTransform } from "./src/dev/debug2/debugTransform.js";
 export * as Dev from "./src/dev/dev.js";
+export * from "./src/handlers/origamiHandlers.js";
 export * as Origami from "./src/origami/origami.js";
 export { default as origamiHighlightDefinition } from "./src/origami/origamiHighlightDefinition.js";
 export { default as constructResponse } from "./src/server/constructResponse.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -18,9 +18,9 @@
   },
   "dependencies": {
     "@hpcc-js/wasm-graphviz": "^1.21.0",
-    "@weborigami/async-tree": "0.6.14",
+    "@weborigami/async-tree": "0.6.16",
     "@weborigami/json-feed-to-rss": "1.0.1",
-    "@weborigami/language": "0.6.14",
+    "@weborigami/language": "0.6.16",
     "css-tree": "3.1.0",
     "highlight.js": "11.11.1",
     "jsdom": "28.1.0",
@@ -29,6 +29,7 @@
     "marked-highlight": "2.2.3",
     "marked-smartypants": "1.1.11",
     "sharp": "0.34.5",
+    "whatwg-mimetype": "5.0.0",
     "yaml": "2.8.2"
   },
   "scripts": {

package/src/common/findOpenPort.js

@@ -0,0 +1,58 @@
+import net from "node:net";
+
+const DEFAULT_PORT = 5000;
+
+/**
+ * Return the first open port number on or after the given port number.
+ *
+ * @param {number} startPort
+ * @returns {Promise<number>}
+ */
+export async function findOpenPort(startPort = DEFAULT_PORT) {
+  for (let port = startPort; port <= 65535; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+
+  throw new Error(`No open port found on or after ${startPort}`);
+}
+
+/**
+ * Check whether a port is available on both IPv4 and IPv6 loopback addresses
+ * by attempting TCP connections. On macOS, IPv4 and IPv6 port spaces are
+ * independent (IPV6_V6ONLY=1 by default), so a server bound to [::]:PORT is
+ * invisible to a 127.0.0.1 bind check. Using connect probes on both loopbacks
+ * catches servers regardless of which protocol family they listen on. Any
+ * connection error (ECONNREFUSED, EADDRNOTAVAIL, etc.) means nothing is
+ * listening there, so the function is safe on systems without IPv6.
+ *
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+async function isPortAvailable(port) {
+  const [v4, v6] = await Promise.all([
+    isPortListening("127.0.0.1", port),
+    isPortListening("::1", port),
+  ]);
+  return !v4 && !v6;
+}
+
+/**
+ * @param {string} host
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function isPortListening(host, port) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection(port, host);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}

package/src/dev/debug2/debug2.js

@@ -1,37 +1,20 @@
 import { OrigamiFileMap } from "@weborigami/language";
-import { fork } from "node:child_process";
-import http from "node:http";
-import net from "node:net";
 import path from "node:path";
-
-const PUBLIC_HOST = "127.0.0.1";
-const DEFAULT_PORT = 5000;
-
-// Module that loads the server in the child process
-const childModuleUrl = new URL("./debugChild.js", import.meta.url);
-
-// The active child process and port
-/** @typedef {import("node:child_process").ChildProcess} ChildProcess */
-/** @typedef {{ process: ChildProcess, port: number | null }} ChildInfo */
-/** @type {ChildInfo | null} */
-let activeChild = null;
-
-// The most recently started child (may not be ready yet)
-/** @type {ChildInfo | null} */
-let pendingChild = null;
+import debugParent from "./debugParent.js";
 
 /**
- * Given an Origami function, determine the runtime state's parent container,
- * then start a new debug server with that parent as the root of the resource
- * tree.
+ * Given an Origami expression, start a new debug server with that parent as the
+ * root of the resource tree.
+ *
+ * This function expects unevaluated arguments. This is what it allows it to
+ * extract the source code of the expression to be debugged. (If it were
+ * evaluated, the function will be called with the result of the expression.)
  *
- * This function expects an unevaluated expression. It will obtain the original
- * source of the expression and pass that to the child for evaluation. This
- * arrangement ensures the expression is evaluated in a clean Node context (not
- * polluted by previous evaluations).
+ * @typedef {import("@weborigami/language").RuntimeState} RuntimeState
+ * @typedef {import("@weborigami/language").AnnotatedCode} AnnotatedCode
  *
- * @param {import("@weborigami/language").AnnotatedCode} code
- * @param {import("@weborigami/language").RuntimeState} state
+ * @param {AnnotatedCode} code
+ * @param {RuntimeState} state
  */
 export default async function debug2(code, state) {
   if (
@@ -43,6 +26,9 @@ export default async function debug2(code, state) {
       "Dev.debug2 expects an Origami expression to evaluate: `debug2 <expression>`",
     );
   }
+
+  const expression = code.source;
+
   const { parent } = state;
   // @ts-ignore
   const parentPath = parent?.path;
@@ -50,301 +36,45 @@ export default async function debug2(code, state) {
     throw new Error("Dev.debug2 couldn't work out the parent path.");
   }
 
-  const serverOptions = {
-    expression: code.source,
-    parent: parentPath,
-  };
+  // Start the debug server
+  const server = await debugParent({
+    expression,
+    parentPath,
+  });
 
+  // Watch the parent files for changes
   const tree = new OrigamiFileMap(parentPath);
   tree.watch();
-  tree.addEventListener?.("change", (event) => {
+  tree.addEventListener?.("change", async (event) => {
     // @ts-ignore
     const { filePath } = event.options;
     if (isJavaScriptFile(filePath)) {
       // Need to restart the child process
       console.log("JavaScript file changed, restarting server…");
-      startChild(serverOptions);
-    } else if (isPackageJsonFile(filePath)) {
+      await server.restart();
+    } else if (path.basename(filePath) === "package.json") {
       // Need to restart the child process
       console.log("package.json changed, restarting server…");
-      startChild(serverOptions);
+      await server.restart();
     } else {
       // Just have the child reevaluate the expression
       console.log("File changed, reloading site…");
-      activeChild?.process.send({ type: "REEVALUATE" });
+      await server.reevaluate();
     }
   });
 
-  const port = await findOpenPort(PUBLIC_HOST);
-
-  // ---- Public server
-  const publicServer = http.createServer(proxyRequest);
-  publicServer.listen(port, PUBLIC_HOST, () => {
-    startChild(serverOptions);
-    console.log(
-      `Server running at http://localhost:${port}. Press Ctrl+C to stop.`,
-    );
+  // When server closes, stop watching for file changes
+  server.on("close", () => {
+    tree.unwatch();
   });
+
+  console.log(`Server running at ${server.origin}. Press Ctrl+C to stop.`);
 }
 debug2.needsState = true;
 debug2.unevaluatedArgs = true;
 
-/**
- * Give a child process a chance to finish any in-flight requests before we kill
- * it.
- *
- * @param {ChildProcess} childProcess
- */
-async function drainAndStopChild(childProcess) {
-  if (childProcess.killed) {
-    return;
-  }
-
-  // Ask it to drain first.
-  try {
-    childProcess.send({ type: "DRAIN" });
-  } catch {
-    // ignore
-  }
-
-  const drained = new Promise((resolve) => {
-    const onMessage = (msg) => {
-      if (msg && typeof msg === "object" && msg.type === "DRAINED") {
-        cleanup(resolve);
-      }
-    };
-    const onExit = () => cleanup(resolve);
-
-    function cleanup(done) {
-      childProcess.off("message", onMessage);
-      childProcess.off("exit", onExit);
-      done();
-    }
-
-    childProcess.on("message", onMessage);
-    childProcess.on("exit", onExit);
-  });
-
-  // Give it a short grace window to finish in-flight work.
-  const GRACE_MS = 1500;
-  await Promise.race([
-    drained,
-    new Promise((r) => setTimeout(r, GRACE_MS).unref()),
-  ]);
-
-  if (!childProcess.killed) {
-    childProcess.kill("SIGTERM");
-  }
-
-  // Final escalation.
-  setTimeout(() => {
-    // Child should have exited by now, but if not kill it
-    if (!childProcess.killed) {
-      childProcess.kill("SIGKILL");
-    }
-  }, GRACE_MS).unref();
-}
-
-// Return the first open port number on or after the given port number.
-async function findOpenPort(host, startPort = DEFAULT_PORT) {
-  for (let port = startPort; port <= 65535; port++) {
-    const open = await isPortAvailable(host, port);
-    if (open) {
-      return port;
-    }
-  }
-
-  throw new Error(`No open port found on or after ${startPort}`);
-}
-
 function isJavaScriptFile(filePath) {
   const extname = path.extname(filePath).toLowerCase();
   const jsExtensions = [".cjs", ".js", ".mjs", ".ts"];
   return jsExtensions.includes(extname);
 }
-
-function isPackageJsonFile(filePath) {
-  return path.basename(filePath).toLowerCase() === "package.json";
-}
-
-/**
- * Check whether a TCP port can be bound.
- *
- * @param {string} host
- * @param {number} port
- * @returns {Promise<boolean>}
- */
-async function isPortAvailable(host, port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-
-    server.unref();
-
-    server.once("error", (/** @type {any} */ error) => {
-      // Port is unavailable or cannot be bound on this host.
-      if (
-        error.code === "EADDRINUSE" ||
-        error.code === "EACCES" ||
-        error.code === "EADDRNOTAVAIL"
-      ) {
-        resolve(false);
-      } else {
-        resolve(false);
-      }
-    });
-
-    server.once("listening", () => {
-      server.close(() => resolve(true));
-    });
-
-    server.listen(port, host);
-  });
-}
-
-/**
- * Proxy incoming requests to the active child server, or return a 503 if not
- * ready.
- *
- * @param {import("node:http").IncomingMessage} request
- * @param {import("node:http").ServerResponse} response
- */
-function proxyRequest(request, response) {
-  if (!activeChild) {
-    response.statusCode = 503;
-    response.setHeader("content-type", "text/plain; charset=utf-8");
-    response.end("Dev server is starting…\n");
-    return;
-  }
-
-  const { port } = activeChild;
-
-  // Minimal hop-by-hop header stripping
-  const headers = { ...request.headers };
-  delete headers.connection;
-  delete headers["proxy-connection"];
-  delete headers["keep-alive"];
-  delete headers.te;
-  delete headers.trailer;
-  delete headers["transfer-encoding"];
-  delete headers.upgrade;
-
-  const upstreamRequest = http.request(
-    {
-      host: PUBLIC_HOST,
-      port,
-      method: request.method,
-      path: request.url,
-      headers,
-    },
-    (upstreamResponse) => {
-      response.writeHead(
-        upstreamResponse.statusCode ?? 502,
-        upstreamResponse.statusMessage,
-        upstreamResponse.headers,
-      );
-      upstreamResponse.pipe(response);
-    },
-  );
-
-  upstreamRequest.on("error", (err) => {
-    // Stop piping the request body
-    request.unpipe(upstreamRequest);
-    upstreamRequest.destroy();
-
-    // Only send error response if headers haven't been sent yet
-    if (!response.headersSent) {
-      response.statusCode = 502;
-      response.setHeader("content-type", "text/plain; charset=utf-8");
-      response.end(`Upstream error: ${err.message}\n`);
-    } else {
-      // Headers already sent, can't send error message - just close
-      response.destroy();
-    }
-  });
-
-  // Also handle errors on the incoming request
-  request.on("error", () => {
-    upstreamRequest.destroy();
-  });
-
-  request.pipe(upstreamRequest);
-}
-
-/**
- * Start a new child process.
- *
- * This will be a pending process until it sends a READY message, at which point
- * it becomes active and any previous active child is drained and stopped.
- */
-function startChild(serverOptions) {
-  const { expression, parent } = serverOptions;
-
-  // Start the child process, passing parent path via an environment variable.
-  /** @type {ChildProcess} */
-  let childProcess;
-  try {
-    childProcess = fork(childModuleUrl, [], {
-      stdio: ["inherit", "inherit", "inherit", "ipc"],
-      env: {
-        ...process.env,
-        ORIGAMI_EXPRESSION: expression,
-        ORIGAMI_PARENT: parent,
-      },
-    });
-  } catch (error) {
-    throw new Error("Dev.debug2: failed to start child server:", {
-      cause: error,
-    });
-  }
-
-  // This becomes the pending child immediately
-  pendingChild = { process: childProcess, port: null };
-
-  // Listen for messages from the child about its status
-  childProcess.on("message", (/** @type {any} */ message) => {
-    if (!message || typeof message !== "object") {
-      return;
-    }
-
-    if (message.type === "READY" && typeof message.port === "number") {
-      // Only promote to active if this is still the pending child
-      if (pendingChild?.process === childProcess) {
-        const previousChild = activeChild;
-
-        activeChild = pendingChild;
-        pendingChild.port = message.port;
-        pendingChild = null;
-
-        // Drain previous child in background (don't wait)
-        if (previousChild?.process && previousChild.process !== childProcess) {
-          drainAndStopChild(previousChild.process).catch((err) =>
-            console.error("[drain]", err),
-          );
-        }
-      } else {
-        // This child was superseded by a newer one, kill it
-        // console.log("Child process superseded by newer one, killing it...");
-        childProcess.kill("SIGTERM");
-      }
-    }
-
-    if (message.type === "FATAL") {
-      // Child couldn't start (import error, etc.)
-      // Keep previous active child if any; otherwise we'll serve 500/503.
-      console.error("[child fatal]", message.error ?? message);
-      if (pendingChild?.process === childProcess) {
-        pendingChild = null;
-      }
-    }
-  });
-
-  childProcess.on("exit", (code, signal) => {
-    if (activeChild?.process === childProcess) {
-      // Active child died unexpectedly.
-      activeChild = null;
-    }
-    if (pendingChild?.process === childProcess) {
-      pendingChild = null;
-    }
-  });
-}

package/src/dev/debug2/debugChild.js

@@ -3,7 +3,7 @@ import { requestListener } from "../../server/server.js";
 import expressionTree from "./expressionTree.js";
 
 /**
- * The debug2 command runs this module in a child process, passing in a parent
+ * The debug parent runs this module in a child process, passing in a parent
  * path in an environment variable.
  *
  * This module starts an HTTP server that will serve resources from that tree.
@@ -31,11 +31,13 @@ if (expression === undefined) {
 
 /** @type {string} */
 // @ts-ignore
-const parentPath = process.env.ORIGAMI_PARENT;
+const parentPath = process.env.ORIGAMI_PARENT_PATH;
 if (parentPath === undefined) {
   fail("Missing Origami parent");
 }
 
+const quiet = process.env.ORIGAMI_QUIET === "1";
+
 // An indirect pointer to the tree of resources;
 let treeHandle = {};
 
@@ -43,7 +45,7 @@ let treeHandle = {};
 await evaluateExpression();
 
 // Serve the tree of resources
-const listener = requestListener(treeHandle);
+const listener = requestListener(treeHandle, { quiet });
 const server = http.createServer(listener);
 
 // Track live connections so we can drain/close cleanly.
@@ -88,7 +90,10 @@ function beginDrain() {
 }
 
 async function evaluateExpression() {
-  const tree = await expressionTree(expression, parentPath);
+  const tree = await expressionTree({
+    expression,
+    parentPath,
+  });
   if (!tree) {
     fail("Dev.debug2: expression did not evaluate to a maplike resource tree");
   }
@@ -106,6 +111,8 @@ async function evaluateExpression() {
   } catch {
     // Ignore errors.
   }
+
+  process.send?.({ type: "EVALUATED" });
 }
 
 function maybeFinishDrain() {

package/src/dev/debug2/debugCommands.js

@@ -0,0 +1,11 @@
+// Subset of commands made available via debugTransform
+
+import { Tree } from "@weborigami/async-tree";
+export const keys = Tree.keys;
+export const json = Tree.json;
+
+export { default as index } from "../../origami/indexPage.js";
+export { default as yaml } from "../../origami/yaml.js";
+export { default as explore } from "../explore.js";
+export { default as svg } from "../svg.js";
+export { default as version } from "../version.js";