feat: add a detach mode to the CLI

src/packages/cli/src/args.ts

@@ -236,6 +236,16 @@ export default function (
   }
 
   args = args
+    .command(
+      "stop [name]",
+      "Stop an instance of Ganache running in detached mode",
+      stopArgs => {
+        stopArgs.positional("name", {
+          type: "string",
+          name: "The name of the instance to stop"
+        });
+      }
+    )
     .showHelpOnFail(false, "Specify -? or --help for available options")
     .alias("help", "?")
     .wrap(wrapWidth)
@@ -246,7 +256,7 @@ export default function (
     flavor: parsedArgs._.length > 0 ? parsedArgs._[0] : DefaultFlavor,
     detach: parsedArgs.detach || false
   } as Argv;
-  for (let key in parsedArgs) {
+  for (const key in parsedArgs) {
     // split on the first "."
     const [group, option] = key.split(/\.(.+)/);
     // only copy namespaced/group keys

src/packages/cli/src/cli.ts

@@ -8,7 +8,26 @@ import initializeEthereum from "./initialize/ethereum";
 import initializeFilecoin from "./initialize/filecoin";
 import type { FilecoinProvider } from "@ganache/filecoin";
 import type { EthereumProvider } from "@ganache/ethereum";
-import { fork } from "child_process";
+import {
+  cleanupDetachedInstanceFile,
+  notifyDetachedInstanceReady,
+  stopDetachedInstance,
+  startDetachedInstance
+} from "./detach";
+import { TruffleColors } from "@ganache/colors";
+import chalk from "chalk";
+
+// if process.send is defined, this is a child_process (we assume a detached
+// instance), so we need to notify that we are ready.
+const isDetachedInstance = process.send !== undefined;
+
+if (isDetachedInstance) {
+  // we want to attach this listener as early as possible, to avoid leaving a
+  // dangling instance file
+  process.on("exit", () => {
+    cleanupDetachedInstanceFile(process.pid);
+  });
+}
 
 const logAndForceExit = (messages: any[], exitCode = 0) => {
   // https://nodejs.org/api/process.html#process_process_exit_code
@@ -40,52 +59,26 @@ const isDocker =
 
 const argv = args(detailedVersion, isDocker);
 
-if (argv.detach) {
-  // Start Ganache in a child process, and allow it to run in the background.
-  // The only output to stdout should be the PID of the child process.
-  const module = process.argv[1];
-  const args = process.argv.slice(2);
-  args.splice(args.indexOf("--detach"), 1);
-
-  const child = fork(module, args, {
-    stdio: ["ignore", "ignore", "pipe", "ipc"],
-    detached: true
-  });
-
-  // Any messages output to stderr by the child process (before the `ready`
-  // event is emitted) will be streamed to stderr on the parent.
-  child.stderr.pipe(process.stderr);
-
-  child.on("message", message => {
-    if (message === "ready") {
-      console.log(child.pid);
-
-      // Destroy the ReadableStream exposed by the child process, to allow the
-      // parent to exit gracefully.
-      child.stderr.destroy();
-      child.unref();
-      child.disconnect();
-    }
-  });
+// todo: defs need to improve this
+if (process.argv.indexOf("stop") !== -1) {
+  const instanceName = process.argv[process.argv.length - 1];
 
-  child.on("error", err => {
-    // This only happens if there's an error starting the child process, not if
-    // the application throws within the child process.
-    console.error(
-      `An error occurred starting Ganache in detached mode: ${err}`
+  if (stopDetachedInstance(instanceName)) {
+    console.log("Process stopped");
+  } else {
+    console.error("Process not found");
+  }
+} else if (argv.detach) {
+  startDetachedInstance(process.argv).then(instance => {
+    const highlightedName = chalk.hex(TruffleColors.porsche)(
+      instance.friendlyName
     );
-    process.exit(1);
-  });
-
-  child.on("exit", (code: number) => {
-    // If the child process exits before the parent, something has gone wrong,
-    // so let the user know (even if the exit code is 0).
-    console.error(`The child process exited with exit code ${code}`);
-    process.exit(code);
+    // output only the friendly name to allow users to capture stdout and use to
+    // programmatically stop the instance
+    console.log(highlightedName);
   });
 } else {
   const flavor = argv.flavor;
-
   const cliSettings = argv.server;
 
   console.log(detailedVersion);
@@ -186,10 +179,8 @@ if (argv.detach) {
       }
     }
 
-    // in "detach" mode, the parent will wait until the "ready" message is
-    // received before disconnecting from the child process.
-    if (process.send) {
-      process.send("ready");
+    if (isDetachedInstance) {
+      notifyDetachedInstanceReady();
     }
   }
   console.log("Starting RPC server");

src/packages/cli/src/detach.ts

@@ -0,0 +1,167 @@
+import { fork } from "child_process";
+import createProcessName from "./process-name";
+import envPaths from "env-paths";
+import {
+  existsSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  readdirSync,
+  readFileSync
+} from "fs";
+import path from "path";
+
+export type DetachedInstance = {
+  friendlyName: string;
+  pid: number;
+  startTime: number;
+};
+
+const dataPath = envPaths(`ganache`).data;
+if (!existsSync(dataPath)) mkdirSync(dataPath);
+
+const READY_MESSAGE = "ready";
+
+/**
+ * Notify that the detached instance has started and is ready to receive requests.
+ */
+export function notifyDetachedInstanceReady() {
+  // in "detach" mode, the parent will wait until the "ready" message is
+  // received before disconnecting from the child process.
+  process.send(READY_MESSAGE);
+}
+
+/**
+ * Attempt to find and remove the instance file for a detached instance.
+ * @param  {number} pid the pid of the detached instance
+ * @returns boolean indicating whether the instance file was cleaned up successfully
+ */
+export function cleanupDetachedInstanceFile(pid: number): boolean {
+  const instanceFilename = `${dataPath}/${pid}`;
+  if (existsSync(instanceFilename)) {
+    rmSync(instanceFilename);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Register a new detached instance. Creates an instance file containing
+ * information about the instance.
+ * @param  {DetachedInstance} instance
+ */
+function registerDetachedInstance(instance: DetachedInstance) {
+  const instanceFilename = `${dataPath}/${instance.pid}`;
+
+  writeFileSync(
+    instanceFilename,
+    `${instance.friendlyName}|${instance.startTime}`
+  );
+}
+
+/**
+ * Attempts to stop a detached instance with the specified instance name by
+ * sending a SIGTERM signal. Returns a boolean indicating whether the process
+ * was found. If the PID is identified, but the process is not found, any
+ * corresponding instance file will be removed.
+ *
+ * Note: This does not guarantee that the instance actually stops.
+ * @param  {string} instanceName
+ * @returns boolean indicating whether the instance was found.
+ */
+export function stopDetachedInstance(instanceName: string): boolean {
+  const instance = findInstanceByName(instanceName);
+
+  if (instance) {
+    try {
+      process.kill(instance.pid, "SIGTERM");
+    } catch (err) {
+      // process.kill throws if the process was not found (or was a group process in Windows)
+      cleanupDetachedInstanceFile(instance.pid);
+      return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Start an instance of Ganache in detached mode.
+ * @param  {string[]} argv arguments to be passed to the new instance.
+ * @returns {Promise<DetachedInstance>} resolves to the DetachedInstance once it
+ * is started and ready to receive requests.
+ */
+export async function startDetachedInstance(
+  argv: string[]
+): Promise<DetachedInstance> {
+  const module = argv[1];
+  const args = argv.slice(1).splice(argv.indexOf("--detach"), 1);
+
+  const child = fork(module, args, {
+    stdio: ["ignore", "ignore", "pipe", "ipc"],
+    detached: true
+  });
+
+  // Any messages output to stderr by the child process (before the `ready`
+  // event is emitted) will be streamed to stderr on the parent.
+  child.stderr.pipe(process.stderr);
+
+  let friendlyName: string;
+  do {
+    friendlyName = createProcessName();
+  } while (findInstanceByName(friendlyName));
+
+  await new Promise<void>((resolve, reject) => {
+    child.on("message", message => {
+      if (message === READY_MESSAGE) {
+        resolve();
+      }
+    });
+
+    child.on("error", err => {
+      // This only happens if there's an error starting the child process, not if
+      // the application throws within the child process.
+      reject(err);
+    });
+
+    child.on("exit", (code: number) => {
+      // If the child process exits before the parent, something has gone wrong,
+      // so let the user know (even if the exit code is 0).
+      reject(new Error(`The child process exited with code ${code}`));
+    });
+  });
+
+  // destroy the ReadableStream exposed by the child process, to allow the
+  // parent to exit gracefully.
+  child.stderr.destroy();
+  child.unref();
+  child.disconnect();
+
+  const instance = {
+    startTime: Date.now(),
+    pid: child.pid,
+    friendlyName
+  };
+
+  registerDetachedInstance(instance);
+
+  return instance;
+}
+
+function findInstanceByName(
+  friendlyName: string
+): DetachedInstance | undefined {
+  const files = readdirSync(dataPath);
+  for (let i = 0; i < files.length; i++) {
+    const filepath = path.join(dataPath, files[i]);
+    const content = readFileSync(filepath).toString("utf8");
+    const [name, startTime] = content.split("|");
+    if (name === friendlyName) {
+      return {
+        friendlyName,
+        pid: parseInt(files[i]),
+        startTime: parseInt(startTime)
+      };
+    }
+  }
+}

src/packages/cli/src/process-name.ts

@@ -0,0 +1,83 @@
+export default function createFriendlyName() {
+  const name = [...Array(3)].map((_, i) => {
+    const partSource = nameParts[i];
+    const partIndex = Math.floor(Math.random() * partSource.length);
+    return partSource[partIndex];
+  });
+
+  return name.join("-");
+}
+
+const adjectives = [
+  "baked",
+  "candied",
+  "deepfried",
+  "frozen",
+  "hot",
+  "molten",
+  "pureed",
+  "salted",
+  "spiced",
+  "sticky"
+];
+const flavours = [
+  "almond",
+  "apple",
+  "banana",
+  "blackforest",
+  "caramel",
+  "cherry",
+  "chocolate",
+  "cinnamon",
+  "coconut",
+  "coffee",
+  "cream",
+  "custard",
+  "fruit",
+  "ginger",
+  "gingerbread",
+  "jelly",
+  "lemon",
+  "lime",
+  "milk",
+  "nut",
+  "orange",
+  "peanut",
+  "plum",
+  "poppy-seed",
+  "rhubarb",
+  "strawberry",
+  "sugar",
+  "tiramisu"
+];
+const kinds = [
+  "bar",
+  "biscuit",
+  "brownie",
+  "cake",
+  "cheesecake",
+  "cookie",
+  "crumble",
+  "cupcake",
+  "doughnut",
+  "drizzle",
+  "dumpling",
+  "friand",
+  "ganache",
+  "loaf",
+  "macaroon",
+  "mousse",
+  "muffin",
+  "pastry",
+  "pie",
+  "pudding",
+  "sponge",
+  "strudel",
+  "tart",
+  "torte",
+  "trifle",
+  "truffle",
+  "waffle"
+];
+
+const nameParts = [adjectives, flavours, kinds];