npm - orator - Versions diffs - 4.0.3 → 5.0.1 - Mend

orator 4.0.3 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/.vscode/launch.json +1 -0
package/debug/Harness.js +3 -1
package/debug/package.json +14 -0
package/debug/site/Test.html +1 -1
package/package.json +9 -7
package/source/Orator-ServiceServer-IPC-SynthesizedResponse.js +11 -0
package/source/Orator-ServiceServer-IPC.js +65 -1
package/source/Orator.js +193 -4

package/.vscode/launch.json CHANGED Viewed

@@ -12,6 +12,7 @@
             "skipFiles": [
                 "<node_internals>/**"
             ],
+            "cwd": "${workspaceFolder}/debug/",
             "program": "${workspaceFolder}/debug/Harness.js",
             "presentation": {
                 "hidden": false,

package/debug/Harness.js CHANGED Viewed

@@ -41,4 +41,6 @@ tmpServiceServer.invoke('GET', tmpURI, null,
 	(pError, pResponseData) =>
 	{
 		tmpServiceServer.log.info(`Response to [${tmpURI}] came back from IPC resulting in [${pResponseData}]!`)
-	});
+	});
+tmpServiceServer.addStaticRoute('site', 'Test.html', '/*', '/');

package/debug/package.json ADDED Viewed

@@ -0,0 +1,14 @@
+{
+  "name": "orator-debug-server",
+  "version": "1.0.0",
+  "description": "",
+  "main": "Harness.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "orator-serviceserver-restify": "^2.0.3"
+  }
+}

package/debug/site/Test.html CHANGED Viewed

	@@ -1 +1 @@
1	- <html><head></head><body>Um</body></html>
1	+ <html><head></head><body>Umm</body></html>

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
     "name": "orator",
-    "version": "4.0.3",
-    "description": "Unopinionated API behavior container - REST or IPC",
+    "version": "5.0.1",
+    "description": "Unopinionated API http server abstraction - REST or IPC",
     "main": "source/Orator.js",
     "scripts": {
         "start": "node source/Orator.js",
@@ -51,12 +51,14 @@
     },
     "homepage": "https://github.com/stevenvelozo/orator",
     "devDependencies": {
-        "fable": "^3.0.96",
-        "quackage": "^1.0.24"
+        "fable": "^3.0.147",
+        "quackage": "^1.0.36"
     },
     "dependencies": {
-        "fable-serviceproviderbase": "^3.0.12",
-        "find-my-way": "^7.7.0",
-        "orator-serviceserver-base": "^1.0.0"
+        "fable-serviceproviderbase": "^3.0.15",
+        "finalhandler": "^1.3.1",
+        "find-my-way": "^9.1.0",
+        "orator-serviceserver-base": "^1.0.1",
+        "serve-static": "^1.16.2"
     }
 }

package/source/Orator-ServiceServer-IPC-SynthesizedResponse.js CHANGED Viewed

@@ -1,3 +1,8 @@
+/**
+ * Represents a synthesized server response for the Orator service server IPC.
+ *
+ * @class
+ */
 class OratorServiceServerIPCSynthesizedResponse
 {
 	constructor(pHandler, pLog, pRequestGUID)
@@ -27,6 +32,12 @@ class OratorServiceServerIPCSynthesizedResponse
 		this.responseStatus = -1;
 	}
+	/**
+	 * Sends data to the server.
+	 *
+	 * @param {string|object} pData - The data to be sent. It can be either a string or an object.
+	 * @returns {boolean} - Returns true if the data was successfully sent, false otherwise.
+	 */
 	send(pData)
 	{
 		if (typeof(pData) == 'string')

package/source/Orator-ServiceServer-IPC.js CHANGED Viewed

@@ -6,6 +6,13 @@ const libOratorServiceServerIPCSynthesizedResponse = require('./Orator-ServiceSe
 // This library is the default router for our services
 const libFindMyWay = require('find-my-way');
+/**
+ * OratorServiceServerIPC class.
+ *
+ * @class
+ * @extends libOratorServiceServerBase
+ * @classdesc Represents an IPC service server for Orator.
+ */
 class OratorServiceServerIPC extends libOratorServiceServerBase
 {
 	constructor(pFable, pOptions, pServiceHash)
@@ -183,36 +190,85 @@ class OratorServiceServerIPC extends libOratorServiceServerBase
 		};
 	}
+	/**
+	 * Handles the HTTP GET request for a specific route.
+	 *
+	 * @param {string} pRoute - The route to handle.
+	 * @param {...Function} fRouteProcessingFunctions - The processing functions to execute for the route.
+	 * @returns {Promise} A promise that resolves when the route processing is complete.
+	 */
 	doGet(pRoute, ...fRouteProcessingFunctions)
 	{
 		return this.addRouteProcessor('GET', pRoute, Array.from(fRouteProcessingFunctions));
 	}
+	/**
+	 * Handles the PUT request for a specific route.
+	 *
+	 * @param {string} pRoute - The route to handle.
+	 * @param {...Function} fRouteProcessingFunctions - The processing functions to execute for the route.
+	 * @returns {Promise} - A promise that resolves when the route processing is complete.
+	 */
 	doPut(pRoute, ...fRouteProcessingFunctions)
 	{
 		return this.addRouteProcessor('PUT', pRoute, Array.from(fRouteProcessingFunctions));
 	}
+	/**
+	 * Handles the HTTP POST request for a specific route.
+	 *
+	 * @param {string} pRoute - The route to handle.
+	 * @param {...Function} fRouteProcessingFunctions - The processing functions to execute for the route.
+	 * @returns {Promise} - A promise that resolves when the route processing is complete.
+	 */
 	doPost(pRoute, ...fRouteProcessingFunctions)
 	{
 		return this.addRouteProcessor('POST', pRoute, Array.from(fRouteProcessingFunctions));
 	}
+	/**
+	 * Handles the HTTP DEL request for a specific route.
+	 *
+	 * @param {string} pRoute - The route to be deleted.
+	 * @param {...Function} fRouteProcessingFunctions - The route processing functions to be added.
+	 * @returns {Object} - The updated route processor object.
+	 */
 	doDel(pRoute, ...fRouteProcessingFunctions)
 	{
 		return this.addRouteProcessor('DELETE', pRoute, Array.from(fRouteProcessingFunctions));
 	}
+	/**
+	 * Adds a PATCH route processor to the service server.
+	 *
+	 * @param {string} pRoute - The route to be processed.
+	 * @param {...Function} fRouteProcessingFunctions - The route processing functions.
+	 * @returns {boolean} - Returns true if the route processor was added successfully, false otherwise.
+	 */
 	doPatch(pRoute, ...fRouteProcessingFunctions)
 	{
 		return this.addRouteProcessor('PATCH', pRoute, Array.from(fRouteProcessingFunctions));
 	}
+	/**
+	 * Adds a route processor for the OPTIONS method.
+	 *
+	 * @param {string} pRoute - The route to add the processor to.
+	 * @param {...Function} fRouteProcessingFunctions - The processing functions to be executed for the route.
+	 * @returns {Object} - The updated Orator-ServiceServer-IPC object.
+	 */
 	doOpts(pRoute, ...fRouteProcessingFunctions)
 	{
 		return this.addRouteProcessor('OPTIONS', pRoute, Array.from(fRouteProcessingFunctions));
 	}
+	/**
+	 * Handles the HEAD request for a specific route.
+	 *
+	 * @param {string} pRoute - The route to handle.
+	 * @param {...Function} fRouteProcessingFunctions - The processing functions to execute for the route.
+	 * @returns {Promise} - A promise that resolves when the route processing is complete.
+	 */
 	doHead(pRoute, ...fRouteProcessingFunctions)
 	{
 		return this.addRouteProcessor('HEAD', pRoute, Array.from(fRouteProcessingFunctions));
@@ -221,7 +277,15 @@ class OratorServiceServerIPC extends libOratorServiceServerBase
 	 * End of Service Route Creation Functions
 	 */
-	// Programmatically invoke a route
+	/**
+	 * Invokes a method on the IPC provider.
+	 *
+	 * @param {string} pMethod - The method to invoke.
+	 * @param {string} pRoute - The route to invoke.
+	 * @param {any} pData - The data to pass to the method.
+	 * @param {Function} fCallback - The callback function to handle the response.
+	 * @throws {Error} Throws an error if invoked without a callback function.
+	 */
 	invoke(pMethod, pRoute, pData, fCallback)
 	{
 		// If the data is skipped and a callback is parameter 3, do the right thing

package/source/Orator.js CHANGED Viewed

@@ -11,8 +11,22 @@ const libFableServiceProviderBase = require('fable-serviceproviderbase');
 const libDefaultOratorServiceServer = require('./Orator-Default-ServiceServer.js');
+const libServeStatic = require('serve-static');
+const libFinalHandler = require('finalhandler');
+const libMime = require('mime');
 const defaultOratorConfiguration = require('./Orator-Default-Configuration.js');
+/**
+ * @class Orator
+ * @extends libFableServiceProviderBase
+ *
+ * Represents the Orator service provider.
+ *
+ * @param {Object} pFable - The Fable instance.
+ * @param {Object} pOptions - The options for the Orator service.
+ * @param {string} pServiceHash - The hash of the service.
+ */
 class Orator extends libFableServiceProviderBase
 {
 	constructor(pFable, pOptions, pServiceHash)
@@ -45,8 +59,20 @@ class Orator extends libFableServiceProviderBase
 		{
 			this.options.Product = defaultOratorConfiguration.Product;
 		}
+		// This is here because libMime has a breaking change from v1 to v2 and the lookup function was update to be getType per https://stackoverflow.com/a/60741078
+		// We don't want to introspect properties on this library every single time we need to check mime types.
+		// Therefore we are setting this boolean here and using it to branch.
+		this.oldLibMime = false;
+		if ('lookup' in libMime)
+		{
+			this.oldLibMime = true;
+		}
 	}
+	/**
+	 * Lifecycle event that executes before initializing the service.  For overloading.
+	 */
 	onBeforeInitialize()
 	{
 		if (this.fable.settings.LogNoisiness > 3)
@@ -54,6 +80,11 @@ class Orator extends libFableServiceProviderBase
 			this.log.trace(`Orator [${this.UUID}]::[${this.Hash}] ${this.options.Product} onBeforeInitialize:`);
 		}
 	}
+	/**
+	 * Lifecycle event that executes before initializing the service.  For overloading.
+	 *
+	 * @param {Function} fNext - The callback function to be called after the actions are executed.
+	 */
 	onBeforeInitializeAsync(fNext)
 	{
 		this.onBeforeInitialize();
@@ -92,12 +123,20 @@ class Orator extends libFableServiceProviderBase
 			this.log.trace(`Orator [${this.UUID}]::[${this.Hash}] ${this.options.Product} onInitialize:`);
 		}
 	}
+	/**
+	 * Lifecycle event that executes at the moment of initializing the service.  For overloading.
+	 *
+	 * @param {Function} fNext - The callback function to be executed after initialization.
+	 */
 	onInitializeAsync(fNext)
 	{
 		this.onInitialize();
 		return fNext();
 	}
+	/**
+	 * Lifecycle event that executes after initializing the service.  For overloading.
+	 */
 	onAfterInitialize()
 	{
 		if (this.fable.settings.LogNoisiness > 3)
@@ -105,12 +144,22 @@ class Orator extends libFableServiceProviderBase
 			this.log.trace(`Orator [${this.UUID}]::[${this.Hash}] ${this.options.Product} onAfterInitialize:`);
 		}
 	}
+	/**
+	 * Lifecycle event that executes after initializing the service.  For overloading.
+	 * @param {Function} fNext - The callback function to be called after executing onAfterInitialize.
+	 * @returns {Promise} - A promise that resolves when the callback function is called.
+	 */
 	onAfterInitializeAsync(fNext)
 	{
 		this.onAfterInitialize();
 		return fNext();
 	}
+	/**
+	 * Initializes the Orator instance.
+	 *
+	 * @param {Function} fCallback - The callback function to be executed after initialization.
+	 */
 	initialize(fCallback)
 	{
 		// I hate this -- as long as we want to be "mostly" backwards compatible it needs to do it though
@@ -148,10 +197,22 @@ class Orator extends libFableServiceProviderBase
 		}
 	}
+	/**
+	 * Lifecycle event that executes before starting the service.  For overloading.
+	 *
+	 * @param {Function} fNext - The function to be executed before starting the service.
+	 * @returns {Promise} A promise that resolves when the function is completed.
+	 */
 	onBeforeStartService(fNext)
 	{
 		return fNext();
 	}
+	/**
+	 * Lifecycle event that executes when the service starts.  For overloading.
+	 *
+	 * @param {Function} fNext - The callback function to be called after the service starts.
+	 * @returns {Promise} A promise that resolves when the service starts successfully, or rejects with an error.
+	 */
 	onStartService(fNext)
 	{
 		this.onAfterInitialize();
@@ -165,11 +226,22 @@ class Orator extends libFableServiceProviderBase
 			}
 		);
 	}
+	/**
+	 * Lifecycle event that executes after starting the service.  For overloading.
+	 *
+	 * @param {Function} fNext - The callback function to be executed after the service starts.
+	 * @returns {Promise} - A promise that resolves when the callback function is completed.
+	 */
 	onAfterStartService(fNext)
 	{
 		return fNext();
 	}
+	/**
+	 * Starts the service.
+	 *
+	 * @param {Function} fNext - The callback function to be executed after the service has started.
+	 */
 	startService(fNext)
 	{
 		var tmpNext = (typeof(fNext) === 'function') ? fNext : ()=>{};
@@ -203,6 +275,12 @@ class Orator extends libFableServiceProviderBase
 			});
 	}
+	/**
+	 * Stops the service server.
+	 *
+	 * @param {Function} fCallback - The callback function to be executed after the service server is stopped.
+	 * @returns {void}
+	 */
 	stopService(fCallback)
 	{
 		var tmpCallback = (typeof(fCallback) === 'function') ? fCallback : ()=>{};
@@ -224,28 +302,51 @@ class Orator extends libFableServiceProviderBase
 		return this.serviceServer.close(tmpCallback);
 	}
+	/**
+	 * Programmatically invokes a method on the service server.
+	 *
+	 * @param {string} pMethod - The method to invoke.
+	 * @param {string} pRoute - The route to invoke.
+	 * @param {any} pData - The data to send with the invocation.
+	 * @param {Function} fCallback - The callback function to execute after the invocation.
+	 * @returns {any} - The result of the invocation.
+	 */
 	invoke(pMethod, pRoute, pData, fCallback)
 	{
 		//this.log.trace(`Orator [${this.UUID}]::[${this.Hash}] ${this.options.Product} invoking ${pMethod} ${pRoute}`);
 		return this.serviceServer.invoke(pMethod, pRoute, pData, fCallback);
 	}
 	/*
-	 * Legacy Orator Functions
+	 * Legacy Orator / Backwards Compatibility Functions
 	 *************************************************************************/
+	/**
+	 * Starts the web server.
+	 *
+	 * @param {Function} fNext - The callback function to be executed after the web server starts.
+	 * @returns {Promise} A promise that resolves when the web server has started.
+	 */
 	startWebServer(fNext)
 	{
 		return this.startService(fNext);
 	}
-	// For legacy purposes
+	/**
+	 * Stops the web server.
+	 *
+	 * @param {Function} fNext - The callback function to be called after the web server is stopped.
+	 * @returns {Promise} A promise that resolves when the web server is stopped.
+	 */
 	stopWebServer(fNext)
 	{
 		return this.stopService(fNext);
 	}
-	// For legacy purposes
+	/**
+	 * Retrieves the web server instance.
+	 *
+	 * @returns {WebServer} The web server instance.
+	 */
 	getWebServer()
 	{
 		// The old behavior was to lazily construct the service the first time
@@ -260,6 +361,94 @@ class Orator extends libFableServiceProviderBase
 	/*************************************************************************
 	 * End of Legacy Orator Functions
 	 */
+	setMimeHeader(pFileName, pResponse)
+	{
+		let tmpHeader;
+		if (this.oldLibMime)
+		{
+			tmpHeader = libMime.lookup(pFileName);
+		}
+		else
+		{
+			tmpHeader = libMime.getType(pFileName);
+		}
+		if (!tmpHeader)
+		{
+			tmpHeader = 'application/octet-stream';
+		}
+		pResponse.setHeader('Content-Type', tmpHeader);
+	}
+	/**
+	 * Serve a static folder, optionally with magic subdomain masking.
+	 *
+	 * @param {string} pFilePath The path on disk that we are serving files from.
+	 * @param {string?} pDefaultFile (optional) The default file served if no specific file is requested.
+	 * @param {string?} pRoute (optional) The route matcher that will be used. Defaults to everything.
+	 * @param {string?} pRouteStrip (optional) If provided, this prefix will be removed from URL paths before being served.
+	 * @param {object?} pParams (optional) Additional parameters to pass to serve-static.
+	 * @return {boolean} true if the handler was successfully installed, otherwise false.
+	 */
+	addStaticRoute(pFilePath, pDefaultFile, pRoute, pRouteStrip, pParams)
+	{
+		if (typeof(pFilePath) !== 'string')
+		{
+				this.fable.log.error('A file path must be passed in as part of the server.');
+				return false;
+		}
+		// Default to just serving from root
+		const tmpRoute = (typeof(pRoute) === 'undefined') ? '/*' : pRoute;
+		const tmpRouteStrip = (typeof(pRouteStrip) === 'undefined') ? '/' : pRouteStrip;
+		// Default to serving index.html
+		const tmpDefaultFile = (typeof(pDefaultFile) === 'undefined') ? 'index.html' : pDefaultFile;
+		this.fable.log.info('Orator mapping static route to files: '+tmpRoute+' ==> '+pFilePath+' '+tmpDefaultFile);
+		// Add the route
+		this.serviceServer.get(tmpRoute,
+			(pRequest, pResponse, fNext) =>
+			{
+					// See if there is a magic subdomain put at the beginning of a request.
+					// If there is, then we need to see if there is a subfolder and add that to the file path
+					let tmpHostSet = pRequest.headers.host.split('.');
+					let tmpPotentialSubfolderMagicHost = false;
+					let servePath = pFilePath;
+					// Check if there are more than one host in the host header (this will be 127 a lot)
+					if (tmpHostSet.length > 1)
+					{
+						tmpPotentialSubfolderMagicHost = tmpHostSet[0];
+					}
+					if (tmpPotentialSubfolderMagicHost)
+					{
+						// Check if the subfolder exists -- this is only one dimensional for now
+						let tmpPotentialSubfolder = servePath + tmpPotentialSubfolderMagicHost;
+						if (this.fable.FilePersistence.libFS.existsSync(tmpPotentialSubfolder))
+						{
+							// If it does, then we need to add it to the file path
+							servePath = `${tmpPotentialSubfolder}/`;
+						}
+					}
+					pRequest.url = pRequest.url.split('?')[0].substr(tmpRouteStrip.length) || '/';
+					pRequest.path = function()
+					{
+							return pRequest.url;
+					};
+					this.setMimeHeader(pRequest.url, pResponse);
+					const tmpServe = libServeStatic(servePath, Object.assign({ index: tmpDefaultFile }, pParams));
+					tmpServe(pRequest, pResponse, libFinalHandler(pRequest, pResponse));
+					// TODO: This may break things if a post request send handler is setup...
+					//fNext();
+			});
+		return true;
+	}
 }
 module.exports = Orator;