meadow-endpoints 3.0.7 → 4.0.3

package/source/Controller/components/Meadow-Endpoints-Controller-Error.js

@@ -0,0 +1,118 @@
+class MeadowEndpointsControllerErrorBase
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+    // Get the error object
+    getError(pMessage, pStatusCode, pSuppressSoftwareTrace)
+    {
+		let tmpError = new Error(pMessage);
+
+    	// Default the error status code to 400 if none is passed
+		tmpError.StatusCode = (typeof(pStatusCode) == 'number') ? pStatusCode : 400;
+		// This suppresses the stack trace from being sent back or logged.
+		// And by default it does not send a stack trace, as we expect errors created this way to be protocol, schema or data related.
+		tmpError.SuppressSoftwareTrace = (typeof(pSuppressSoftwareTrace) != 'undefined') ? pSuppressSoftwareTrace : true;
+
+        return tmpError;
+    }
+
+    // Handle an error if set -- some errors don't send the response back because they aren't fully errory errors.
+	handleErrorIfSet(pRequest, pRequestState, pResponse, pError, fCallback)
+	{
+		if (pError)
+		{
+			return this.sendError(pRequest, pRequestState, pResponse, pError, fCallback);
+		}
+
+		return fCallback();
+	}
+
+    // Send an error object
+	sendError(pRequest, pRequestState, pResponse, pError, fCallback)
+	{
+		this._Controller.log.logRequestError(pRequest, pRequestState, pError);
+
+		// TODO: Detect if we've already sent headers?
+		if (!this._Controller.ControllerOptions.SendErrorStatusCodes)
+		{
+			let tmpStatusCode = (pError.hasOwnProperty('StatusCode')) ? pError.StatusCode : 500;
+			pResponse.status(tmpStatusCode);
+		}
+
+		let tmpResponseObject = (
+			{
+				Error:pError.message,
+				StatusCode:pError.StatusCode
+			});
+
+		tmpResponseObject = this._Controller.ErrorHandler.prepareRequestContextOutputObject(tmpResponseObject, pRequest, pRequestState, pError);
+
+		pResponse.send(tmpResponseObject);
+
+		fCallback(pError);
+	}
+
+	// This looks for some generic markers in the request state and puts them into a log or send object
+	prepareRequestContextOutputObject(pObjectToPopulate, pRequest, pRequestState, pError)
+	{
+		// Internally created errors supress stack traces
+		if (pError)
+		{
+			pObjectToPopulate.Error = pError.message;
+			pObjectToPopulate.Code = pError.code;
+			pObjectToPopulate.StatusCode = pError.StatusCode;
+
+			if (!pError.SuppressSoftwareTrace)
+			{
+				pObjectToPopulate.Stack = pError.stack;
+			}
+
+			if (pRequestState.hasOwnProperty('Record'))
+			{
+				pObjectToPopulate.Record = pRequestState.Record;
+			}
+
+			if (pRequestState.hasOwnProperty('Query') && (typeof(pRequestState.Query) == 'object'))
+			{
+				if (pRequestState.Query.query)
+				{
+					if (typeof(pRequestState.Query.query.body) == 'string')
+					{
+						pObjectToPopulate.Query = pRequestState.Query.query.body;
+					}
+
+					if ((typeof(pRequestState.Query.query.parameters) == 'object'))
+					{
+						pObjectToPopulate.QueryParameters = pRequestState.Query.query.parameters;
+
+						pObjectToPopulate.RebuiltQueryString = (typeof(pObjectToPopulate.Query) == 'string') ? pObjectToPopulate.Query : '';
+
+						// This gnarly bit of code attempts to reconstruct a non prepared string version of the query, to help.
+						let tmpQueryParameterSet = Object.keys(pObjectToPopulate.QueryParameters);
+						for (let i = 0; i < tmpQueryParameterSet.length; i++)
+						{
+							switch(typeof(tmpQueryParameterSet[i]))
+							{
+								case 'number':
+									pObjectToPopulate.RebuiltQueryString  = pObjectToPopulate.RebuiltQueryString.replace(new RegExp(`:${tmpQueryParameterSet[i]}\\b`, 'g'), `'${pObjectToPopulate.QueryParameters[tmpQueryParameterSet[i]]}'`);
+									break;
+								case 'string':
+									// TODO: This may need more ... nuance...
+									default:
+									pObjectToPopulate.RebuiltQueryString  = pObjectToPopulate.RebuiltQueryString.replace(new RegExp(`:${tmpQueryParameterSet[i]}\\b`,'g'), pObjectToPopulate.QueryParameters[tmpQueryParameterSet[i]]);
+									break;
+							}
+						}
+					}
+				}
+			}
+		}
+
+		return pObjectToPopulate;
+	}
+}
+
+module.exports = MeadowEndpointsControllerErrorBase;

package/source/Controller/components/Meadow-Endpoints-Controller-Log.js

@@ -0,0 +1,103 @@
+class MeadowEndpointsControllerLogBase
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+	// This is called for every successful request log line.  Be careful what you add in overloads!
+	prepareLogData(pRequest, pRequestState, pLogData)
+	{
+		// TODO: Discuss if these should be configurations
+		if (pRequestState.hasOwnProperty('Record'))
+		{
+			if (pRequestState.Record.hasOwnProperty(this._Controller.DAL.defaultIdentifier))
+			{
+				pLogData[this._Controller.DAL.defaultIdentifier] = pRequestState.Record[this._Controller.DAL.defaultIdentifier];
+			}
+			if (pRequestState.Record.hasOwnProperty(this._Controller.DAL.defaultGUIdentifier))
+			{
+				pLogData[this._Controller.DAL.defaultGUIdentifier] = pRequestState.Record[this._Controller.DAL.defaultGUIdentifier];
+			}
+		}
+		if (pRequestState.hasOwnProperty('UpdatedRecords'))
+		{
+			pLogData.UpdatedRecordCount = pRequestState.UpdatedRecords.length;
+		}
+		if (pRequestState.hasOwnProperty('CreatedRecords'))
+		{
+			pLogData.UpdatedRecordCount = pRequestState.CreatedRecords.length;
+		}
+		if (pRequestState.hasOwnProperty('UpsertedRecords'))
+		{
+			pLogData.UpdatedRecordCount = pRequestState.UpsertedRecords.length;
+		}
+		return pLogData;
+	}
+
+    // This is called whenever an endpoint is completed successfully
+	requestCompletedSuccessfully(pRequest, pRequestState, pActionSummary)
+	{
+		let tmpLogData = (
+			{
+				SessionID: pRequestState.SessionData.SessionID,
+				RequestID: pRequest.RequestUUID,
+				RequestURL: pRequest.url,
+				Scope: this._Controller.DAL.scope,
+				Action: `${this._Controller.DAL.scope}-${pRequestState.Verb}`,
+				Verb: pRequestState.Verb
+			});
+
+		this._Controller.log.info(pActionSummary, this.prepareLogData(pRequest, pRequestState, tmpLogData));
+	}
+
+    // This is called whenever an endpoint is completed successfully
+	logRequestError(pRequest, pRequestState, pError)
+	{
+		let tmpErrorLogData = (
+			{
+				SessionID: pRequestState.SessionData.SessionID,
+				RequestID: pRequest.RequestUUID,
+				RequestURL: pRequest.url,
+				Scope: this._Controller.DAL.scope,
+				Action: `${this._Controller.DAL.scope}-${pRequestState.Verb}`,
+				Verb: pRequestState.Verb,
+			});
+
+		tmpErrorLogData = this._Controller.ErrorHandler.prepareRequestContextOutputObject(tmpErrorLogData, pRequest, pRequestState, pError);
+
+		this._Controller.log.error(pError.message, this.prepareLogData(pRequest, pRequestState, tmpErrorLogData));
+	}
+
+    trace(pLogText, pLogObject)
+	{
+		this._Controller.DAL.log.trace(pLogText, pLogObject);
+	}
+
+	debug(pLogText, pLogObject)
+	{
+		this._Controller.DAL.log.debug(pLogText, pLogObject);
+	}
+
+	info(pLogText, pLogObject)
+	{
+		this._Controller.DAL.log.info(pLogText, pLogObject);
+	}
+
+	warn(pLogText, pLogObject)
+	{
+		this._Controller.DAL.log.warn(pLogText, pLogObject);
+	}
+
+	error(pLogText, pLogObject)
+	{
+		this._Controller.DAL.log.error(pLogText, pLogObject);
+	}
+
+	fatal(pLogText, pLogObject)
+	{
+		this._Controller.DAL.log.fatal(pLogText, pLogObject);
+	}
+}
+
+module.exports = MeadowEndpointsControllerLogBase;

package/source/Controller/utility/Meadow-Endpoints-Filter-Parser.js

@@ -0,0 +1,225 @@
+/**
+* Meadow Endpoint Utility Class - Parse a Filter String and put it into a Query.
+*
+* @license MIT
+*
+* @author Steven Velozo <steven@velozo.com>
+* @module Meadow
+*/
+/**
+* Parse GET-passed Filter Strings, turn the results into proper Meadow query stanzas
+
+ Take the filter and return an array of filter instructions
+ Basic instruction anatomy:
+       INSTRUCTION~FIELD~OPERATOR~VALUE
+ FOP - Filter Open Paren
+       FOP~0~(~0
+ FCP - Filter Close Paren
+       FCP~0~)~0
+ FBV - Filter By Value (left-side AND connected)
+       FBV~Category~EQ~Books
+       Possible comparisons:
+       * EQ - Equals To (=)
+       * NE - Not Equals To (!=)
+       * GT - Greater Than (>)
+       * GE - Greater Than or Equals To (>=)
+       * LT - Less Than (<)
+       * LE - Less Than or Equals To (<=)
+       * LK - Like (Like)
+       * IN - Is NULL
+       * NN - Is NOT NULL
+       * INN - IN list
+ FBVOR - Filter By Value (left-side OR connected)
+ FBL - Filter By List (value list, separated by commas)
+       FBL~Category~EQ~Books,Movies
+ FBD - Filter by Date (exclude time)
+       FBD~UpdateDate~EQ~2015-10-01
+ FSF - Filter Sort Field
+       FSF~Category~ASC~0
+       FSF~Category~DESC~0
+ FDST - Filter by Distinct (adds distinct keyword to Read and Count queries)
+       FDST~0~0~0~
+
+ This means: FBV~Category~EQ~Books~FBV~PublishedYear~GT~2000~FSF~PublishedYear~DESC~0
+             Filters down to ALL BOOKS PUBLUSHED AFTER 2000 IN DESCENDING ORDER
+*/
+
+class MeadowEndpointsFilterParser
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+    // Get the comparison operator for use in a query stanza
+    getFilterComparisonOperator(pFilterOperator)
+    {
+        let tmpOperator = '=';
+        switch(pFilterOperator)
+        {
+            case 'EQ':
+                tmpOperator = '=';
+                break;
+            case 'NE':
+                tmpOperator = '!=';
+                break;
+            case 'GT':
+                tmpOperator = '>';
+                break;
+            case 'GE':
+                tmpOperator = '>=';
+                break;
+            case 'LT':
+                tmpOperator = '<';
+                break;
+            case 'LE':
+                tmpOperator = '<=';
+                break;
+            case 'LK':
+                tmpOperator = 'LIKE';
+                break;
+            case 'NLK':
+                tmpOperator = 'NOT LIKE';
+                break;
+            case 'IN':
+                tmpOperator = 'IS NULL';
+                break;
+            case 'NN':
+                tmpOperator = 'IS NOT NULL';
+                break;
+            case 'INN':
+                tmpOperator = 'IN';
+                break;
+            case 'FOP':
+                tmpOperator = '(';
+                break;
+            case 'FCP':
+                tmpOperator = ')';
+                break;
+        }
+        return tmpOperator;
+    }
+
+    addFilterStanzaToQuery(pFilterStanza, pQuery)
+    {
+        if (!pFilterStanza.Instruction)
+        {
+            return false;
+        }
+
+        switch(pFilterStanza.Instruction)
+        {
+            case 'FBV':   // Filter by Value (left-side AND)
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value, this.getFilterComparisonOperator(pFilterStanza.Operator), 'AND');
+                break;
+
+            case 'FBVOR': // Filter by Value (left-side OR)
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value, this.getFilterComparisonOperator(pFilterStanza.Operator), 'OR');
+                break;
+
+            case 'FBL':   // Filter by List (left-side AND)
+                // Just split the value by comma for now.  May want to revisit better characters or techniques later.
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'AND');
+                break;
+
+            case 'FBLOR': // Filter by List (left-side OR)
+                // Just split the value by comma for now.  May want to revisit better characters or techniques later.
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'OR');
+                break;
+
+            case 'FBD': // Filter by Date (exclude time)
+                pQuery.addFilter(`DATE(${pFilterStanza.Field})`, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'AND', pFilterStanza.Field);
+                break;
+
+            case 'FBDOR': // Filter by Date (exclude time)
+                pQuery.addFilter(`DATE(${pFilterStanza.Field})`, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'OR', pFilterStanza.Field);
+                break;
+
+            case 'FSF':   // Filter Sort Field
+                const tmpSortDirection = (pFilterStanza.Operator === 'DESC') ? 'Descending' : 'Ascending';
+                pQuery.addSort({ Column: pFilterStanza.Field, Direction: tmpSortDirection });
+                break;
+
+            case 'FOP':   // Filter Open Paren
+                pQuery.addFilter('', '', '(');
+                break;
+
+            case 'FCP':   // Filter Close Paren
+                pQuery.addFilter('', '', ')');
+                break;
+
+            case 'FDST':   // Filter Distinct
+                // ensure we don't break if using an older foxhound version
+                if (pQuery.setDistinct)
+                {
+                    pQuery.setDistinct(true);
+                }
+                break;
+
+            default:
+                //console.log('Unparsable filter stanza.');
+                return false;
+                break;
+        }
+
+        // Be paranoid about the instruction
+        pFilterStanza.Instruction = false;
+        return true;
+    };
+
+    parseFilter(pFilterString, pQuery)
+    {
+        if (typeof(pFilterString) !== 'string')
+        {
+            return false;
+        }
+
+        const tmpFilterTerms = pFilterString.split('~');
+
+        if (tmpFilterTerms.length < 4)
+        {
+            return true;
+        }
+
+        let tmpFilterStanza = { Instruction: false };
+
+        for (let i = 0; i < tmpFilterTerms.length; i++)
+        {
+            switch(i % 4)
+            {
+                case 0:  // INSTRUCTION
+                    this.addFilterStanzaToQuery(tmpFilterStanza, pQuery);
+                    //console.log(i+' Instruction: '+tmpFilterTerms[i]);
+                    tmpFilterStanza = (
+                    {
+                        Instruction: tmpFilterTerms[i],
+                        Field: '',
+                        Operator: '',
+                        Value: ''
+                    });
+                    break;
+
+                case 1:  // FIELD
+                    //console.log(i+' Field:       '+tmpFilterTerms[i]);
+                    tmpFilterStanza.Field = tmpFilterTerms[i];
+                    break;
+
+                case 2:  // OPERATOR
+                    //console.log(i+' Operator:    '+tmpFilterTerms[i]);
+                    tmpFilterStanza.Operator = tmpFilterTerms[i];
+                    break;
+
+                case 3:  // VALUE
+                    //console.log(i+' Value:       '+tmpFilterTerms[i]);
+                    tmpFilterStanza.Value = tmpFilterTerms[i];
+                    break;
+            }
+        }
+
+        this.addFilterStanzaToQuery(tmpFilterStanza, pQuery);
+
+        return true;
+    };
+}
+
+module.exports = MeadowEndpointsFilterParser;

package/source/Controller/utility/Meadow-Endpoints-Session-Marshaler.js

@@ -0,0 +1,48 @@
+class MeadowEndpointsSessionMarshaler
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+    getSessionData(pRequest)
+    {
+        let tmpSession = Object.assign({}, this._Controller.settings.MeadowEndpointsDefaultSessionObject);
+
+        switch (this._Controller.settings.MeadowEndpointsSessionDataSource || 'Request')
+        {
+            default:
+                this._LogController.warn(`Unknown session source configured: ${_SessionDataSource} - defaulting to Request for backward compatibility`);
+            case 'Request':
+                // noop - already set by orator-session
+                tmpSession = this._Controller.extend(tmpSession, pRequest.UserSession);
+                break;
+            case 'None':
+                break;
+            case 'Header':
+                try
+                {
+                    const tmpHeaderSessionString = pRequest.headers['x-trusted-session'];
+                    if (!tmpHeaderSessionString)
+                    {
+                        break;
+                    }
+                    tmpHeaderSession = JSON.parse(tmpHeaderSessionString);
+                    tmpSession = this._Controller.extend(tmpSession, pRequest.tmpHeaderSession);
+                }
+                catch (pError)
+                {
+                    this._LogController.error(`Meadow Endpoints attempted to process a Header Session String with value [${tmpHeaderSessionString}] and failed -- likely culprit is bad JSON.`)
+                }
+                break;
+        }
+
+        // Do we keep this here for backwards compatibility?
+        // Yes this makes sense here.
+        pRequest.UserSession = tmpSession;
+
+        return tmpSession;
+    }
+}
+
+module.exports = MeadowEndpointsSessionMarshaler;

package/source/Controller/utility/Meadow-Endpoints-Stream-RecordArray.js

@@ -0,0 +1,66 @@
+/**
+* Meadow Endpoint Streamer - Stream an array of recods as JSON to an output stream.
+*/
+const libAsyncEachSeries = require('async/eachSeries');
+const JSONStream = require('JSONStream');
+
+class MeadowEndpointsStreamRecordArray
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+	chunk(pInput, pChunkSize, pChunkCache)
+	{
+		let tmpInputArray = [...pInput];
+		// Note lodash defaults to 1, underscore defaults to 0
+		let tmpChunkSize = (typeof(pChunkSize) == 'number') ? pChunkSize : 0;
+		let tmpChunkCache = (typeof(pChunkCache) != 'undefined') ? pChunkCache : [];
+
+		if (tmpChunkSize <= 0)
+		{
+			return tmpChunkCache;
+		}
+
+		while (tmpInputArray.length)
+		{
+			tmpChunkCache.push(tmpInputArray.splice(0, tmpChunkSize));
+		}
+
+		return tmpChunkCache;
+	}
+
+	streamRecordArray(pResponse, pRecords, fCallback)
+	{
+		// for meadow invoke, writeHead isn't provided, so just call send(), which is the shim it uses...
+		// also, for small arrays, don't bother with the async serialization; this threshold could use tuning
+		if (!pResponse.writeHead || !Array.isArray(pRecords) || pRecords.length < 2500)
+		{
+			pResponse.send(pRecords);
+			return fCallback();
+		}
+
+		pResponse.writeHead(200,
+		{
+			'content-type': 'application/json',
+		});
+
+		const recordJsonMarshaller = JSONStream.stringify();
+		recordJsonMarshaller.pipe(pResponse);
+
+		// we write the records in chunks; doing one per loop is very inefficient, doing all is the same as not doing this at all
+		libAsyncEachSeries(this.chunk(pRecords, 1000), (pRecordChunk, fNext) =>
+		{
+			pRecordChunk.forEach(recordJsonMarshaller.write);
+			setImmediate(fNext);
+		},
+		(error) =>
+		{
+			recordJsonMarshaller.end();
+			fCallback(error);
+		});
+	}
+}
+
+module.exports = MeadowEndpointsStreamRecordArray;

package/source/Meadow-Endpoints-Browser-Shim.js

@@ -0,0 +1,14 @@
+/**
+* Simple browser shim loader - assign the npm module to a window global automatically
+*
+* @license MIT
+* @author <steven@velozo.com>
+*/
+var libNPMModuleWrapper = require('./Meadow-Endpoints.js');
+
+if ((typeof(window) === 'object') && !window.hasOwnProperty('MeadowEndpoints'))
+{
+	window.MeadowEndpoints = libNPMModuleWrapper;
+}
+
+module.exports = libNPMModuleWrapper;