immortal-js 1.0.0

package/docs/api/chaos.md

@@ -0,0 +1,179 @@
+# API Reference — Chaos Engineering
+
+Immortal.js ships a built-in chaos engine for fault injection in staging and pre-production environments. It is **permanently disabled in `NODE_ENV=production`**.
+
+---
+
+## ChaosEngine
+
+### `new ChaosEngine()`
+
+```typescript
+import { ChaosEngine } from '@immortal/core';
+
+const chaos = new ChaosEngine();
+```
+
+---
+
+### `chaos.addFault(config)`
+
+Register a fault definition.
+
+```typescript
+chaos.addFault({
+  type: 'latency',
+  probability: 0.1,
+  minMs: 100,
+  maxMs: 2_000,
+  targetRoutes: ['/api/orders', '/api/payments'],
+});
+```
+
+**Fault types:**
+
+#### `type: 'latency'`
+
+Inject random delay before calling the real handler.
+
+```typescript
+interface LatencyOptions {
+  type: 'latency';
+  probability: number;      // 0.0–1.0
+  minMs: number;
+  maxMs: number;
+  targetRoutes?: string[];  // if omitted, applies to all routes
+}
+```
+
+#### `type: 'error'`
+
+Throw a simulated error instead of calling the handler.
+
+```typescript
+interface ErrorOptions {
+  type: 'error';
+  probability: number;
+  errorMessage?: string;   // default: 'Chaos: injected error'
+  statusCode?: number;
+  targetRoutes?: string[];
+}
+```
+
+#### `type: 'worker-kill'`
+
+Simulate a worker process crash by throwing an uncaught error.
+
+```typescript
+interface WorkerKillOptions {
+  type: 'worker-kill';
+  probability: number;
+}
+```
+
+---
+
+### `chaos.removeFault(index)`
+
+Remove a registered fault by index.
+
+```typescript
+const idx = chaos.addFault(config);
+chaos.removeFault(idx);
+```
+
+### `chaos.clearFaults()`
+
+Remove all registered faults.
+
+```typescript
+chaos.clearFaults();
+```
+
+### `chaos.enable()` / `chaos.disable()`
+
+Toggle the engine. When disabled, `wrapHandler` passes through directly.
+
+```typescript
+chaos.enable();
+chaos.disable();
+
+const isEnabled = chaos.isEnabled();
+```
+
+---
+
+### `chaos.wrapHandler(fn, route?)`
+
+Wrap a route handler function with chaos injection.
+
+```typescript
+const chaosHandler = chaos.wrapHandler(originalHandler, '/api/orders');
+
+// Express / Fastify:
+app.get('/api/orders', chaosHandler);
+```
+
+The wrapped handler probabilistically applies registered faults before calling through to `fn`.
+
+---
+
+### `chaos.injectLatency(route?)`
+
+Directly inject latency (for use outside of handler wrapping).
+
+```typescript
+await chaos.injectLatency('/api/orders');
+// Resolves after delay (or immediately if no latency fault matches)
+```
+
+---
+
+## Events
+
+| Event | Trigger |
+|-------|---------|
+| `chaos:latency-injected` | Latency fault was applied |
+| `chaos:error-injected` | Error fault was applied |
+| `chaos:worker-killed` | Worker-kill fault was applied |
+
+---
+
+## Safety rules
+
+1. **Production guard**: Attempting to `enable()` or `addFault()` when `NODE_ENV === 'production'` logs an error and is a no-op.
+2. **Rate limiting**: The chaos engine tracks injections per-route to prevent runaway fault amplification.
+3. **Deterministic testing**: Seed the random number generator for reproducible test scenarios.
+
+---
+
+## Integration example
+
+```typescript
+import { ChaosEngine } from '@immortal/core';
+import Fastify from 'fastify';
+
+const chaos = new ChaosEngine();
+
+if (process.env.CHAOS_ENABLED === 'true') {
+  chaos.enable();
+  chaos.addFault({
+    type: 'latency',
+    probability: parseFloat(process.env.CHAOS_LATENCY_PROB ?? '0.05'),
+    minMs: 100,
+    maxMs: 3_000,
+  });
+  chaos.addFault({
+    type: 'error',
+    probability: parseFloat(process.env.CHAOS_ERROR_PROB ?? '0.02'),
+    statusCode: 503,
+  });
+}
+
+const app = Fastify();
+
+app.get('/api/products', chaos.wrapHandler(async (req, reply) => {
+  const products = await db.products.findAll();
+  reply.send(products);
+}));
+```

package/docs/api/dashboard.md

@@ -0,0 +1,109 @@
+# API Reference — Dashboard (`@immortal/dashboard`)
+
+The `@immortal/dashboard` package provides a real-time web dashboard for visualizing the health, metrics, and event stream of your Immortal.js runtime.
+
+---
+
+## Installation
+
+```bash
+npm install @immortal/dashboard
+```
+
+Optional dependency for WebSocket push:
+
+```bash
+npm install ws
+```
+
+---
+
+## Usage
+
+```typescript
+import { createDashboard } from '@immortal/dashboard';
+import { getImmortal } from '@immortal/core';
+
+const dashboard = createDashboard({
+  port: 9090,
+  host: '0.0.0.0',
+  refreshIntervalMs: 2_000,
+  auth: {
+    username: 'admin',
+    password: process.env.DASHBOARD_PASSWORD!,
+  },
+});
+
+await dashboard.start();
+console.log('Dashboard running at http://localhost:9090');
+```
+
+---
+
+## Configuration
+
+```typescript
+interface DashboardConfig {
+  port?: number;                // default: 9090
+  host?: string;                // default: '127.0.0.1'
+  refreshIntervalMs?: number;   // default: 5_000
+  auth?: {
+    username: string;
+    password: string;
+  };
+  cors?: {
+    origin: string | string[];
+  };
+  websocket?: boolean;          // enable WS push (requires 'ws' package)
+}
+```
+
+---
+
+## Dashboard pages
+
+| Route | Description |
+|-------|-------------|
+| `/` | Overview — health, key metrics, recent events |
+| `/metrics` | Full system metrics with time-series charts |
+| `/circuits` | Circuit breaker states and history |
+| `/bulkheads` | Bulkhead pool saturation |
+| `/workers` | Supervisor worker states and restart history |
+| `/events` | Live event stream (WebSocket if enabled) |
+
+---
+
+## REST API
+
+The dashboard exposes a JSON API:
+
+```
+GET /api/health    → { status, timestamp, metrics }
+GET /api/metrics   → SystemMetrics
+GET /api/circuits  → CircuitBreakerStatus[]
+GET /api/bulkheads → BulkheadStatus[]
+GET /api/workers   → WorkerStatus[]
+GET /api/events    → ImmortalEvent[] (last 1000)
+```
+
+---
+
+## WebSocket stream
+
+When `websocket: true`, events are pushed in real time:
+
+```javascript
+const ws = new WebSocket('ws://localhost:9090/ws');
+ws.onmessage = (msg) => {
+  const event = JSON.parse(msg.data);
+  console.log(event.type, event.data);
+};
+```
+
+---
+
+## Security
+
+- The dashboard is **not recommended for public exposure**. Bind to `127.0.0.1` and use a reverse proxy with TLS.
+- Basic auth credentials are verified on every request.
+- In production, prefer exporting metrics to Prometheus/Datadog and using their dashboards instead.

package/docs/api/isolation.md

@@ -0,0 +1,191 @@
+# API Reference — Isolation (Layer 3)
+
+The **Isolation** layer prevents a misbehaving dependency or compute-heavy operation from consuming all available resources. It uses two mechanisms: **bulkheads** (concurrency limits) and **worker sandboxes** (thread isolation).
+
+---
+
+## BulkheadPool
+
+A bulkhead limits the number of concurrent operations to a named pool, with an optional overflow queue.
+
+### `new BulkheadPool(name, config?)`
+
+```typescript
+import { BulkheadPool } from '@immortal/core';
+
+const dbPool = new BulkheadPool('database', {
+  maxConcurrent: 10,
+  maxQueueSize: 50,
+  defaultTimeoutMs: 5_000,
+});
+```
+
+**Config:**
+
+```typescript
+interface BulkheadConfig {
+  maxConcurrent?: number;     // default: 10
+  maxQueueSize?: number;      // default: 100
+  defaultTimeoutMs?: number;  // default: 30_000
+}
+```
+
+### `pool.run(task, priority?, timeoutMs?)`
+
+Execute a task within the bulkhead.
+
+```typescript
+const result = await pool.run(
+  () => db.query('SELECT * FROM users'),
+  'high',   // 'high' | 'medium' | 'low'
+  3_000     // per-call timeout override
+);
+```
+
+- If `active >= maxConcurrent` and `queued < maxQueueSize` → task is queued
+- If queue is also full → throws `BulkheadRejectedError` immediately
+- Priority ordering: `high` > `medium` > `low`
+
+**Throws:** `BulkheadRejectedError` when the pool is saturated.
+
+### `pool.getStatus()`
+
+Returns the current pool snapshot:
+
+```typescript
+interface BulkheadStatus {
+  name: string;
+  active: number;
+  queued: number;
+  maxConcurrent: number;
+  maxQueueSize: number;
+  rejected: number;
+  totalExecuted: number;
+}
+```
+
+### `pool.drainAll()`
+
+Waits for all currently active and queued tasks to complete. Useful during graceful shutdown.
+
+```typescript
+await pool.drainAll();
+```
+
+### Events
+
+| Event | Trigger |
+|-------|---------|
+| `bulkhead:queued` | Task enters the overflow queue |
+| `bulkhead:rejected` | Task rejected (pool + queue full) |
+| `bulkhead:timeout` | Task exceeds its timeout while queued |
+
+### `BulkheadRejectedError`
+
+Thrown when the pool is full. Extends `ImmortalError` with `kind: 'operational'`.
+
+```typescript
+import { BulkheadRejectedError } from '@immortal/core';
+
+try {
+  await pool.run(task);
+} catch (err) {
+  if (err instanceof BulkheadRejectedError) {
+    return res.status(503).json({ error: 'Service overloaded, try again later' });
+  }
+  throw err;
+}
+```
+
+---
+
+## BulkheadRegistry
+
+Singleton registry for named bulkhead pools.
+
+```typescript
+import { BulkheadRegistry } from '@immortal/core';
+
+const registry = BulkheadRegistry.getInstance();
+
+// Get or create a named pool
+const pool = registry.get('database', { maxConcurrent: 5 });
+
+// Iterate all pools
+for (const [name, pool] of registry.entries()) {
+  console.log(name, pool.getStatus());
+}
+```
+
+---
+
+## WorkerSandbox
+
+Executes untrusted or CPU-intensive code in an isolated Node.js worker thread.
+
+### `new WorkerSandbox(config?)`
+
+```typescript
+import { WorkerSandbox } from '@immortal/core';
+
+const sandbox = new WorkerSandbox({
+  timeoutMs: 5_000,
+  memoryLimitMb: 128,
+});
+```
+
+**Config:**
+
+```typescript
+interface WorkerSandboxConfig {
+  timeoutMs?: number;       // default: 10_000
+  memoryLimitMb?: number;   // default: 256
+  maxWorkers?: number;      // default: os.cpus().length
+}
+```
+
+### `sandbox.execute(code, args?)`
+
+Execute a string of JavaScript code in an isolated worker thread. The code must `return` a value.
+
+```typescript
+const result = await sandbox.execute(
+  `return input.a + input.b`,
+  { input: { a: 10, b: 32 } }
+);
+// → 42
+```
+
+- `args` are serialized and passed to the worker via `structuredClone`
+- The worker terminates after `timeoutMs` milliseconds
+- Memory is garbage-collected after the task completes
+
+**Throws:** `ImmortalError` with `code: 'WORKER_TIMEOUT'` or `code: 'WORKER_ERROR'`.
+
+### `sandbox.terminate()`
+
+Forcefully terminates all worker threads in the pool.
+
+---
+
+## Design Notes
+
+### Bulkhead sizing
+
+A common mistake is setting `maxConcurrent` too high. The optimal value depends on your I/O concurrency model:
+
+- **Database connections:** Match your connection pool size (e.g. 10–20)
+- **HTTP calls to external services:** Match the service's rate limit / connection limit
+- **CPU work (Worker threads):** Match `os.cpus().length`
+
+### Queue sizing
+
+`maxQueueSize` is a safety valve. A large queue adds latency — callers wait longer before failing. A size of 0 means "reject immediately when all slots are taken." Choose based on your SLA:
+
+```
+queue_wait_time ≈ (maxQueueSize / maxConcurrent) × avg_task_duration
+```
+
+### Priority queuing
+
+Priority queuing (`'high' | 'medium' | 'low'`) ensures critical paths are served first during overload. Use sparingly — abusing `'high'` starves lower priorities.

package/docs/api/lifecycle.md

@@ -0,0 +1,187 @@
+# API Reference — Lifecycle
+
+Lifecycle management ensures your service starts cleanly, shuts down gracefully, and drains in-flight requests before exiting.
+
+---
+
+## GracefulShutdown
+
+### `new GracefulShutdown(config, bus)`
+
+```typescript
+import { GracefulShutdown } from '@immortal/core';
+
+const shutdown = new GracefulShutdown(
+  {
+    enabled: true,
+    timeoutMs: 30_000,
+    signals: ['SIGTERM', 'SIGINT'],
+  },
+  getEventBus()
+);
+```
+
+**Config:**
+
+```typescript
+interface GracefulShutdownConfig {
+  enabled?: boolean;
+  timeoutMs?: number;                  // default: 30_000
+  signals?: NodeJS.Signals[];          // default: ['SIGTERM', 'SIGINT']
+  forceExitAfterMs?: number;           // default: timeoutMs + 5_000
+}
+```
+
+---
+
+### `shutdown.addHandler(name, fn, priority?)`
+
+Register a shutdown hook. Handlers are called in **descending priority order** (highest first).
+
+```typescript
+shutdown.addHandler('http-server', async () => {
+  await server.close();
+}, 100);
+
+shutdown.addHandler('database', async () => {
+  await db.end();
+}, 50);
+
+shutdown.addHandler('cache', async () => {
+  await redis.quit();
+}, 10);
+```
+
+**Parameters:**
+- `name: string` — identifier for logging
+- `fn: () => Promise<void>` — async cleanup function
+- `priority?: number` — default `0`, higher runs first
+
+---
+
+### `shutdown.execute(signal?)`
+
+Trigger the shutdown sequence programmatically.
+
+```typescript
+await shutdown.execute('SIGTERM');
+```
+
+1. Emits `shutdown:initiated` on the event bus
+2. Calls all registered handlers in priority order
+3. Waits up to `timeoutMs` for each handler
+4. Emits `shutdown:complete` (or `shutdown:forced` on timeout)
+
+---
+
+### Automatic signal handling
+
+When `enabled: true` and `signals` are configured, the shutdown sequence runs automatically on signal receipt:
+
+```typescript
+// Registered automatically — no extra code needed
+process.on('SIGTERM', () => shutdown.execute('SIGTERM'));
+process.on('SIGINT', () => shutdown.execute('SIGINT'));
+```
+
+---
+
+## createImmortal
+
+High-level factory that wires all five layers together.
+
+```typescript
+import { createImmortal } from '@immortal/core';
+
+const immortal = await createImmortal({
+  logger: { level: 'info', transport: 'json' },
+  healthMonitor: { enabled: true, checkIntervalMs: 30_000 },
+  memoryGuard: { enabled: true, warningThresholdMb: 400 },
+  gracefulShutdown: { enabled: true, timeoutMs: 30_000 },
+  plugins: [ConsoleLogPlugin, RequestTracingPlugin],
+});
+```
+
+Returns an `ImmortalRuntime` instance with all layers initialized.
+
+---
+
+## ImmortalRuntime
+
+### `runtime.config`
+
+The fully-resolved (merged with defaults) configuration object.
+
+### `runtime.getMetrics()`
+
+Returns the current `SystemMetrics` snapshot.
+
+### `runtime.isHealthy()`
+
+Returns `true` if no critical health events have occurred.
+
+### `runtime.addPlugin(plugin)`
+
+Attach a plugin after initialization. `onInit` is called immediately.
+
+```typescript
+runtime.addPlugin(createSlackAlertPlugin({ webhookUrl: '...' }));
+```
+
+### `runtime.shutdown(signal?)`
+
+Trigger graceful shutdown.
+
+```typescript
+await runtime.shutdown('SIGTERM');
+```
+
+---
+
+## getImmortal
+
+Returns the singleton `ImmortalRuntime`. Throws if `createImmortal()` has not been called.
+
+```typescript
+import { getImmortal } from '@immortal/core';
+
+const runtime = getImmortal();
+const metrics = runtime.getMetrics();
+```
+
+---
+
+## Typical startup pattern
+
+```typescript
+import { createImmortal, ConsoleLogPlugin } from '@immortal/core';
+import { createServer } from './server.js';
+
+async function main() {
+  const immortal = await createImmortal({
+    logger: { level: process.env.LOG_LEVEL ?? 'info' },
+    gracefulShutdown: {
+      enabled: true,
+      timeoutMs: 30_000,
+      signals: ['SIGTERM', 'SIGINT'],
+    },
+    plugins: [ConsoleLogPlugin],
+  });
+
+  const server = await createServer();
+
+  // Register shutdown hooks
+  immortal.config.gracefulShutdown; // already wired via createImmortal
+  // Add app-specific hooks via the GracefulShutdown instance:
+  const { GracefulShutdown } = await import('@immortal/core');
+  // (or construct separately and pass via plugin)
+
+  await server.listen({ port: 3000 });
+  console.log('Server running on port 3000');
+}
+
+main().catch((err) => {
+  console.error('Fatal startup error:', err);
+  process.exit(1);
+});
+```