immortal-js 1.0.0

package/docs/api/supervision.md

@@ -0,0 +1,285 @@
+# API Reference — Supervision (Layer 4)
+
+The **Supervision** layer manages long-running processes — both in-process async workers and multi-core OS processes — with automatic restart policies and escalation.
+
+---
+
+## Supervisor
+
+Manages named async workers (in-process) with configurable restart limits.
+
+### `new Supervisor(options?)`
+
+```typescript
+import { Supervisor } from '@immortal/core';
+
+const supervisor = new Supervisor({
+  config: {
+    maxRestartsInWindow: 5,
+    windowMs: 60_000,
+    baseRestartDelayMs: 1_000,
+  },
+  onEscalation: (workerId) => {
+    alertTeam(`Worker "${workerId}" escalated — manual intervention required`);
+  },
+});
+```
+
+**Options:**
+
+```typescript
+interface SupervisorOptions {
+  config?: Partial<SupervisorConfig>;
+  onEscalation?: (workerId: string) => void;
+}
+
+interface SupervisorConfig {
+  maxRestartsInWindow: number;   // default: 5
+  windowMs: number;              // default: 60_000
+  baseRestartDelayMs: number;    // default: 1_000
+}
+```
+
+---
+
+### `supervisor.register(id, entry)`
+
+Register and immediately start a worker.
+
+```typescript
+supervisor.register('http-server', {
+  spawnFn: () => startHttpServer(),          // returns the worker instance
+  terminate: (instance) => instance.close(), // called before restart or on stop
+});
+```
+
+**Entry:**
+
+```typescript
+interface WorkerEntry {
+  spawnFn: () => unknown | Promise<unknown>;
+  terminate?: (instance: unknown) => void | Promise<void>;
+}
+```
+
+`spawnFn` is called immediately. The returned instance (if any) is passed to `terminate` before each restart.
+
+**Throws** if the same `id` is registered twice.
+
+---
+
+### `supervisor.onWorkerExit(id, exitCode?)`
+
+Signal that a worker has exited (used by your own process management code to trigger the restart logic).
+
+```typescript
+// Example: worker thread exited
+worker.on('exit', (code) => {
+  supervisor.onWorkerExit('my-worker', code);
+});
+```
+
+The supervisor will schedule a restart after `baseRestartDelayMs * 2^(restartCount)` ms (exponential backoff), unless `maxRestartsInWindow` has been reached.
+
+When the restart limit is reached, the worker state is set to `'escalated'`, no further restarts occur, and `onEscalation` is called.
+
+---
+
+### `supervisor.updateWorkerMetrics(id, metrics)`
+
+Push current resource metrics for a worker (used by the Monitoring layer).
+
+```typescript
+supervisor.updateWorkerMetrics('http-server', {
+  memoryMb: 256,
+  cpuPercent: 12.5,
+});
+```
+
+---
+
+### `supervisor.requestGracefulRestart(id, reason?)`
+
+Trigger a graceful restart for a specific worker: calls `terminate`, then re-spawns.
+
+```typescript
+await supervisor.requestGracefulRestart('http-server', 'memory-threshold');
+```
+
+---
+
+### `supervisor.getWorkerStatuses()`
+
+Returns the current state of all registered workers.
+
+```typescript
+const statuses = supervisor.getWorkerStatuses();
+```
+
+**Returns:** `WorkerStatus[]`
+
+```typescript
+interface WorkerStatus {
+  id: string;
+  state: 'running' | 'restarting' | 'escalated' | 'stopped';
+  restartCount: number;
+  uptime: number;           // ms since last (re)start
+  pid?: number;             // OS PID if available
+  lastRestartTime?: number; // epoch ms of last restart
+  memoryMb?: number;
+  cpuPercent?: number;
+}
+```
+
+---
+
+### `supervisor.stop(id)`
+
+Stop a specific worker (calls `terminate`, removes from registry).
+
+```typescript
+await supervisor.stop('http-server');
+```
+
+---
+
+### `supervisor.stopAll()`
+
+Stop all registered workers.
+
+```typescript
+await supervisor.stopAll();
+```
+
+---
+
+## computeRestartDecision
+
+Low-level utility used internally by `Supervisor`. Determines which workers to restart based on a `RestartStrategy`.
+
+```typescript
+import { computeRestartDecision } from '@immortal/core';
+
+const decision = computeRestartDecision(
+  'worker-1',          // failed worker ID
+  allWorkers,          // WorkerEntry[]
+  'one-for-one'        // strategy
+);
+
+// decision.workersToRestart → string[] of worker IDs to restart
+// decision.strategy         → the strategy used
+```
+
+**Strategies:**
+
+| Strategy | Description |
+|----------|-------------|
+| `'one-for-one'` | Restart only the failed worker (default) |
+| `'one-for-all'` | Restart all workers when one fails |
+| `'rest-for-one'` | Restart the failed worker and all workers registered after it |
+
+---
+
+## ClusterManager
+
+Manages OS-level worker processes using the Node.js `cluster` module.
+
+### `ClusterManager.isPrimary()`
+
+Static method — returns `true` if the current process is the cluster primary.
+
+```typescript
+import { ClusterManager } from '@immortal/core';
+
+if (ClusterManager.isPrimary()) {
+  // primary: fork workers
+} else {
+  // worker: start app
+}
+```
+
+### `new ClusterManager(options?)`
+
+```typescript
+const mgr = new ClusterManager({
+  workerCount: 4,                    // default: os.cpus().length
+  supervisorConfig: {
+    maxRestartsInWindow: 3,
+    windowMs: 30_000,
+    baseRestartDelayMs: 500,
+  },
+  onWorkerExit: (id, code, signal) => {
+    console.log(`Worker ${id} exited: code=${code} signal=${signal}`);
+  },
+  onEscalation: (id) => {
+    alertTeam(`Cluster worker ${id} escalated`);
+  },
+});
+```
+
+### `mgr.start()`
+
+Fork `workerCount` workers and attach exit/online handlers. Must be called in the primary process.
+
+```typescript
+await mgr.start();
+```
+
+### `mgr.rollingRestart()`
+
+Zero-downtime rolling restart: fork new worker → wait for online → kill old worker → repeat.
+
+```typescript
+await mgr.rollingRestart();
+```
+
+### `mgr.stop()`
+
+Send `SIGTERM` to all workers.
+
+```typescript
+await mgr.stop();
+```
+
+### `mgr.getWorkerStatuses()`
+
+Returns `WorkerStatus[]` for all cluster workers.
+
+---
+
+## Typical patterns
+
+### Primary/Worker split
+
+```typescript
+import { ClusterManager } from '@immortal/core';
+
+if (ClusterManager.isPrimary()) {
+  const mgr = new ClusterManager({ workerCount: os.cpus().length });
+  await mgr.start();
+
+  // Schedule rolling restart every 24h
+  setInterval(() => mgr.rollingRestart(), 24 * 60 * 60_000).unref();
+} else {
+  // Each worker starts its own HTTP server
+  const app = express();
+  app.listen(3000);
+}
+```
+
+### In-process supervisor
+
+```typescript
+const supervisor = new Supervisor({ onEscalation: alertTeam });
+
+supervisor.register('message-consumer', {
+  spawnFn: () => {
+    const consumer = new KafkaConsumer(config);
+    consumer.on('error', (err) => {
+      supervisor.onWorkerExit('message-consumer', 1);
+    });
+    return consumer;
+  },
+  terminate: (consumer) => consumer.disconnect(),
+});
+```

package/docs/guides/configuration.md

@@ -0,0 +1,168 @@
+# Configuration Guide
+
+Immortal.js is configured through a single `ImmortalConfig` object passed to `createImmortal()`. All fields are optional — sensible defaults are applied for everything.
+
+---
+
+## Full configuration reference
+
+```typescript
+import { createImmortal } from '@immortal/core';
+
+const immortal = await createImmortal({
+  // ─────────────────────────────────────────────────────────
+  // Logger
+  // ─────────────────────────────────────────────────────────
+  logger: {
+    level: 'info',          // 'debug' | 'info' | 'warn' | 'error' | 'silent'
+    transport: 'json',      // 'console' | 'json' | 'pretty'
+    prefix: 'my-service',   // prepended to all log lines
+  },
+
+  // ─────────────────────────────────────────────────────────
+  // Health Monitor (Layer 5)
+  // ─────────────────────────────────────────────────────────
+  healthMonitor: {
+    enabled: true,
+    checkIntervalMs: 30_000,          // how often to check
+    eventLoopLagWarningMs: 50,        // warn threshold
+    eventLoopLagCriticalMs: 100,      // critical threshold
+    heapUsageWarningPercent: 80,
+    heapUsageCriticalPercent: 90,
+    cpuWarningPercent: 80,
+    cpuCriticalPercent: 95,
+  },
+
+  // ─────────────────────────────────────────────────────────
+  // Memory Leak Guard (Layer 5)
+  // ─────────────────────────────────────────────────────────
+  memoryGuard: {
+    enabled: true,
+    checkIntervalMs: 60_000,
+    warningThresholdMb: 400,          // heap MB before warning event
+    restartThresholdMb: 600,          // heap MB before restart event
+    growthWindowCount: 5,             // samples to confirm growth trend
+    adaptive: true,                   // adjust thresholds based on baseline
+  },
+
+  // ─────────────────────────────────────────────────────────
+  // Graceful Shutdown (Lifecycle)
+  // ─────────────────────────────────────────────────────────
+  gracefulShutdown: {
+    enabled: true,
+    timeoutMs: 30_000,
+    signals: ['SIGTERM', 'SIGINT'],
+  },
+
+  // ─────────────────────────────────────────────────────────
+  // Supervisor (Layer 4)
+  // ─────────────────────────────────────────────────────────
+  supervisor: {
+    maxRestartsInWindow: 5,
+    windowMs: 60_000,
+    baseRestartDelayMs: 1_000,
+  },
+
+  // ─────────────────────────────────────────────────────────
+  // Chaos Engineering
+  // ─────────────────────────────────────────────────────────
+  chaos: {
+    enabled: false,    // NEVER enable in production — runtime enforces this
+  },
+
+  // ─────────────────────────────────────────────────────────
+  // Plugins
+  // ─────────────────────────────────────────────────────────
+  plugins: [],
+});
+```
+
+---
+
+## Environment-based configuration
+
+```typescript
+import { createImmortal } from '@immortal/core';
+
+const isProd = process.env.NODE_ENV === 'production';
+
+const immortal = await createImmortal({
+  logger: {
+    level: isProd ? 'warn' : 'debug',
+    transport: isProd ? 'json' : 'pretty',
+  },
+  healthMonitor: {
+    enabled: true,
+    checkIntervalMs: isProd ? 30_000 : 60_000,
+  },
+  memoryGuard: {
+    enabled: isProd,
+    warningThresholdMb: parseInt(process.env.MEMORY_WARNING_MB ?? '400'),
+    restartThresholdMb: parseInt(process.env.MEMORY_RESTART_MB ?? '600'),
+  },
+  gracefulShutdown: {
+    enabled: true,
+    timeoutMs: parseInt(process.env.SHUTDOWN_TIMEOUT_MS ?? '30000'),
+  },
+  chaos: {
+    enabled: process.env.CHAOS_ENABLED === 'true',
+  },
+});
+```
+
+---
+
+## Default values
+
+| Config key | Default |
+|------------|---------|
+| `logger.level` | `'info'` |
+| `logger.transport` | `'console'` |
+| `healthMonitor.enabled` | `true` |
+| `healthMonitor.checkIntervalMs` | `30_000` |
+| `healthMonitor.eventLoopLagWarningMs` | `50` |
+| `healthMonitor.eventLoopLagCriticalMs` | `100` |
+| `memoryGuard.enabled` | `true` |
+| `memoryGuard.checkIntervalMs` | `60_000` |
+| `memoryGuard.warningThresholdMb` | OS heap × 0.5 |
+| `memoryGuard.restartThresholdMb` | OS heap × 0.75 |
+| `memoryGuard.growthWindowCount` | `5` |
+| `memoryGuard.adaptive` | `true` |
+| `gracefulShutdown.enabled` | `true` |
+| `gracefulShutdown.timeoutMs` | `30_000` |
+| `gracefulShutdown.signals` | `['SIGTERM', 'SIGINT']` |
+| `supervisor.maxRestartsInWindow` | `5` |
+| `supervisor.windowMs` | `60_000` |
+| `supervisor.baseRestartDelayMs` | `1_000` |
+| `chaos.enabled` | `false` |
+
+---
+
+## Configuration validation
+
+Immortal.js validates the configuration at construction time. Invalid configurations throw immediately with descriptive messages:
+
+```typescript
+// Throws: "Immortal.js configuration errors:\n  chaos.enabled must be false in production"
+const immortal = await createImmortal({ chaos: { enabled: true } }); // in production
+```
+
+Validation warnings (non-fatal) are printed to `console.warn`.
+
+---
+
+## TypeScript types
+
+All configuration types are exported:
+
+```typescript
+import type {
+  ImmortalConfig,
+  LoggerConfig,
+  HealthMonitorConfig,
+  MemoryGuardConfig,
+  GracefulShutdownConfig,
+  SupervisorConfig,
+  ChaosConfig,
+} from '@immortal/core';
+```

package/docs/guides/express.md

@@ -0,0 +1,171 @@
+# Guide — Express Integration
+
+Immortal.js works with Express through direct use of the `@immortal/core` primitives. There is no Express-specific adapter — the core API is framework-agnostic.
+
+---
+
+## Installation
+
+```bash
+npm install @immortal/core express
+npm install -D @types/express
+```
+
+---
+
+## Basic setup
+
+```typescript
+import express from 'express';
+import {
+  createImmortal,
+  asyncBoundary,
+  CircuitBreaker,
+  BulkheadPool,
+  withRetry,
+  RouteFallbackCache,
+  classifyError,
+  BulkheadRejectedError,
+} from '@immortal/core';
+
+const app = express();
+app.use(express.json());
+
+// Initialize Immortal runtime
+const immortal = await createImmortal({
+  logger: { level: 'info' },
+  healthMonitor: { enabled: true },
+  gracefulShutdown: { enabled: true, timeoutMs: 30_000 },
+});
+
+// Resilience primitives
+const dbBreaker = new CircuitBreaker('database', { threshold: 5 });
+const dbPool = new BulkheadPool('database', { maxConcurrent: 10 });
+const cache = new RouteFallbackCache();
+```
+
+---
+
+## Request tracing middleware
+
+```typescript
+import { AsyncBoundary } from '@immortal/core';
+import { randomUUID } from 'node:crypto';
+
+app.use((req, res, next) => {
+  const requestId = (req.headers['x-request-id'] as string) ?? randomUUID();
+  res.setHeader('x-request-id', requestId);
+
+  AsyncBoundary.run(next, { requestId });
+});
+```
+
+---
+
+## Route with resilience
+
+```typescript
+app.get('/api/products/:id', asyncBoundary(async (req, res) => {
+  const { id } = req.params;
+  const cacheKey = `products:${id}`;
+
+  try {
+    const product = await dbPool.run(() =>
+      dbBreaker.run(() =>
+        withRetry(() => db.findProduct(id), { maxAttempts: 2 })
+      )
+    );
+
+    cache.set(cacheKey, product);
+    res.json(product);
+  } catch (err) {
+    const stale = cache.get(cacheKey);
+    if (stale) return res.json({ ...stale, stale: true });
+    throw err;
+  }
+}));
+```
+
+---
+
+## Error handling middleware
+
+```typescript
+import type { ErrorRequestHandler } from 'express';
+import { ImmortalError, BulkheadRejectedError, classifyError } from '@immortal/core';
+
+const errorHandler: ErrorRequestHandler = (err, req, res, next) => {
+  if (err instanceof BulkheadRejectedError) {
+    return res.status(503).json({
+      error: 'Service overloaded — try again shortly',
+      retryAfter: 1,
+    });
+  }
+
+  if (err instanceof ImmortalError) {
+    const status = err.statusCode ?? (err.kind === 'programming' ? 500 : 503);
+    return res.status(status).json({ error: err.message, code: err.code });
+  }
+
+  const kind = classifyError(err);
+  const status = kind === 'programming' ? 500 : 503;
+  res.status(status).json({ error: 'Internal server error', kind });
+};
+
+app.use(errorHandler);
+```
+
+---
+
+## Health endpoint
+
+```typescript
+app.get('/health', (req, res) => {
+  res.json({
+    status: immortal.isHealthy() ? 'ok' : 'degraded',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+  });
+});
+
+app.get('/metrics', (req, res) => {
+  res.json(immortal.getMetrics());
+});
+```
+
+---
+
+## Graceful shutdown
+
+```typescript
+const server = app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+
+process.on('SIGTERM', async () => {
+  // Stop accepting new connections
+  server.close(async () => {
+    await immortal.shutdown('SIGTERM');
+    process.exit(0);
+  });
+
+  // Force exit after timeout
+  setTimeout(() => process.exit(1), 35_000).unref();
+});
+```
+
+---
+
+## Full patterns reference
+
+| Pattern | Core API |
+|---------|----------|
+| Retry | `withRetry(fn, options)` |
+| Timeout | `withTimeout(fn, ms, label)` |
+| Circuit breaker | `new CircuitBreaker(name, config).run(fn)` |
+| Bulkhead | `new BulkheadPool(name, config).run(fn)` |
+| Stale cache | `new RouteFallbackCache().get(key)` |
+| Error classification | `classifyError(err)` → operational/programming/transient/external |
+| Request tracing | `AsyncBoundary.run(fn)` + `AsyncBoundary.getRequestId()` |
+| Global error trap | `new ErrorTrap(bus).install()` |
+| Safe handler wrap | `asyncBoundary(fn, { fallback })` |