graceful exiting

1 files changed, 392 insertions, 304 deletions

diff --git a/src/server/Session/session.ts b/src/server/Session/session.ts
index cc9e7dd1a..8bee99f41 100644
--- a/src/server/Session/session.ts
+++ b/src/server/Session/session.ts
@@ -1,4 +1,4 @@
-import { red, cyan, green, yellow, magenta, blue } from "colors";
+import { red, cyan, green, yellow, magenta, blue, white } from "colors";
 import { on, fork, setupMaster, Worker, isMaster } from "cluster";
 import { get } from "request-promise";
 import { Utils } from "../../Utils";
@@ -8,26 +8,32 @@ import { validate, ValidationError } from "jsonschema";
 import { configurationSchema } from "./session_config_schema";
 
 /**
-     * This namespace relies on NodeJS's cluster module, which allows a parent (master) process to share
-     * code with its children (workers). A simple `isMaster` flag indicates who is trying to access
-     * the code, and thus determines the functionality that actually gets invoked (checked by the caller, not internally).
-     * 
-     * Think of the master thread as a factory, and the workers as the helpers that actually run the server.
-     * 
-     * So, when we run `npm start`, given the appropriate check, initializeMaster() is called in the parent process
-     * This will spawn off its own child process (by default, mirrors the execution path of its parent),
-     * in which initializeWorker() is invoked.
-     */
+ * This namespace relies on NodeJS's cluster module, which allows a parent (master) process to share
+ * code with its children (workers). A simple `isMaster` flag indicates who is trying to access
+ * the code, and thus determines the functionality that actually gets invoked (checked by the caller, not internally).
+ * 
+ * Think of the master thread as a factory, and the workers as the helpers that actually run the server.
+ * 
+ * So, when we run `npm start`, given the appropriate check, initializeMaster() is called in the parent process
+ * This will spawn off its own child process (by default, mirrors the execution path of its parent),
+ * in which initializeWorker() is invoked.
+ */
 export namespace Session {
 
     export abstract class AppliedSessionAgent {
 
+        // the following two methods allow the developer to create a custom
+        // session and use the built in customization options for each thread
+        protected abstract async launchMonitor(): Promise<Session.Monitor>;
+        protected abstract async launchServerWorker(): Promise<Session.ServerWorker>;
+
+        private launched = false;
+
         public killSession(graceful = true) {
             const target = isMaster ? this.sessionMonitor : this.serverWorker;
             target.killSession(graceful);
         }
 
-        private launched = false;
 
         private sessionMonitorRef: Session.Monitor | undefined;
         public get sessionMonitor(): Session.Monitor {
@@ -58,9 +64,6 @@ export namespace Session {
             }
         }
 
-        protected abstract async launchMonitor(): Promise<Session.Monitor>;
-        protected abstract async launchServerWorker(): Promise<Session.ServerWorker>;
-
     }
 
     interface Configuration {
@@ -81,377 +84,462 @@ export namespace Session {
         ports: { server: 3000 },
         pollingRoute: "/",
         pollingIntervalSeconds: 30,
-        pollingFailureTolerance: 1
+        pollingFailureTolerance: 0
     };
 
-    export interface Monitor {
-        log: (...optionalParams: any[]) => void;
-        restartServer: () => void;
-        setPort: (port: "server" | "socket" | string, value: number, immediateRestart: boolean) => void;
-        killSession: (graceful?: boolean) => never;
-        addReplCommand: (basename: string, argPatterns: (RegExp | string)[], action: ReplAction) => void;
-        addServerMessageListener: (message: string, handler: ActionHandler) => void;
-        removeServerMessageListener: (message: string, handler: ActionHandler) => void;
-        clearServerMessageListeners: (message: string) => void;
-    }
+    export type ExitHandler = (reason: Error | null) => void | Promise<void>;
 
-    export interface ServerWorker {
-        killSession: (graceful?: boolean) => void;
-        sendSessionAction: (message: string, args?: any) => void;
-        addExitHandler: (handler: ExitHandler) => void;
-    }
+    export namespace Monitor {
 
-    export interface MonitorNotifierHooks {
-        key?: (key: string, masterLog: (...optionalParams: any[]) => void) => boolean | Promise<boolean>;
-        crash?: (error: Error, masterLog: (...optionalParams: any[]) => void) => boolean | Promise<boolean>;
-    }
+        export interface NotifierHooks {
+            key?: (key: string) => (boolean | Promise<boolean>);
+            crash?: (error: Error) => (boolean | Promise<boolean>);
+        }
 
-    export interface SessionAction {
-        message: string;
-        args: any;
-    }
+        export interface Action {
+            message: string;
+            args: any;
+        }
+
+        export type ServerMessageHandler = (action: Action) => void | Promise<void>;
 
-    export type ExitHandler = (reason: Error | null) => void | Promise<void>;
-    export type ActionHandler = (action: SessionAction) => void | Promise<void>;
-    export interface EmailTemplate {
-        subject: string;
-        body: string;
     }
 
-    function loadAndValidateConfiguration(): Configuration {
-        try {
-            console.log(timestamp(), cyan("validating configuration..."));
-            const configuration: Configuration = JSON.parse(readFileSync('./session.config.json', 'utf8'));
-            const options = {
-                throwError: true,
-                allowUnknownAttributes: false
-            };
-            // ensure all necessary and no excess information is specified by the configuration file
-            validate(configuration, configurationSchema, options);
-            let formatMaster = true;
-            let formatWorker = true;
-            Object.keys(defaultConfiguration).forEach(property => {
-                if (!configuration[property]) {
-                    if (property === "masterIdentifier") {
-                        formatMaster = false;
-                    } else if (property === "workerIdentifier") {
-                        formatWorker = false;
+    /**
+     * Validates and reads the configuration file, accordingly builds a child process factory
+     * and spawns off an initial process that will respawn as predecessors die.
+     */
+    export class Monitor {
+
+        private exitHandlers: ExitHandler[] = [];
+        private readonly notifiers: Monitor.NotifierHooks | undefined;
+        private readonly configuration: Configuration;
+        private onMessage: { [message: string]: Monitor.ServerMessageHandler[] | undefined } = {};
+        private activeWorker: Worker | undefined;
+        private key: string | undefined;
+        private repl: Repl;
+
+        /**
+         * Kill this session and its active child
+         * server process, either gracefully (may wait
+         * indefinitely, but at least allows active networking
+         * requests to complete) or immediately.
+         */
+        public killSession = async (graceful = true): Promise<never> => {
+            this.log(cyan(`exiting session ${graceful ? "clean" : "immediate"}ly`));
+            this.tryKillActiveWorker(graceful);
+            process.exit(0);
+        }
+
+        /**
+         * Execute the list of functions registered to be called
+         * whenever the process exits.
+         */
+        public addExitHandler = (handler: ExitHandler) => this.exitHandlers.push(handler);
+
+        /**
+         * Extend the default repl by adding in custom commands
+         * that can invoke application logic external to this module
+         */
+        public addReplCommand = (basename: string, argPatterns: (RegExp | string)[], action: ReplAction) => {
+            this.repl.registerCommand(basename, argPatterns, action);
+        }
+
+        /**
+         * Add a listener at this message. When the monitor process
+         * receives a message, it will invoke all registered functions.
+         */
+        public addServerMessageListener = (message: string, handler: Monitor.ServerMessageHandler) => {
+            const handlers = this.onMessage[message];
+            if (handlers) {
+                handlers.push(handler);
+            } else {
+                this.onMessage[message] = [handler];
+            }
+        }
+
+        /**
+         * Unregister a given listener at this message.
+         */
+        public removeServerMessageListener = (message: string, handler: Monitor.ServerMessageHandler) => {
+            const handlers = this.onMessage[message];
+            if (handlers) {
+                const index = handlers.indexOf(handler);
+                if (index > -1) {
+                    handlers.splice(index, 1);
+                }
+            }
+        }
+
+        /**
+         * Unregister all listeners at this message.
+         */
+        public clearServerMessageListeners = (message: string) => this.onMessage[message] = undefined;
+
+        constructor(notifiers?: Monitor.NotifierHooks) {
+            this.notifiers = notifiers;
+
+            console.log(this.timestamp(), cyan("initializing session..."));
+
+            this.configuration = this.loadAndValidateConfiguration();
+            this.initializeSessionKey();
+            // determines whether or not we see the compilation / initialization / runtime output of each child server process
+            setupMaster({ silent: !this.configuration.showServerOutput });
+
+            // handle exceptions in the master thread - there shouldn't be many of these
+            // the IPC (inter process communication) channel closed exception can't seem
+            // to be caught in a try catch, and is inconsequential, so it is ignored
+            process.on("uncaughtException", ({ message, stack }): void => {
+                if (message !== "Channel closed") {
+                    this.log(red(message));
+                    if (stack) {
+                        this.log(`uncaught exception\n${red(stack)}`);
                     }
-                    configuration[property] = defaultConfiguration[property];
                 }
             });
-            if (formatMaster) {
-                configuration.masterIdentifier = yellow(configuration.masterIdentifier + ":");
-            }
-            if (formatWorker) {
-                configuration.workerIdentifier = magenta(configuration.workerIdentifier + ":");
-            }
-            return configuration;
-        } catch (error) {
-            if (error instanceof ValidationError) {
-                console.log(red("\nSession configuration failed."));
-                console.log("The given session.config.json configuration file is invalid.");
-                console.log(`${error.instance}: ${error.stack}`);
-                process.exit(0);
-            } else if (error.code === "ENOENT" && error.path === "./session.config.json") {
-                console.log(cyan("Loading default session parameters..."));
-                console.log("Consider including a session.config.json configuration file in your project root for customization.");
-                return defaultConfiguration;
-            } else {
-                console.log(red("\nSession configuration failed."));
-                console.log("The following unknown error occurred during configuration.");
-                console.log(error.stack);
-                process.exit(0);
-            }
+
+            // a helpful cluster event called on the master thread each time a child process exits
+            on("exit", ({ process: { pid } }, code, signal) => {
+                const prompt = `server worker with process id ${pid} has exited with code ${code}${signal === null ? "" : `, having encountered signal ${signal}`}.`;
+                this.log(cyan(prompt));
+                // to make this a robust, continuous session, every time a child process dies, we immediately spawn a new one
+                this.spawn();
+            });
+
+            this.repl = this.initializeRepl();
+            this.spawn();
         }
-    }
 
-    function timestamp() {
-        return blue(`[${new Date().toUTCString()}]`);
-    }
 
-    /**
-     * Validates and reads the configuration file, accordingly builds a child process factory
-     * and spawns off an initial process that will respawn as predecessors die.
-     */
-    export async function initializeMonitorThread(notifiers?: MonitorNotifierHooks): Promise<Monitor> {
-        console.log(timestamp(), cyan("initializing session..."));
-        let activeWorker: Worker;
-        const onMessage: { [message: string]: ActionHandler[] | undefined } = {};
-
-        // read in configuration .json file only once, in the master thread
-        // pass down any variables the pertinent to the child processes as environment variables
-        const configuration = loadAndValidateConfiguration();
-        const {
-            masterIdentifier,
-            workerIdentifier,
-            ports,
-            pollingRoute,
-            showServerOutput,
-            pollingFailureTolerance
-        } = configuration;
-        let { pollingIntervalSeconds } = configuration;
-
-        const log = (...optionalParams: any[]) => console.log(timestamp(), masterIdentifier, ...optionalParams);
-
-        // this sends a pseudorandomly generated guid to the configuration's recipients, allowing them alone
-        // to kill the server via the /kill/:key route
-        let key: string | undefined;
-        if (notifiers && notifiers.key) {
-            key = Utils.GenerateGuid();
-            const success = await notifiers.key(key, log);
-            const statement = success ? green("distributed session key to recipients") : red("distribution of session key failed");
-            log(statement);
+        /**
+         * Generates a blue UTC string associated with the time
+         * of invocation.
+         */
+        private timestamp = () => blue(`[${new Date().toUTCString()}]`);
+
+        /**
+         * A formatted, identified and timestamped log in color
+         */
+        public log = (...optionalParams: any[]) => {
+            console.log(this.timestamp(), this.configuration.masterIdentifier, ...optionalParams);
+        }
+
+        /**
+         * If the caller has indicated an interest
+         * in being notified of this feature, creates
+         * a GUID for this session that can, for example,
+         * be used as authentication for killing the server
+         * (checked externally).
+         */
+        private initializeSessionKey = async (): Promise<void> => {
+            if (this.notifiers?.key) {
+                this.key = Utils.GenerateGuid();
+                const success = await this.notifiers.key(this.key);
+                const statement = success ? green("distributed session key to recipients") : red("distribution of session key failed");
+                this.log(statement);
+            }
         }
 
-        // handle exceptions in the master thread - there shouldn't be many of these
-        // the IPC (inter process communication) channel closed exception can't seem
-        // to be caught in a try catch, and is inconsequential, so it is ignored
-        process.on("uncaughtException", ({ message, stack }): void => {
-            if (message !== "Channel closed") {
-                log(red(message));
-                if (stack) {
-                    log(`uncaught exception\n${red(stack)}`);
+        /**
+         * Builds the repl that allows the following commands to be typed into stdin of the master thread.
+         */
+        private initializeRepl = (): Repl => {
+            const repl = new Repl({ identifier: () => `${this.timestamp()} ${this.configuration.masterIdentifier}` });
+            const boolean = /true|false/;
+            const number = /\d+/;
+            const letters = /[a-zA-Z]+/;
+            repl.registerCommand("exit", [/clean|force/], args => this.killSession(args[0] === "clean"));
+            repl.registerCommand("restart", [/clean|force/], args => this.tryKillActiveWorker(args[0] === "clean"));
+            repl.registerCommand("set", [letters, "port", number, boolean], args => this.setPort(args[0], Number(args[2]), args[3] === "true"));
+            repl.registerCommand("set", [/polling/, number, boolean], args => {
+                const newPollingIntervalSeconds = Math.floor(Number(args[2]));
+                if (newPollingIntervalSeconds < 0) {
+                    this.log(red("the polling interval must be a non-negative integer"));
+                } else {
+                    if (newPollingIntervalSeconds !== this.configuration.pollingIntervalSeconds) {
+                        this.configuration.pollingIntervalSeconds = newPollingIntervalSeconds;
+                        if (args[3] === "true") {
+                            this.activeWorker?.send({ newPollingIntervalSeconds });
+                        }
+                    }
+                }
+            });
+            return repl;
+        }
+
+        /**
+         * Reads in configuration .json file only once, in the master thread
+         * and pass down any variables the pertinent to the child processes as environment variables.
+         */
+        private loadAndValidateConfiguration = (): Configuration => {
+            try {
+                console.log(this.timestamp(), cyan("validating configuration..."));
+                const configuration: Configuration = JSON.parse(readFileSync('./session.config.json', 'utf8'));
+                const options = {
+                    throwError: true,
+                    allowUnknownAttributes: false
+                };
+                // ensure all necessary and no excess information is specified by the configuration file
+                validate(configuration, configurationSchema, options);
+                let formatMaster = true;
+                let formatWorker = true;
+                Object.keys(defaultConfiguration).forEach(property => {
+                    if (!configuration[property]) {
+                        if (property === "masterIdentifier") {
+                            formatMaster = false;
+                        } else if (property === "workerIdentifier") {
+                            formatWorker = false;
+                        }
+                        configuration[property] = defaultConfiguration[property];
+                    }
+                });
+                if (formatMaster) {
+                    configuration.masterIdentifier = yellow(configuration.masterIdentifier + ":");
+                }
+                if (formatWorker) {
+                    configuration.workerIdentifier = magenta(configuration.workerIdentifier + ":");
+                }
+                return configuration;
+            } catch (error) {
+                if (error instanceof ValidationError) {
+                    console.log(red("\nSession configuration failed."));
+                    console.log("The given session.config.json configuration file is invalid.");
+                    console.log(`${error.instance}: ${error.stack}`);
+                    process.exit(0);
+                } else if (error.code === "ENOENT" && error.path === "./session.config.json") {
+                    console.log(cyan("Loading default session parameters..."));
+                    console.log("Consider including a session.config.json configuration file in your project root for customization.");
+                    return defaultConfiguration;
+                } else {
+                    console.log(red("\nSession configuration failed."));
+                    console.log("The following unknown error occurred during configuration.");
+                    console.log(error.stack);
+                    process.exit(0);
                 }
             }
-        });
+        }
 
-        // determines whether or not we see the compilation / initialization / runtime output of each child server process
-        setupMaster({ silent: !showServerOutput });
 
-        // attempts to kills the active worker ungracefully, unless otherwise specified
-        const tryKillActiveWorker = (graceful = false): boolean => {
-            if (activeWorker && !activeWorker.isDead()) {
+        private executeExitHandlers = async (reason: Error | null) => Promise.all(this.exitHandlers.map(handler => handler(reason)));
+
+        /**
+         * Attempts to kill the active worker gracefully, unless otherwise specified.
+         */
+        private tryKillActiveWorker = (graceful = true): boolean => {
+            if (!this.activeWorker?.isDead()) {
                 if (graceful) {
-                    activeWorker.kill();
+                    this.activeWorker?.send({ manualExit: true });
                 } else {
-                    activeWorker.process.kill();
+                    this.activeWorker?.process.kill();
                 }
                 return true;
             }
             return false;
-        };
-
-        const restartServer = (): void => {
-            // indicate to the worker that we are 'expecting' this restart
-            activeWorker.send({ setResponsiveness: false });
-            tryKillActiveWorker(true);
-        };
-
-        const killSession = (graceful = true): never => {
-            log(cyan(`exiting session ${graceful ? "clean" : "immediate"}ly`));
-            tryKillActiveWorker(graceful);
-            process.exit(0);
-        };
+        }
 
-        const setPort = (port: "server" | "socket" | string, value: number, immediateRestart: boolean): void => {
+        /**
+         * Allows the caller to set the port at which the target (be it the server,
+         * the websocket, some other custom port) is listening. If an immediate restart
+         * is specified, this monitor will kill the active child and re-launch the server
+         * at the port. Otherwise, the updated port won't be used until / unless the child
+         * dies on its own and triggers a restart.
+         */
+        private setPort = (port: "server" | "socket" | string, value: number, immediateRestart: boolean): void => {
             if (value > 1023 && value < 65536) {
-                ports[port] = value;
+                this.configuration.ports[port] = value;
                 if (immediateRestart) {
-                    restartServer();
+                    this.tryKillActiveWorker();
                 }
             } else {
-                log(red(`${port} is an invalid port number`));
+                this.log(red(`${port} is an invalid port number`));
             }
-        };
+        }
 
-        // kills the current active worker and proceeds to spawn a new worker,
-        // feeding in configuration information as environment variables
-        const spawn = (): void => {
-            tryKillActiveWorker();
-            activeWorker = fork({
+        /**
+         * Kills the current active worker and proceeds to spawn a new worker,
+         * feeding in configuration information as environment variables.
+         */
+        private spawn = (): void => {
+            const {
+                pollingRoute,
+                pollingFailureTolerance,
+                pollingIntervalSeconds,
+                ports
+            } = this.configuration;
+            this.tryKillActiveWorker();
+            this.activeWorker = fork({
                 pollingRoute,
                 pollingFailureTolerance,
                 serverPort: ports.server,
                 socketPort: ports.socket,
                 pollingIntervalSeconds,
-                session_key: key
+                session_key: this.key
             });
-            log(cyan(`spawned new server worker with process id ${activeWorker.process.pid}`));
+            this.log(cyan(`spawned new server worker with process id ${this.activeWorker.process.pid}`));
             // an IPC message handler that executes actions on the master thread when prompted by the active worker
-            activeWorker.on("message", async ({ lifecycle, action }) => {
+            this.activeWorker.on("message", async ({ lifecycle, action }) => {
                 if (action) {
-                    const { message, args } = action as SessionAction;
-                    console.log(timestamp(), `${workerIdentifier} action requested (${cyan(message)})`);
+                    const { message, args } = action as Monitor.Action;
+                    console.log(this.timestamp(), `${this.configuration.workerIdentifier} action requested (${cyan(message)})`);
                     switch (message) {
                         case "kill":
-                            log(red("an authorized user has manually ended the server session"));
-                            killSession(args.graceful);
+                            this.log(red("an authorized user has manually ended the server session"));
+                            this.killSession(args.graceful);
                         case "notify_crash":
-                            if (notifiers && notifiers.crash) {
+                            if (this.notifiers?.crash) {
                                 const { error } = args;
-                                const success = await notifiers.crash(error, log);
+                                const success = await this.notifiers.crash(error);
                                 const statement = success ? green("distributed crash notification to recipients") : red("distribution of crash notification failed");
-                                log(statement);
+                                this.log(statement);
                             }
                         case "set_port":
                             const { port, value, immediateRestart } = args;
-                            setPort(port, value, immediateRestart);
-                        default:
-                            const handlers = onMessage[message];
-                            if (handlers) {
-                                handlers.forEach(handler => handler({ message, args }));
-                            }
+                            this.setPort(port, value, immediateRestart);
+                    }
+                    const handlers = this.onMessage[message];
+                    if (handlers) {
+                        handlers.forEach(handler => handler({ message, args }));
                     }
                 } else if (lifecycle) {
-                    console.log(timestamp(), `${workerIdentifier} lifecycle phase (${lifecycle})`);
+                    console.log(this.timestamp(), `${this.configuration.workerIdentifier} lifecycle phase (${lifecycle})`);
                 }
             });
-        };
-
-        // a helpful cluster event called on the master thread each time a child process exits
-        on("exit", ({ process: { pid } }, code, signal) => {
-            const prompt = `server worker with process id ${pid} has exited with code ${code}${signal === null ? "" : `, having encountered signal ${signal}`}.`;
-            log(cyan(prompt));
-            // to make this a robust, continuous session, every time a child process dies, we immediately spawn a new one
-            spawn();
-        });
-
-        // builds the repl that allows the following commands to be typed into stdin of the master thread
-        const repl = new Repl({ identifier: () => `${timestamp()} ${masterIdentifier}` });
-        const boolean = /true|false/;
-        const number = /\d+/;
-        const letters = /[a-zA-Z]+/;
-        repl.registerCommand("exit", [/clean|force/], args => killSession(args[0] === "clean"));
-        repl.registerCommand("restart", [], restartServer);
-        repl.registerCommand("set", [letters, "port", number, boolean], args => setPort(args[0], Number(args[2]), args[3] === "true"));
-        repl.registerCommand("set", [/polling/, number, boolean], args => {
-            const newPollingIntervalSeconds = Math.floor(Number(args[2]));
-            if (newPollingIntervalSeconds < 0) {
-                log(red("the polling interval must be a non-negative integer"));
-            } else {
-                if (newPollingIntervalSeconds !== pollingIntervalSeconds) {
-                    pollingIntervalSeconds = newPollingIntervalSeconds;
-                    if (args[3] === "true") {
-                        activeWorker.send({ newPollingIntervalSeconds });
-                    }
-                }
-            }
-        });
-        // finally, set things in motion by spawning off the first child (server) process
-        spawn();
-
-        // returned to allow the caller to add custom commands
-        return {
-            addReplCommand: repl.registerCommand,
-            addServerMessageListener: (message: string, handler: ActionHandler) => {
-                const handlers = onMessage[message];
-                if (handlers) {
-                    handlers.push(handler);
-                } else {
-                    onMessage[message] = [handler];
-                }
-            },
-            removeServerMessageListener: (message: string, handler: ActionHandler) => {
-                const handlers = onMessage[message];
-                if (handlers) {
-                    const index = handlers.indexOf(handler);
-                    if (index > -1) {
-                        handlers.splice(index, 1);
-                    }
-                }
-            },
-            clearServerMessageListeners: (message: string) => onMessage[message] = undefined,
-            restartServer,
-            killSession,
-            setPort,
-            log
-        };
+        }
+
     }
 
+
+
     /**
      * Effectively, each worker repairs the connection to the server by reintroducing a consistent state
      * if its predecessor has died. It itself also polls the server heartbeat, and exits with a notification
      * email if the server encounters an uncaught exception or if the server cannot be reached.
-     * @param work the function specifying the work to be done by each worker thread
      */
-    export async function initializeWorkerThread(work: Function): Promise<ServerWorker> {
-        let shouldServerBeResponsive = false;
-        const exitHandlers: ExitHandler[] = [];
-        let pollingFailureCount = 0;
-
-        const lifecycleNotification = (lifecycle: string) => process.send?.({ lifecycle });
-
-        // notify master thread (which will log update in the console) of initialization via IPC
-        lifecycleNotification(green("compiling and initializing..."));
+    export class ServerWorker {
+
+        private shouldServerBeResponsive = false;
+        private exitHandlers: ExitHandler[] = [];
+        private pollingFailureCount = 0;
+        private pollingIntervalSeconds: number;
+        private pollingFailureTolerance: number;
+        private pollTarget: string;
+        private serverPort: number;
+
+        /**
+         * Allows developers to invoke application specific logic
+         * by hooking into the exiting of the server process.
+         */
+        public addExitHandler = (handler: ExitHandler) => this.exitHandlers.push(handler);
+
+        /**
+         * Kill the session monitor (parent process) from this
+         * server worker (child process). This will also kill
+         * this process (child process).
+         */
+        public killSession = (graceful = true) => this.sendMonitorAction("kill", { graceful });
+
+        /**
+         * A convenience wrapper to tell the session monitor (parent process)
+         * to carry out the action with the specified message and arguments.
+         */
+        public sendMonitorAction = (message: string, args?: any) => process.send!({ action: { message, args } });
+
+        constructor(work: Function) {
+            this.lifecycleNotification(green(`initializing process... (${white(`${process.execPath} ${process.execArgv.join(" ")}`)})`));
+
+            const { pollingRoute, serverPort, pollingIntervalSeconds, pollingFailureTolerance } = process.env;
+            this.serverPort = Number(serverPort);
+            this.pollingIntervalSeconds = Number(pollingIntervalSeconds);
+            this.pollingFailureTolerance = Number(pollingFailureTolerance);
+            this.pollTarget = `http://localhost:${serverPort}${pollingRoute}`;
+
+            this.configureProcess();
+            work();
+            this.pollServer();
+        }
 
-        // updates the local value of listening to the value sent from master
-        process.on("message", ({ setResponsiveness, newPollingIntervalSeconds }) => {
-            if (setResponsiveness) {
-                shouldServerBeResponsive = setResponsiveness;
-            }
-            if (newPollingIntervalSeconds) {
-                pollingIntervalSeconds = newPollingIntervalSeconds;
-            }
-        });
+        /**
+         * Set up message and uncaught exception handlers for this
+         * server process.
+         */
+        private configureProcess = () => {
+            // updates the local values of variables to the those sent from master
+            process.on("message", async ({ setResponsiveness, newPollingIntervalSeconds, manualExit }) => {
+                if (setResponsiveness !== undefined) {
+                    this.shouldServerBeResponsive = setResponsiveness;
+                }
+                if (newPollingIntervalSeconds !== undefined) {
+                    this.pollingIntervalSeconds = newPollingIntervalSeconds;
+                }
+                if (manualExit !== undefined) {
+                    await this.executeExitHandlers(null);
+                    process.exit(0);
+                }
+            });
 
-        const executeExitHandlers = async (reason: Error | null) => Promise.all(exitHandlers.map(handler => handler(reason)));
+            // one reason to exit, as the process might be in an inconsistent state after such an exception
+            process.on('uncaughtException', this.proactiveUnplannedExit);
+        }
 
-        // called whenever the process has a reason to terminate, either through an uncaught exception
-        // in the process (potentially inconsistent state) or the server cannot be reached
-        const activeExit = async (error: Error): Promise<void> => {
-            shouldServerBeResponsive = false;
+        /**
+         * Execute the list of functions registered to be called
+         * whenever the process exits.
+         */
+        private executeExitHandlers = async (reason: Error | null) => Promise.all(this.exitHandlers.map(handler => handler(reason)));
+
+        /**
+         * Notify master thread (which will log update in the console) of initialization via IPC.
+         */
+        private lifecycleNotification = (event: string) => process.send?.({ lifecycle: event });
+
+        /**
+         * Called whenever the process has a reason to terminate, either through an uncaught exception
+         * in the process (potentially inconsistent state) or the server cannot be reached.
+         */
+        private proactiveUnplannedExit = async (error: Error): Promise<void> => {
+            this.shouldServerBeResponsive = false;
             // communicates via IPC to the master thread that it should dispatch a crash notification email
-            process.send?.({
-                action: {
-                    message: "notify_crash",
-                    args: { error }
-                }
-            });
-            await executeExitHandlers(error);
+            this.sendMonitorAction("notify_crash", { error });
+            await this.executeExitHandlers(error);
             // notify master thread (which will log update in the console) of crash event via IPC
-            lifecycleNotification(red(`crash event detected @ ${new Date().toUTCString()}`));
-            lifecycleNotification(red(error.message));
+            this.lifecycleNotification(red(`crash event detected @ ${new Date().toUTCString()}`));
+            this.lifecycleNotification(red(error.message));
             process.exit(1);
-        };
-
-        // one reason to exit, as the process might be in an inconsistent state after such an exception
-        process.on('uncaughtException', activeExit);
-
-        const { env } = process;
-        const { pollingRoute, serverPort } = env;
-        let pollingIntervalSeconds = Number(env.pollingIntervalSeconds);
-        const pollingFailureTolerance = Number(env.pollingFailureTolerance);
-        // this monitors the health of the server by submitting a get request to whatever port / route specified
-        // by the configuration every n seconds, where n is also given by the configuration. 
-        const pollTarget = `http://localhost:${serverPort}${pollingRoute}`;
-        const pollServer = async (): Promise<void> => {
+        }
+
+        /**
+         * This monitors the health of the server by submitting a get request to whatever port / route specified
+         * by the configuration every n seconds, where n is also given by the configuration. 
+         */
+        private pollServer = async (): Promise<void> => {
             await new Promise<void>(resolve => {
                 setTimeout(async () => {
                     try {
-                        await get(pollTarget);
-                        if (!shouldServerBeResponsive) {
-                            // notify master thread (which will log update in the console) via IPC that the server is up and running
-                            process.send?.({ lifecycle: green(`listening on ${serverPort}...`) });
+                        await get(this.pollTarget);
+                        if (!this.shouldServerBeResponsive) {
+                            // notify monitor thread that the server is up and running
+                            this.lifecycleNotification(green(`listening on ${this.serverPort}...`));
                         }
-                        shouldServerBeResponsive = true;
+                        this.shouldServerBeResponsive = true;
                         resolve();
                     } catch (error) {
                         // if we expect the server to be unavailable, i.e. during compilation,
                         // the listening variable is false, activeExit will return early and the child
                         // process will continue
-                        if (shouldServerBeResponsive) {
-                            if (++pollingFailureCount > pollingFailureTolerance) {
-                                activeExit(error);
+                        if (this.shouldServerBeResponsive) {
+                            if (++this.pollingFailureCount > this.pollingFailureTolerance) {
+                                this.proactiveUnplannedExit(error);
                             } else {
-                                lifecycleNotification(yellow(`the server has encountered ${pollingFailureCount} of ${pollingFailureTolerance} tolerable failures`));
+                                this.lifecycleNotification(yellow(`the server has encountered ${this.pollingFailureCount} of ${this.pollingFailureTolerance} tolerable failures`));
                             }
                         }
                     }
-                }, 1000 * pollingIntervalSeconds);
+                }, 1000 * this.pollingIntervalSeconds);
             });
             // controlled, asynchronous infinite recursion achieves a persistent poll that does not submit a new request until the previous has completed
-            pollServer();
-        };
-
-        work();
-        pollServer(); // begin polling
+            this.pollServer();
+        }
 
-        return {
-            addExitHandler: (handler: ExitHandler) => exitHandlers.push(handler),
-            killSession: (graceful = true) => process.send!({ action: { message: "kill", args: { graceful } } }),
-            sendSessionAction: (message: string, args?: any) => process.send!({ action: { message, args } })
-        };
     }
 
 }
\ No newline at end of file