soajs.controller 4.2.42 → 4.3.0

package/docs/middleware/oauth.md

@@ -0,0 +1,173 @@
+# OAuth Middleware
+
+**File:** `mw/oauth/index.js`
+
+**Order:** 15
+
+The OAuth middleware handles authentication by validating OAuth2 tokens or JWT tokens.
+
+## Purpose
+
+- Validates OAuth2 access tokens via oauth2-server
+- Validates JWT tokens via jsonwebtoken
+- Supports tenant-specific OAuth configuration
+- Sets `req.oauth` with token information
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Determine OAuth Type   │ tenantOauth.type or
+  │                         │ registry.serviceConfig.oauth.type
+  └────────┬────────────────┘
+           │
+           ├─── Type 0 (JWT) ──▶ JWT Validation
+           │
+           ├─── Type 2 (OAuth2) ──▶ OAuth2 Server Validation
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Set req.oauth          │ { bearerToken, type }
+  └────────┬────────────────┘
+           │
+           ▼
+       next() or Error
+```
+
+## OAuth Types
+
+### Type 2: OAuth2 (Default)
+
+Uses oauth2-server library for token validation.
+
+```
+  Request with access_token
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  oauth2-server          │ Validates token against DB
+  │  authorise()            │
+  └────────┬────────────────┘
+           │
+           ├─── Invalid ──▶ OAuth2Error
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  req.oauth = {          │
+  │    bearerToken: user,   │
+  │    type: 2              │
+  │  }                      │
+  └─────────────────────────┘
+```
+
+### Type 0: JWT
+
+Uses jsonwebtoken library for JWT validation.
+
+```
+  Request with Authorization: Bearer <jwt>
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Extract Bearer Token   │ from Authorization header
+  └────────┬────────────────┘
+           │
+           ├─── No match ──▶ Error 143
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  jwt.verify()           │ Using secret and algorithms
+  └────────┬────────────────┘
+           │
+           ├─── Invalid ──▶ Error 143
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  req.oauth = {          │
+  │    bearerToken: decoded,│
+  │    type: 0              │
+  │  }                      │
+  └─────────────────────────┘
+```
+
+## Configuration
+
+### OAuth2 Configuration
+
+Located in `registry.serviceConfig.oauth`:
+
+```javascript
+{
+  "oauth": {
+    "type": 2,
+    "grants": ["password", "refresh_token"],
+    "debug": false,
+    "accessTokenLifetime": 7200,
+    "refreshTokenLifetime": 1209600
+  }
+}
+```
+
+### JWT Configuration
+
+```javascript
+{
+  "oauth": {
+    "type": 0,
+    "secret": "jwt_secret_key",
+    "algorithms": ["HS256"],
+    "audience": "my-app"
+  }
+}
+```
+
+### Tenant-Specific OAuth
+
+Tenants can override OAuth settings via `tenantOauth`:
+
+```javascript
+{
+  "type": 0,                    // Override to JWT
+  "secret": "tenant_jwt_secret"
+}
+```
+
+## OAuth Service Integration
+
+Default OAuth service configuration:
+
+```javascript
+{
+  "oauthService": {
+    "name": "oauth",
+    "tokenApi": "/token",
+    "authorizationApi": "/authorization",
+    "pinApi": "/pin"
+  }
+}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 143 | Invalid or missing JWT token |
+| OAuth2Error | Various OAuth2 errors (invalid_token, expired, etc.) |
+
+## Properties Set
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `req.oauth.bearerToken` | object | Decoded token or user object |
+| `req.oauth.type` | number | OAuth type (0=JWT, 2=OAuth2) |
+
+## Usage Notes
+
+- OAuth type can be set globally or per-tenant
+- JWT requires `Authorization: Bearer <token>` header
+- OAuth2 uses `access_token` query parameter or header
+- Tenant OAuth settings override global settings
+- OAuth model is provided by configuration (provision module)

package/docs/middleware/response.md

@@ -0,0 +1,106 @@
+# Response Middleware
+
+**File:** `mw/response/index.js`
+
+**Order:** 4
+
+The Response middleware adds standardized response builder methods to the request object.
+
+## Purpose
+
+- Adds `req.soajs.buildResponse()` for creating SOAJS-formatted responses
+- Adds `req.soajs.controllerResponse()` for sending gateway responses
+- Provides consistent error/success response structure
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Attach buildResponse() │ Creates SOAJS response objects
+  └────────────┬────────────┘
+               │
+               ▼
+  ┌─────────────────────────────┐
+  │  Attach controllerResponse()│ Sends JSON responses
+  └────────────┬────────────────┘
+               │
+               ▼
+           next()
+```
+
+## Methods Added
+
+### `req.soajs.buildResponse(error, data)`
+
+Creates a SOAJS-formatted response object.
+
+**Parameters:**
+- `error` - Error object or array of errors (optional)
+- `data` - Response data (optional)
+
+**Returns:**
+```javascript
+// Success
+{
+  "result": true,
+  "data": { ... }
+}
+
+// Error
+{
+  "result": false,
+  "errors": {
+    "codes": [100, 101],
+    "details": [
+      { "code": 100, "message": "Error message" },
+      { "code": 101, "message": "Another error" }
+    ]
+  }
+}
+```
+
+### `req.soajs.controllerResponse(jsonObj)`
+
+Sends a JSON response and ends the request.
+
+**Parameters:**
+- `jsonObj` - Response object with optional `status`, `headObj`, `code`, `msg`
+
+**Examples:**
+```javascript
+// Success response
+req.soajs.controllerResponse({ data: { user: "john" } });
+
+// Error response
+req.soajs.controllerResponse({
+  status: 403,
+  code: 150,
+  msg: "Access denied"
+});
+
+// With custom headers
+req.soajs.controllerResponse({
+  status: 429,
+  msg: "Too many requests",
+  headObj: {
+    "Retry-After": 60,
+    "X-RateLimit-Limit": 100
+  }
+});
+```
+
+## Response Format
+
+All responses include:
+- `Content-Type: application/json` header
+- HTTP status code (default: 200)
+- JSON body
+
+## Usage Notes
+
+- `controllerResponse()` only available when `controllerResponse: true` in config
+- Prevents double-ending responses (tracks `ended` state)
+- Automatically formats errors using `buildResponse()` when `code` and `msg` provided

package/docs/middleware/soajs.md

@@ -0,0 +1,71 @@
+# SOAJS Middleware
+
+**File:** `mw/soajs/index.js`
+
+**Order:** 1
+
+The SOAJS middleware is the first middleware in the pipeline. It initializes the `req.soajs` context object that all subsequent middleware depend on.
+
+## Purpose
+
+- Creates the `req.soajs` namespace
+- Attaches the logger instance
+- Attaches the current registry reference
+- Attaches core utility modules (meta, validator)
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Create         │ if (!req.soajs) req.soajs = {}
+  │  req.soajs      │
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Attach Logger  │ req.soajs.log = log
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Attach         │ req.soajs.registry = registryModule.get()
+  │  Registry       │
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Attach Core    │ req.soajs.meta = core.meta
+  │  Modules        │ req.soajs.validator = core.validator
+  └────────┬────────┘
+           │
+           ▼
+       next()
+```
+
+## Configuration
+
+```javascript
+{
+  "log": logger,        // Logger instance
+  "core": coreModule    // soajs.core.libs module
+}
+```
+
+## Properties Set
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `req.soajs.log` | object | Logger instance for request-scoped logging |
+| `req.soajs.registry` | object | Current environment registry |
+| `req.soajs.meta` | object | Metadata utilities from core |
+| `req.soajs.validator` | object | JSON schema validator |
+
+## Usage Notes
+
+- This middleware MUST be first in the pipeline
+- All other middleware assume `req.soajs` exists
+- The registry is fetched fresh on each request (reference, not copy)
+- Logger supports: `debug()`, `info()`, `warn()`, `error()`, `fatal()`

package/docs/middleware/traffic.md

@@ -0,0 +1,190 @@
+# Traffic Middleware
+
+**File:** `mw/traffic/index.js`
+
+**Order:** 16
+
+The Traffic middleware implements rate limiting (throttling) with configurable strategies and storage backends.
+
+## Purpose
+
+- Enforces rate limiting per tenant/IP
+- Supports configurable throttling strategies
+- Provides memory and MongoDB storage backends
+- Returns rate limit headers in responses
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Check Prerequisites    │ registry, tenant, controller exist?
+  └────────┬────────────────┘
+           │
+           ├─── Missing ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Determine Strategy     │ publicAPIStrategy or privateAPIStrategy
+  └────────┬────────────────┘
+           │
+           ├─── No strategy ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Get Throttling Config  │ Priority:
+  │                         │ 1. servicesConfig.gateway.throttling
+  │                         │ 2. custom.gateway.value.traffic.throttling
+  │                         │ 3. serviceConfig.throttling
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Check Throttling       │ Get/increment counter
+  │  Counter                │ Compare to limit
+  └────────┬────────────────┘
+           │
+           ├─── Under limit ──▶ next()
+           │
+           ├─── Over limit, retries left ──▶ Delay and retry
+           │
+           └─── Over limit, no retries ──▶ 429 Too Many Requests
+```
+
+## Configuration
+
+### Strategy Definition
+
+Located in `registry.serviceConfig.throttling`:
+
+```javascript
+{
+  "throttling": {
+    "publicAPIStrategy": "default",      // For unauthenticated requests
+    "privateAPIStrategy": "heavy",       // For authenticated requests
+    "default": {
+      "status": 1,                       // 0=Off, 1=On
+      "type": 1,                         // 0=tenant, 1=tenant+IP
+      "window": 60000,                   // Time window in ms
+      "limit": 50,                       // Max requests per window
+      "retries": 2,                      // Retries when over limit
+      "delay": 1000                      // Delay between retries (ms)
+    },
+    "heavy": {
+      "status": 1,
+      "type": 1,
+      "window": 60000,
+      "limit": 500,
+      "retries": 2,
+      "delay": 1000
+    },
+    "strict": {
+      "status": 1,
+      "type": 1,
+      "window": 60000,
+      "limit": 10,
+      "retries": 0,
+      "delay": 0
+    }
+  }
+}
+```
+
+### Service-Specific Override
+
+Via custom registry or tenant config:
+
+```javascript
+{
+  "throttling": {
+    "oauth": {
+      "publicAPIStrategy": "strict",
+      "apis": ["/token"]                 // Only these APIs
+    },
+    "payment": {
+      "publicAPIStrategy": "strict",
+      "privateAPIStrategy": "heavy",
+      "apis": ["/charge", "/refund"]
+    }
+  }
+}
+```
+
+## Strategy Selection
+
+| Request Type | Strategy Used |
+|--------------|---------------|
+| Public API (no auth) | `publicAPIStrategy` |
+| Private API (authenticated) | `privateAPIStrategy` |
+
+Determined by: `req.soajs.controller.serviceParams.isAPIPublic`
+
+## Storage Backends
+
+### Memory (Default)
+
+- Fast, in-process storage
+- Lost on restart
+- Good for single-instance deployments
+
+### MongoDB
+
+- Persistent storage
+- Shared across instances
+- Required for multi-instance deployments
+
+Configure via `registry.custom.gateway.value.traffic.model`:
+
+```javascript
+{
+  "traffic": {
+    "model": "mongo"                     // or "memory"
+  }
+}
+```
+
+## Rate Limit Response
+
+When rate limit exceeded:
+
+```
+HTTP/1.1 429 Too Many Requests
+Content-Type: application/json
+Retry-After: 45
+X-RateLimit-Limit: 50
+X-RateLimit-Remaining: 0
+
+{
+  "result": false,
+  "errors": { ... }
+}
+```
+
+## Response Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-RateLimit-Limit` | Maximum requests allowed |
+| `X-RateLimit-Remaining` | Requests remaining in window |
+| `Retry-After` | Seconds until window resets |
+
+## Throttle Key Structure
+
+```javascript
+{
+  "l1": "tenant_id",
+  "l2": "client_ip"
+}
+```
+
+Creates unique tracking per tenant per IP.
+
+## Usage Notes
+
+- Throttling disabled if no strategy configured
+- Service-specific config overrides global config
+- APIs array allows targeting specific endpoints
+- Retries add delay before rejection
+- MongoDB model required for horizontal scaling

package/docs/middleware/url.md

@@ -0,0 +1,102 @@
+# URL Middleware
+
+**File:** `mw/url/index.js`
+
+**Order:** 8
+
+The URL middleware parses the request URL and extracts service routing information.
+
+## Purpose
+
+- Parses URL into components (service name, version, path)
+- Validates service exists in registry
+- Normalizes header and query parameters (key, access_token)
+- Creates `req.soajs.controller.serviceParams` structure
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Ensure         │ if (!req.soajs.controller)
+  │  Controller     │    req.soajs.controller = {}
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Parse URL      │ url.parse(req.url, true)
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Extract        │ service_n, service_v, service_nv
+  │  Service Info   │ serviceInfo, path
+  └────────┬────────┘
+           │
+           ├─── No service name? ──▶ Error 136
+           │
+           ├─── Service not in registry? ──▶ Error 130
+           │
+           ▼
+  ┌─────────────────┐
+  │  Normalize      │ key, access_token from headers/query
+  │  Auth Params    │
+  └────────┬────────┘
+           │
+           ▼
+       next()
+```
+
+## URL Parsing
+
+**URL Format:** `/{service}/{version}/{path}`
+
+| Component | Example | Description |
+|-----------|---------|-------------|
+| `service_n` | `oauth` | Service name |
+| `service_v` | `1` | Service version (optional) |
+| `service_nv` | `oauth/1` | Service with version |
+| `path` | `/token` | API path |
+
+**Examples:**
+```
+/oauth/token         → service: oauth, version: null, path: /token
+/oauth/1/token       → service: oauth, version: 1, path: /token
+/urac/3/user/login   → service: urac, version: 3, path: /user/login
+```
+
+## Properties Set
+
+| Property | Description |
+|----------|-------------|
+| `req.soajs.controller.serviceParams.service_n` | Service name |
+| `req.soajs.controller.serviceParams.service_v` | Service version |
+| `req.soajs.controller.serviceParams.service_nv` | Service with version |
+| `req.soajs.controller.serviceParams.serviceInfo` | URL path segments array |
+| `req.soajs.controller.serviceParams.parsedUrl` | Full parsed URL object |
+| `req.query` | Query parameters |
+
+## Auth Parameter Normalization
+
+The middleware normalizes authentication parameters:
+
+1. **Key:** `req.headers.key` ← `req.headers.key || req.query.key`
+2. **Access Token:** `req.query.access_token` ←
+   - `req.query.access_token`
+   - `req.headers.access_token`
+   - Bearer token from `Authorization` header
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 130 | Service not found in registry |
+| 136 | Empty or missing service name |
+
+## Usage Notes
+
+- Throws TypeError if SOAJS middleware hasn't run first
+- Special handling for `soajs` service name (gateway routes)
+- Authorization header is deleted after extracting Bearer token