meadow-endpoints 4.0.22 → 4.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meadow-endpoints",
-  "version": "4.0.22",
+  "version": "4.0.24",
   "description": "Automatic API endpoints for Meadow data.",
   "main": "source/Meadow-Endpoints.js",
   "scripts": {
@@ -35,7 +35,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/stevenvelozo/meadow-endpoints.git"
+    "url": "https://github.com/fable-retold/meadow-endpoints.git"
   },
   "keywords": [
     "crud",
@@ -44,9 +44,9 @@
   "author": "Steven Velozo <steven@velozo.com> (http://velozo.com/)",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/stevenvelozo/meadow-endpoints/issues"
+    "url": "https://github.com/fable-retold/meadow-endpoints/issues"
   },
-  "homepage": "https://github.com/stevenvelozo/meadow-endpoints",
+  "homepage": "https://github.com/fable-retold/meadow-endpoints",
   "devDependencies": {
     "alasql": "^4.17.2",
     "chance": "^1.1.13",
@@ -55,18 +55,18 @@
     "mysql2": "^3.22.1",
     "orator-serviceserver-restify": "^2.0.11",
     "papaparse": "^5.5.3",
-    "pict-docuserve": "^1.3.2",
-    "quackage": "^1.2.3",
+    "pict-docuserve": "^1.4.19",
+    "quackage": "^1.3.0",
     "supertest": "^7.2.2",
     "typescript": "^5.9.3",
     "why-is-node-running": "^3.2.2"
   },
   "dependencies": {
     "async": "3.2.6",
-    "fable": "^3.1.75",
+    "fable": "^3.1.78",
     "fable-serviceproviderbase": "^3.0.19",
     "JSONStream": "^1.3.5",
-    "meadow": "^2.0.41",
+    "meadow": "^2.0.46",
     "meadow-filter": "^1.0.10",
     "orator": "^6.1.2",
     "underscore": "^1.13.8"

package/source/Meadow-Endpoints.js

@@ -73,6 +73,9 @@ class MeadowEndpoints
 			Reads: require('./endpoints/read/Meadow-Endpoint-Reads.js'),
 			ReadsBy: require('./endpoints/read/Meadow-Endpoint-ReadsBy.js'),
 
+			// Body-driven read: filter/pagination/mode travel in a JSON POST body
+			Query: require('./endpoints/read/Meadow-Endpoint-Query.js'),
+
 			ReadSelectList: require('./endpoints/read/Meadow-Endpoint-ReadSelectList.js'),
 			ReadLiteList: require('./endpoints/read/Meadow-Endpoint-ReadLiteList.js'),
 			ReadDistinctList: require('./endpoints/read/Meadow-Endpoint-ReadDistinctList.js'),
@@ -183,6 +186,7 @@ class MeadowEndpoints
 		}
 		if (this._EnabledBehaviorSets.Reads)
 		{
+			this.connectRoute(pServiceServer, 'postWithBodyParser', `s/Query`, this._Endpoints.Query, `the internal behavior _Endpoints.Query`);
 			this.connectRoute(pServiceServer, 'get', `s`, this._Endpoints.Reads, `the internal behavior _Endpoints.Reads`);
 			this.connectRoute(pServiceServer, 'get', `s/By/:ByField/:ByValue`, this._Endpoints.ReadsBy, `the internal behavior _Endpoints.ReadsBy`);
 			this.connectRoute(pServiceServer, 'get', `s/By/:ByField/:ByValue/:Begin/:Cap`, this._Endpoints.ReadsBy, `the internal behavior _Endpoints.ReadsBy`);

package/source/controller/Meadow-Endpoints-Controller-Base.js

@@ -155,6 +155,46 @@ class MeadowEndpointControllerBase
 	{
 		return this._SessionMarshaler.getSessionData(pRequest);
 	}
+
+	/**
+	 * Stamp the request's session onto a meadow query so a downstream provider
+	 * can act under the caller's identity.
+	 *
+	 * Today only the MeadowEndpoints provider consumes this — when a beacon
+	 * fronts a remote meadow-endpoints API it presents this session upstream
+	 * (instead of its bound machine session) so the remote enforces row-level
+	 * auth as the real caller. SQL providers ignore the parameter. The override
+	 * rides the per-operation FoxHound query (concurrency-safe).
+	 *
+	 * No-op for the default/anonymous session (UserID 0 / SessionID 0x0000) —
+	 * those carry no identity, so the provider keeps its existing behavior.
+	 *
+	 * @param {object} pRequestState - the request state (carries SessionData + Query)
+	 * @returns {void}
+	 */
+	stampSessionOverrideOnQuery(pRequestState)
+	{
+		if (!pRequestState || !pRequestState.Query || !pRequestState.SessionData)
+		{
+			return;
+		}
+		let tmpSession = pRequestState.SessionData;
+		let tmpSessionID = tmpSession.SessionID;
+		if (typeof(tmpSessionID) !== 'string' || tmpSessionID.length < 1 || tmpSessionID === '0x0000')
+		{
+			return;
+		}
+		if (pRequestState.Query.query && pRequestState.Query.query.parameters)
+		{
+			pRequestState.Query.query.parameters.MeadowEndpointsSessionOverride = (
+				{
+					SessionID: tmpSessionID,
+					CustomerID: tmpSession.CustomerID,
+					UserID: tmpSession.UserID,
+					UserRoleIndex: tmpSession.UserRoleIndex
+				});
+		}
+	}
 }
 
 module.exports = MeadowEndpointControllerBase;

package/source/endpoints/count/Meadow-Endpoint-Count.js

@@ -11,6 +11,7 @@ const doAPIEndpointCount = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 				if (typeof(pRequest.params.Filter) === 'string')
 				{
 					// If a filter has been passed in, parse it and add the values to the query.

package/source/endpoints/count/Meadow-Endpoint-CountBy.js

@@ -11,6 +11,7 @@ const doAPIEndpointCountBy = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 				tmpRequestState.Query.addFilter(pRequest.params.ByField, pRequest.params.ByValue, '=', 'AND', 'RequestByField');
 				return fStageComplete();
 			},

package/source/endpoints/create/Meadow-Operation-Create.js

@@ -31,6 +31,7 @@ const doCreate = function(pRecord, pRequest, pRequestState, pResponse, fCallback
 		{
 			// Prepare create query
 			tmpRequestState.Query = this.DAL.query;
+			this.stampSessionOverrideOnQuery(tmpRequestState);
 			tmpRequestState.Query.setIDUser(tmpRequestState.SessionData.UserID);
 			tmpRequestState.Query.addRecord(tmpRequestState.RecordToCreate);
 			return fStageComplete();

package/source/endpoints/delete/Meadow-Endpoint-Delete.js

@@ -36,6 +36,7 @@ const doAPIEndpointDelete = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 				tmpRequestState.Query.addFilter(this.DAL.defaultIdentifier, tmpRequestState.IDRecord);
 				tmpRequestState.Query.setIDUser(tmpRequestState.SessionData.UserID);
 				return fStageComplete();

package/source/endpoints/delete/Meadow-Endpoint-Undelete.js

@@ -54,6 +54,7 @@ const doAPIEndpointUndelete = function(pRequest, pResponse, fNext)
 			{
 				// Now see if the record, with this identifier, for this user, exists with the deleted bit set to 1
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 				tmpRequestState.Query.addFilter(this.DAL.defaultIdentifier, tmpIDRecord);
 				tmpRequestState.Query.addFilter('Deleted', 1);
 				tmpRequestState.Query.setIDUser(tmpRequestState.SessionData.UserID);

package/source/endpoints/read/Meadow-Endpoint-Query.js

@@ -0,0 +1,86 @@
+/**
+* Meadow Endpoint - Body-driven Read
+*
+* A single POST endpoint that carries the filter, pagination and read-mode
+* selection in a JSON body instead of the URI. This sidesteps URI length
+* limits hit by complex filters and large IN-lists, while reusing the exact
+* GET read handlers (and therefore their behavior hooks, marshalling and
+* response shapes) by mapping the body onto pRequest.params and delegating.
+*
+* Body envelope:
+*   {
+*     "Filter": "FBV~Genre~EQ~Books~...",   // meadow-filter string
+*     "Begin": 0,
+*     "Cap": 250,
+*     "ExtraColumns": "ColumnA,ColumnB",    // Lite read
+*     "Columns": "ColumnA,ColumnB",         // Distinct read
+*     "Lite": true, "Distinct": true, "Count": true
+*   }
+*
+* The read mode is selected by the flags, resolved by precedence:
+* Count > Distinct > Lite > Reads (the default). This lets a caller compose a
+* read query (filter, pagination, Lite/Distinct shaping) and flip Count on to
+* get the count of that same query.
+*/
+const doReads = require('./Meadow-Endpoint-Reads.js');
+const doReadLite = require('./Meadow-Endpoint-ReadLiteList.js');
+const doReadDistinct = require('./Meadow-Endpoint-ReadDistinctList.js');
+const doCount = require('../count/Meadow-Endpoint-Count.js');
+
+// Body keys hydrated onto pRequest.params so the delegated GET handlers see
+// the same inputs they read from the URI.
+const PARAM_KEYS = [ 'Filter', 'Begin', 'Cap', 'ExtraColumns', 'Columns' ];
+
+/**
+* Resolve the read mode from the request body flags, by precedence:
+* Count > Distinct > Lite > Reads (the default).
+*
+* @param {Record<string, any>} pBody - the parsed request body
+*
+* @return {string} one of 'Count', 'Distinct', 'Lite', 'Reads'
+*/
+const resolveMode = function(pBody)
+{
+	if (pBody.Count)
+	{
+		return 'Count';
+	}
+	if (pBody.Distinct)
+	{
+		return 'Distinct';
+	}
+	if (pBody.Lite)
+	{
+		return 'Lite';
+	}
+	return 'Reads';
+};
+
+const doAPIEndpointQuery = function(pRequest, pResponse, fNext)
+{
+	const tmpBody = (pRequest.body && typeof(pRequest.body) === 'object') ? pRequest.body : {};
+	pRequest.params = (pRequest.params && typeof(pRequest.params) === 'object') ? pRequest.params : {};
+
+	for (let i = 0; i < PARAM_KEYS.length; i++)
+	{
+		if (typeof(tmpBody[PARAM_KEYS[i]]) !== 'undefined')
+		{
+			pRequest.params[PARAM_KEYS[i]] = tmpBody[PARAM_KEYS[i]];
+		}
+	}
+
+	switch (resolveMode(tmpBody))
+	{
+		case 'Count':
+			return doCount.call(this, pRequest, pResponse, fNext);
+		case 'Distinct':
+			return doReadDistinct.call(this, pRequest, pResponse, fNext);
+		case 'Lite':
+			return doReadLite.call(this, pRequest, pResponse, fNext);
+		case 'Reads':
+		default:
+			return doReads.call(this, pRequest, pResponse, fNext);
+	}
+};
+
+module.exports = doAPIEndpointQuery;

package/source/endpoints/read/Meadow-Endpoint-Read.js

@@ -11,6 +11,7 @@ const doAPIEndpointRead = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 				return fStageComplete();
 			},
 			fBehaviorInjector(`Read-PreOperation`),

package/source/endpoints/read/Meadow-Endpoint-ReadDistinctList.js

@@ -15,6 +15,7 @@ const doAPIEndpointReadDistinct = function(pRequest, pResponse, fNext)
 		(fStageComplete) =>
 		{
 			tmpRequestState.Query = this.DAL.query.setDistinct(true);
+			this.stampSessionOverrideOnQuery(tmpRequestState);
 
 			/** @type {number | boolean} */
 			let tmpCap = false;

package/source/endpoints/read/Meadow-Endpoint-ReadLiteList.js

@@ -14,6 +14,7 @@ const doAPIEndpointReadLite = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 				// TODO: Limit the query to the columns we need for the templated expression
 
 				/** @type {number | boolean} */

package/source/endpoints/read/Meadow-Endpoint-ReadMax.js

@@ -11,6 +11,7 @@ const doAPIEndpointReadMax = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 				return fStageComplete();
 			},
 			(fStageComplete) =>

package/source/endpoints/read/Meadow-Endpoint-ReadSelectList.js

@@ -11,6 +11,7 @@ const doAPIEndpointReadSelectList = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 
 				/** @type {number | boolean} */
 				var tmpCap = false;

package/source/endpoints/read/Meadow-Endpoint-Reads.js

@@ -11,6 +11,7 @@ const doAPIEndpointReads = function(pRequest, pResponse, fNext)
 		(fStageComplete) =>
 		{
 			tmpRequestState.Query = this.DAL.query;
+			this.stampSessionOverrideOnQuery(tmpRequestState);
 
 			/** @type {number | boolean} */
 			var tmpCap = false;

package/source/endpoints/read/Meadow-Endpoint-ReadsBy.js

@@ -12,6 +12,7 @@ const doAPIEndpointReadsBy = function(pRequest, pResponse, fNext)
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 
 				/** @type {number | boolean} */
 				var tmpCap = false;

package/source/endpoints/update/Meadow-Operation-Update.js

@@ -33,6 +33,7 @@ const doUpdate = function(pRecordToModify, pRequest, pRequestState, pResponse, f
 			else
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 
 				tmpRequestState.Query.addFilter(this.DAL.defaultIdentifier, tmpRequestState.RecordToModify[this.DAL.defaultIdentifier]);
 
@@ -64,6 +65,7 @@ const doUpdate = function(pRecordToModify, pRequest, pRequestState, pResponse, f
 		(fStageComplete) =>
 		{
 			tmpRequestState.Query = this.DAL.query;
+			this.stampSessionOverrideOnQuery(tmpRequestState);
 			return fStageComplete();
 		},
 		fBehaviorInjector(`Update-PreOperation`),

package/source/endpoints/upsert/Meadow-Operation-Upsert.js

@@ -14,6 +14,7 @@ const doUpsert = function(pRecordToUpsert, pRequest, pRequestState, pResponse, f
 			(fStageComplete) =>
 			{
 				tmpRequestState.Query = this.DAL.query;
+				this.stampSessionOverrideOnQuery(tmpRequestState);
 
 				// Prepare to gather requirements for upserting
 				tmpRequestState.Record = pRecordToUpsert;

package/test/MeadowEndpoints_SessionOverride_tests.js

@@ -0,0 +1,75 @@
+/**
+ * Meadow Endpoints — per-request session override stamping.
+ *
+ * stampSessionOverrideOnQuery copies a real request session onto the meadow
+ * query (Query.query.parameters.MeadowEndpointsSessionOverride) so a
+ * downstream provider (the MeadowEndpoints provider, when a beacon fronts a
+ * remote API) can act under the caller's identity. The default/anonymous
+ * session is a no-op.
+ *
+ *   npx mocha test/MeadowEndpoints_SessionOverride_tests.js -u tdd --exit
+ */
+
+const Chai = require('chai');
+const Expect = Chai.expect;
+
+const libFable = require('fable');
+const libMeadow = require('meadow');
+const libMeadowEndpointsControllerBase = require('../source/controller/Meadow-Endpoints-Controller-Base.js');
+
+const _BookSchema = require('../test_support/model/meadow_schema/BookStore-MeadowSchema-Book.json');
+
+function buildController()
+{
+	let tmpFable = new libFable({ Product: 'SessionOverrideTest', LogStreams: [ { streamtype: 'console', level: 'fatal' } ] });
+	let tmpMeadow = libMeadow.new(tmpFable, 'Book')
+		.setSchema(_BookSchema.Schema)
+		.setJsonSchema(_BookSchema.JsonSchema)
+		.setDefaultIdentifier(_BookSchema.DefaultIdentifier)
+		.setDefault(_BookSchema.DefaultObject);
+	return new libMeadowEndpointsControllerBase({ DAL: tmpMeadow, _ControllerOptions: {} });
+}
+
+function realSession()
+{
+	return { SessionID: 'caller-session-xyz', CustomerID: 182, UserID: 5150, UserRoleIndex: 3, LoggedIn: true };
+}
+
+suite('Meadow-Endpoints session override stamping', () =>
+{
+	test('a real session is stamped onto the query parameters', () =>
+	{
+		let tmpController = buildController();
+		let tmpRequestState = { SessionData: realSession(), Query: tmpController.DAL.query };
+		tmpController.stampSessionOverrideOnQuery(tmpRequestState);
+		let tmpOverride = tmpRequestState.Query.query.parameters.MeadowEndpointsSessionOverride;
+		Expect(tmpOverride).to.be.an('object');
+		Expect(tmpOverride.SessionID).to.equal('caller-session-xyz');
+		Expect(tmpOverride.CustomerID).to.equal(182);
+		Expect(tmpOverride.UserID).to.equal(5150);
+	});
+
+	test('the default/anonymous session (0x0000) is a no-op', () =>
+	{
+		let tmpController = buildController();
+		let tmpRequestState = { SessionData: { SessionID: '0x0000', UserID: 0 }, Query: tmpController.DAL.query };
+		tmpController.stampSessionOverrideOnQuery(tmpRequestState);
+		Expect(tmpRequestState.Query.query.parameters.MeadowEndpointsSessionOverride).to.equal(undefined);
+	});
+
+	test('a missing SessionID is a no-op', () =>
+	{
+		let tmpController = buildController();
+		let tmpRequestState = { SessionData: { UserID: 5 }, Query: tmpController.DAL.query };
+		tmpController.stampSessionOverrideOnQuery(tmpRequestState);
+		Expect(tmpRequestState.Query.query.parameters.MeadowEndpointsSessionOverride).to.equal(undefined);
+	});
+
+	test('missing Query or SessionData does not throw', () =>
+	{
+		let tmpController = buildController();
+		Expect(() => tmpController.stampSessionOverrideOnQuery({})).to.not.throw();
+		Expect(() => tmpController.stampSessionOverrideOnQuery({ SessionData: realSession() })).to.not.throw();
+		Expect(() => tmpController.stampSessionOverrideOnQuery(null)).to.not.throw();
+	});
+});

package/test/MeadowEndpoints_basic_tests.js

@@ -505,6 +505,103 @@ suite
 					}
 				);
 				test
+				(
+					"query: reads all records via JSON body (default mode)",
+					function (fDone)
+					{
+						_SuperTest
+							.post("1.0/Books/Query")
+							.send({})
+							.end(
+								(pError, pResponse) =>
+								{
+									Expect(pError).to.not.exist;
+									let tmpResult = JSON.parse(pResponse.text);
+									Expect(tmpResult).to.be.an("array");
+									Expect(tmpResult.length).to.be.at.least(5);
+									fDone();
+								}
+							);
+					}
+				);
+				test
+				(
+					"query: reads with filter and pagination in the body",
+					function (fDone)
+					{
+						_SuperTest
+							.post("1.0/Books/Query")
+							.send({ Filter: "FBV~Genre~LK~%Science%", Begin: 0, Cap: 1 })
+							.end(
+								(pError, pResponse) =>
+								{
+									let tmpResult = JSON.parse(pResponse.text);
+									Expect(tmpResult).to.be.an("array");
+									Expect(tmpResult.length).to.equal(1);
+									Expect(tmpResult[0].Genre).to.contain("Science");
+									fDone();
+								}
+							);
+					}
+				);
+				test
+				(
+					"query: Lite read via boolean flag",
+					function (fDone)
+					{
+						_SuperTest
+							.post("1.0/Books/Query")
+							.send({ Lite: true, Begin: 0, Cap: 3 })
+							.end(
+								(pError, pResponse) =>
+								{
+									let tmpResult = JSON.parse(pResponse.text);
+									Expect(tmpResult).to.be.an("array");
+									Expect(tmpResult.length).to.equal(3);
+									fDone();
+								}
+							);
+					}
+				);
+				test
+				(
+					"query: Distinct read via boolean flag and Columns",
+					function (fDone)
+					{
+						_SuperTest
+							.post("1.0/Books/Query")
+							.send({ Distinct: true, Columns: "Genre" })
+							.end(
+								(pError, pResponse) =>
+								{
+									let tmpResult = JSON.parse(pResponse.text);
+									Expect(tmpResult).to.be.an("array");
+									Expect(tmpResult.length).to.be.at.least(1);
+									fDone();
+								}
+							);
+					}
+				);
+				test
+				(
+					"query: Count flag takes precedence and honors the filter",
+					function (fDone)
+					{
+						_SuperTest
+							.post("1.0/Books/Query")
+							.send({ Lite: true, Count: true, Filter: "FBV~Genre~LK~%Science%" })
+							.end(
+								(pError, pResponse) =>
+								{
+									let tmpResult = JSON.parse(pResponse.text);
+									Expect(tmpResult).to.have.property("Count");
+									Expect(tmpResult.Count).to.be.at.least(3);
+									fDone();
+								}
+							);
+					}
+				);
+				test
 				(
 					'reads by: get records filtered by a field value',
 					function (fDone)