soajs.controller 4.3.3 → 4.3.5

package/Gruntfile.js

@@ -65,7 +65,7 @@ module.exports = function (grunt) {
 				"curly": true,
 				"eqeqeq": true,
 				"eqnull": true,
-				"esversion": 8,
+				"esversion": 9,
 				"forin": true,
 				"latedef": "nofunc",
 				"leanswitch": true,

package/docs/configuration-custom-registry.md

@@ -16,6 +16,13 @@ registry.custom
 │       │   ├── model               # Throttling storage backend
 │       │   ├── ip2ban              # Banned IP addresses
 │       │   └── throttling          # Service-level rate limiting
+│       ├── idempotency             # Idempotency key configuration
+│       │   ├── model               # Storage backend (memory/mongo)
+│       │   └── [service]           # Per-service idempotency config
+│       ├── cache                   # GET response caching
+│       │   ├── model               # Storage backend (memory/mongo)
+│       │   ├── defaultTTL          # Default cache TTL
+│       │   └── [service]           # Per-service cache config
 │       ├── maintenanceMode         # Gateway maintenance mode
 │       ├── lastSeen                # User activity tracking
 │       └── gotoService
@@ -122,7 +129,119 @@ Configures rate limiting strategies and storage backend.
 
 ---
 
-## 4. Multi-Tenant IP Whitelist
+## 4. Idempotency
+
+**Path:** `registry.custom.gateway.value.idempotency`
+
+**Middleware:** `mw/idempotency/index.js`
+
+Prevents duplicate write operations by tracking requests via `Idempotency-Key` headers. When a client retries a request with the same key, the cached response is returned without re-executing the operation.
+
+```javascript
+{
+  "idempotency": {
+    "model": "memory",                    // Storage: "memory" or "mongo"
+    "av": {                               // Service name
+      "enabled": true,                    // Enable for this service
+      "ttl": 60000,                       // Key expiration (ms)
+      "apis": [                           // APIs to protect
+        "POST /av/calls",
+        "PUT /av/call/p2p/ended",
+        "PUT /av/call/p2p/rejected"
+      ]
+    },
+    "payment": {
+      "enabled": true,
+      "ttl": 120000,
+      "apis": [
+        "POST /payment/charge",
+        "POST /payment/refund"
+      ]
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
+| `[service].enabled` | boolean | `false` | Enable idempotency for this service |
+| `[service].ttl` | number | `60000` | Key expiration time in milliseconds |
+| `[service].apis` | string[] | `[]` | API patterns to protect (e.g., `"POST /path"`) |
+
+**Client Usage:**
+```http
+POST /av/calls HTTP/1.1
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+```
+
+**Error Codes:**
+- `180` (400): Invalid Idempotency-Key format (not UUID v4)
+- `181` (409): Request with this key is still being processed
+
+---
+
+## 5. Response Caching
+
+**Path:** `registry.custom.gateway.value.cache`
+
+**Middleware:** `mw/cache/index.js`
+
+Caches GET API responses with per-API TTL configuration. Returns `X-Cache: HIT` or `X-Cache: MISS` headers.
+
+```javascript
+{
+  "cache": {
+    "model": "memory",                    // Storage: "memory" or "mongo"
+    "defaultTTL": 300000,                 // Default TTL: 5 minutes
+    "av": {                               // Service name
+      "enabled": true,                    // Enable caching for this service
+      "apis": {
+        "GET /av/calls": {
+          "enabled": true,
+          "ttl": 30000                    // 30 seconds
+        },
+        "GET /av/call/:id": {
+          "enabled": true,
+          "ttl": 60000                    // 60 seconds
+        }
+      }
+    },
+    "catalog": {
+      "enabled": true,
+      "apis": {
+        "GET /catalog/products": {
+          "enabled": true,
+          "ttl": 600000                   // 10 minutes
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
+| `defaultTTL` | number | `300000` | Default cache TTL in milliseconds |
+| `[service].enabled` | boolean | `false` | Enable caching for this service |
+| `[service].apis` | object | `{}` | API-specific cache configuration |
+| `[service].apis[api].enabled` | boolean | `false` | Enable caching for this API |
+| `[service].apis[api].ttl` | number | `defaultTTL` | Cache TTL for this specific API |
+
+**Response Headers:**
+- `X-Cache: HIT` - Response served from cache
+- `X-Cache: MISS` - Response fetched from backend
+- `X-Cache-Age: <seconds>` - Time since cached (on HIT)
+
+**Notes:**
+- Only GET requests are cached
+- Only 2xx responses are cached
+- Cache key includes tenant ID, service name, path, and query hash
+
+---
+
+## 6. Multi-Tenant IP Whitelist
 
 **Path:** `registry.custom.gateway.value.mt.whitelist`
 
@@ -150,7 +269,7 @@ Allows specific IP ranges to bypass ACL and/or OAuth checks.
 
 ---
 
-## 5. User Activity Tracking (Last Seen)
+## 7. User Activity Tracking (Last Seen)
 
 **Path:** `registry.custom.gateway.value.lastSeen`
 
@@ -180,7 +299,7 @@ Tracks user activity by notifying a service (typically URAC) of user access.
 
 ---
 
-## 6. Request Monitoring
+## 8. Request Monitoring
 
 **Path:** `registry.custom.gateway.value.gotoService.monitor`
 
@@ -208,7 +327,7 @@ Controls which services are monitored for metrics collection.
 
 ---
 
-## 7. Request Timeout Renewal
+## 9. Request Timeout Renewal
 
 **Path:** `registry.custom.gateway.value.gotoService.renewReqMonitorOff`
 
@@ -230,7 +349,7 @@ Disables the heartbeat renewal mechanism for long-running requests.
 
 ---
 
-## 8. OAuth Roaming (Cross-Environment)
+## 10. OAuth Roaming (Cross-Environment)
 
 **Path:** `registry.custom.oauth.value.roaming`
 
@@ -260,7 +379,7 @@ Enables cross-environment access for specific services with IP-based whitelistin
 
 ---
 
-## 9. PIN Login Wrapper
+## 11. PIN Login Wrapper
 
 **Path:** `registry.custom.oauth.value.pinWrapper`
 
@@ -284,7 +403,7 @@ Defines a custom PIN-based login endpoint that bypasses standard OAuth flow.
 
 ---
 
-## 10. PIN Login API Whitelist
+## 12. PIN Login API Whitelist
 
 **Path:** `registry.custom.oauth.value.pinWhitelist`
 
@@ -359,6 +478,25 @@ Whitelists specific APIs that can be accessed when a user is PIN-locked (during
         }
       }
     },
+    "idempotency": {
+      "model": "mongo",
+      "payment": {
+        "enabled": true,
+        "ttl": 120000,
+        "apis": ["POST /payment/charge", "POST /payment/refund"]
+      }
+    },
+    "cache": {
+      "model": "mongo",
+      "defaultTTL": 300000,
+      "catalog": {
+        "enabled": true,
+        "apis": {
+          "GET /catalog/products": { "enabled": true, "ttl": 600000 },
+          "GET /catalog/categories": { "enabled": true, "ttl": 3600000 }
+        }
+      }
+    },
     "lastSeen": {
       "active": true,
       "serviceName": "urac",
@@ -417,5 +555,7 @@ Custom registry configurations are processed in this order:
 | 4 | gotoService/preRedirect | `gotoService.renewReqMonitorOff` |
 | 5 | gotoService/redirectToService | `gotoService.monitor` |
 | 6 | mt (security checks) | `mt.whitelist`, `oauth.value.pinWrapper`, `oauth.value.pinWhitelist` |
-| 7 | traffic | `traffic.model`, `traffic.throttling` |
-| 8 | lastSeen | `lastSeen` |
+| 7 | idempotency | `idempotency.model`, `idempotency.[service]` |
+| 8 | traffic | `traffic.model`, `traffic.throttling` |
+| 9 | cache | `cache.model`, `cache.defaultTTL`, `cache.[service]` |
+| 10 | lastSeen | `lastSeen` |

package/docs/middleware/cache.md

@@ -0,0 +1,237 @@
+# Cache Middleware
+
+**File:** `mw/cache/index.js`
+
+**Order:** 19 (after Traffic middleware)
+
+The Cache middleware provides response caching for GET APIs with per-API TTL configuration.
+
+## Purpose
+
+- Caches GET API responses to reduce backend load
+- Supports per-API TTL configuration
+- Provides cache hit/miss headers for debugging
+- Supports memory and MongoDB storage backends
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Check Method           │ GET request?
+  └────────┬────────────────┘
+           │
+           ├─── Not GET ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Check Configuration    │ Service enabled? API matches?
+  └────────┬────────────────┘
+           │
+           ├─── Not configured ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Generate Cache Key     │ tenant:service:path:queryHash
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Lookup Cache           │
+  └────────┬────────────────┘
+           │
+           ├─── HIT ──▶ Return cached response (X-Cache: HIT)
+           │
+           └─── MISS ──▶ Execute → Cache response → Return (X-Cache: MISS)
+```
+
+## Configuration
+
+**Path:** `registry.custom.gateway.value.cache`
+
+```javascript
+{
+  "cache": {
+    "model": "memory",                    // Storage: "memory" or "mongo"
+    "defaultTTL": 300000,                 // Default TTL: 5 minutes
+    "services": {                         // Service configurations
+      "av": {                             // Service name
+        "enabled": true,                  // Enable caching for this service
+        "apis": {
+          "GET /calls": {
+            "enabled": true,
+            "ttl": 30000                  // 30 seconds
+          },
+          "GET /call/:id": {
+            "enabled": true,
+            "ttl": 60000                  // 60 seconds
+          },
+          "GET /users": {
+            "enabled": true
+            // Uses defaultTTL (300000ms)
+          }
+        }
+      },
+      "catalog": {
+        "enabled": true,
+        "apis": {
+          "GET /products": {
+            "enabled": true,
+            "ttl": 600000                 // 10 minutes
+          },
+          "GET /categories": {
+            "enabled": true,
+            "ttl": 3600000                // 1 hour
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
+| `defaultTTL` | number | `300000` | Default cache TTL in milliseconds (5 min) |
+| `services.[name].enabled` | boolean | `false` | Enable caching for this service |
+| `services.[name].apis` | object | `{}` | API-specific cache configuration |
+| `services.[name].apis[api].enabled` | boolean | `false` | Enable caching for this API |
+| `services.[name].apis[api].ttl` | number | `defaultTTL` | Cache TTL for this API |
+
+## API Pattern Matching
+
+APIs are matched using `GET /path` format with support for path parameters:
+
+```javascript
+"apis": {
+  "GET /users": { ... },                  // Exact match
+  "GET /users/:id": { ... },              // :id matches any segment
+  "GET /users/:userId/posts/:postId": { ... }  // Multiple params
+}
+```
+
+## Cache Key Structure
+
+```javascript
+{
+  "l1": "tenant_id",
+  "l2": "serviceName:GET:/path:queryHash"
+}
+```
+
+- **tenant_id**: Isolates cache per tenant
+- **serviceName**: The target service name
+- **path**: The API path
+- **queryHash**: MD5 hash of sorted query parameters
+
+### Query Parameter Handling
+
+Query parameters are included in the cache key via MD5 hash:
+
+```
+GET /users?page=1&limit=10  → key includes hash of {"limit":"10","page":"1"}
+GET /users?limit=10&page=1  → same hash (sorted)
+GET /users                  → different key (no query hash)
+```
+
+## 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
+
+## Response Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Cache` | `HIT` or `MISS` indicating cache status |
+| `X-Cache-Age` | Seconds since response was cached (on HIT) |
+
+### Cache HIT
+
+```http
+HTTP/1.1 200 OK
+X-Cache: HIT
+X-Cache-Age: 15
+Content-Type: application/json
+
+{"data": [...]}
+```
+
+### Cache MISS
+
+```http
+HTTP/1.1 200 OK
+X-Cache: MISS
+Content-Type: application/json
+
+{"data": [...]}
+```
+
+## Caching Behavior
+
+### What Gets Cached
+
+- Only successful responses (HTTP 2xx)
+- Response status code
+- Response headers
+- Response body
+
+### What Doesn't Get Cached
+
+- Non-GET requests
+- Error responses (4xx, 5xx)
+- APIs not configured for caching
+
+## Usage Notes
+
+- Only GET requests are cached
+- Cache is tenant-isolated
+- Query parameters affect cache key
+- Only 2xx responses are cached
+- Headers like `X-Cache` are not stored in cache
+- MongoDB backend required for horizontal scaling
+- Consider TTL based on data freshness requirements
+
+## Example Scenarios
+
+### Static Data (Long TTL)
+
+```javascript
+"GET /catalog/categories": {
+  "enabled": true,
+  "ttl": 3600000  // 1 hour - categories rarely change
+}
+```
+
+### Dynamic Data (Short TTL)
+
+```javascript
+"GET /av/calls": {
+  "enabled": true,
+  "ttl": 5000     // 5 seconds - frequently updated
+}
+```
+
+### User-Specific Data
+
+```javascript
+// Cache key includes tenant ID, so each tenant has separate cache
+"GET /users/profile": {
+  "enabled": true,
+  "ttl": 60000    // 1 minute
+}
+```

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