immortal-js 1.0.0

package/examples/express-basic/index.ts

@@ -0,0 +1,462 @@
+/**
+ * @file examples/express-basic/index.ts
+ * @description Immortal.js — Express Resilience Example (Ultra Pro Edition)
+ *
+ * Demonstrates:
+ *   - CircuitBreaker       — wraps unreliable external APIs
+ *   - BulkheadPool         — per-service concurrency isolation
+ *   - FallbackCache        — serve stale data when backends fail
+ *   - GracefulShutdown     — drain connections before process exit
+ *   - withRetry            — exponential back-off for transient errors
+ *   - withTimeout          — hard deadline on any async operation
+ *
+ * Run:   npm run dev
+ * Build: npm run build
+ * Start: npm start
+ */
+
+import express from "express";
+import {
+  CircuitBreaker,
+  BulkheadPool,
+  FallbackCache,
+  GracefulShutdown,
+  withRetry,
+  withTimeout,
+  getEventBus,
+} from "@immortal/core";
+
+// ─── App ──────────────────────────────────────────────────────────────────────
+
+const app = express();
+app.use(express.json());
+
+// ─── Immortal.js Primitives ───────────────────────────────────────────────────
+
+/**
+ * Payment circuit breaker
+ * Opens after 5 failures in a 100-request sliding window.
+ * Attempts half-open probe after 15s cooldown.
+ */
+const paymentCircuit = new CircuitBreaker("payment-provider", {
+  threshold: 5,
+  cooldownMs: 15_000,
+  slidingWindowSize: 100,
+});
+
+/**
+ * Inventory circuit breaker
+ * More sensitive — opens after 3 failures in a 50-request window.
+ */
+const inventoryCircuit = new CircuitBreaker("inventory-service", {
+  threshold: 3,
+  cooldownMs: 10_000,
+  slidingWindowSize: 50,
+});
+
+/**
+ * Payments bulkhead — max 10 concurrent, 20 queued
+ * BulkheadRejectedError thrown if both pools are full.
+ */
+const paymentsBulkhead = new BulkheadPool("payments", {
+  maxConcurrent: 10,
+  maxQueueSize: 20,
+  queueTimeoutMs: 15_000,
+});
+
+/**
+ * Search bulkhead — high concurrency allowed (read-only)
+ */
+const searchBulkhead = new BulkheadPool("search", {
+  maxConcurrent: 50,
+  maxQueueSize: 100,
+  queueTimeoutMs: 5_000,
+});
+
+/**
+ * FallbackCache — LRU with TTL
+ * Serves stale results when upstream is unavailable.
+ */
+const cache = new FallbackCache<unknown>({
+  maxSize: 1_000,
+  defaultTtlMs: 60_000,
+});
+
+// ─── Graceful Shutdown ────────────────────────────────────────────────────────
+
+const bus = getEventBus();
+
+// ─── Routes ───────────────────────────────────────────────────────────────────
+
+/**
+ * GET /
+ * Welcome + route map
+ */
+app.get("/", (_req, res) => {
+  res.json({
+    name: "Immortal.js Express Basic Example",
+    version: "1.0.0",
+    status: "running",
+    timestamp: new Date().toISOString(),
+    routes: {
+      "GET  /":                    "This route map",
+      "GET  /health":              "Live health snapshot",
+      "GET  /status/circuits":     "All circuit statuses",
+      "POST /payments/charge":     "Charge payment [Bulkhead + Circuit + Retry]",
+      "GET  /inventory/:productId": "Check inventory [Circuit + Cache]",
+      "GET  /search?q=...":        "Search [Bulkhead + Cache]",
+      "GET  /chaos/trip-payment":  "Force payment circuit OPEN (dev)",
+      "GET  /chaos/reset-circuits": "Reset all circuits (dev)",
+      "GET  /simulate/crash":      "Test global error handler",
+      "GET  /simulate/leak":       "Test MemoryLeakGuard",
+    },
+  });
+});
+
+/**
+ * GET /health
+ * Live snapshot of all Immortal.js primitive statuses.
+ */
+app.get("/health", (_req, res) => {
+  const payBk = paymentsBulkhead.getStatus();
+  const srchBk = searchBulkhead.getStatus();
+
+  res.json({
+    status: "ok",
+    timestamp: new Date().toISOString(),
+    uptime: Math.round(process.uptime()),
+    circuits: {
+      paymentProvider: paymentCircuit.getStatus(),
+      inventoryService: inventoryCircuit.getStatus(),
+    },
+    bulkheads: {
+      payments: { active: payBk.active, queued: payBk.queued },
+      search: { active: srchBk.active, queued: srchBk.queued },
+    },
+    cache: {
+      description: "FallbackCache (LRU + TTL) — inspect keys via /status/cache",
+    },
+  });
+});
+
+/**
+ * POST /payments/charge
+ * Body: { amount: number, cardToken: string }
+ *
+ * Layers:
+ *   1. BulkheadPool     — cap concurrent payment requests
+ *   2. CircuitBreaker   — open circuit if gateway repeatedly fails
+ *   3. withRetry        — retry transient gateway errors
+ *   4. withTimeout      — hard 10s deadline on the API call
+ */
+app.post("/payments/charge", async (req, res, next) => {
+  try {
+    const result = await paymentsBulkhead.run(
+      async () =>
+        paymentCircuit.execute(
+          async () =>
+            withRetry(
+              async () => {
+                const { amount, cardToken } = req.body as {
+                  amount: number;
+                  cardToken: string;
+                };
+                return withTimeout(
+                  () => simulatePaymentAPI(amount, cardToken),
+                  10_000,
+                  "payment-api"
+                );
+              },
+              { maxAttempts: 2, baseDelayMs: 300, maxDelayMs: 2_000 }
+            ),
+          // Circuit-open fallback — inform caller to retry later
+          () => ({
+            success: false as boolean,
+            transactionId: `queued-${Date.now()}`,
+            amount: 0,
+            queued: true,
+          })
+        ),
+      "high"
+    );
+
+    res.json(result);
+  } catch (err) {
+    next(err);
+  }
+});
+
+/**
+ * GET /inventory/:productId
+ * Circuit Breaker + FallbackCache
+ */
+app.get("/inventory/:productId", async (req, res, next) => {
+  const { productId } = req.params as { productId: string };
+  const cacheKey = `inventory:${productId}`;
+
+  try {
+    const data = await inventoryCircuit.execute(
+      async () => {
+        const result = await withTimeout(
+          () => simulateInventoryAPI(productId),
+          5_000,
+          "inventory-api"
+        );
+        // Cache successful response
+        cache.set(cacheKey, result, 30_000);
+        return result;
+      },
+      // Circuit-open fallback — serve stale cache or empty
+      () => {
+        const stale = cache.get(cacheKey);
+        if (stale) {
+          res.setHeader("X-Immortal-Fallback", "stale-cache");
+          return stale;
+        }
+        return { productId, stock: 0, stale: true, circuitOpen: true };
+      }
+    );
+
+    res.json(data);
+  } catch (err) {
+    next(err);
+  }
+});
+
+/**
+ * GET /search?q=...
+ * Bulkhead + FallbackCache (1-minute TTL)
+ */
+app.get("/search", async (req, res, next) => {
+  try {
+    const q = (req.query["q"] as string | undefined) ?? "";
+    const cacheKey = `search:${q}`;
+
+    const result = await searchBulkhead.run(async () => {
+      const cached = cache.get(cacheKey);
+      if (cached) {
+        res.setHeader("X-Cache", "HIT");
+        return cached;
+      }
+
+      const results = await simulateSearchAPI(q);
+      cache.set(cacheKey, results, 60_000);
+      return results;
+    }, "medium");
+
+    res.json(result);
+  } catch (err) {
+    next(err);
+  }
+});
+
+/**
+ * GET /status/circuits
+ * All circuit breaker statuses (open/closed/half-open)
+ */
+app.get("/status/circuits", (_req, res) => {
+  res.json({
+    paymentProvider: paymentCircuit.getStatus(),
+    inventoryService: inventoryCircuit.getStatus(),
+  });
+});
+
+/**
+ * GET /chaos/trip-payment
+ * Force payment circuit OPEN (dev / load-test use only)
+ */
+app.get("/chaos/trip-payment", (_req, res) => {
+  if (process.env["NODE_ENV"] === "production") {
+    res.status(403).json({ error: "Chaos endpoints disabled in production" });
+    return;
+  }
+  paymentCircuit.forceState("OPEN");
+  res.json({
+    message: "Payment circuit forced OPEN",
+    state: paymentCircuit.getStatus().state,
+  });
+});
+
+/**
+ * GET /chaos/reset-circuits
+ * Reset all circuits to CLOSED
+ */
+app.get("/chaos/reset-circuits", (_req, res) => {
+  if (process.env["NODE_ENV"] === "production") {
+    res.status(403).json({ error: "Chaos endpoints disabled in production" });
+    return;
+  }
+  paymentCircuit.forceState("CLOSED");
+  inventoryCircuit.forceState("CLOSED");
+  res.json({
+    message: "All circuits reset to CLOSED",
+    payment: paymentCircuit.getStatus().state,
+    inventory: inventoryCircuit.getStatus().state,
+  });
+});
+
+/**
+ * GET /simulate/crash
+ * Intentional error — exercises the global error handler.
+ */
+app.get("/simulate/crash", (_req, _res, next) => {
+  next(new Error("Simulated crash — global error handler should catch this!"));
+});
+
+/**
+ * GET /simulate/leak
+ * Intentional memory leak — exercises MemoryLeakGuard.
+ */
+const leakyArray: Buffer[] = [];
+app.get("/simulate/leak", (_req, res) => {
+  leakyArray.push(Buffer.alloc(1024 * 1024)); // 1 MB per request
+  res.json({
+    message: "Memory leaked (1 MB)",
+    totalLeakedMb: leakyArray.length,
+    note: "MemoryLeakGuard detects heap growth trends and initiates proactive restart",
+  });
+});
+
+// ─── Global Error Handler ─────────────────────────────────────────────────────
+
+app.use(
+  (
+    err: unknown,
+    _req: express.Request,
+    res: express.Response,
+    _next: express.NextFunction
+  ) => {
+    if (res.headersSent) return;
+
+    const status =
+      (err as { statusCode?: number; status?: number }).statusCode ??
+      (err as { statusCode?: number; status?: number }).status ??
+      500;
+
+    const name = (err as { name?: string }).name ?? "Error";
+
+    // Translate Immortal.js-specific error names to HTTP status codes
+    const httpStatus =
+      name === "BulkheadRejectedError"
+        ? 429
+        : name === "TimeoutError"
+          ? 504
+          : status;
+
+    res.status(httpStatus).json({
+      error:
+        httpStatus >= 500
+          ? "Internal Server Error"
+          : (err as Error).message ?? "Unknown error",
+      errorType: name,
+      timestamp: new Date().toISOString(),
+    });
+  }
+);
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const PORT = parseInt(process.env["PORT"] ?? "3000", 10);
+
+const server = app.listen(PORT, () => {
+  console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║         Immortal.js — Express Basic Example  🚀              ║
+╠══════════════════════════════════════════════════════════════╣
+║  Server      →  http://localhost:${PORT}                       ║
+║  Health      →  http://localhost:${PORT}/health                ║
+║  Circuits    →  http://localhost:${PORT}/status/circuits        ║
+╠══════════════════════════════════════════════════════════════╣
+║  Routes                                                       ║
+║  POST /payments/charge       Bulkhead + Circuit + Retry       ║
+║  GET  /inventory/:productId  Circuit + FallbackCache          ║
+║  GET  /search?q=...          Bulkhead + FallbackCache         ║
+║  GET  /chaos/trip-payment    Force payment circuit OPEN       ║
+║  GET  /chaos/reset-circuits  Reset all circuits               ║
+║  GET  /simulate/crash        Test global error handler        ║
+║  GET  /simulate/leak         Test MemoryLeakGuard             ║
+╚══════════════════════════════════════════════════════════════╝
+`);
+});
+
+// Register graceful shutdown — drains server before exit
+const shutdown = new GracefulShutdown(
+  {
+    timeoutMs: 20_000,
+    signals: ["SIGTERM", "SIGINT"],
+    onShutdown: [
+      async (_signal: string) => {
+        // Drain the payments bulkhead queue
+        paymentsBulkhead.drain();
+        // Close HTTP server (stop accepting new requests)
+        await new Promise<void>((resolve, reject) => {
+          server.close((err) => (err ? reject(err) : resolve()));
+        });
+      },
+    ],
+  },
+  bus
+);
+
+// Keep reference alive (signal handlers are installed in constructor)
+void shutdown;
+
+// ─── Simulated External Services ─────────────────────────────────────────────
+
+async function simulatePaymentAPI(
+  amount: number,
+  _cardToken: string
+): Promise<{ success: boolean; transactionId: string; amount: number }> {
+  // 20% failure rate — exercises retry + circuit breaker
+  if (Math.random() < 0.2) {
+    const err = Object.assign(new Error("Payment gateway timeout"), {
+      statusCode: 503,
+    });
+    throw err;
+  }
+
+  await sleep(100 + Math.random() * 200);
+
+  return {
+    success: true,
+    transactionId: `txn_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
+    amount,
+  };
+}
+
+async function simulateInventoryAPI(
+  productId: string
+): Promise<{ productId: string; stock: number; warehouseId: string }> {
+  // 10% failure rate
+  if (Math.random() < 0.1) {
+    throw new Error("Inventory service unavailable");
+  }
+
+  await sleep(30 + Math.random() * 70);
+
+  return {
+    productId,
+    stock: Math.floor(Math.random() * 200),
+    warehouseId: `WH-${Math.floor(Math.random() * 5) + 1}`,
+  };
+}
+
+async function simulateSearchAPI(
+  query: string
+): Promise<{ results: Array<{ id: number; title: string; score: number }> }> {
+  await sleep(20 + Math.random() * 50);
+
+  return {
+    results: Array.from({ length: 5 }, (_, i) => ({
+      id: i + 1,
+      title: `Result ${i + 1} for "${query}"`,
+      score: Math.round(Math.random() * 100) / 100,
+    })).sort((a, b) => b.score - a.score),
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export { app };

package/examples/express-basic/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "immortal-express-basic-example",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --import tsx/esm --no-warnings index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@immortal/core": "*",
+    "express": "^4.18.3"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}

package/examples/express-basic/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "strict": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "declaration": false,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "./"
+  },
+  "include": ["index.ts"],
+  "exclude": ["node_modules", "dist"]
+}