soajs.controller 4.3.6 → 4.3.7

package/docs/middleware/idempotency.md

@@ -59,6 +59,7 @@ The Idempotency middleware prevents duplicate write operations by tracking reque
 {
   "idempotency": {
     "model": "memory",                    // Storage: "memory" or "mongo"
+    "enforce": false,                     // Global default for enforcement (optional)
     "services": {                         // Service configurations
       "av": {                             // Service name
         "enabled": true,                  // Enable for this service
@@ -71,6 +72,7 @@ The Idempotency middleware prevents duplicate write operations by tracking reque
       },
       "payment": {
         "enabled": true,
+        "enforce": true,                  // Require Idempotency-Key on matched APIs
         "ttl": 120000,
         "apis": [
           "POST /charge",
@@ -85,10 +87,18 @@ The Idempotency middleware prevents duplicate write operations by tracking reque
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
+| `enforce` | boolean | `false` | Global default enforcement (overridden per service) |
 | `services.[name].enabled` | boolean | `false` | Enable idempotency for this service |
+| `services.[name].enforce` | boolean | *(global)* | Require `Idempotency-Key` on matched APIs; overrides the global `enforce`. If unset, falls back to the global default |
 | `services.[name].ttl` | number | `60000` | Key expiration time in milliseconds |
 | `services.[name].apis` | string[] | `[]` | API patterns to protect (e.g., `"POST /path"`) |
 
+## Enforcement
+
+By default, requests without an `Idempotency-Key` header pass through untouched (backwards compatible). When `enforce` is enabled, a matched, non-GET API **requires** the header — a missing key returns **428 Precondition Required** (code `182`).
+
+Resolution order: `services.[name].enforce` takes precedence when set to a boolean; otherwise the top-level `enforce` applies. Enforcement never affects GET requests, unconfigured/disabled services, or APIs outside the configured `apis` list.
+
 ## API Pattern Matching
 
 APIs are matched using `METHOD /path` format with support for path parameters:
@@ -181,6 +191,26 @@ Content-Type: application/json
 }
 ```
 
+### Enforced (Missing Key)
+
+Returned when the matched API has enforcement enabled and no `Idempotency-Key` header is provided.
+
+```
+HTTP/1.1 428 Precondition Required
+Content-Type: application/json
+
+{
+  "result": false,
+  "errors": {
+    "codes": [182],
+    "details": [{
+      "code": 182,
+      "message": "Idempotency-Key header is required for this API."
+    }]
+  }
+}
+```
+
 ## Key Structure
 
 ```javascript
@@ -198,6 +228,7 @@ Keys are isolated per tenant to prevent cross-tenant collisions.
 |------|-------------|-------------|
 | 180 | 400 | Invalid Idempotency-Key format (not UUID v4) |
 | 181 | 409 | Request with this key is still being processed |
+| 182 | 428 | Idempotency-Key header required (enforcement enabled) |
 
 ## Usage Notes
 

package/mw/idempotency/index.js

@@ -62,11 +62,9 @@ module.exports = function (configuration) {
 	return (req, res, next) => {
 		const idempotencyKey = req.headers['idempotency-key'];
 
-		if (!idempotencyKey) {
-			return next();
-		}
-
-		if (!isValidUUIDv4(idempotencyKey)) {
+		// Validate format only when a key was actually provided. The decision on a
+		// missing key is deferred until we know whether the target API enforces it.
+		if (idempotencyKey && !isValidUUIDv4(idempotencyKey)) {
 			req.soajs.controllerResponse({
 				'status': 400,
 				'code': 180,
@@ -103,6 +101,22 @@ module.exports = function (configuration) {
 			return next();
 		}
 
+		// Request targets an idempotency-enabled and matched API. Resolve enforcement:
+		// service-level 'enforce' overrides the global default.
+		const enforce = (typeof serviceConfig.enforce === 'boolean') ? serviceConfig.enforce : (idempotencyConfig.enforce === true);
+
+		if (!idempotencyKey) {
+			if (enforce) {
+				req.soajs.controllerResponse({
+					'status': 428,
+					'code': 182,
+					'msg': 'Idempotency-Key header is required for this API.'
+				});
+				return;
+			}
+			return next();
+		}
+
 		const modelType = idempotencyConfig.model || 'memory';
 		if (!model[modelType]) {
 			configuration.log.warn('Idempotency: Unknown model [' + modelType + ']. It can only be [memory || mongo]');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.3.6",
+  "version": "4.3.7",
   "author": {
     "name": "soajs team",
     "email": "team@soajs.org"

package/test/unit/mw/idempotency/index.js

@@ -30,6 +30,7 @@ describe("Unit test for: mw - idempotency", () => {
 		it("should call next() when no Idempotency-Key header", (done) => {
 			let req = {
 				headers: {},
+				method: 'POST',
 				soajs: {
 					tenant: { id: '123' },
 					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
@@ -313,6 +314,244 @@ describe("Unit test for: mw - idempotency", () => {
 		});
 	});
 
+	describe("enforcement", () => {
+		it("should return 428 when enforced and no key on matched API", (done) => {
+			let responseData = null;
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					},
+					controllerResponse: (data) => {
+						responseData = data;
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, () => {
+				assert.fail('Should not call next');
+			});
+			setTimeout(() => {
+				assert.notStrictEqual(responseData, null);
+				assert.strictEqual(responseData.status, 428);
+				assert.strictEqual(responseData.code, 182);
+				done();
+			}, 10);
+		});
+
+		it("should call next() when enforced and key is present", (done) => {
+			let req = {
+				headers: { 'idempotency-key': '550e8400-e29b-41d4-a716-446655440010' },
+				method: 'POST',
+				soajs: {
+					tenant: { id: 'tenant-enforce' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										model: 'memory',
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {
+				writeHead: function() { return this; },
+				write: function() { return true; },
+				end: function() {},
+				on: function() {}
+			};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should call next() when not enforced and no key (backwards compatible)", (done) => {
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should return 428 when global enforce is set and service has no override", (done) => {
+			let responseData = null;
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										enforce: true,
+										services: {
+											test: { enabled: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					},
+					controllerResponse: (data) => {
+						responseData = data;
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, () => {
+				assert.fail('Should not call next');
+			});
+			setTimeout(() => {
+				assert.notStrictEqual(responseData, null);
+				assert.strictEqual(responseData.status, 428);
+				assert.strictEqual(responseData.code, 182);
+				done();
+			}, 10);
+		});
+
+		it("should let service enforce=false override global enforce=true", (done) => {
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										enforce: true,
+										services: {
+											test: { enabled: true, enforce: false, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should not enforce on GET requests", (done) => {
+			let req = {
+				headers: {},
+				method: 'GET',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should not enforce when API is not in the configured list", (done) => {
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'other'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+	});
+
 	describe("UUID validation", () => {
 		it("should accept valid UUID v4", (done) => {
 			let req = {