soajs.controller 4.2.42 → 4.2.43

package/docs/gateway-routes.md

@@ -0,0 +1,259 @@
+# Built-in Gateway Routes
+
+The SOAJS Controller provides special built-in routes that are handled directly by the gateway rather than being proxied to backend services.
+
+## Route Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                          BUILT-IN GATEWAY ROUTES                                │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+    ┌─────────────────────────────────────────────────────────────────────────────┐
+    │                                                                             │
+    │   /soajs/acl                                                                │
+    │   ├── Method: GET                                                           │
+    │   ├── Purpose: Retrieve ACL/permissions for authenticated user              │
+    │   ├── Requires: External key (header), OAuth token (query)                  │
+    │   └── Returns: ACL, packages, user info, tenant info                        │
+    │                                                                             │
+    │   /soajs/proxy                                                              │
+    │   ├── Method: Any                                                           │
+    │   ├── Purpose: Proxy requests to external URLs or cross-environment         │
+    │   ├── Requires: proxyRoute query parameter                                  │
+    │   └── Optional: __env, tCode, extKey parameters                             │
+    │                                                                             │
+    │   /proxy/redirect  (DEPRECATED → use /soajs/proxy)                          │
+    │                                                                             │
+    └─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. ACL Route (`/soajs/acl`)
+
+**Endpoint:** `GET /soajs/acl`
+
+**Purpose:** Returns the Access Control List (ACL) and permissions for the currently authenticated user. This route is useful for frontend applications to determine what services and APIs the user has access to.
+
+### Required Headers
+
+| Header | Description |
+|--------|-------------|
+| `key` | External tenant key (required) |
+
+### Query Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `access_token` | OAuth2 access token for user-specific ACL |
+
+### Response Structure
+
+```javascript
+{
+  "acl": {                          // Raw ACL from tenant application or package
+    "serviceName": {
+      "version": {
+        "access": true,
+        "apisPermission": "restricted",
+        "get": { "apis": { "/api/path": {} } }
+      }
+    }
+  },
+  "finalACL": {                     // Computed ACL with latest versions
+    "serviceName": {
+      "version": "1",
+      "get": ["/api/path"]          // Allowed APIs per method (if restricted)
+    }
+  },
+  "packages": ["PACKAGE_CODE"],     // Allowed product packages
+  "urac": {                         // User info (if authenticated)
+    "_id": "user_id"
+  },
+  "tenant": {                       // Tenant info
+    "id": "tenant_id",
+    "name": "Tenant Name",
+    "code": "TCODE",
+    "type": "product"
+  }
+}
+```
+
+### Example
+
+```bash
+# Get ACL for authenticated user
+curl -X GET "http://api.example.com/soajs/acl?access_token=YOUR_TOKEN" \
+  -H "key: YOUR_EXTERNAL_KEY"
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| 132 | Missing or invalid external key |
+| 400 | OAuth token required but not provided |
+
+---
+
+## 2. Proxy Route (`/soajs/proxy`)
+
+**Endpoint:** `ANY /soajs/proxy`
+
+**Purpose:** Proxies requests to external URLs or to services in other SOAJS environments. Supports cross-environment communication with automatic key resolution.
+
+### Required Headers
+
+| Header | Description |
+|--------|-------------|
+| `key` | External tenant key |
+
+### Query Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `proxyRoute` | Yes | URL-encoded target route (full URL or service path) |
+| `__env` | No | Target environment code (e.g., "STG", "PROD") for cross-environment |
+| `tCode` | No | Tenant code for automatic key lookup in target environment |
+| `extKey` | No | Explicit external key to use for target environment |
+| `access_token` | No | OAuth token to forward |
+
+### Usage Modes
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           PROXY REQUEST MODES                                   │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  Mode 1: Direct URL Proxy
+  ─────────────────────────
+    proxyRoute=http://service:port/path
+
+    Request flows directly to the specified URL.
+    No environment lookup required.
+
+  Mode 2: Cross-Environment Proxy
+  ────────────────────────────────
+    proxyRoute=/service/api&__env=PROD&tCode=TENANT
+
+    1. Loads target environment registry
+    2. Looks up tenant's external key for that environment
+    3. Constructs URL from registry (protocol://domain:port)
+    4. Forwards request with remote ext key
+
+  Mode 3: Cross-Environment with Explicit Key
+  ───────────────────────────────────────────
+    proxyRoute=/service/api&__env=PROD&extKey=xxx
+
+    Uses the provided extKey instead of looking up tenant key.
+
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Examples
+
+```bash
+# Direct URL proxy
+curl -X GET "http://api.example.com/soajs/proxy?proxyRoute=http%3A%2F%2F127.0.0.1%3A4002%2FCheckPhoneNumber&access_token=TOKEN" \
+  -H "key: YOUR_EXTERNAL_KEY"
+
+# Cross-environment proxy with automatic key resolution
+curl -X GET "http://api.example.com/soajs/proxy?proxyRoute=%2Furac%2FgetUser&__env=STG&access_token=TOKEN" \
+  -H "key: YOUR_EXTERNAL_KEY"
+
+# Cross-environment proxy with explicit key
+curl -X POST "http://api.example.com/soajs/proxy?proxyRoute=%2Fservice%2Fapi&__env=PROD&extKey=REMOTE_KEY" \
+  -H "key: YOUR_EXTERNAL_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"data": "value"}'
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| 135 | Invalid proxy URL or connection failed |
+| 137 | No external key found for tenant in target environment |
+| 139 | Missing proxyRoute parameter |
+| 207 | Failed to load target environment registry |
+| 208 | Target environment registry missing protocol/domain/port |
+
+### Request Flow
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│                           PROXY REQUEST FLOW                                     │
+└──────────────────────────────────────────────────────────────────────────────────┘
+
+  Client Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Parse Query    │
+  │  Parameters     │
+  └────────┬────────┘
+           │
+           ├─── proxyRoute (required)
+           ├─── __env (optional)
+           ├─── tCode (optional)
+           └─── extKey (optional)
+           │
+           ▼
+  ┌─────────────────┐    ┌─────────────────┐
+  │  __env          │ NO │  Direct Proxy   │
+  │  provided?      │───▶│  to proxyRoute  │
+  └────────┬────────┘    └─────────────────┘
+           │ YES
+           ▼
+  ┌─────────────────┐
+  │  Load Remote    │
+  │  Environment    │
+  │  Registry       │
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐    ┌─────────────────┐
+  │  extKey         │YES │  Use Provided   │
+  │  provided?      │───▶│  extKey         │
+  └────────┬────────┘    └────────┬────────┘
+           │ NO                   │
+           ▼                      │
+  ┌─────────────────┐             │
+  │  Lookup Tenant  │             │
+  │  Key for Env    │             │
+  └────────┬────────┘             │
+           │                      │
+           └──────────┬───────────┘
+                      │
+                      ▼
+  ┌─────────────────────────────────────────┐
+  │  Construct Full URL                     │
+  │  protocol://domain:port/proxyRoute      │
+  └────────────────────┬────────────────────┘
+                       │
+                       ▼
+  ┌─────────────────────────────────────────┐
+  │  Forward Request with Headers           │
+  │  • soajs_roaming: source environment    │
+  │  • key: remote ext key (if applicable)  │
+  │  • Original headers (except host)       │
+  └────────────────────┬────────────────────┘
+                       │
+                       ▼
+                 Target Service
+```
+
+---
+
+## 3. Deprecated: `/proxy/redirect`
+
+**Status:** DEPRECATED
+
+**Replacement:** Use `/soajs/proxy` instead
+
+This route has identical functionality to `/soajs/proxy` but is deprecated. The gateway will log a warning when this route is used:
+
+```
+Route: [/proxy/redirect] is deprecated. You should use [/soajs/proxy].
+```

package/docs/maintenance-routes.md

@@ -0,0 +1,308 @@
+# Maintenance Routes
+
+The SOAJS Controller provides maintenance endpoints on a separate port (default: 5000) for health checks, configuration management, and system administration.
+
+## Server Overview
+
+**File:** `server/maintenance.js`
+
+**Default Port:** 5000
+
+The maintenance server runs on a separate port from the main gateway to allow internal access for health checks and administration without exposing these endpoints publicly.
+
+## Available Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/heartbeat` | GET | Basic health check |
+| `/loadProvision` | GET | Reload provision/tenant data |
+| `/reloadRegistry` | GET | Reload environment registry |
+| `/awarenessStat` | GET | Get service awareness statistics |
+
+---
+
+## 1. Heartbeat (`/heartbeat`)
+
+**Endpoint:** `GET /heartbeat`
+
+**Purpose:** Basic health check to verify the gateway is running.
+
+### Response
+
+```javascript
+{
+  "result": true,
+  "ts": 1699999999999,           // Timestamp
+  "service": {
+    "service": "controller",
+    "type": "rest",
+    "route": "/heartbeat"
+  }
+}
+```
+
+### Usage
+
+```bash
+curl http://localhost:5000/heartbeat
+```
+
+### Kubernetes/Docker Health Probes
+
+```yaml
+# Kubernetes
+livenessProbe:
+  httpGet:
+    path: /heartbeat
+    port: 5000
+  initialDelaySeconds: 30
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /heartbeat
+    port: 5000
+  initialDelaySeconds: 5
+  periodSeconds: 5
+```
+
+---
+
+## 2. Load Provision (`/loadProvision`)
+
+**Endpoint:** `GET /loadProvision`
+
+**Purpose:** Reloads tenant, key, and package data from the Core DB.
+
+### Response
+
+```javascript
+{
+  "result": true,
+  "ts": 1699999999999,
+  "service": {
+    "service": "controller",
+    "type": "rest",
+    "route": "/loadProvision"
+  }
+}
+```
+
+### Usage
+
+```bash
+curl http://localhost:5000/loadProvision
+```
+
+### When to Use
+
+- After updating tenant configurations
+- After modifying application keys
+- After changing package ACLs
+- To force refresh of cached provision data
+
+---
+
+## 3. Reload Registry (`/reloadRegistry`)
+
+**Endpoint:** `GET /reloadRegistry`
+
+**Purpose:** Reloads the environment registry from the Core DB.
+
+### Response
+
+```javascript
+{
+  "result": true,
+  "ts": 1699999999999,
+  "service": {
+    "service": "controller",
+    "type": "rest",
+    "route": "/reloadRegistry"
+  }
+}
+```
+
+### Usage
+
+```bash
+curl http://localhost:5000/reloadRegistry
+```
+
+### What Gets Reloaded
+
+- Service definitions and hosts
+- Database configurations
+- Service config (throttling, CORS, OAuth)
+- Custom gateway settings
+- All environment-specific settings
+
+### When to Use
+
+- After modifying environment configuration
+- After adding new services
+- After changing service hosts
+- After modifying custom registry settings
+
+---
+
+## 4. Awareness Statistics (`/awarenessStat`)
+
+**Endpoint:** `GET /awarenessStat`
+
+**Purpose:** Returns the current state of service awareness/discovery.
+
+### Response (Custom Mode)
+
+```javascript
+{
+  "result": true,
+  "ts": 1699999999999,
+  "service": {
+    "service": "controller",
+    "type": "rest",
+    "route": "/awarenessStat"
+  },
+  "data": {
+    "services": {
+      "oauth": {
+        "1": {
+          "hosts": ["host1.local:4002", "host2.local:4002"],
+          "healthy": 2
+        },
+        "2": {
+          "hosts": ["host3.local:4002"],
+          "healthy": 1
+        }
+      },
+      "urac": {
+        "3": {
+          "hosts": ["host1.local:4001"],
+          "healthy": 1
+        }
+      }
+    }
+  }
+}
+```
+
+### Response (HA Mode)
+
+```javascript
+{
+  "result": true,
+  "ts": 1699999999999,
+  "service": {
+    "service": "controller",
+    "type": "rest",
+    "route": "/awarenessStat"
+  },
+  "data": {
+    "mode": "kubernetes",
+    "services": {
+      "oauth": {
+        "1": {
+          "pods": ["oauth-v1-abc123", "oauth-v1-def456"],
+          "healthy": 2
+        }
+      }
+    }
+  }
+}
+```
+
+### Usage
+
+```bash
+curl http://localhost:5000/awarenessStat
+```
+
+### When to Use
+
+- To verify service discovery is working
+- To check service health status
+- To debug routing issues
+- To monitor cluster state
+
+---
+
+## Security Considerations
+
+### Network Access
+
+The maintenance port should only be accessible from:
+- Internal networks
+- Kubernetes cluster (for probes)
+- Monitoring systems
+
+### Firewall Rules
+
+```bash
+# Example: Only allow internal access to maintenance port
+iptables -A INPUT -p tcp --dport 5000 -s 10.0.0.0/8 -j ACCEPT
+iptables -A INPUT -p tcp --dport 5000 -j DROP
+```
+
+### Kubernetes NetworkPolicy
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: controller-maintenance
+spec:
+  podSelector:
+    matchLabels:
+      soajs.service.name: controller
+  ingress:
+  - from:
+    - namespaceSelector:
+        matchLabels:
+          name: monitoring
+    ports:
+    - port: 5000
+```
+
+---
+
+## Integration with Monitoring
+
+### Prometheus Metrics
+
+The heartbeat endpoint can be used with Prometheus blackbox exporter:
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: 'soajs-controller'
+    metrics_path: /probe
+    params:
+      module: [http_2xx]
+    static_configs:
+      - targets:
+        - http://controller:5000/heartbeat
+    relabel_configs:
+      - source_labels: [__address__]
+        target_label: __param_target
+      - source_labels: [__param_target]
+        target_label: instance
+      - target_label: __address__
+        replacement: blackbox-exporter:9115
+```
+
+### Health Check Scripts
+
+```bash
+#!/bin/bash
+# health-check.sh
+
+RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5000/heartbeat)
+
+if [ "$RESPONSE" == "200" ]; then
+  echo "Gateway is healthy"
+  exit 0
+else
+  echo "Gateway health check failed: HTTP $RESPONSE"
+  exit 1
+fi
+```

package/docs/middleware/awareness.md

@@ -0,0 +1,120 @@
+# Awareness Middleware
+
+**File:** `mw/awareness/index.js`
+
+**Order:** 9
+
+The Awareness middleware provides service discovery functions for resolving service hosts.
+
+## Purpose
+
+- Attaches service discovery functions to `req.soajs.awareness`
+- Supports both Custom mode (static registry) and HA mode (Kubernetes/Swarm)
+- Provides host resolution and version lookup
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────┐
+  │  Determine Mode     │ process.env.SOAJS_DEPLOY_HA?
+  │  Custom or HA       │
+  └────────┬────────────┘
+           │
+           ├─── No HA ──▶ Use custom.js driver
+           │
+           ├─── HA ──▶ Use ha.js driver
+           │
+           ▼
+  ┌─────────────────────┐
+  │  Attach Awareness   │ req.soajs.awareness = { ... }
+  │  Functions          │
+  └────────┬────────────┘
+           │
+           ▼
+       next()
+```
+
+## Drivers
+
+### Custom Mode (Non-HA)
+
+**File:** `mw/awareness/custom.js`
+
+- Uses registry's static host lists
+- In-memory health tracking
+- Round-robin load balancing
+
+### HA Mode (Kubernetes/Swarm)
+
+**File:** `mw/awareness/ha.js`
+
+- Uses infrastructure module for discovery
+- Dynamic service resolution via cluster API
+- Automatic health monitoring
+
+## Methods Added
+
+### `req.soajs.awareness.getHost(serviceName, [version], callback)`
+
+Resolves a host for the given service.
+
+**Parameters:**
+- `serviceName` - Name of the service
+- `version` - Service version (optional)
+- `callback` - Function receiving `(host)` where host is `"hostname:port"` or `null`
+
+**Example:**
+```javascript
+req.soajs.awareness.getHost("oauth", "1", (host) => {
+  if (host) {
+    // host = "oauth-service:4002"
+  }
+});
+```
+
+### `req.soajs.awareness.getLatestVersion(serviceName, callback)`
+
+Gets the latest available version of a service.
+
+**Parameters:**
+- `serviceName` - Name of the service
+- `callback` - Function receiving `(version)` as string or `null`
+
+**Example:**
+```javascript
+req.soajs.awareness.getLatestVersion("oauth", (version) => {
+  // version = "2"
+});
+```
+
+### `req.soajs.awareness.getLatestVersionFromCluster(serviceName, callback)`
+
+(HA mode only) Gets the latest version directly from the cluster.
+
+**Example:**
+```javascript
+if (process.env.SOAJS_DEPLOY_HA) {
+  req.soajs.awareness.getLatestVersionFromCluster("oauth", (version) => {
+    // Fresh lookup from K8s/Swarm API
+  });
+}
+```
+
+## Configuration
+
+```javascript
+{
+  "awareness": true,           // Enable awareness
+  "doNotRebuildCache": false   // Skip initial cache build (HA mode)
+}
+```
+
+## Usage Notes
+
+- Custom mode caches hosts in memory, updated via heartbeat
+- HA mode queries cluster API for each lookup (with caching)
+- Version can be omitted to get any available host
+- Returns `null` if service/version not found