soajs.controller 4.2.41 → 4.2.43

package/docs/request-flow.md

@@ -0,0 +1,230 @@
+# Request Flow
+
+The complete request lifecycle through the SOAJS Controller Gateway.
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│                              REQUEST LIFECYCLE                                   │
+└──────────────────────────────────────────────────────────────────────────────────┘
+
+  HTTP Request                                                      HTTP Response
+       │                                                                  ▲
+       ▼                                                                  │
+┌──────────────┐                                                   ┌──────────────┐
+│ 1. SOAJS MW  │ Initialize req.soajs context                      │ Error Handler│
+│              │ Attach registry reference                         │              │
+└──────┬───────┘                                                   └──────▲───────┘
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 2. Security  │ CORS, IP Ban, Maintenance Mode                           │
+│    Checks    │                                                          │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 3. URL Parse │ Extract: serviceName, version, path                      │
+│              │ Extract: key/token from header/query                     │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 4. Service   │ Resolve service host via awareness                       │
+│   Discovery  │ Support HA (K8s/Swarm) or custom                         │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 5. Tenant    │ Load key data, validate tenant                           │
+│   Resolution │ Extract ACL from package                                 │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 6. Security  │ IP Whitelist → Geo Check → Device Check                  │
+│   Pipeline   │ → ACL Check → OAuth Check                                │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 7. Traffic   │ Rate limiting with configurable                          │
+│   Control    │ strategies and storage backends                          │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────────────────────────────────────────────────────────┬──────┘
+│ 8. PROXY TO SERVICE                                              │
+│                                                                  │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐  │
+│  │  Resolve Host   │───▶│  Build Request  │───▶│  HTTP Proxy  │  │
+│  │  (awareness)    │    │  (headers/body) │    │  (forward)   │  │
+│  └─────────────────┘    └─────────────────┘    └──────────────┘  │
+│                                                       │          │
+│                                                       ▼          │
+│                                            ┌──────────────────┐  │
+│                                            │  Target Service  │  │
+│                                            │  (Microservice)  │  │
+│                                            └──────────────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Stage Details
+
+### 1. SOAJS Initialization
+
+**Middleware:** `mw/soajs/index.js`
+
+- Creates `req.soajs` object
+- Attaches registry reference
+- Sets up logging context
+- Initializes controller params
+
+### 2. Security Checks
+
+**Middlewares:** `mw/cors`, `mw/ip2ban`, `mw/maintenanceMode`
+
+- CORS preflight handling
+- IP blacklist enforcement
+- Maintenance mode check
+
+### 3. URL Parsing
+
+**Middleware:** `mw/url/index.js`
+
+- Extracts service name from URL path
+- Parses version number (if provided)
+- Extracts API path
+
+### 4. Service Discovery
+
+**Middleware:** `mw/awareness/index.js`
+
+- Attaches `getHost()` and `getLatestVersion()` functions
+- Supports both custom and HA modes
+
+### 5. Tenant Resolution
+
+**Middlewares:** `mw/key`, `mw/keyACL`
+
+- Loads external key data
+- Validates key for environment
+- Extracts ACL from package or application
+
+### 6. Security Pipeline
+
+**Middleware:** `mw/mt/index.js`
+
+- IP whitelist validation
+- Geo-location checks
+- Device fingerprint verification
+- ACL enforcement
+- OAuth token validation
+
+### 7. Traffic Control
+
+**Middleware:** `mw/traffic/index.js`
+
+- Rate limiting per strategy
+- Response headers (X-RateLimit-*)
+
+### 8. Proxy to Service
+
+**Middleware:** `mw/gotoService/*`
+
+- Resolves target host
+- Builds proxy request
+- Forwards to microservice
+- Returns response to client
+
+## Configuration Model
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           CONFIGURATION HIERARCHY                               │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                    ENVIRONMENT VARIABLES (Highest Priority)             │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  SOAJS_ENV              │  Environment code (default: "dev")            │
+    │  SOAJS_SOLO             │  Solo mode flag (local registry)              │
+    │  SOAJS_DEPLOY_HA        │  HA mode: "kubernetes" | "swarm"              │
+    │  SOAJS_MAX_BODY_SIZE    │  Max request body (default: 10MB)             │
+    │  SOAJS_SENSITIVE_ENVS   │  Sensitive env codes (default: ["dashboard"]) │
+    └─────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                         SERVICE CONFIGURATION                           │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  config.js              │  Service metadata (name, version, port)       │
+    │  profiles/single.js     │  MongoDB connection profile                   │
+    │  profiles/solo.js       │  Local file-based profile                     │
+    └─────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                       REGISTRY (from Core DB)                           │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  services               │  Service definitions (ports, hosts, versions) │
+    │  serviceConfig          │  Global configs (throttling, CORS, OAuth)     │
+    │  custom.gateway         │  Gateway-specific settings                    │
+    │  dbs                    │  Database connection configs                  │
+    └─────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                      TENANT/APPLICATION (Lowest Priority)               │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  Tenant.application     │  App-specific OAuth, ACL overrides            │
+    │  Package.acl            │  Package-level access control                 │
+    └─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Rate Limiting Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           RATE LIMITING (THROTTLING)                            │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         STRATEGY SELECTION                                 │
+    │                                                                            │
+    │   ┌─────────────────────────┐        ┌─────────────────────────┐           │
+    │   │   publicAPIStrategy     │        │   privateAPIStrategy    │           │
+    │   │   (Unauthenticated)     │        │   (Authenticated)       │           │
+    │   └───────────┬─────────────┘        └───────────┬─────────────┘           │
+    │               │                                  │                         │
+    │               └──────────────┬───────────────────┘                         │
+    │                              ▼                                             │
+    └──────────────────────────────┬─────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         CONFIGURATION CASCADE                              │
+    │                                                                            │
+    │   1. Service-specific: gateway.throttling                                  │
+    │   2. Custom registry: gateway.value.traffic.throttling                     │
+    │   3. Global default: serviceConfig.throttling                              │
+    └──────────────────────────────┬─────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         STORAGE BACKENDS                                   │
+    │                                                                            │
+    │   ┌─────────────────────────┐        ┌─────────────────────────┐           │
+    │   │       Memory            │        │       MongoDB           │           │
+    │   │   (Fast, volatile)      │        │   (Persistent, shared)  │           │
+    │   └─────────────────────────┘        └─────────────────────────┘           │
+    └──────────────────────────────┬─────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         RESPONSE HEADERS                                   │
+    │                                                                            │
+    │   X-RateLimit-Limit      │  Maximum requests allowed                       │
+    │   X-RateLimit-Remaining  │  Requests remaining in window                   │
+    │   Retry-After            │  Seconds until window resets                    │
+    └────────────────────────────────────────────────────────────────────────────┘
+```

package/docs/service-discovery.md

@@ -0,0 +1,167 @@
+# Service Discovery Modes
+
+The SOAJS Controller Gateway supports two service discovery modes: Custom (non-Kubernetes) and HA (Kubernetes/Docker Swarm).
+
+## Discovery Modes Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           SERVICE DISCOVERY MODES                               │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────┐    ┌──────────────────────────────────────────┐
+│        CUSTOM MODE              │    │            HA MODE                       │
+│      (Non-Kubernetes)           │    │     (Kubernetes / Docker Swarm)          │
+├─────────────────────────────────┤    ├──────────────────────────────────────────┤
+│                                 │    │                                          │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │      Registry DB        │    │    │  │        Cluster API               │    │
+│  │   (MongoDB/Local)       │    │    │  │    (K8s API / Docker API)        │    │
+│  └───────────┬─────────────┘    │    │  └────────────────┬─────────────────┘    │
+│              │                  │    │                   │                      │
+│              ▼                  │    │                   ▼                      │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │   Static Host List      │    │    │  │    Dynamic Service Discovery     │    │
+│  │   per Service/Version   │    │    │  │    via Labels/Selectors          │    │
+│  └───────────┬─────────────┘    │    │  └────────────────┬─────────────────┘    │
+│              │                  │    │                   │                      │
+│              ▼                  │    │                   ▼                      │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │   In-Memory Health      │    │    │  │   Automatic Health Monitoring    │    │
+│  │   State Tracking        │    │    │  │   via Pod/Container Status       │    │
+│  └───────────┬─────────────┘    │    │  └────────────────┬─────────────────┘    │
+│              │                  │    │                   │                      │
+│              ▼                  │    │                   ▼                      │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │   Round-Robin           │    │    │  │   Cluster Load Balancing         │    │
+│  │   Selection             │    │    │  │   (via Service/Ingress)          │    │
+│  └─────────────────────────┘    │    │  └──────────────────────────────────┘    │
+│                                 │    │                                          │
+└─────────────────────────────────┘    └──────────────────────────────────────────┘
+```
+
+## Custom Mode
+
+Used when running outside of container orchestration platforms.
+
+### Configuration
+
+Set via environment variable:
+```bash
+# Do not set SOAJS_DEPLOY_HA, or set it to empty
+unset SOAJS_DEPLOY_HA
+```
+
+### How it Works
+
+1. **Registry Loading**: Service hosts are loaded from MongoDB registry
+2. **Host List**: Static list of hosts per service/version
+3. **Health Tracking**: In-memory state tracking with heartbeat
+4. **Load Balancing**: Round-robin selection among healthy hosts
+
+### Registry Structure
+
+```javascript
+// In environment registry
+{
+  "services": {
+    "oauth": {
+      "port": 4002,
+      "hosts": {
+        "1": ["host1.local", "host2.local"],
+        "2": ["host3.local"]
+      }
+    }
+  }
+}
+```
+
+## HA Mode (Kubernetes)
+
+Used when running in Kubernetes.
+
+### Configuration
+
+```bash
+export SOAJS_DEPLOY_HA=kubernetes
+```
+
+### How it Works
+
+1. **API Discovery**: Uses Kubernetes API to discover services
+2. **Label Selectors**: Finds pods via SOAJS labels
+3. **Health Monitoring**: Leverages pod readiness/liveness probes
+4. **Load Balancing**: Can use Kubernetes Service or direct pod access
+
+### Kubernetes Labels
+
+SOAJS uses these labels to discover services:
+
+```yaml
+metadata:
+  labels:
+    soajs.env.code: dev
+    soajs.service.name: oauth
+    soajs.service.version: "1"
+```
+
+## HA Mode (Docker Swarm)
+
+Used when running in Docker Swarm.
+
+### Configuration
+
+```bash
+export SOAJS_DEPLOY_HA=swarm
+```
+
+### How it Works
+
+1. **API Discovery**: Uses Docker Swarm API to discover services
+2. **Label Selectors**: Finds tasks via SOAJS labels
+3. **Health Monitoring**: Leverages task health checks
+4. **Load Balancing**: Can use Swarm service mesh or direct task access
+
+## Awareness Middleware
+
+**File:** `mw/awareness/index.js`
+
+The awareness middleware attaches helper functions to the request:
+
+```javascript
+req.soajs.awareness = {
+  getHost: function(serviceName, version, callback) {
+    // Returns host:port for the service
+  },
+  getLatestVersion: function(serviceName, callback) {
+    // Returns latest available version
+  }
+};
+```
+
+## Cross-Environment Awareness
+
+**File:** `mw/awarenessEnv/index.js`
+
+For roaming requests that need to access services in other environments:
+
+```javascript
+req.soajs.awarenessEnv = {
+  getHost: function(envCode, serviceName, version, callback) {
+    // Returns host:port for service in specified environment
+  }
+};
+```
+
+## Driver Module
+
+**File:** `modules/driver/index.js`
+
+The driver module abstracts infrastructure-specific operations:
+
+| Method | Description |
+|--------|-------------|
+| `getServiceHosts()` | Get all hosts for a service |
+| `getServiceHost()` | Get a single host (load balanced) |
+| `getLatestVersion()` | Get latest version number |
+| `getInfo()` | Get node/container info |

package/mw/gotoService/redirectToService.js

@@ -194,6 +194,9 @@ module.exports = (configuration) => {
 			const extraOptions = {};
 
 			if (monitor && !monitor_service_blacklist && monitor.req_response) {
+				const MAX_RESPONSE_SIZE = process.env.SOAJS_MAX_RESPONSE_SIZE || 10 * 1024 * 1024; // 10MB default
+				let responseSize = 0;
+				let responseExceeded = false;
 				extraOptions.events = {
 					"response": (_resContentType) => {
 						resContentType = _resContentType;
@@ -209,10 +212,18 @@ module.exports = (configuration) => {
 					},
 					"data": (chunk) => {
 						if (!isStream && allowedContentType) {
-							if (!monitoObj.response) {
-								monitoObj.response = chunk;
-							} else {
-								monitoObj.response += chunk;
+							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 + "\"}";

package/mw/key/index.js

@@ -8,13 +8,15 @@
  * found in the LICENSE file at the root of this repository
  */
 
+const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
+
 /**
  *
  * @param {object} configuration {provision,regEnvironment}
  * @returns {Function}
  */
 module.exports = (configuration) => {
-	
+
 	return (req, res, next) => {
 		let key = req.get("key");
 		if (key) {
@@ -34,6 +36,19 @@ module.exports = (configuration) => {
 							return next(144);
 						}
 					}
+
+					// Check for network-based package override
+					let network = get(["soajs", "registry", "custom", "gateway", "value", "lastSeen", "network"], req);
+					if (network) {
+						let product = keyObj.application.product;
+						let networkPackageConfig = get(["config", "gateway", "networkPackages", network, product], keyObj);
+						if (networkPackageConfig && networkPackageConfig.default) {
+							let originalPackage = keyObj.application.package;
+							keyObj.application.package = networkPackageConfig.default;
+							req.soajs.log.debug("Network package override: replaced package [" + originalPackage + "] with [" + networkPackageConfig.default + "] for network [" + network + "] and product [" + product + "]");
+						}
+					}
+
 					configuration.provision.getPackageData(keyObj.application.package, function (err, packObj) {
 						if (err) {
 							req.soajs.log.error("Unable to fetch data about package [" + keyObj.application.package + "]");

package/mw/lastSeen/index.js

@@ -47,6 +47,9 @@ module.exports = () => {
                                 "json": true,
                                 "method": "POST"
                             };
+                            if (lastSeen.network) {
+                                options.body = { "network": lastSeen.network };
+                            }
                             if (req.headers && req.headers.soajsinjectobj) {
                                 options.headers = { "soajsinjectobj": req.headers.soajsinjectobj };
                             }

package/mw/mt/urac.js

@@ -14,6 +14,8 @@ let provision = coreModules.provision;
 
 const lib = require("./lib.js");
 
+const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
+
 function Urac(param) {
 	let _self = this;
 
@@ -101,7 +103,25 @@ Urac.prototype.resolveACL = function (cb) {
 		let productCode = _self.soajs.tenant.application.product;
 		if (_self.userRecord.groupsConfig && _self.userRecord.groupsConfig.allowedPackages) {
 			if (_self.userRecord.groupsConfig.allowedPackages[productCode]) {
-				provision.getPackagesData(_self.userRecord.groupsConfig.allowedPackages[productCode], (error, arrayACLs) => {
+				let allowedPackages = _self.userRecord.groupsConfig.allowedPackages[productCode].slice();
+
+				// Check for user-specific network package override
+				let network = get(["registry", "custom", "gateway", "value", "lastSeen", "network"], _self.soajs);
+				if (network) {
+					let keyObj = get(["controller", "serviceParams", "keyObj"], _self.soajs);
+					let networkPackageConfig = get(["config", "gateway", "networkPackages", network, productCode], keyObj);
+					if (networkPackageConfig && networkPackageConfig.users) {
+						for (let i = 0; i < allowedPackages.length; i++) {
+							if (networkPackageConfig.users[allowedPackages[i]]) {
+								let originalPackage = allowedPackages[i];
+								allowedPackages[i] = networkPackageConfig.users[allowedPackages[i]];
+								_self.soajs.log.debug("User network package override: replaced package [" + originalPackage + "] with [" + allowedPackages[i] + "] for network [" + network + "] and product [" + productCode + "]");
+							}
+						}
+					}
+				}
+
+				provision.getPackagesData(allowedPackages, (error, arrayACLs) => {
 					if (error) {
 						return cb();
 					} else {

package/mw/mt/utils.js

@@ -632,6 +632,8 @@ let utils = {
 					obj.req.soajs.log.error(error.message, error.code);
 					return cb(146);
 				}
+				//NOTE: if the user changes the account's email or phone and validateTokenAccount is set to true,
+				// 		kick the user out to force re login. i.e. the username behaviour is similar by default
 				if (obj.keyObj.config && obj.keyObj.config.gateway && obj.keyObj.config.gateway.validateTokenAccount) {
 					if (obj.req.soajs.uracDriver.bearerTokenUser && record) {
 						if (obj.keyObj.config.gateway.validateTokenAccount.email && record.email) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.2.41",
+  "version": "4.2.43",
   "author": {
     "name": "soajs team",
     "email": "team@soajs.org"
@@ -21,7 +21,7 @@
     "async": "3.2.6",
     "connect": "3.7.0",
     "http-proxy": "1.18.1",
-    "jsonwebtoken": "9.0.2",
+    "jsonwebtoken": "9.0.3",
     "kubernetes-client": "9.0.0",
     "lodash": "4.17.21",
     "merge": "2.1.1",
@@ -34,11 +34,11 @@
     "useragent": "2.3.0"
   },
   "devDependencies": {
-    "@babel/core": "7.28.5",
+    "@babel/core": "7.28.6",
     "@babel/plugin-transform-runtime": "7.28.5",
-    "@babel/preset-env": "7.28.5",
-    "@babel/runtime": "7.28.4",
-    "express": "4.21.1",
+    "@babel/preset-env": "7.28.6",
+    "@babel/runtime": "7.28.6",
+    "express": "5.2.1",
     "grunt": "1.6.1",
     "grunt-babel": "8.0.0",
     "grunt-contrib-clean": "2.0.1",
@@ -52,6 +52,6 @@
     "mocha": "11.7.5",
     "nock": "14.0.10",
     "request": "2.88.2",
-    "sinon": "21.0.0"
+    "sinon": "21.0.1"
   }
 }

package/test/integration/UC1-gateway-routes/index.js

@@ -166,7 +166,7 @@ describe("Integration for Usecase 1", function () {
 		};
 		requester('get', options, (error, body) => {
 			assert.ok(body);
-			assert.equal(body.data.type, "endpoint");
+			assert.strictEqual(body.data.type, "endpoint");
 			done();
 		});
 	});
@@ -252,7 +252,7 @@ describe("Integration for Usecase 1", function () {
 			}
 		};
 		requester('get', options, (error, body) => {
-			assert.equal(body.data.id, '/muser/:12?access_token=cfb209a91b23896820f510aadbf1f4284b512123');
+			assert.strictEqual(body.data.id, '/muser/:12?access_token=cfb209a91b23896820f510aadbf1f4284b512123');
 			done();
 		});
 	});