soajs.controller 4.3.4 → 4.3.5

package/docs/request-flow.md

@@ -47,13 +47,25 @@ The complete request lifecycle through the SOAJS Controller Gateway.
        │                                                                  │
        ▼                                                                  │
 ┌──────────────┐                                                          │
-│ 7. Traffic   │ Rate limiting with configurable                          │
+│ 7.Idempotency│ Check Idempotency-Key header                             │
+│   Check      │ Return cached response or lock key                       │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 8. Traffic   │ Rate limiting with configurable                          │
 │   Control    │ strategies and storage backends                          │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 9. Response  │ Check cache for GET requests                             │
+│   Caching    │ Return cached response or proceed                        │
 └──────┬───────┘                                                          │
        │                                                                  │
        ▼                                                                  │
 ┌──────────────────────────────────────────────────────────────────┬──────┘
-│ 8. PROXY TO SERVICE                                              │
+│ 10. PROXY TO SERVICE                                             │
 │                                                                  │
 │  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐  │
 │  │  Resolve Host   │───▶│  Build Request  │───▶│  HTTP Proxy  │  │
@@ -120,14 +132,33 @@ The complete request lifecycle through the SOAJS Controller Gateway.
 - ACL enforcement
 - OAuth token validation
 
-### 7. Traffic Control
+### 7. Idempotency Check
+
+**Middleware:** `mw/idempotency/index.js`
+
+- Checks for `Idempotency-Key` header (UUID v4)
+- Returns cached response for completed requests
+- Returns 409 Conflict for in-flight requests
+- Locks key and proceeds for new requests
+- Stores response after completion
+
+### 8. Traffic Control
 
 **Middleware:** `mw/traffic/index.js`
 
 - Rate limiting per strategy
 - Response headers (X-RateLimit-*)
 
-### 8. Proxy to Service
+### 9. Response Caching
+
+**Middleware:** `mw/cache/index.js`
+
+- Caches GET API responses
+- Returns cached response on cache hit
+- Adds X-Cache and X-Cache-Age headers
+- Stores response after backend call
+
+### 10. Proxy to Service
 
 **Middleware:** `mw/gotoService/*`
 

package/lib/request.js

@@ -409,6 +409,11 @@ function proxyRequestMonitor(req, res, options, extraOptions = {}) {
             }
             let resContentType = proxyRes.headers['content-type'];
 
+            // Emit statusCode event for caching
+            if (extraOptions && extraOptions.events && extraOptions.events.statusCode) {
+                extraOptions.events.statusCode(proxyRes.statusCode, proxyRes.headers);
+            }
+
             if (extraOptions && extraOptions.events && extraOptions.events.response) {
                 extraOptions.events.response(resContentType);
             }

package/mw/cache/index.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * @license
+ * Copyright SOAJS All Rights Reserved.
+ *
+ * Use of this source code is governed by an Apache license that can be
+ * found in the LICENSE file at the root of this repository
+ */
+
+const crypto = require('crypto');
+const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
+const memory = require('./model/memory.js');
+const mongo = require('./model/mongo.js');
+
+let model = { memory, mongo };
+
+function hashQuery(query) {
+	if (!query || Object.keys(query).length === 0) {
+		return '';
+	}
+	const sortedQuery = Object.keys(query).sort().reduce((obj, key) => {
+		obj[key] = query[key];
+		return obj;
+	}, {});
+	return crypto.createHash('md5').update(JSON.stringify(sortedQuery)).digest('hex');
+}
+
+function matchesApi(method, path, apis) {
+	if (!apis || typeof apis !== 'object') {
+		return null;
+	}
+	const requestSignature = `${method} ${path}`;
+
+	if (apis[requestSignature]) {
+		return apis[requestSignature];
+	}
+
+	for (const api in apis) {
+		if (apis.hasOwnProperty(api)) {
+			const [apiMethod, apiPath] = api.split(' ');
+			if (apiMethod !== method) {
+				continue;
+			}
+			const apiParts = apiPath.split('/');
+			const pathParts = path.split('/');
+			if (apiParts.length !== pathParts.length) {
+				continue;
+			}
+			let matches = true;
+			for (let i = 0; i < apiParts.length; i++) {
+				if (apiParts[i].startsWith(':')) {
+					continue;
+				}
+				if (apiParts[i] !== pathParts[i]) {
+					matches = false;
+					break;
+				}
+			}
+			if (matches) {
+				return apis[api];
+			}
+		}
+	}
+	return null;
+}
+
+// Export model for use by gotoService
+module.exports = function (configuration) {
+	model.memory.init(configuration.log);
+	model.mongo.init(configuration.log, configuration.gatewayDB);
+
+	return (req, res, next) => {
+		if (req.method.toUpperCase() !== 'GET') {
+			return next();
+		}
+
+		if (!req.soajs || !req.soajs.tenant || !req.soajs.controller || !req.soajs.controller.serviceParams) {
+			return next();
+		}
+
+		const serviceName = req.soajs.controller.serviceParams.name;
+		// Strip service prefix from pathname to get API path (e.g., /marketplace/items -> /items)
+		const serviceInfo = req.soajs.controller.serviceParams.serviceInfo;
+		const apiPath = "/" + serviceInfo.slice(2).join("/");
+		const method = req.method.toUpperCase();
+
+		const cacheConfig = get(["soajs", "registry", "custom", "gateway", "value", "cache"], req);
+		if (!cacheConfig) {
+			return next();
+		}
+
+		const serviceConfig = cacheConfig.services && cacheConfig.services[serviceName];
+		if (!serviceConfig || !serviceConfig.enabled) {
+			return next();
+		}
+
+		const apiConfig = matchesApi(method, apiPath, serviceConfig.apis);
+		if (!apiConfig || !apiConfig.enabled) {
+			return next();
+		}
+
+		const modelType = cacheConfig.model || 'memory';
+		if (!model[modelType]) {
+			configuration.log.warn('Cache: Unknown model [' + modelType + ']. It can only be [memory || mongo]');
+			return next();
+		}
+
+		const ttl = apiConfig.ttl || cacheConfig.defaultTTL || 300000;
+		const queryHash = hashQuery(req.query);
+		const key = {
+			'l1': req.soajs.tenant.id,
+			'l2': `${serviceName}:GET:${apiPath}:${queryHash}`
+		};
+
+		const processCache = async () => {
+			try {
+				const cached = await model[modelType].get(key);
+
+				if (cached && cached.response) {
+					res.setHeader('X-Cache', 'HIT');
+					res.setHeader('X-Cache-Age', Math.floor((Date.now() - cached.cachedAt) / 1000));
+					res.writeHead(cached.response.statusCode, cached.response.headers);
+					res.end(cached.response.body);
+					return;
+				}
+
+				// Store cache context for gotoService to use
+				req.soajs.cacheContext = {
+					key: key,
+					ttl: ttl,
+					modelType: modelType,
+					model: model[modelType],
+					log: configuration.log
+				};
+
+				res.setHeader('X-Cache', 'MISS');
+				next();
+			} catch (err) {
+				configuration.log.error('Cache error:', err);
+				next();
+			}
+		};
+
+		processCache();
+	};
+};
+
+// Export model for external use
+module.exports.model = model;

package/mw/cache/model/memory.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * @license
+ * Copyright SOAJS All Rights Reserved.
+ *
+ * Use of this source code is governed by an Apache license that can be
+ * found in the LICENSE file at the root of this repository
+ */
+
+let dataHolder = {};
+let cleanupInterval = null;
+
+let model = {
+	'log': null,
+
+	'init': (log) => {
+		model.log = log;
+		dataHolder = {};
+
+		if (cleanupInterval) {
+			clearInterval(cleanupInterval);
+		}
+		const CLEANUP_INTERVAL = process.env.SOAJS_CACHE_CLEANUP_INTERVAL || 60000;
+		cleanupInterval = setInterval(() => {
+			model.cleanupExpiredEntries();
+		}, CLEANUP_INTERVAL);
+	},
+
+	'cleanupExpiredEntries': () => {
+		const now = Date.now();
+		let removedCount = 0;
+
+		for (const l1Key in dataHolder) {
+			if (dataHolder.hasOwnProperty(l1Key)) {
+				const tenantData = dataHolder[l1Key];
+
+				for (const l2Key in tenantData) {
+					if (tenantData.hasOwnProperty(l2Key)) {
+						const entry = tenantData[l2Key];
+						if (entry.expiresAt && now > entry.expiresAt) {
+							delete tenantData[l2Key];
+							removedCount++;
+						}
+					}
+				}
+
+				if (Object.keys(tenantData).length === 0) {
+					delete dataHolder[l1Key];
+				}
+			}
+		}
+
+		if (removedCount > 0 && model.log) {
+			model.log.debug(`Cache cleanup: removed ${removedCount} expired entries`);
+		}
+	},
+
+	'get': (key) => {
+		if (!dataHolder[key.l1]) {
+			return null;
+		}
+		const entry = dataHolder[key.l1][key.l2];
+		if (!entry) {
+			return null;
+		}
+		if (entry.expiresAt && Date.now() > entry.expiresAt) {
+			delete dataHolder[key.l1][key.l2];
+			return null;
+		}
+		return entry;
+	},
+
+	'set': (key, response, ttl) => {
+		if (!dataHolder[key.l1]) {
+			dataHolder[key.l1] = {};
+		}
+		dataHolder[key.l1][key.l2] = {
+			'response': response,
+			'cachedAt': Date.now(),
+			'expiresAt': Date.now() + ttl
+		};
+	},
+
+	'invalidate': (key) => {
+		if (dataHolder[key.l1] && dataHolder[key.l1][key.l2]) {
+			delete dataHolder[key.l1][key.l2];
+		}
+	},
+
+	'invalidateTenant': (tenantId) => {
+		if (dataHolder[tenantId]) {
+			delete dataHolder[tenantId];
+		}
+	},
+
+	'shutdown': () => {
+		if (cleanupInterval) {
+			clearInterval(cleanupInterval);
+			cleanupInterval = null;
+		}
+		dataHolder = {};
+		if (model.log) {
+			model.log.info('Cache memory model shutdown complete');
+		}
+	}
+};
+
+if (typeof process !== 'undefined') {
+	const shutdownHandler = () => {
+		model.shutdown();
+	};
+	process.once('SIGTERM', shutdownHandler);
+	process.once('SIGINT', shutdownHandler);
+}
+
+module.exports = model;

package/mw/cache/model/mongo.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * @license
+ * Copyright SOAJS All Rights Reserved.
+ *
+ * Use of this source code is governed by an Apache license that can be
+ * found in the LICENSE file at the root of this repository
+ */
+
+const core = require('soajs.core.modules');
+const Mongo = core.mongo;
+
+const cache_store = 'cache_store';
+
+let model = {
+	'mongo': null,
+	'log': null,
+
+	'init': (log, dbConfiguration) => {
+		model.log = log;
+		if (!model.mongo) {
+			model.mongo = new Mongo(dbConfiguration);
+			model.mongo.createIndex(cache_store, { 'l1': 1, 'l2': 1 }, { unique: true }, (err, index) => {
+				log.debug("Cache index: " + index + " created with error: " + err);
+			});
+			model.mongo.createIndex(cache_store, { 'expiresAt': 1 }, { expireAfterSeconds: 0 }, (err, index) => {
+				log.debug("Cache TTL index: " + index + " created with error: " + err);
+			});
+		}
+	},
+
+	'get': async (key) => {
+		let condition = {
+			'l1': key.l1,
+			'l2': key.l2
+		};
+		try {
+			const entry = await model.mongo.findOne(cache_store, condition);
+			if (!entry) {
+				return null;
+			}
+			if (entry.expiresAt && Date.now() > entry.expiresAt.getTime()) {
+				return null;
+			}
+			return entry;
+		} catch (e) {
+			model.log.error('Cache get:', e.message);
+			return null;
+		}
+	},
+
+	'set': async (key, response, ttl) => {
+		let condition = {
+			'l1': key.l1,
+			'l2': key.l2
+		};
+		let doc = {
+			'l1': key.l1,
+			'l2': key.l2,
+			'response': response,
+			'cachedAt': new Date(),
+			'expiresAt': new Date(Date.now() + ttl)
+		};
+		let options = { 'upsert': true };
+		let s = { '$set': doc };
+		try {
+			await model.mongo.updateOne(cache_store, condition, s, options);
+		} catch (e) {
+			model.log.error('Cache set:', e.message);
+		}
+	},
+
+	'invalidate': async (key) => {
+		let condition = {
+			'l1': key.l1,
+			'l2': key.l2
+		};
+		try {
+			await model.mongo.deleteOne(cache_store, condition);
+		} catch (e) {
+			model.log.error('Cache invalidate:', e.message);
+		}
+	},
+
+	'invalidateTenant': async (tenantId) => {
+		let condition = {
+			'l1': tenantId
+		};
+		try {
+			await model.mongo.deleteMany(cache_store, condition);
+		} catch (e) {
+			model.log.error('Cache invalidateTenant:', e.message);
+		}
+	}
+};
+
+module.exports = model;

package/mw/gotoService/redirectToService.js

@@ -315,7 +315,21 @@ module.exports = (configuration) => {
 			let resContentType = "";
 			const extraOptions = {};
 
-			if (monitor && !monitor_service_blacklist && monitor.req_response) {
+			// Cache response capture
+			let cacheContext = req.soajs.cacheContext;
+			let cacheResponseChunks = [];
+			let cacheResponseStatusCode = 200;
+			let cacheResponseHeaders = {};
+
+			// Idempotency response capture
+			let idempotencyContext = req.soajs.idempotencyContext;
+			let idempotencyResponseChunks = [];
+			let idempotencyResponseStatusCode = 200;
+			let idempotencyResponseHeaders = {};
+
+			// Set up events for monitoring, caching, and/or idempotency
+			let needsEvents = (monitor && !monitor_service_blacklist && monitor.req_response) || cacheContext || idempotencyContext;
+			if (needsEvents) {
 				const MAX_RESPONSE_SIZE = process.env.SOAJS_MAX_RESPONSE_SIZE || 10 * 1024 * 1024; // 10MB default
 				let responseSize = 0;
 				let responseExceeded = false;
@@ -330,35 +344,78 @@ module.exports = (configuration) => {
 								isStream = resContentType.match(/stream/i);
 							}
 						}
-						monitoObj.time.res_start = new Date().getTime();
+						if (monitor && !monitor_service_blacklist && monitor.req_response) {
+							monitoObj.time.res_start = new Date().getTime();
+						}
 					},
 					"data": (chunk) => {
-						if (!isStream && allowedContentType) {
-							responseSize += chunk.length;
-							if (responseSize > MAX_RESPONSE_SIZE) {
-								if (!responseExceeded) {
-									responseExceeded = true;
-									monitoObj.response = "{\"error\": \"Response body exceeds maximum size limit\"}";
-								}
-							} else if (!responseExceeded) {
-								if (!monitoObj.response) {
-									monitoObj.response = chunk;
-								} else {
-									monitoObj.response += chunk;
+						// Capture for caching
+						if (cacheContext) {
+							cacheResponseChunks.push(chunk);
+						}
+						// Capture for idempotency
+						if (idempotencyContext) {
+							idempotencyResponseChunks.push(chunk);
+						}
+						// Capture for monitoring
+						if (monitor && !monitor_service_blacklist && monitor.req_response) {
+							if (!isStream && allowedContentType) {
+								responseSize += chunk.length;
+								if (responseSize > MAX_RESPONSE_SIZE) {
+									if (!responseExceeded) {
+										responseExceeded = true;
+										monitoObj.response = "{\"error\": \"Response body exceeds maximum size limit\"}";
+									}
+								} else if (!responseExceeded) {
+									if (!monitoObj.response) {
+										monitoObj.response = chunk;
+									} else {
+										monitoObj.response += chunk;
+									}
 								}
+							} else {
+								monitoObj.response = "{\"contentType\": \"is stream or not allowed\", \"value': \"" + resContentType + "\"}";
 							}
-						} else {
-							monitoObj.response = "{\"contentType\": \"is stream or not allowed\", \"value': \"" + resContentType + "\"}";
 						}
 					},
 					"fetchProxReq": (proxyReq) => {
 						req.soajs.controller.redirectedRequest = proxyReq;
+					},
+					"statusCode": (statusCode, headers) => {
+						if (cacheContext) {
+							cacheResponseStatusCode = statusCode;
+							cacheResponseHeaders = headers || {};
+						}
+						if (idempotencyContext) {
+							idempotencyResponseStatusCode = statusCode;
+							idempotencyResponseHeaders = headers || {};
+						}
 					}
 				};
 			}
 
 			proxyRequestMonitor(req, res, requestOptions, extraOptions)
 				.then(() => {
+					// Save to cache if applicable
+					if (cacheContext && cacheResponseStatusCode >= 200 && cacheResponseStatusCode < 300) {
+						let cacheBody = Buffer.concat(cacheResponseChunks).toString('utf8');
+						let cacheData = {
+							statusCode: cacheResponseStatusCode,
+							headers: cacheResponseHeaders,
+							body: cacheBody
+						};
+						cacheContext.model.set(cacheContext.key, cacheData, cacheContext.ttl);
+					}
+					// Complete idempotency if applicable
+					if (idempotencyContext) {
+						let idempotencyBody = Buffer.concat(idempotencyResponseChunks).toString('utf8');
+						let idempotencyData = {
+							statusCode: idempotencyResponseStatusCode,
+							headers: idempotencyResponseHeaders,
+							body: idempotencyBody
+						};
+						idempotencyContext.model.complete(idempotencyContext.key, idempotencyData, idempotencyContext.ttl);
+					}
 					if (monitor && !monitor_service_blacklist && monitor.req_response) {
 						monitoObj.time.res_end = new Date().getTime();
 						log_monitor(monitoObj);
@@ -370,6 +427,10 @@ module.exports = (configuration) => {
 						req.soajs.controller.redirectedRequest.destroy();
 						req.soajs.controller.redirectedRequest = null;
 					}
+					// Unlock idempotency on error
+					if (idempotencyContext) {
+						idempotencyContext.model.unlock(idempotencyContext.key);
+					}
 					if (!req.soajs.controller.monitorEndingReq) {
 						req.soajs.controllerResponse(core.error.getError(135));
 					}