immortal-js 1.0.0

package/packages/adapter-fastify/src/plugin.ts

@@ -0,0 +1,226 @@
+/**
+ * @file adapter-fastify/src/plugin.ts
+ * @description Immortal.js Fastify Plugin
+ *
+ * Uses Fastify's native hook system for tighter integration:
+ * - onRequest: request ID injection + bulkhead check
+ * - onError: error capture + fallback dispatch
+ * - onResponse: metrics recording
+ * - onSend: cache response for fallback
+ * - onClose: graceful shutdown integration
+ */
+
+import type {
+  FastifyPluginAsync,
+  FastifyRequest,
+  FastifyReply,
+  FastifyInstance,
+  HookHandlerDoneFunction,
+  RouteOptions,
+} from "fastify";
+import type { ImmortalConfig, FallbackGenerator, Priority, LoggerConfig } from "@immortal/core";
+import {
+  mergeWithDefaults,
+  validateConfig,
+  createLogger,
+  getEventBus,
+  ErrorTrap,
+  AsyncBoundary,
+  BulkheadPool,
+  BulkheadRegistry,
+  CircuitBreakerRegistry,
+  FallbackCache,
+  GracefulShutdown,
+  MetricsCollector,
+  HealthMonitor,
+  MemoryLeakGuard,
+  DiagnosticsChannel,
+} from "@immortal/core";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FASTIFY DECLARATIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+declare module "fastify" {
+  interface FastifyInstance {
+    immortal: {
+      getMetrics: () => ReturnType<MetricsCollector["getSnapshot"]>;
+      circuits: CircuitBreakerRegistry;
+      bulkheads: BulkheadRegistry;
+      cache: FallbackCache;
+      bulkhead: (name: string, priority?: Priority) => (
+        request: FastifyRequest,
+        reply: FastifyReply,
+        done: HookHandlerDoneFunction
+      ) => void;
+    };
+  }
+  interface FastifyRequest {
+    immortalRequestId: string;
+    immortalStartedAt: number;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PLUGIN OPTIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ImmortalFastifyOptions extends ImmortalConfig {
+  /** Skip routes matching these patterns */
+  skipRoutes?: RegExp[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FASTIFY PLUGIN
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const immortalPlugin: FastifyPluginAsync<ImmortalFastifyOptions> = async (
+  fastify: FastifyInstance,
+  userOptions: ImmortalFastifyOptions
+) => {
+  const { skipRoutes, ...userConfig } = userOptions;
+
+  // Validate config
+  const validation = validateConfig(userConfig);
+  if (!validation.valid) {
+    throw new Error(`Immortal.js config errors:\n${validation.errors.join("\n")}`);
+  }
+
+  const config = mergeWithDefaults(userConfig);
+  const logger = createLogger(config.logger as Required<LoggerConfig>);
+  const bus = getEventBus();
+
+  // Initialize 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();
+
+  // ── Fastify Hooks ────────────────────────────────────────────────────────
+
+  // onRequest: Context injection
+  fastify.addHook("onRequest", async (request: FastifyRequest, _reply: FastifyReply) => {
+    const shouldSkip = skipRoutes?.some((r) => r.test(request.routerPath ?? request.url));
+    if (shouldSkip) return;
+
+    const requestId = crypto.randomUUID();
+    request.immortalRequestId = requestId;
+    request.immortalStartedAt = Date.now();
+
+    // Run the rest of the request inside AsyncLocalStorage context
+    await AsyncBoundary.run(
+      {
+        requestId,
+        route: request.routerPath ?? request.url,
+        method: request.method,
+        startedAt: Date.now(),
+      },
+      async () => {
+        metricsCollector.recordRequestStart();
+      }
+    );
+  });
+
+  // onError: Error capture
+  fastify.addHook("onError", async (request: FastifyRequest, _reply: FastifyReply, error: Error) => {
+    errorTrap.capture(error, {
+      requestId: request.immortalRequestId,
+      route: request.routerPath ?? request.url,
+    });
+  });
+
+  // onResponse: Metrics tracking
+  fastify.addHook("onResponse", async (request: FastifyRequest, reply: FastifyReply) => {
+    const wasError = reply.statusCode >= 500;
+    metricsCollector.recordRequestEnd(wasError);
+
+    // Auto-cache successful responses for fallback
+    if (!wasError && reply.statusCode < 300) {
+      // Body caching would require serialization hook
+    }
+  });
+
+  // onClose: Graceful shutdown
+  fastify.addHook("onClose", async (_instance: FastifyInstance) => {
+    logger.info("Fastify closing — initiating graceful shutdown");
+    healthMonitor.stop();
+    memoryLeakGuard.stop();
+    diagnosticsChannel.stop();
+  });
+
+  // ── Dashboard Routes ─────────────────────────────────────────────────────
+  if (config.dashboard.enabled) {
+    const dashPath = config.dashboard.path;
+
+    fastify.get(`${dashPath}/status`, async (_request, _reply) => {
+      return metricsCollector.getSnapshot();
+    });
+
+    fastify.get(`${dashPath}/health`, async (_request, reply) => {
+      const metrics = metricsCollector.getSnapshot();
+      const openCircuits = circuitRegistry.getOpenCircuits();
+      const isHealthy = openCircuits.length === 0;
+
+      reply.status(isHealthy ? 200 : 503);
+      return {
+        status: isHealthy ? "healthy" : "degraded",
+        timestamp: new Date().toISOString(),
+        openCircuits,
+        eventLoopLag: metrics.eventLoopLag,
+      };
+    });
+
+    if (config.dashboard.enablePrometheus) {
+      fastify.get(`${dashPath}/metrics`, async (_request, reply) => {
+        diagnosticsChannel.updateMetrics(metricsCollector.getSnapshot());
+        reply.type("text/plain");
+        return diagnosticsChannel.getPrometheusMetrics();
+      });
+    }
+  }
+
+  // ── Decorate fastify instance ────────────────────────────────────────────
+  fastify.decorate("immortal", {
+    getMetrics: () => metricsCollector.getSnapshot(),
+    circuits: circuitRegistry,
+    bulkheads: bulkheadRegistry,
+    cache: fallbackCache,
+    bulkhead: (name: string, priority: Priority = "medium") => {
+      const pool = bulkheadRegistry.get(name);
+      return async (
+        _request: FastifyRequest,
+        _reply: FastifyReply,
+        done: HookHandlerDoneFunction
+      ) => {
+        try {
+          await pool.run(() => Promise.resolve(), priority);
+          done();
+        } catch (err) {
+          done(err as Error);
+        }
+      };
+    },
+  });
+
+  logger.info("Immortal.js Fastify plugin initialized");
+};
+
+export default immortalPlugin;

package/packages/adapter-fastify/tsconfig.json

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

package/packages/adapter-koa/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@immortal/koa",
+  "version": "1.0.0",
+  "description": "Immortal.js adapter for Koa — resilience via the onion-model middleware architecture",
+  "author": "Immortal.js Team",
+  "license": "MIT",
+  "homepage": "https://github.com/immortal-js/immortal#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/immortal-js/immortal.git",
+    "directory": "packages/adapter-koa"
+  },
+  "keywords": [
+    "koa",
+    "resilience",
+    "circuit-breaker",
+    "bulkhead",
+    "retry",
+    "middleware",
+    "immortal"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@immortal/core": "*"
+  },
+  "peerDependencies": {
+    "koa": ">=2.14.0"
+  },
+  "peerDependenciesMeta": {
+    "koa": { "optional": false }
+  },
+  "devDependencies": {
+    "@types/koa": "^2.14.0",
+    "@types/node": "^20.0.0",
+    "koa": "^2.15.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

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

@@ -0,0 +1,207 @@
+/**
+ * @file adapter-koa/src/index.ts
+ * @description Immortal.js Koa Adapter
+ *
+ * Koa's onion model (middleware compose) aligns naturally with Immortal's
+ * containment layer philosophy — each middleware wraps the next like nested shells.
+ *
+ * Usage:
+ * ```ts
+ * import Koa from 'koa';
+ * import { immortal } from '@immortal/koa';
+ *
+ * const app = new Koa();
+ * immortal(app, { retry: { maxAttempts: 3 } });
+ *
+ * app.use(async (ctx, next) => {
+ *   await next();
+ *   ctx.body = { status: 'ok' };
+ * });
+ * ```
+ */
+
+import type { ImmortalConfig, FallbackGenerator, Priority, LoggerConfig } from "@immortal/core";
+import {
+  mergeWithDefaults,
+  validateConfig,
+  createLogger,
+  getEventBus,
+  ErrorTrap,
+  AsyncBoundary,
+  BulkheadRegistry,
+  CircuitBreakerRegistry,
+  FallbackCache,
+  GracefulShutdown,
+  MetricsCollector,
+  HealthMonitor,
+  MemoryLeakGuard,
+  DiagnosticsChannel,
+  serializeError,
+} from "@immortal/core";
+
+// Minimal Koa-like types (avoids hard peer dependency in type imports)
+interface KoaContext {
+  path: string;
+  method: string;
+  url: string;
+  status: number;
+  body: unknown;
+  set: (key: string, value: string) => void;
+  state: Record<string, unknown>;
+  request: { body?: unknown };
+  response: { status: number; body: unknown };
+}
+
+type KoaNext = () => Promise<void>;
+type KoaMiddleware = (ctx: KoaContext, next: KoaNext) => Promise<void>;
+
+interface KoaApplication {
+  use: (middleware: KoaMiddleware) => KoaApplication;
+  [key: string]: unknown;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MAIN ADAPTER FUNCTION
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function immortal(app: KoaApplication, userConfig: ImmortalConfig = {}): KoaApplication {
+  const validation = validateConfig(userConfig);
+  if (!validation.valid) {
+    throw new Error(`Immortal.js config errors:\n${validation.errors.join("\n")}`);
+  }
+
+  const config = mergeWithDefaults(userConfig);
+  const logger = createLogger(config.logger as Required<LoggerConfig>);
+  const bus = getEventBus();
+
+  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();
+
+  // ── Core containment middleware ──────────────────────────────────────────
+  // The outermost onion layer — catches everything that slips through inner layers
+  app.use(async (ctx: KoaContext, next: KoaNext) => {
+    const requestId = crypto.randomUUID();
+    const route = ctx.path ?? ctx.url;
+    const startedAt = Date.now();
+
+    ctx.set("X-Request-Id", requestId);
+    ctx.state["immortalRequestId"] = requestId;
+    ctx.state["immortalStartedAt"] = startedAt;
+
+    metricsCollector.recordRequestStart();
+
+    await AsyncBoundary.run(
+      { requestId, route, method: ctx.method, startedAt },
+      async () => {
+        try {
+          await next();
+          metricsCollector.recordRequestEnd(ctx.status >= 500);
+        } catch (err) {
+          metricsCollector.recordRequestEnd(true);
+
+          errorTrap.capture(err, { requestId, route });
+
+          bus.emit("error:captured", {
+            requestId,
+            route,
+            error: serializeError(err),
+          });
+
+          // Check for cached fallback
+          const cached = fallbackCache.get(`${ctx.method}:${route}`);
+          if (cached) {
+            ctx.set("X-Immortal-Fallback", "true");
+            ctx.status = 200;
+            ctx.body = cached;
+            bus.emit("fallback:cache-hit", { route, data: { method: ctx.method } });
+            return;
+          }
+
+          // No fallback: proper error response
+          const serialized = serializeError(err);
+          const statusCode = (err as { statusCode?: number; status?: number }).statusCode
+            ?? (err as { statusCode?: number; status?: number }).status
+            ?? 500;
+
+          ctx.status = statusCode;
+          ctx.body = {
+            error: statusCode >= 500 ? "Internal Server Error" : (err as Error).message,
+            requestId,
+            timestamp: new Date().toISOString(),
+            ...(config.safeZone.exposeErrors ? { details: serialized } : {}),
+          };
+        }
+      }
+    );
+  });
+
+  // ── Dashboard routes ─────────────────────────────────────────────────────
+  if (config.dashboard.enabled) {
+    const dashPath = config.dashboard.path;
+
+    app.use(async (ctx: KoaContext, next: KoaNext) => {
+      if (ctx.path === `${dashPath}/status`) {
+        ctx.body = metricsCollector.getSnapshot();
+        return;
+      }
+
+      if (ctx.path === `${dashPath}/health`) {
+        const openCircuits = circuitRegistry.getOpenCircuits();
+        const isHealthy = openCircuits.length === 0;
+        ctx.status = isHealthy ? 200 : 503;
+        ctx.body = { status: isHealthy ? "healthy" : "degraded", openCircuits };
+        return;
+      }
+
+      if (config.dashboard.enablePrometheus && ctx.path === `${dashPath}/metrics`) {
+        diagnosticsChannel.updateMetrics(metricsCollector.getSnapshot());
+        ctx.set("Content-Type", "text/plain");
+        ctx.body = diagnosticsChannel.getPrometheusMetrics();
+        return;
+      }
+
+      await next();
+    });
+  }
+
+  // ── Attach API to app ────────────────────────────────────────────────────
+  app["immortal"] = {
+    getMetrics: () => metricsCollector.getSnapshot(),
+    circuits: circuitRegistry,
+    bulkheads: bulkheadRegistry,
+    cache: fallbackCache,
+    registerServer: (server: { close: (cb?: () => void) => void }) =>
+      gracefulShutdown.registerServer(server),
+    bulkhead: (name: string, priority: Priority = "medium"): KoaMiddleware => {
+      const pool = bulkheadRegistry.get(name);
+      return async (_ctx: KoaContext, next: KoaNext) => {
+        await pool.run(next, priority);
+      };
+    },
+  };
+
+  logger.info("Immortal.js Koa adapter initialized");
+  return app;
+}
+
+export type { ImmortalConfig, FallbackGenerator };

package/packages/adapter-koa/tsconfig.json

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

package/packages/adapter-nestjs/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@immortal/nestjs",
+  "version": "1.0.0",
+  "description": "Immortal.js Dynamic Module for NestJS — enterprise-grade resilience with DI-friendly decorators",
+  "author": "Immortal.js Team",
+  "license": "MIT",
+  "homepage": "https://github.com/immortal-js/immortal#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/immortal-js/immortal.git",
+    "directory": "packages/adapter-nestjs"
+  },
+  "keywords": [
+    "nestjs",
+    "resilience",
+    "circuit-breaker",
+    "bulkhead",
+    "retry",
+    "dependency-injection",
+    "enterprise",
+    "immortal"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@immortal/core": "*"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10.0.0",
+    "@nestjs/core": ">=10.0.0",
+    "reflect-metadata": ">=0.1.13"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": { "optional": false },
+    "@nestjs/core": { "optional": false },
+    "reflect-metadata": { "optional": false }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.3.0",
+    "@nestjs/core": "^10.3.0",
+    "@types/node": "^20.0.0",
+    "reflect-metadata": "^0.2.1",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}