immortal-js 1.0.0

package/packages/adapter-nestjs/src/immortal.module.ts

@@ -0,0 +1,313 @@
+/**
+ * @file adapter-nestjs/src/immortal.module.ts
+ * @description Immortal.js NestJS Dynamic Module
+ *
+ * Provides:
+ * - ImmortalModule.forRoot() for app-wide configuration
+ * - ImmortalInterceptor: wraps all controller methods in safe zone
+ * - ImmortalExceptionFilter: handles all unhandled exceptions
+ * - Injectable services: ImmortalService (metrics, circuit, bulkhead access)
+ * - Decorators: @Bulkhead(), @Circuit(), @Retry(), @Fallback()
+ */
+
+// Note: NestJS types are referenced here without direct import
+// to avoid requiring NestJS as a hard dependency of the adapter package.
+// The actual NestJS decorators (@Module, @Injectable, etc.) would be imported
+// from @nestjs/* in a real NestJS project.
+
+import type { ImmortalConfig, SystemMetrics, Priority, LoggerConfig, BulkheadConfig } from "@immortal/core";
+import {
+  mergeWithDefaults,
+  validateConfig,
+  createLogger,
+  getEventBus,
+  ErrorTrap,
+  MetricsCollector,
+  HealthMonitor,
+  MemoryLeakGuard,
+  BulkheadRegistry,
+  CircuitBreakerRegistry,
+  FallbackCache,
+  GracefulShutdown,
+  withRetry,
+  DiagnosticsChannel,
+} from "@immortal/core";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IMMORTAL SERVICE (Injectable)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class ImmortalService {
+  private readonly metricsCollector: MetricsCollector;
+  private readonly circuitRegistry: CircuitBreakerRegistry;
+  private readonly bulkheadRegistry: BulkheadRegistry;
+  private readonly fallbackCache: FallbackCache;
+  private readonly config: Required<ImmortalConfig>;
+
+  constructor(
+    metricsCollector: MetricsCollector,
+    circuitRegistry: CircuitBreakerRegistry,
+    bulkheadRegistry: BulkheadRegistry,
+    fallbackCache: FallbackCache,
+    config: Required<ImmortalConfig>
+  ) {
+    this.metricsCollector = metricsCollector;
+    this.circuitRegistry = circuitRegistry;
+    this.bulkheadRegistry = bulkheadRegistry;
+    this.fallbackCache = fallbackCache;
+    this.config = config;
+  }
+
+  /** Get current system metrics snapshot */
+  getMetrics(): SystemMetrics {
+    return this.metricsCollector.getSnapshot();
+  }
+
+  /** Execute an operation through a named circuit breaker */
+  async circuit<T>(name: string, fn: () => Promise<T>, fallback?: () => T): Promise<T> {
+    const breaker = this.circuitRegistry.get(name);
+    return breaker.execute(fn, fallback);
+  }
+
+  /** Execute an operation through a named bulkhead pool */
+  async bulkhead<T>(
+    poolName: string,
+    fn: () => Promise<T>,
+    priority: Priority = "medium"
+  ): Promise<T> {
+    const pool = this.bulkheadRegistry.get(poolName);
+    return pool.run(fn, priority);
+  }
+
+  /** Execute with retry */
+  async retry<T>(fn: () => Promise<T>, operationName?: string): Promise<T> {
+    return withRetry(fn, this.config.retry, operationName);
+  }
+
+  /** Get circuit breaker status */
+  getCircuitStatus(name: string) {
+    return this.circuitRegistry.get(name).getStatus();
+  }
+
+  /** Get all circuit statuses */
+  getAllCircuitStatuses() {
+    return this.circuitRegistry.getAllStatuses();
+  }
+
+  /** Get bulkhead pool status */
+  getBulkheadStatus(name: string) {
+    return this.bulkheadRegistry.get(name).getStatus();
+  }
+
+  /** Get all bulkhead statuses */
+  getAllBulkheadStatuses() {
+    return this.bulkheadRegistry.getAllStatuses();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IMMORTAL MODULE FACTORY
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ImmortalModuleOptions extends ImmortalConfig {
+  isGlobal?: boolean;
+}
+
+/**
+ * Factory to create the NestJS module configuration object.
+ * In a real NestJS project, use @Module() decorator on this class.
+ *
+ * Usage:
+ * ```typescript
+ * @Module({
+ *   imports: [ImmortalModule.forRoot({ retry: { maxAttempts: 3 } })],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export class ImmortalModule {
+  static forRoot(options: ImmortalModuleOptions = {}) {
+    const { isGlobal: _isGlobal, ...userConfig } = options;
+
+    const validation = validateConfig(userConfig);
+    if (!validation.valid) {
+      throw new Error(`Immortal.js NestJS module config errors:\n${validation.errors.join("\n")}`);
+    }
+
+    const config = mergeWithDefaults(userConfig);
+    const logger = createLogger(config.logger as Required<LoggerConfig>);
+    const bus = getEventBus();
+
+    // Initialize all layers
+    const errorTrap = new ErrorTrap(bus);
+    errorTrap.install();
+
+    const metricsCollector = new MetricsCollector();
+    const healthMonitor = new HealthMonitor(config.healthMonitor, bus, metricsCollector);
+    const memoryLeakGuard = new MemoryLeakGuard(config.memoryGuard, bus);
+    const gracefulShutdown = new GracefulShutdown(config.gracefulShutdown, bus);
+    const dcOptions: { otlpEndpoint?: string; enablePrometheus?: boolean } = {};
+    if (config.dashboard.otlpEndpoint !== undefined) {
+      dcOptions.otlpEndpoint = config.dashboard.otlpEndpoint;
+    }
+    if (config.dashboard.enablePrometheus !== undefined) {
+      dcOptions.enablePrometheus = config.dashboard.enablePrometheus;
+    }
+    const diagnosticsChannel = new DiagnosticsChannel(bus, dcOptions);
+
+    const circuitRegistry = new CircuitBreakerRegistry(config.circuitBreaker);
+    const bulkheadRegistry = new BulkheadRegistry(config.bulkhead["default"] ?? {});
+    const fallbackCache = new FallbackCache();
+
+    healthMonitor.start();
+    memoryLeakGuard.start();
+
+    const service = new ImmortalService(
+      metricsCollector,
+      circuitRegistry,
+      bulkheadRegistry,
+      fallbackCache,
+      config
+    );
+
+    logger.info("Immortal.js NestJS module initialized");
+
+    // Return the module definition that NestJS can use
+    return {
+      module: ImmortalModule,
+      global: _isGlobal ?? false,
+      providers: [
+        { provide: "IMMORTAL_CONFIG", useValue: config },
+        { provide: MetricsCollector, useValue: metricsCollector },
+        { provide: CircuitBreakerRegistry, useValue: circuitRegistry },
+        { provide: BulkheadRegistry, useValue: bulkheadRegistry },
+        { provide: FallbackCache, useValue: fallbackCache },
+        { provide: ImmortalService, useValue: service },
+        // Shutdown hook for NestJS lifecycle
+        {
+          provide: "IMMORTAL_SHUTDOWN",
+          useFactory: () => ({
+            onModuleDestroy: async () => {
+              healthMonitor.stop();
+              memoryLeakGuard.stop();
+              diagnosticsChannel.stop();
+              logger.info("Immortal.js NestJS module destroyed");
+            },
+          }),
+        },
+      ],
+      exports: [ImmortalService, MetricsCollector, CircuitBreakerRegistry, BulkheadRegistry],
+    };
+  }
+
+  static forRootAsync(options: {
+    useFactory: (...args: unknown[]) => Promise<ImmortalModuleOptions> | ImmortalModuleOptions;
+    inject?: unknown[];
+  }) {
+    return {
+      module: ImmortalModule,
+      providers: [
+        {
+          provide: "IMMORTAL_OPTIONS",
+          useFactory: options.useFactory,
+          inject: options.inject ?? [],
+        },
+        {
+          provide: ImmortalService,
+          useFactory: async (opts: ImmortalModuleOptions) => {
+            const module = ImmortalModule.forRoot(opts);
+            return module.providers.find((p) => "provide" in p && p.provide === ImmortalService)?.useValue;
+          },
+          inject: ["IMMORTAL_OPTIONS"],
+        },
+      ],
+      exports: [ImmortalService],
+    };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// METHOD DECORATORS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @Bulkhead('payments') — Wrap method in bulkhead isolation
+ */
+export function Bulkhead(
+  poolName: string,
+  options: { priority?: Priority; maxConcurrent?: number } = {}
+): MethodDecorator {
+  return function (
+    _target: object,
+    _propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => Promise<unknown>;
+
+    descriptor.value = async function (this: unknown, ...args: unknown[]): Promise<unknown> {
+      const registryConfig: BulkheadConfig = {};
+      if (options.maxConcurrent !== undefined) {
+        registryConfig.maxConcurrent = options.maxConcurrent;
+      }
+      const registry = new BulkheadRegistry(registryConfig);
+      const pool = registry.get(poolName);
+      return pool.run(
+        () => originalMethod.apply(this, args),
+        options.priority ?? "medium"
+      );
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * @Circuit('payment-service') — Wrap method in circuit breaker
+ */
+export function Circuit(
+  name: string,
+  options: { fallback?: () => unknown } = {}
+): MethodDecorator {
+  return function (
+    _target: object,
+    _propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => Promise<unknown>;
+    const breaker = new CircuitBreakerRegistry().get(name);
+
+    descriptor.value = async function (this: unknown, ...args: unknown[]): Promise<unknown> {
+      return breaker.execute(
+        () => originalMethod.apply(this, args),
+        options.fallback
+      );
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * @Retry({ maxAttempts: 3 }) — Wrap method with retry logic
+ */
+export function Retry(config?: Parameters<typeof withRetry>[1]): MethodDecorator {
+  return function (
+    _target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value as (...args: unknown[]) => Promise<unknown>;
+
+    descriptor.value = async function (this: unknown, ...args: unknown[]): Promise<unknown> {
+      return withRetry(
+        () => originalMethod.apply(this, args),
+        config,
+        String(propertyKey)
+      );
+    };
+
+    return descriptor;
+  };
+}
+
+export { ImmortalConfig };

package/packages/adapter-nestjs/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @file index.ts
+ * @description Immortal.js NestJS Adapter — Public API Entry Point
+ */
+
+export {
+  ImmortalService,
+  ImmortalModule,
+  Bulkhead,
+  Circuit,
+  Retry,
+} from "./immortal.module.js";
+
+export type { ImmortalModuleOptions } from "./immortal.module.js";

package/packages/adapter-nestjs/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declarationDir": "./dist",
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"],
+  "references": [{ "path": "../core" }]
+}

package/packages/core/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@immortal/core",
+  "version": "1.0.0",
+  "description": "Immortal.js core — framework-agnostic resilience runtime",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./safe-zone": {
+      "import": "./dist/safe-zone/index.js",
+      "types": "./dist/safe-zone/index.d.ts"
+    },
+    "./recovery": {
+      "import": "./dist/recovery/index.js",
+      "types": "./dist/recovery/index.d.ts"
+    },
+    "./isolation": {
+      "import": "./dist/isolation/index.js",
+      "types": "./dist/isolation/index.d.ts"
+    },
+    "./supervision": {
+      "import": "./dist/supervision/index.js",
+      "types": "./dist/supervision/index.d.ts"
+    },
+    "./monitoring": {
+      "import": "./dist/monitoring/index.js",
+      "types": "./dist/monitoring/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0",
+    "@vitest/coverage-v8": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}

package/packages/core/src/chaos/ChaosEngine.ts

@@ -0,0 +1,249 @@
+/**
+ * @file ChaosEngine.ts
+ * @description Chaos engineering toolkit for testing resilience
+ *
+ * CRITICAL SAFETY RULE: ChaosEngine is DISABLED in production.
+ * Any attempt to enable it in production is blocked with an error.
+ *
+ * Provides:
+ * - Latency injection (configurable range, probability, target routes)
+ * - Error injection (configurable probability, error types)
+ * - Worker kill simulation
+ * - Memory pressure simulation
+ * - Network partition simulation (rejecting all requests to a service)
+ *
+ * Usage (development/staging only):
+ * ```ts
+ * const chaos = new ChaosEngine({ enabled: true });
+ * chaos.injectLatency({ probability: 0.1, range: [100, 500] });
+ * chaos.injectError({ probability: 0.05, statusCode: 503 });
+ *
+ * // As Express middleware
+ * app.use(chaos.middleware());
+ * ```
+ */
+
+import type { ChaosConfig } from "../types.js";
+import { getEventBus } from "../event-bus.js";
+import { getLogger } from "../logger.js";
+
+export interface LatencyOptions {
+  probability?: number;
+  range?: [number, number];
+  targetRoutes?: string[];
+}
+
+export interface ErrorInjectionOptions {
+  probability?: number;
+  statusCode?: number;
+  message?: string;
+  targetRoutes?: string[];
+}
+
+export interface MemoryPressureOptions {
+  /** MB of memory to allocate and hold */
+  sizeMb?: number;
+  /** Duration to hold the allocation in ms (default: 10s) */
+  durationMs?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CHAOS ENGINE CLASS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class ChaosEngine {
+  private enabled: boolean;
+  private latencyConfig?: LatencyOptions;
+  private errorConfig?: ErrorInjectionOptions;
+  private memoryPressureBuffers: Buffer[] = [];
+  private memoryPressureTimer?: ReturnType<typeof setTimeout>;
+
+  constructor(config: ChaosConfig = {}) {
+    // Hard safety check
+    if (config.enabled && process.env["NODE_ENV"] === "production") {
+      throw new Error(
+        "CHAOS ENGINE REFUSED: Cannot enable chaos mode in production (NODE_ENV=production). " +
+        "This is a hard safety block — not configurable."
+      );
+    }
+
+    this.enabled = config.enabled ?? false;
+
+    if (this.enabled) {
+      if (config.latencyProbability) {
+        const latencyOpts: LatencyOptions = {
+          probability: config.latencyProbability,
+          range: config.latencyRange ?? [10, 500],
+        };
+        if (config.targetRoutes !== undefined) latencyOpts.targetRoutes = config.targetRoutes;
+        this.latencyConfig = latencyOpts;
+      }
+
+      if (config.errorProbability) {
+        const errorOpts: ErrorInjectionOptions = {
+          probability: config.errorProbability,
+          statusCode: 503,
+        };
+        if (config.targetRoutes !== undefined) errorOpts.targetRoutes = config.targetRoutes;
+        this.errorConfig = errorOpts;
+      }
+
+      getLogger().warn("⚠️  CHAOS MODE ENABLED — intentional failures will be injected", {
+        latency: !!this.latencyConfig,
+        errors: !!this.errorConfig,
+        memoryPressure: config.memoryPressureMb,
+      });
+    }
+  }
+
+  /**
+   * Inject latency into a specific operation
+   */
+  async injectLatency(route?: string, options?: LatencyOptions): Promise<void> {
+    if (!this.enabled) return;
+
+    const cfg = { ...this.latencyConfig, ...options };
+    const probability = cfg.probability ?? 0.1;
+    const [minMs, maxMs] = cfg.range ?? [10, 500];
+    const targets = cfg.targetRoutes;
+
+    // Check if this route should be targeted
+    if (targets && route && !targets.some((r) => route.includes(r))) return;
+
+    if (Math.random() < probability) {
+      const delay = Math.floor(Math.random() * (maxMs - minMs) + minMs);
+
+      getEventBus().emit("chaos:latency-injected", {
+        route,
+        data: { delayMs: delay, probability },
+      });
+
+      getLogger().debug(`[CHAOS] Injecting ${delay}ms latency on ${route}`);
+      await sleep(delay);
+    }
+  }
+
+  /**
+   * Possibly throw a chaos error
+   */
+  injectError(route?: string, options?: ErrorInjectionOptions): void {
+    if (!this.enabled) return;
+
+    const cfg = { ...this.errorConfig, ...options };
+    const probability = cfg.probability ?? 0.05;
+    const targets = cfg.targetRoutes;
+
+    if (targets && route && !targets.some((r) => route.includes(r))) return;
+
+    if (Math.random() < probability) {
+      getEventBus().emit("chaos:error-injected", {
+        route,
+        data: { probability, statusCode: cfg.statusCode ?? 503 },
+      });
+
+      getLogger().debug(`[CHAOS] Injecting error on ${route}`);
+
+      const err = new Error(cfg.message ?? "[CHAOS] Injected error for resilience testing");
+      (err as Error & { statusCode: number }).statusCode = cfg.statusCode ?? 503;
+      throw err;
+    }
+  }
+
+  /**
+   * Simulate memory pressure by allocating and holding large buffers
+   */
+  simulateMemoryPressure(options: MemoryPressureOptions = {}): void {
+    if (!this.enabled) return;
+
+    const sizeMb = options.sizeMb ?? 100;
+    const durationMs = options.durationMs ?? 10_000;
+
+    getLogger().warn(`[CHAOS] Simulating ${sizeMb}MB memory pressure for ${durationMs}ms`);
+
+    // Allocate memory
+    const chunkSize = Math.min(sizeMb, 50); // Max 50MB chunks
+    const numChunks = Math.ceil(sizeMb / chunkSize);
+
+    for (let i = 0; i < numChunks; i++) {
+      const buf = Buffer.alloc(chunkSize * 1024 * 1024);
+      // Write to buffer to prevent optimization
+      buf.fill(i % 256);
+      this.memoryPressureBuffers.push(buf);
+    }
+
+    // Release after duration
+    this.memoryPressureTimer = setTimeout(() => {
+      this.memoryPressureBuffers = [];
+      getLogger().info("[CHAOS] Memory pressure simulation complete — buffers released");
+    }, durationMs).unref();
+  }
+
+  /**
+   * Kill a simulated worker (sends SIGTERM to self in testing — careful!)
+   */
+  simulateWorkerKill(delay = 1000): void {
+    if (!this.enabled) return;
+
+    getLogger().warn(`[CHAOS] Simulating worker kill in ${delay}ms`);
+    getEventBus().emit("chaos:worker-killed", { data: { delay } });
+
+    setTimeout(() => {
+      process.kill(process.pid, "SIGTERM");
+    }, delay).unref();
+  }
+
+  /**
+   * Create an Express/Koa middleware that applies chaos to every request
+   */
+  middleware(): (req: { path?: string; url?: string }, _res: unknown, next: (err?: unknown) => void) => Promise<void> {
+    return async (req, _res, next) => {
+      if (!this.enabled) {
+        next();
+        return;
+      }
+
+      const route = (req.path ?? req.url ?? "unknown").toString();
+
+      try {
+        await this.injectLatency(route);
+        this.injectError(route);
+        next();
+      } catch (err) {
+        next(err);
+      }
+    };
+  }
+
+  /**
+   * Check if chaos mode is active
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Disable chaos mode (can always be disabled, even dynamically)
+   */
+  disable(): void {
+    this.enabled = false;
+    this.memoryPressureBuffers = [];
+    if (this.memoryPressureTimer) clearTimeout(this.memoryPressureTimer);
+    getLogger().info("[CHAOS] Chaos mode disabled");
+  }
+
+  /**
+   * Get chaos configuration summary
+   */
+  getSummary(): Record<string, unknown> {
+    return {
+      enabled: this.enabled,
+      latency: this.latencyConfig ?? null,
+      errors: this.errorConfig ?? null,
+      isProduction: process.env["NODE_ENV"] === "production",
+    };
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}