immortal-js 1.0.0

package/examples/fastify-microservice/index.ts

@@ -0,0 +1,342 @@
+/**
+ * @file examples/fastify-microservice/index.ts
+ * @description Immortal.js — Fastify Microservice (Ultra Pro Edition)
+ *
+ * Demonstrates: Circuit Breaker, Bulkhead, Retry, Timeout, Fallback Cache,
+ * Graceful Shutdown, Health Monitor, Metrics endpoint.
+ *
+ * Run:   npm run dev
+ * Build: npm run build
+ * Start: npm start
+ */
+
+import Fastify from "fastify";
+import {
+  CircuitBreaker,
+  BulkheadPool,
+  withRetry,
+  withTimeout,
+  FallbackCache,
+  GracefulShutdown,
+  getEventBus,
+} from "@immortal/core";
+
+// ─── App Setup ───────────────────────────────────────────────────────────────
+// Use plain JSON logger — no pino-pretty dependency required
+const fastify = Fastify({
+  logger: true,
+});
+
+// ─── Resilient Primitives ─────────────────────────────────────────────────────
+
+// CircuitBreaker(name: string, config?) — positional constructor
+const inventoryCircuit = new CircuitBreaker("inventory-service", {
+  threshold: 5,
+  cooldownMs: 12_000,
+  slidingWindowSize: 15,
+});
+
+const paymentCircuit = new CircuitBreaker("payment-gateway", {
+  threshold: 3,
+  cooldownMs: 30_000,
+  slidingWindowSize: 10,
+});
+
+// BulkheadPool(name: string, config?) — positional constructor
+const ordersBulkhead = new BulkheadPool("orders", {
+  maxConcurrent: 20,
+  maxQueueSize: 100,
+  queueTimeoutMs: 5_000,
+});
+
+// FallbackCache({ maxSize?, defaultTtlMs? })
+const productCache = new FallbackCache<unknown>({
+  maxSize: 500,
+  defaultTtlMs: 30_000,
+});
+
+// ─── Simulated External Services ─────────────────────────────────────────────
+
+async function fetchInventory(productId: string): Promise<{ stock: number }> {
+  if (Math.random() < 0.15) throw new Error("Inventory service unavailable");
+  await sleep(20 + Math.random() * 80);
+  return { stock: Math.floor(Math.random() * 100), productId } as { stock: number };
+}
+
+async function processPayment(
+  orderId: string,
+  amount: number
+): Promise<{ transactionId: string }> {
+  if (Math.random() < 0.05) throw new Error("Payment gateway timeout");
+  await sleep(100 + Math.random() * 200);
+  return { transactionId: `txn-${orderId}-${Date.now()}`, amount } as { transactionId: string };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ─── Routes ───────────────────────────────────────────────────────────────────
+
+/**
+ * GET /
+ * Welcome page with route map
+ */
+fastify.get("/", async (_request, reply) => {
+  return reply.send({
+    name: "Immortal.js Fastify Microservice",
+    version: "1.0.0",
+    status: "running",
+    timestamp: new Date().toISOString(),
+    routes: {
+      "GET  /":                      "This route map",
+      "GET  /health":                "Live health + circuit status",
+      "GET  /metrics":               "Prometheus-compatible metrics",
+      "GET  /products/:id":          "Inventory lookup [Circuit + Cache]",
+      "POST /orders":                "Create order [Bulkhead + Retry + Circuit]",
+      "GET  /chaos/trip-inventory":  "Force inventory circuit OPEN (dev)",
+      "GET  /chaos/reset-circuits":  "Reset all circuits (dev)",
+    },
+  });
+});
+
+/**
+ * GET /products/:id
+ * Circuit Breaker wraps inventory fetch.
+ * On circuit open / timeout → serve from FallbackCache.
+ */
+fastify.get<{ Params: { id: string } }>("/products/:id", async (request, reply) => {
+  const { id } = request.params;
+
+  try {
+    const data = await withTimeout(
+      () =>
+        inventoryCircuit.execute(
+          () => fetchInventory(id),
+          () => ({ stock: -1, fromFallback: true })
+        ),
+      3_000,
+      "inventory-fetch"
+    );
+
+    // Cache successful (non-fallback) responses
+    if (!("fromFallback" in data)) {
+      productCache.set(`product:${id}`, data);
+    }
+
+    return reply
+      .header("X-Immortal-Circuit", inventoryCircuit.getStatus().state)
+      .send({ productId: id, ...data });
+  } catch {
+    // Serve stale cache on circuit open / timeout
+    const cached = productCache.get(`product:${id}`);
+    if (cached) {
+      return reply
+        .header("X-Immortal-Fallback", "true")
+        .header("X-Immortal-Fallback-Reason", "circuit-or-timeout")
+        .send({ productId: id, ...(cached as object), stale: true });
+    }
+    return reply.status(503).send({ error: "Product service unavailable" });
+  }
+});
+
+/**
+ * POST /orders
+ * Body: { productId: string, quantity: number, amount: number }
+ * Bulkhead → Retry inventory → CircuitBreaker payment
+ */
+fastify.post<{ Body: { productId: string; quantity: number; amount: number } }>(
+  "/orders",
+  async (request, reply) => {
+    const { productId, quantity, amount } = request.body;
+
+    try {
+      const result = await ordersBulkhead.run(async () => {
+        // Check inventory with retry
+        const inventory = await withRetry(
+          () => fetchInventory(productId),
+          {
+            maxAttempts: 3,
+            baseDelayMs: 100,
+            maxDelayMs: 2_000,
+            isRetryable: (e) =>
+              !(e instanceof Error && e.message.includes("insufficient")),
+          }
+        );
+
+        if (inventory.stock < quantity) {
+          return reply
+            .status(409)
+            .send({ error: "Insufficient stock", available: inventory.stock });
+        }
+
+        const orderId = `ord-${Date.now()}`;
+
+        const payment = await paymentCircuit.execute(
+          () => withTimeout(() => processPayment(orderId, amount), 10_000, "payment"),
+          () => ({ transactionId: `queued-${orderId}` })
+        );
+
+        return {
+          orderId,
+          productId,
+          quantity,
+          payment,
+          timestamp: new Date().toISOString(),
+        };
+      }, "high");
+
+      return reply.status(201).send(result);
+    } catch (err: unknown) {
+      if (err instanceof Error && err.name === "BulkheadRejectedError") {
+        return reply.status(429).send({
+          error: "Order system overloaded — try again shortly",
+          retryAfter: 5,
+          bulkhead: ordersBulkhead.getStatus(),
+        });
+      }
+      throw err;
+    }
+  }
+);
+
+/**
+ * GET /health
+ * Real-time status of all resilience primitives
+ */
+fastify.get("/health", async (_request, reply) => {
+  const bulkStatus = ordersBulkhead.getStatus();
+  return reply.send({
+    status: "healthy",
+    uptime: Math.round(process.uptime()),
+    memory: {
+      heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+      rssM: Math.round(process.memoryUsage().rss / 1024 / 1024),
+    },
+    circuits: {
+      inventory: inventoryCircuit.getStatus().state,
+      payment: paymentCircuit.getStatus().state,
+    },
+    bulkhead: {
+      active: bulkStatus.active,
+      queued: bulkStatus.queued,
+    },
+  });
+});
+
+/**
+ * GET /metrics
+ * Prometheus-compatible plain-text output
+ */
+fastify.get("/metrics", async (_request, reply) => {
+  const invState = inventoryCircuit.getStatus().state;
+  const payState = paymentCircuit.getStatus().state;
+  const bk = ordersBulkhead.getStatus();
+
+  return reply.header("Content-Type", "text/plain; version=0.0.4").send(
+    [
+      `# HELP immortal_circuit_state Circuit breaker state (1=CLOSED 2=HALF_OPEN 3=OPEN)`,
+      `immortal_circuit_state{name="inventory"} ${stateToNum(invState)}`,
+      `immortal_circuit_state{name="payment"} ${stateToNum(payState)}`,
+      `# HELP immortal_bulkhead_active Active tasks in bulkhead pool`,
+      `immortal_bulkhead_active{pool="orders"} ${bk.active}`,
+      `# HELP immortal_bulkhead_queued Queued tasks in bulkhead pool`,
+      `immortal_bulkhead_queued{pool="orders"} ${bk.queued}`,
+      `# HELP process_uptime_seconds Node.js process uptime`,
+      `process_uptime_seconds ${Math.round(process.uptime())}`,
+    ].join("\n")
+  );
+});
+
+function stateToNum(state: string): number {
+  if (state === "CLOSED") return 1;
+  if (state === "HALF_OPEN") return 2;
+  return 3; // OPEN
+}
+
+/**
+ * GET /chaos/trip-inventory
+ * Force the inventory circuit breaker OPEN (dev/test only)
+ */
+fastify.get("/chaos/trip-inventory", async (_request, reply) => {
+  if (process.env["NODE_ENV"] === "production") {
+    return reply.status(403).send({ error: "Chaos endpoints disabled in production" });
+  }
+  inventoryCircuit.forceState("OPEN");
+  return reply.send({
+    message: "Inventory circuit forced OPEN",
+    state: inventoryCircuit.getStatus().state,
+  });
+});
+
+/**
+ * GET /chaos/reset-circuits
+ * Reset all circuits to CLOSED
+ */
+fastify.get("/chaos/reset-circuits", async (_request, reply) => {
+  if (process.env["NODE_ENV"] === "production") {
+    return reply.status(403).send({ error: "Chaos endpoints disabled in production" });
+  }
+  inventoryCircuit.forceState("CLOSED");
+  paymentCircuit.forceState("CLOSED");
+  return reply.send({
+    message: "All circuits reset to CLOSED",
+    inventory: inventoryCircuit.getStatus().state,
+    payment: paymentCircuit.getStatus().state,
+  });
+});
+
+// ─── Graceful Shutdown ────────────────────────────────────────────────────────
+// GracefulShutdown(config, bus) — 2 args required
+
+const bus = getEventBus();
+const shutdown = new GracefulShutdown(
+  {
+    timeoutMs: 20_000,
+    signals: ["SIGTERM", "SIGINT"],
+    onShutdown: [
+      async (_signal: string) => {
+        fastify.log.info("Draining bulkhead queue…");
+        ordersBulkhead.drain();
+      },
+      async (_signal: string) => {
+        fastify.log.info("Closing Fastify server…");
+        await fastify.close();
+      },
+    ],
+  },
+  bus
+);
+
+// Keep reference alive (signal handlers installed in constructor)
+void shutdown;
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const PORT = parseInt(process.env["PORT"] ?? "3000", 10);
+
+try {
+  await fastify.listen({ port: PORT, host: "0.0.0.0" });
+
+  // Banner after successful listen
+  console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║          Immortal.js — Fastify Microservice  🚀              ║
+╠══════════════════════════════════════════════════════════════╣
+║  Server   →  http://localhost:${PORT}                          ║
+║  Health   →  http://localhost:${PORT}/health                   ║
+║  Metrics  →  http://localhost:${PORT}/metrics                  ║
+╠══════════════════════════════════════════════════════════════╣
+║  Routes                                                       ║
+║  GET  /products/:id        Circuit Breaker + Cache            ║
+║  POST /orders              Bulkhead + Retry + Circuit         ║
+║  GET  /health              Live health snapshot               ║
+║  GET  /metrics             Prometheus-compatible metrics      ║
+║  GET  /chaos/trip-inventory   Force circuit OPEN (dev)        ║
+║  GET  /chaos/reset-circuits   Reset all circuits (dev)        ║
+╚══════════════════════════════════════════════════════════════╝
+`);
+} catch (err) {
+  fastify.log.error(err);
+  process.exit(1);
+}

package/examples/fastify-microservice/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "immortal-fastify-microservice-example",
+  "version": "1.0.0",
+  "description": "Immortal.js — Fastify microservice example with full resilience patterns",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --import tsx/esm --no-warnings index.ts",
+    "start": "node dist/index.js",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@immortal/core": "*",
+    "fastify": "^4.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "pino-pretty": "^11.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}

package/examples/fastify-microservice/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"]
+}

package/examples/invoice-service/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "immortal-invoice-service",
+  "version": "3.0.0",
+  "description": "Immortal.js — Ultra Pro Invoice PDF Generator with SQLite, Light/Dark theme, Lucide icons",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --import tsx/esm --no-warnings src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@fastify/static": "^7.0.4",
+    "@immortal/core": "*",
+    "better-sqlite3": "^13.0.1",
+    "fastify": "^4.28.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}