ISNode Loader Module

Introduction

This is just a module for the ISNode Framework. To learn how to use the framework, we strongly suggest obtaining a copy of the Hello World example.

The Loader Module is the only module that you need to include (require) from your application server entry point. This module then takes over execution, enumerating all ISNode framework modules, loading them and facilitating messaging between modules and between modules and services. You should never directly include/require other ISNode modules from your application server entry point, as the Loader module basically takes over management and execution of the ISNode application server.

Use Example

#!/usr/bin/env node

/*!
* isnode entry point
*
* Copyright (c) 2019 Darren Smith
* Licensed under the LGPL license.
*/

;!function(undefined) {
  var isnode = require('isnode-loader')();
}();

Loader Module specific system configuration includes "banner" (text banner that is displayed on command-line on application server startup), "nodeId" (a UUID that is unique for each application server instance running in a farm), "maxObjectListeners" (leave as default - 100 - or increase if system errors are happening and there is sufficient memory), "startupModules" (an array of three modules that are required for application server startup - logger, daemon and cli. Should not be altered), "timeouts" (defines timeouts in milliseconds for two loader internal methods - loadDependencies and closeModules. Should not be altered). Example:

  "loader": {
    "banner": "Sample Application Server",
    "nodeId": "4h389ht298h29hg92hg92h2ewsadfdsf",
    "maxObjectListeners": 100,
    "startupModules": ["logger", "daemon", "cli"],
    "timeouts": {
      "loadDependencies": 5000,
      "closeModules": 5000
    }
  }

Methods

cfg()

Synchronous Function. Returns the Application Server System Configuration Object

Input Parameters: - N/A

Returns: (Object) The System Configuration Object w/ All Parameter-Values

Code example

// The below use case assumes that you have an instance of the isnode master object

var cfg = isnode.cfg();

console.log(cfg);

/*
	Console log will print something like:

	{
	  "cli": {
	    "mode": "console"
	  },
	  "errorhandler": {
	    "timeout": 5000
	  },
	  "interfaces": {
	    "http": {
	      "http": {
	        "enabled": true,
	        "ssl": false,
	        "port": 80,
	        "requestTimeout": 60000,
	        "log": false,
	        "fileUploadPath": "./tmp/",
	        "maxUploadFileSizeMb": 50
	      },
	      "https": {
	        "enabled": true,
	        "ssl": true,
	        "port": 443,
	        "requestTimeout": 60000,
	        "log": false,
	        "fileUploadPath": "./tmp/",
	        "maxUploadFileSizeMb": 50,
	        "key": "./config/key.pem",
	        "cert": "./config/server.crt"
	      }
	    }
	  },
	  "loader": {
	    "banner": "Example Application Server",
	    "nodeId": "4h389ht298h29hg92hg92h2ewsadfdsf",
	    "maxObjectListeners": 100,
	    "startupModules": ["logger", "daemon", "cli"],
	    "timeouts": {
	      "loadDependencies": 5000,
	      "closeModules": 5000
	    }
	  },
	  "logger": {
	    "enabled": true,
	    "levels": ["startup", "shutdown", "debug", warning", "error", "fatal"],
	    "logMetadataObjects": true,
	    "sinks": {
	      "console": {"enabled": true},
	      "file": {
	        "enabled": true,
	        "location": "./logs/isnode.log"
	      }
	    }
	  },
	  "router": {
	    "instances": {
	      "RouterOne": {
	        "interfaces": ["*"],
	        "services": ["*"]
	      }
	    }
	  },
	  "services": {
	    "allowShutdownFromControllers": false
	  }
	}
*/

pkg()

Synchronous Function. Returns the Application Server Node.JS Package File as an Object

Input Parameters: - N/A

Returns: (Object) The Node.JS "package.json" Object

Code example

// The below use case assumes that you have an instance of the isnode master object

var pkg = isnode.pkg();

console.log(pkg);

/*
	Console log will print something like:

	{
	  "name": "application-server",
	  "version": "0.0.1",
	  "description": "Sample Application Server",
	  "main": "server.js",
	  "scripts": {
	    "start": "node server.js"
	  },
	  "dependencies": {
	    "isnode-loader": "0.0.8",
	    "isnode-mod-cli": "0.0.8",
	    "isnode-mod-daemon": "0.0.8",
	    "isnode-mod-errorhandler": "0.0.8",
	    "isnode-mod-data": "0.0.8",
	    "isnode-mod-identity": "0.0.8",
	    "isnode-mod-interface-http": "0.0.8",
	    "isnode-mod-jobs": "0.0.8",
	    "isnode-mod-logger": "0.0.8",
	    "isnode-mod-mailer": "0.0.8",
	    "isnode-mod-router": "0.0.8",
	    "isnode-mod-services": "0.0.8",
	    "isnode-mod-utilities": "0.0.8"
	  },
	  "author": {
	    "name": "Darren Smith",
	    "email": "[email protected]",
	    "url": "https://www.darrensmith.com.au/"
	  },
	  "maintainers": [
	    {
	      "name": "Darren Smith",
	      "email": "[email protected]"
	    }
	  ],
	  "engines": [
	    "node"
	  ],
	  "bin": {
	    "isnode": "./server.js"
	  }
	}

*/

module(name, type)

Synchronous Function. Returns the requested loaded module instance and all methods/properties that it contains

Input Parameters:

1. name - (String) Short name of module. For example - "data" for the "isnode-mod-data" module.
2. type - (String) Optional. If set to "interface" it will return an interface-type module. If not set (or set to anything else), the method will attempt to return a standard module.

Returns: (Object) The loaded module instance that can be further operated against

Code example

// The below use case assumes that you have an instance of the isnode master object

var uuid = isnode.module("utilities").uuid4();
console.log(uuid);

/* 
	An example result would be "f7812069-09fc-45a5-8d36-2f1247e0a48a" (result of calling a child method of the utilities module that was loaded with this method)
*/

globals.set(name, value)

Synchronous Function. Sets the value of a globally accessible variable.

Input Parameters:

1. name - (String) Name of the globally accessible variable
2. value - (Anything) The value that you want to set against the defined parameter. Can be of any type - a string, integer, object, array, reference, function, etc.

Returns: (Boolean) Returns true if the variable was set successfully, otherwise false.

Code example

// The below use case assumes that you have an instance of the isnode master object

isnode.globals.set("version", "1.0");

/* 
	In this example - we are defining the value "1.0" for the global variable "version". Given that the isnode object is available from all other modules and servies, the corresponding get method can be used to access the value of this global variable. Refer to the next method described.
*/

globals.get(name)

Synchronous Function. Gets the value of a globally accessible variable.

Input Parameters:

1. name - (String) Name of the globally accessible variable

Returns: (Anything) Returns whatever value (string, object, etc...) that has previously been defined by the globals.set() method

Code example

// The below use case assumes that you have an instance of the isnode master object

var version = isnode.globals.get("version");
console.log(version);

/* 
	Following on from the previous example where we set the value of "version" to "1.0", this value is retrieved from the global variable store in this example and is printed to STDOUT with console.log. For example, here we can expect "1.0" to be printed to STDOUT.
*/

shutdown()

Asynchronous Function. Initiates a system-wide shutdown of the application server, alerting all modules and services that a shutdown is in progress so that they can close any open connections that they have and perform general cleanup.

Important Note - Whilst this method (on the isnode master object) is generally available to all system modules, it is (by default) excluded from the isnode master object that is passed to services - unless specifically configured in the app server config.json file (router.instances[name].allowShutdown = true).

Input Parameters: - N/A

Returns: N/A

Code example

// The below use case assumes that you have an instance of the isnode master object

isnode.shutdown();

/* 
	As soon as this method is called, we can expect a series of log messages that describe how the application server is being shutdown. For example:

	2019-04-07T08:42:11.248Z (shutdown) ISNode System > Initiating System Shutdown.
	2019-04-07T08:42:11.248Z (shutdown) ISNode System > Attempting to close all open modules.
	2019-04-07T08:42:11.248Z (shutdown) Logger Module > Closing any open logging connections and shutting down.
	2019-04-07T08:42:11.248Z (shutdown) Daemon Module > Daemon Module Shutdown Succeeded.
	2019-04-07T08:42:11.248Z (shutdown) CLI Module > CLI Module Shutdown Succeeded.
	2019-04-07T08:42:11.248Z (shutdown) Utilities Module > Utilities Module Shutdown Succeeded.
	2019-04-07T08:42:11.248Z (shutdown) Error Handler Module > Error Handler Module Shutdown Succeeded.
	2019-04-07T08:42:16.765Z (shutdown) ISNode System > Module shutdown timed out.
	2019-04-07T08:42:16.766Z (shutdown) Shutdown Complete
*/