Architecture, Patterns & Databases

// A request that synchronously needs every service in the chain to succeed.
const availability = 0.999; // each service: "three nines"
for (const services of [1, 3, 5, 10]) {
  const overall = availability ** services;
  const failedPerMillion = Math.round((1 - overall) * 1_000_000);
  console.log(`${String(services).padStart(2)} services: ${(overall * 100).toFixed(2)}% available, ~${failedPerMillion} failed requests per million`);
}

// Tail latency: if each service is slow (> its p99) 1% of the time,
// how often is at least one hop in the chain slow?
for (const hops of [1, 5, 10]) {
  console.log(`${String(hops).padStart(2)} hops: ${((1 - 0.99 ** hops) * 100).toFixed(1)}% of requests hit at least one p99-slow hop`);
}

//  1 services: 99.90% available, ~1000 failed requests per million
//  3 services: 99.70% available, ~2997 failed requests per million
//  5 services: 99.50% available, ~4990 failed requests per million
// 10 services: 99.00% available, ~9955 failed requests per million
//  1 hops: 1.0% of requests hit at least one p99-slow hop
//  5 hops: 4.9% of requests hit at least one p99-slow hop
// 10 hops: 9.6% of requests hit at least one p99-slow hop

import http from "node:http";
import { randomUUID } from "node:crypto";

// Two tiny "services". Each only knows its own routes.
function startService(name, handler) {
  const server = http.createServer(handler);
  return new Promise((resolve) => server.listen(0, () => resolve({ server, url: `http://localhost:${server.address().port}`, name })));
}
const users = await startService("users", (req, res) => {
  res.setHeader("content-type", "application/json");
  res.end(JSON.stringify({ service: "users", path: req.url, requestId: req.headers["x-request-id"], caller: req.headers["x-user-id"] }));
});
const orders = await startService("orders", (req, res) => {
  setTimeout(() => res.end("too late"), 2_000).unref(); // a hung dependency
});

const routes = { "/users": users.url, "/orders": orders.url };

const gateway = http.createServer(async (req, res) => {
  const requestId = req.headers["x-request-id"] ?? randomUUID();
  res.setHeader("x-request-id", requestId);

  // 1. Authenticate once, at the edge.
  if (req.headers.authorization !== "Bearer valid-token") return res.writeHead(401).end("missing or bad token\n");

  // 2. Route by path prefix.
  const prefix = Object.keys(routes).find((p) => req.url === p || req.url.startsWith(p + "/"));
  if (!prefix) return res.writeHead(404).end("no such route\n");

  // 3. Forward with a deadline and the context downstream services need.
  try {
    const upstream = await fetch(routes[prefix] + req.url.slice(prefix.length), {
      method: req.method,
      headers: { "x-request-id": requestId, "x-user-id": "u-42" },
      signal: AbortSignal.timeout(500),
    });
    res.writeHead(upstream.status, { "content-type": upstream.headers.get("content-type") ?? "text/plain" });
    res.end(await upstream.text());
  } catch (err) {
    res.writeHead(err.name === "TimeoutError" ? 504 : 502).end(`${prefix} unavailable: ${err.name}\n`);
  }
});
await new Promise((r) => gateway.listen(0, r));
const base = `http://localhost:${gateway.address().port}`;

const show = async (path, headers = {}) => {
  const res = await fetch(base + path, { headers });
  console.log(`${path.padEnd(10)} -> ${res.status} ${(await res.text()).trim()}`);
};
const auth = { authorization: "Bearer valid-token" };
await show("/users/7");
await show("/users/7", { ...auth, "x-request-id": "req-abc" });
await show("/orders/1", auth);
await show("/billing", auth);

for (const s of [gateway, users.server, orders.server]) s.closeAllConnections(), s.close();

// /users/7   -> 401 missing or bad token
// /users/7   -> 200 {"service":"users","path":"/7","requestId":"req-abc","caller":"u-42"}
// /orders/1  -> 504 /orders unavailable: TimeoutError
// /billing   -> 404 no such route

import { setTimeout as sleep } from "node:timers/promises";

let emailUp = false; // the email service is down right now
const inventory = { reserve: async () => sleep(50) };
const email = {
  send: async (to) => {
    await sleep(200);
    if (!emailUp) throw new Error("email service unavailable");
  },
};

// Synchronous style: the order waits for every downstream call.
async function placeOrderSync(order) {
  await inventory.reserve(order);
  await email.send(order.email);
  return "confirmed";
}

// Asynchronous style: wait only for what the answer depends on; publish the rest.
const queue = [];
async function placeOrderAsync(order) {
  await inventory.reserve(order);
  queue.push({ type: "OrderPlaced", email: order.email, attempts: 0 });
  return "confirmed";
}
async function emailWorker() {
  while (queue.length) {
    const msg = queue.shift();
    try {
      await email.send(msg.email);
      console.log(`  worker: email sent on attempt ${msg.attempts + 1}`);
    } catch {
      msg.attempts++;
      queue.push(msg); // a real broker would redeliver with a delay
      emailUp = msg.attempts >= 2; // the service recovers after a while
    }
  }
}

async function time(label, fn) {
  const t = performance.now();
  try {
    console.log(`${label}: ${await fn()} in ${Math.round(performance.now() - t)} ms`);
  } catch (err) {
    console.log(`${label}: FAILED (${err.message}) in ${Math.round(performance.now() - t)} ms`);
  }
}

const order = { id: 1, email: "rohit@example.com" };
await time("sync ", () => placeOrderSync(order));
await time("async", () => placeOrderAsync(order));
await emailWorker();

// sync : FAILED (email service unavailable) in 252 ms
// async: confirmed in 51 ms
//   worker: email sent on attempt 3

// message ReserveRequest { string sku = 1; int32 qty = 2; int64 order_id = 3; }
function varint(n) {
  const bytes = [];
  while (n > 127) {
    bytes.push((n & 0x7f) | 0x80); // low 7 bits, "more bytes follow" flag
    n = Math.floor(n / 128);
  }
  bytes.push(n);
  return bytes;
}
const tag = (field, wireType) => varint((field << 3) | wireType);

function encodeReserveRequest({ sku, qty, orderId }) {
  const skuBytes = [...Buffer.from(sku, "utf8")];
  return Buffer.from([
    ...tag(1, 2), ...varint(skuBytes.length), ...skuBytes, // field 1, length-delimited
    ...tag(2, 0), ...varint(qty), // field 2, varint
    ...tag(3, 0), ...varint(orderId), // field 3, varint
  ]);
}

const msg = { sku: "SKU-1", qty: 150, orderId: 1234567 };
const proto = encodeReserveRequest(msg);
const json = Buffer.from(JSON.stringify(msg));
console.log("protobuf:", proto.length, "bytes", proto.toString("hex").match(/../g).join(" "));
console.log("JSON:    ", json.length, "bytes", json.toString());

// protobuf: 14 bytes 0a 05 53 4b 55 2d 31 10 96 01 18 87 ad 4b
// JSON:     43 bytes {"sku":"SKU-1","qty":150,"orderId":1234567}

// Queue (RabbitMQ/SQS model): each message goes to ONE consumer, then it's gone.
class WorkQueue {
  messages = [];
  consumers = [];
  next = 0;
  publish(m) {
    this.messages.push(m);
  }
  dispatch() {
    while (this.messages.length) {
      const m = this.messages.shift(); // removed once acked
      const consumer = this.consumers[this.next++ % this.consumers.length]; // round robin
      consumer(m);
    }
  }
}

// Log (Kafka model): messages are appended and kept; each group tracks its own offset.
class Log {
  entries = [];
  offsets = new Map(); // groupId -> next offset to read
  append(m) {
    this.entries.push(m);
  }
  poll(groupId) {
    const from = this.offsets.get(groupId) ?? 0;
    const batch = this.entries.slice(from);
    this.offsets.set(groupId, this.entries.length); // "commit" the offset
    return batch;
  }
  seek(groupId, offset) {
    this.offsets.set(groupId, offset);
  }
}

const q = new WorkQueue();
q.consumers.push((m) => console.log(`  worker-1 resized ${m}`), (m) => console.log(`  worker-2 resized ${m}`));
["img-1", "img-2", "img-3"].forEach((m) => q.publish(m));
console.log("queue:");
q.dispatch();
console.log("  left in queue:", q.messages.length);

const log = new Log();
["order-1", "order-2", "order-3"].forEach((m) => log.append(m));
console.log("log:");
console.log("  analytics reads:", log.poll("analytics"));
console.log("  warehouse reads:", log.poll("warehouse"));
log.append("order-4");
console.log("  analytics reads:", log.poll("analytics"));
log.seek("analytics", 0); // replay after fixing a bug
console.log("  analytics replays:", log.poll("analytics"));
console.log("  entries kept:", log.entries.length);

// queue:
//   worker-1 resized img-1
//   worker-2 resized img-2
//   worker-1 resized img-3
//   left in queue: 0
// log:
//   analytics reads: [ 'order-1', 'order-2', 'order-3' ]
//   warehouse reads: [ 'order-1', 'order-2', 'order-3' ]
//   analytics reads: [ 'order-4' ]
//   analytics replays: [ 'order-1', 'order-2', 'order-3', 'order-4' ]
//   entries kept: 4

// A tiny at-least-once broker: a message stays until it's acked; a crash means redelivery.
function deliverAtLeastOnce(messages, handler) {
  const queue = [...messages];
  while (queue.length) {
    const msg = queue[0];
    try {
      handler(msg);
      queue.shift(); // ack
    } catch (err) {
      console.log(`  consumer crashed (${err.message}) before ack -> ${msg.id} redelivered`);
    }
  }
}

let crashOnce = true;
function crashBeforeAck() {
  if (crashOnce) {
    crashOnce = false;
    throw new Error("pod killed");
  }
}

const events = [
  { id: "evt-1", type: "ChargeCustomer", orderId: 123, amount: 50 },
  { id: "evt-2", type: "ChargeCustomer", orderId: 124, amount: 20 },
];

console.log("naive consumer:");
const naiveCharges = [];
deliverAtLeastOnce(events, (msg) => {
  naiveCharges.push(msg.orderId); // the side effect
  crashBeforeAck();
});
console.log("  charges:", naiveCharges);

console.log("idempotent consumer:");
crashOnce = true;
const processed = new Set(); // in real life: a table with a UNIQUE key
const charges = [];
deliverAtLeastOnce(events, (msg) => {
  if (processed.has(msg.id)) {
    console.log(`  ${msg.id} already processed -> ack and skip`);
    return;
  }
  charges.push(msg.orderId);
  processed.add(msg.id);
  crashBeforeAck();
});
console.log("  charges:", charges);

// naive consumer:
//   consumer crashed (pod killed) before ack -> evt-1 redelivered
//   charges: [ 123, 123, 124 ]
// idempotent consumer:
//   consumer crashed (pod killed) before ack -> evt-1 redelivered
//   evt-1 already processed -> ack and skip
//   charges: [ 123, 124 ]

import { setTimeout as sleep } from "node:timers/promises";

// Full jitter: wait a random amount between 0 and the exponential cap.
export async function retry(fn, { retries = 3, baseMs = 100, maxMs = 2_000, signal, random = Math.random, shouldRetry = isTransient, onRetry } = {}) {
  for (let attempt = 0; ; attempt++) {
    signal?.throwIfAborted();
    try {
      return await fn({ attempt, signal });
    } catch (err) {
      if (attempt >= retries || !shouldRetry(err)) throw err;
      const cap = Math.min(maxMs, baseMs * 2 ** attempt);
      const delay = Math.round(random() * cap);
      onRetry?.({ attempt: attempt + 1, err, cap, delay });
      await sleep(delay, undefined, { signal });
    }
  }
}

function isTransient(err) {
  if (["ECONNRESET", "ETIMEDOUT", "ECONNREFUSED"].includes(err.code)) return true;
  return err.status === 429 || err.status === 503 || err.status === 502;
}

export class CircuitOpenError extends Error {
  name = "CircuitOpenError";
}

export class CircuitBreaker {
  #state = "CLOSED";
  #failures = 0;
  #openedAt = 0;
  #probing = false;

  constructor(fn, { failureThreshold = 3, resetMs = 10_000, timeoutMs = 1_000, now = Date.now } = {}) {
    Object.assign(this, { fn, failureThreshold, resetMs, timeoutMs, now });
  }

  get state() {
    return this.#state;
  }

  async call(...args) {
    if (this.#state === "OPEN") {
      if (this.now() - this.#openedAt < this.resetMs) throw new CircuitOpenError("circuit open: failing fast");
      this.#state = "HALF_OPEN"; // the cool-down is over: let one probe through
    }
    if (this.#state === "HALF_OPEN") {
      if (this.#probing) throw new CircuitOpenError("circuit half-open: probe in flight");
      this.#probing = true;
    }
    try {
      const result = await this.fn(...args, AbortSignal.timeout(this.timeoutMs));
      this.#onSuccess();
      return result;
    } catch (err) {
      this.#onFailure();
      throw err;
    } finally {
      this.#probing = false;
    }
  }

  #onSuccess() {
    this.#failures = 0;
    this.#state = "CLOSED";
  }

  #onFailure() {
    this.#failures++;
    if (this.#state === "HALF_OPEN" || this.#failures >= this.failureThreshold) {
      this.#state = "OPEN";
      this.#openedAt = this.now();
    }
  }
}

// Each "service" owns its own data. No transaction spans them.
const orders = new Map();
const stock = { "sku-1": 5 };
const reservations = new Map();

const orderService = {
  create: async (o) => orders.set(o.id, { ...o, status: "PENDING" }),
  approve: async (id) => (orders.get(id).status = "APPROVED"),
  reject: async (id) => (orders.get(id).status = "REJECTED"),
};
const inventoryService = {
  reserve: async (o) => {
    if (stock[o.sku] < o.qty) throw new Error("out of stock");
    stock[o.sku] -= o.qty;
    reservations.set(o.id, o.qty);
  },
  release: async (o) => {
    stock[o.sku] += reservations.get(o.id) ?? 0;
    reservations.delete(o.id);
  },
};
const paymentService = {
  charge: async (o) => {
    if (o.card === "declined") throw new Error("card declined");
  },
};

async function placeOrderSaga(order) {
  const steps = [
    { name: "create order", run: () => orderService.create(order), undo: () => orderService.reject(order.id) },
    { name: "reserve stock", run: () => inventoryService.reserve(order), undo: () => inventoryService.release(order) },
    { name: "charge card", run: () => paymentService.charge(order), undo: null },
    { name: "approve order", run: () => orderService.approve(order.id), undo: null },
  ];
  const done = [];
  for (const step of steps) {
    try {
      await step.run();
      done.push(step);
      console.log(`  ✓ ${step.name}`);
    } catch (err) {
      console.log(`  ✗ ${step.name}: ${err.message} — compensating`);
      for (const prev of done.reverse()) {
        if (prev.undo) {
          await prev.undo();
          console.log(`  ↩ undo ${prev.name}`);
        }
      }
      return "FAILED";
    }
  }
  return "OK";
}

for (const order of [
  { id: "A", sku: "sku-1", qty: 2, card: "ok" },
  { id: "B", sku: "sku-1", qty: 2, card: "declined" },
]) {
  console.log(`order ${order.id}:`);
  console.log(`  => ${await placeOrderSaga(order)}`);
}
console.log({ orders: Object.fromEntries([...orders].map(([id, o]) => [id, o.status])), stock });

// order A:
//   ✓ create order
//   ✓ reserve stock
//   ✓ charge card
//   ✓ approve order
//   => OK
// order B:
//   ✓ create order
//   ✓ reserve stock
//   ✗ charge card: card declined — compensating
//   ↩ undo reserve stock
//   ↩ undo create order
//   => FAILED
// { orders: { A: 'APPROVED', B: 'REJECTED' }, stock: { 'sku-1': 3 } }

# 1. A private CA that both services trust
openssl req -x509 -newkey rsa:2048 -nodes -days 1 -subj "/CN=demo-internal-ca" \
  -keyout ca.key -out ca.crt
# 2. The server's certificate, signed by the CA (SAN must match the host the client dials)
openssl req -newkey rsa:2048 -nodes -subj "/CN=inventory" -keyout server.key -out server.csr
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -days 1 -out server.crt \
  -extfile <(printf "subjectAltName=DNS:localhost")
# 3. The client's certificate, signed by the same CA
openssl req -newkey rsa:2048 -nodes -subj "/CN=order-service" -keyout client.key -out client.csr
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -days 1 -out client.crt

import { DatabaseSync } from "node:sqlite";
import { randomUUID } from "node:crypto";

// Two implementations of the same shape: save(order) and findById(id).
function memoryOrderRepo() {
  const rows = new Map();
  return {
    save: async (order) => void rows.set(order.id, structuredClone(order)),
    findById: async (id) => rows.get(id) ?? null,
  };
}

function sqliteOrderRepo(db) {
  db.exec("CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY, body TEXT NOT NULL)");
  const insert = db.prepare("INSERT INTO orders (id, body) VALUES (?, ?)");
  const select = db.prepare("SELECT body FROM orders WHERE id = ?");
  return {
    save: async (order) => void insert.run(order.id, JSON.stringify(order)),
    findById: async (id) => {
      const row = select.get(id);
      return row ? JSON.parse(row.body) : null;
    },
  };
}

// Factory: configuration picks the implementation, once, at start-up.
export function createOrderRepo(env) {
  switch (env.ORDER_STORE) {
    case "sqlite":
      return sqliteOrderRepo(new DatabaseSync(env.SQLITE_PATH ?? ":memory:"));
    case "memory":
      return memoryOrderRepo();
    default:
      throw new Error(`ORDER_STORE must be "sqlite" or "memory", got ${JSON.stringify(env.ORDER_STORE)}`);
  }
}

// The business logic receives everything it depends on.
export function createOrderService({ repo, clock, newId }) {
  return {
    async place(customerId, items) {
      if (items.length === 0) throw new Error("an order needs at least one item");
      const order = { id: newId(), customerId, items, placedAt: clock().toISOString() };
      await repo.save(order);
      return order;
    },
    get: (id) => repo.findById(id),
  };
}

// Composition root: the only place that reads env and picks real implementations.
export function buildApp(env = process.env) {
  const repo = createOrderRepo(env);
  return { orders: createOrderService({ repo, clock: () => new Date(), newId: randomUUID }) };
}

if (import.meta.main) {
  const app = buildApp();
  const order = await app.orders.place("c-1", [{ sku: "SKU-1", qty: 2 }]);
  console.log("stored via", process.env.ORDER_STORE, "->", await app.orders.get(order.id));
}

// $ ORDER_STORE=sqlite node orders.mjs
// stored via sqlite -> { id: 'dea200e0-…', customerId: 'c-1', items: [ { sku: 'SKU-1', qty: 2 } ], placedAt: '2026-10-07T18:52:33.674Z' }
// $ node orders.mjs
// Error: ORDER_STORE must be "sqlite" or "memory", got undefined

import { DatabaseSync } from "node:sqlite";

const db = new DatabaseSync(":memory:");
db.exec(`
  CREATE TABLE customers (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
  CREATE TABLE products  (sku TEXT PRIMARY KEY, title TEXT NOT NULL);
  CREATE TABLE orders    (id INTEGER PRIMARY KEY, customer_id INTEGER NOT NULL REFERENCES customers(id));
  CREATE TABLE order_items (
    order_id INTEGER REFERENCES orders(id), sku TEXT REFERENCES products(sku),
    qty INTEGER NOT NULL, unit_price INTEGER NOT NULL
  );
  INSERT INTO customers VALUES (1, 'Rohit'), (2, 'Neha');
  INSERT INTO products VALUES ('SKU-1', 'Keyboard'), ('SKU-2', 'Mouse');
  INSERT INTO orders VALUES (10, 1), (11, 2), (12, 1);
  INSERT INTO order_items VALUES (10, 'SKU-1', 1, 4000), (10, 'SKU-2', 2, 1500), (11, 'SKU-2', 1, 1500), (12, 'SKU-2', 3, 1400);
`);

// A question nobody planned for when designing the schema: revenue per product per customer.
console.log(db.prepare(`
  SELECT c.name, p.title, SUM(i.qty * i.unit_price) AS revenue
  FROM order_items i
  JOIN orders o    ON o.id = i.order_id
  JOIN customers c ON c.id = o.customer_id
  JOIN products p  ON p.sku = i.sku
  GROUP BY c.name, p.title
  ORDER BY revenue DESC
`).all().map((r) => ({ ...r })));

// [
//   { name: 'Rohit', title: 'Mouse', revenue: 7200 },
//   { name: 'Rohit', title: 'Keyboard', revenue: 4000 },
//   { name: 'Neha', title: 'Mouse', revenue: 1500 }
// ]

import { DatabaseSync } from "node:sqlite";

const db = new DatabaseSync(":memory:");
db.exec(`
  CREATE TABLE accounts (
    name    TEXT PRIMARY KEY,
    balance INTEGER NOT NULL CHECK (balance >= 0)
  );
  INSERT INTO accounts VALUES ('alice', 100), ('bob', 0);
`);

const debit = db.prepare("UPDATE accounts SET balance = balance - ? WHERE name = ?");
const credit = db.prepare("UPDATE accounts SET balance = balance + ? WHERE name = ?");
const balances = () => db.prepare("SELECT name, balance FROM accounts ORDER BY name").all().map((r) => `${r.name}=${r.balance}`).join(" ");

function transfer(from, to, amount, { crashAfterCredit = false } = {}) {
  db.exec("BEGIN");
  try {
    credit.run(amount, to);
    if (crashAfterCredit) throw new Error("process died mid-transfer");
    debit.run(amount, from); // CHECK fails if this would go negative
    db.exec("COMMIT");
    console.log(`transfer ${amount}: committed   -> ${balances()}`);
  } catch (err) {
    console.log(`  inside the transaction before rollback: ${balances()}`);
    db.exec("ROLLBACK");
    console.log(`transfer ${amount}: rolled back (${err.message}) -> ${balances()}`);
  }
}

console.log("start:", balances());
transfer("alice", "bob", 30);
transfer("alice", "bob", 500);
transfer("alice", "bob", 10, { crashAfterCredit: true });

// start: alice=100 bob=0
// transfer 30: committed   -> alice=70 bob=30
//   inside the transaction before rollback: alice=70 bob=530
// transfer 500: rolled back (CHECK constraint failed: balance >= 0) -> alice=70 bob=30
//   inside the transaction before rollback: alice=70 bob=40
// transfer 10: rolled back (process died mid-transfer) -> alice=70 bob=30