soajs.controller 4.2.42 → 4.3.0

package/docs/middleware/keyACL.md

@@ -0,0 +1,139 @@
+# Key ACL Middleware
+
+**File:** `mw/keyACL/index.js`
+
+**Order:** 12
+
+The Key ACL middleware extracts and processes the Access Control List (ACL) from the tenant's key or package.
+
+## Purpose
+
+- Extracts ACL for the requested service
+- Resolves ACL from application or package level
+- Handles both old and new ACL schema formats
+- Supports version-specific and method-specific ACL
+
+## Flow
+
+```
+  Incoming Request (after key middleware)
+       │
+       ▼
+  ┌─────────────────┐
+  │  Have keyObj    │ keyObj && packObj exist?
+  │  and packObj?   │
+  └────────┬────────┘
+           │
+           ├─── No ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Extract ACL            │ Priority:
+  │  for Service            │ 1. keyObj.application.acl
+  └────────┬────────────────┘ 2. packObj.acl
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Detect Schema Type     │ Old: apis/apisRegExp at root
+  │                         │ New: versioned with methods
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Resolve Version        │ Match requested version
+  │  (if versioned)         │ or get latest from ACL
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Extract Method-        │ get, post, put, delete
+  │  Specific ACL           │
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Store finalAcl         │ req.soajs.controller.serviceParams.finalAcl
+  └────────┬────────────────┘
+           │
+           ▼
+       next()
+```
+
+## ACL Resolution Priority
+
+1. **Application ACL** - `keyObj.application.acl[serviceName]`
+2. **Package ACL** - `packObj.acl[serviceName]`
+
+## ACL Schema Formats
+
+### Old Schema (Deprecated)
+
+```javascript
+{
+  "serviceName": {
+    "access": true,
+    "apis": {
+      "/api/path": { "access": ["group1"] }
+    },
+    "apisRegExp": [
+      { "regExp": /^\/api\/.*/, "access": ["group2"] }
+    ]
+  }
+}
+```
+
+### New Schema (Versioned)
+
+```javascript
+{
+  "serviceName": {
+    "1": {                              // Version
+      "access": true,
+      "apisPermission": "restricted",
+      "get": {
+        "apis": { "/user": {} }
+      },
+      "post": {
+        "apis": { "/user": { "access": ["admin"] } }
+      }
+    }
+  }
+}
+```
+
+### New Schema (Method-Based, Non-Versioned)
+
+```javascript
+{
+  "serviceName": {
+    "access": true,
+    "apisPermission": "restricted",
+    "get": {
+      "apis": { "/user": {} }
+    },
+    "post": {
+      "apis": { "/user": { "access": ["admin"] } }
+    }
+  }
+}
+```
+
+## Properties Set
+
+| Property | Description |
+|----------|-------------|
+| `req.soajs.controller.serviceParams.finalAcl` | Processed ACL for the service |
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 154 | Requested version not found in ACL |
+
+## Usage Notes
+
+- Runs after key middleware loads keyObj and packObj
+- Application-level ACL overrides package ACL
+- If no version specified, uses latest version from ACL
+- Converts regex patterns for API matching
+- Method-specific ACL inherits service-level `access` and `apisPermission`

package/docs/middleware/lastSeen.md

@@ -0,0 +1,111 @@
+# LastSeen Middleware
+
+**File:** `mw/lastSeen/index.js`
+
+**Order:** 17
+
+The LastSeen middleware asynchronously notifies a service (typically URAC) of user activity for tracking purposes.
+
+## Purpose
+
+- Tracks user activity (last seen time)
+- Asynchronous notification (non-blocking)
+- Configurable service endpoint
+- Only tracks authenticated users
+
+## Flow
+
+```
+  Incoming Request (after OAuth/MT)
+       │
+       ▼
+  ┌─────────────────┐
+  │  Call next()    │ Continue immediately (non-blocking)
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Have URAC Driver?      │ req.soajs.uracDriver exists?
+  └────────┬────────────────┘
+           │
+           ├─── No ──▶ (done)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  LastSeen Active?       │ custom.gateway.value.lastSeen.active?
+  └────────┬────────────────┘
+           │
+           ├─── No ──▶ (done)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Get User ID            │ From URAC profile
+  └────────┬────────────────┘
+           │
+           ├─── No user ID ──▶ (done, log debug)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Resolve Service Host   │ awareness.getHost()
+  └────────┬────────────────┘
+           │
+           ├─── No host ──▶ (done, log debug)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  POST to LastSeen       │ http://host:port/api
+  │  API (async)            │ body: { network: ... }
+  └─────────────────────────┘
+```
+
+## Configuration
+
+Located in `registry.custom.gateway.value.lastSeen`:
+
+```javascript
+{
+  "lastSeen": {
+    "active": true,                      // Enable tracking
+    "serviceName": "urac",               // Target service
+    "serviceVersion": "3",               // Service version
+    "api": "/user/last/seen",            // API endpoint
+    "network": "internal"                // Optional network identifier
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `active` | boolean | `false` | Enable/disable tracking |
+| `serviceName` | string | `"urac"` | Service to notify |
+| `serviceVersion` | string | `"3"` | Service version |
+| `api` | string | `"/user/last/seen"` | API endpoint |
+| `network` | string | - | Network identifier in request body |
+
+## Request to URAC
+
+**Method:** POST
+
+**URL:** `http://{host}:{port}/user/last/seen`
+
+**Headers:**
+```
+Content-Type: application/json
+soajsinjectobj: <inject object from MT middleware>
+```
+
+**Body:**
+```javascript
+{
+  "network": "internal"                  // If configured
+}
+```
+
+## Usage Notes
+
+- Non-blocking: calls `next()` immediately
+- Only activates for authenticated users with URAC profile
+- Errors are logged but don't affect the request
+- Uses awareness for service host resolution
+- Forwards `soajsinjectobj` header for authentication context
+- Network identifier useful for tracking activity by location/network

package/docs/middleware/maintenanceMode.md

@@ -0,0 +1,81 @@
+# Maintenance Mode Middleware
+
+**File:** `mw/maintenanceMode/index.js`
+
+**Order:** 7
+
+The Maintenance Mode middleware returns a configurable response when the gateway is in maintenance mode.
+
+## Purpose
+
+- Blocks all requests when maintenance mode is enabled
+- Returns configurable status code and message
+- Supports `Retry-After` header for clients
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────┐
+  │  Get Maintenance    │ registry.custom.gateway.value.maintenanceMode
+  │  Mode Config        │
+  └────────┬────────────┘
+           │
+           ▼
+  ┌─────────────────────┐
+  │  Maintenance        │ maintenanceMode.on === true?
+  │  Enabled?           │
+  └────────┬────────────┘
+           │
+           ├─── Yes ──▶ Return configured status/message
+           │            Set Retry-After header if configured
+           ▼
+       next()
+```
+
+## Configuration
+
+Located in `registry.custom.gateway.value.maintenanceMode`:
+
+```javascript
+{
+  "maintenanceMode": {
+    "on": true,                              // Enable maintenance mode
+    "status": 503,                           // HTTP status code
+    "message": "System maintenance",         // Response message
+    "retryAfter": 3600                       // Retry-After header (seconds)
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `on` | boolean | `false` | Enable/disable maintenance mode |
+| `status` | number | `503` | HTTP status code |
+| `message` | string | `"Maintenance mode is on, come back soon"` | Response message |
+| `retryAfter` | number | - | Seconds until retry |
+
+## Response
+
+When maintenance mode is enabled:
+```
+HTTP/1.1 503 Service Unavailable
+Content-Type: application/json
+Retry-After: 3600
+
+{
+  "result": false,
+  "errors": {
+    "codes": [xxx],
+    "details": [{ "code": xxx, "message": "System maintenance" }]
+  }
+}
+```
+
+## Usage Notes
+
+- All requests blocked when enabled (no exceptions)
+- Configure via Core DB custom registry
+- Use maintenance port (5000) for health checks during maintenance