soajs.controller 4.3.4 → 4.3.6

package/docs/middleware/idempotency.md

@@ -0,0 +1,209 @@
+# Idempotency Middleware
+
+**File:** `mw/idempotency/index.js`
+
+**Order:** 17 (after MT middleware)
+
+The Idempotency middleware prevents duplicate write operations by tracking requests via `Idempotency-Key` headers.
+
+## Purpose
+
+- Prevents duplicate side effects from retried requests
+- Stores and replays responses for completed requests
+- Returns 409 Conflict for in-flight duplicate requests
+- Supports memory and MongoDB storage backends
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Check Idempotency-Key  │ Header present?
+  └────────┬────────────────┘
+           │
+           ├─── Missing ──▶ next() (backwards compatible)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Validate UUID v4       │ Format check
+  └────────┬────────────────┘
+           │
+           ├─── Invalid ──▶ 400 Bad Request (code: 180)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Check Configuration    │ Service enabled? API matches?
+  └────────┬────────────────┘
+           │
+           ├─── Not configured ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Lookup Existing Key    │ Check store
+  └────────┬────────────────┘
+           │
+           ├─── Found (completed) ──▶ Return cached response
+           │
+           ├─── Found (in_flight) ──▶ 409 Conflict (code: 181)
+           │
+           └─── Not found ──▶ Lock key → Execute → Store response
+```
+
+## Configuration
+
+**Path:** `registry.custom.gateway.value.idempotency`
+
+```javascript
+{
+  "idempotency": {
+    "model": "memory",                    // Storage: "memory" or "mongo"
+    "services": {                         // Service configurations
+      "av": {                             // Service name
+        "enabled": true,                  // Enable for this service
+        "ttl": 60000,                     // Time-to-live in ms (default: 60s)
+        "apis": [                         // APIs to protect
+          "POST /calls",
+          "PUT /call/p2p/ended",
+          "PUT /call/p2p/rejected"
+        ]
+      },
+      "payment": {
+        "enabled": true,
+        "ttl": 120000,
+        "apis": [
+          "POST /charge",
+          "POST /refund"
+        ]
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
+| `services.[name].enabled` | boolean | `false` | Enable idempotency for this service |
+| `services.[name].ttl` | number | `60000` | Key expiration time in milliseconds |
+| `services.[name].apis` | string[] | `[]` | API patterns to protect (e.g., `"POST /path"`) |
+
+## API Pattern Matching
+
+APIs are matched using `METHOD /path` format with support for path parameters:
+
+```javascript
+"apis": [
+  "POST /av/calls",              // Exact match
+  "PUT /av/call/:id/ended",      // :id matches any segment
+  "DELETE /users/:userId/posts/:postId"  // Multiple params
+]
+```
+
+## Storage Backends
+
+### Memory (Default)
+
+- Fast, in-process storage
+- Lost on restart
+- Good for single-instance deployments
+- Automatic cleanup of expired entries
+
+### MongoDB
+
+- Persistent storage
+- Shared across instances
+- Required for multi-instance deployments
+- Uses TTL index for automatic expiration
+
+## Client Usage
+
+Clients must include the `Idempotency-Key` header with a UUID v4:
+
+```http
+POST /av/calls HTTP/1.1
+Host: api.example.com
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+Content-Type: application/json
+
+{"caller": "user1", "callee": "user2"}
+```
+
+## Response Scenarios
+
+### New Request (First Time)
+
+```
+Request processed normally, response cached
+```
+
+### Replay (Completed)
+
+```
+HTTP/1.1 200 OK
+(Cached response body returned, no side effects)
+```
+
+### Replay (In-Flight)
+
+```
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+  "result": false,
+  "errors": {
+    "codes": [181],
+    "details": [{
+      "code": 181,
+      "message": "Request with this Idempotency-Key is still being processed."
+    }]
+  }
+}
+```
+
+### Invalid Key Format
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "result": false,
+  "errors": {
+    "codes": [180],
+    "details": [{
+      "code": 180,
+      "message": "Invalid Idempotency-Key format. Expected UUID v4."
+    }]
+  }
+}
+```
+
+## Key Structure
+
+```javascript
+{
+  "l1": "tenant_id",           // Tenant isolation
+  "l2": "idempotency_key"      // Client-provided UUID
+}
+```
+
+Keys are isolated per tenant to prevent cross-tenant collisions.
+
+## Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| 180 | 400 | Invalid Idempotency-Key format (not UUID v4) |
+| 181 | 409 | Request with this key is still being processed |
+
+## Usage Notes
+
+- Only applies to non-GET requests (POST, PUT, DELETE, PATCH)
+- GET requests always pass through (idempotent by nature)
+- Keys expire after TTL (default 60 seconds)
+- Clients should generate a new UUID for each unique operation
+- Same UUID = same operation (for retries)
+- MongoDB backend required for horizontal scaling

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,175 @@
+'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();
+		}
+
+		// Determine caching scope.
+		// Public APIs (no access_token required) return the same response for the whole
+		// tenant, so they are cached per tenant ("tenant"). Private APIs may return a
+		// different response per logged-in user, so they must be cached per tenant + user
+		// ("tenant_user") to avoid serving one user's response to another.
+		// Scope can be overridden per API in the custom registry via apiConfig.scope.
+		// Default: public -> "tenant", private -> "tenant_user".
+		const isAPIPublic = req.soajs.controller.serviceParams.isAPIPublic;
+		const userId = req.soajs.uracDriver && req.soajs.uracDriver.id;
+
+		let scope = apiConfig.scope;
+		if (scope !== 'tenant' && scope !== 'tenant_user') {
+			if (scope) {
+				configuration.log.warn('Cache: Unknown scope [' + scope + '] for API [' + method + ' ' + apiPath + ']. It can only be [tenant || tenant_user]. Falling back to default.');
+			}
+			scope = isAPIPublic ? 'tenant' : 'tenant_user';
+		}
+
+		// Safety: a user-scoped entry without a resolved user would leak across users.
+		// Skip caching rather than risk serving the wrong user's response.
+		if (scope === 'tenant_user' && !userId) {
+			return next();
+		}
+
+		const ttl = apiConfig.ttl || cacheConfig.defaultTTL || 300000;
+		const queryHash = hashQuery(req.query);
+		const userPart = (scope === 'tenant_user') ? `:u:${userId}` : '';
+		const key = {
+			'l1': req.soajs.tenant.id,
+			'l2': `${serviceName}:GET:${apiPath}:${queryHash}${userPart}`
+		};
+
+		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,121 @@
+'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);
+		// Do not keep the event loop alive solely for the cleanup timer.
+		if (cleanupInterval.unref) {
+			cleanupInterval.unref();
+		}
+	},
+
+	'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;