distributed-systems

Distributed Systems Patterns

Core Principle

In a distributed system, you cannot have both strong consistency and high availability during a network partition (CAP theorem). Design for eventual consistency where possible, and use patterns that make the system correct even when components fail independently.

---

1. Idempotency

What it does: Ensures that performing the same operation multiple times produces the same result as performing it once. This is essential because in distributed systems, messages can be delivered more than once.

When to apply: Every mutation endpoint in your API. Every message consumer. Every payment or state-changing operation.

Idempotency Key Pattern for APIs

The client generates a unique key and sends it with the request. The server stores the result keyed by this value and returns the stored result on duplicate requests.

// Client sends: POST /v1/charges
// Header: Idempotency-Key: idem_a1b2c3d4

async function handleChargeRequest(req: Request): Promise<Response> {
  const idempotencyKey = req.headers['idempotency-key'];
  if (!idempotencyKey) {
    return errorResponse(400, 'Idempotency-Key header is required');
  }

  // Check if we already processed this key
  const existing = await idempotencyStore.get(idempotencyKey);
  if (existing) {
    if (existing.status === 'processing') {
      return errorResponse(409, 'Request is already being processed');
    }
    return existing.response; // Return the stored response
  }

  // Lock the key to prevent concurrent processing
  await idempotencyStore.set(idempotencyKey, { status: 'processing' });

  try {
    const result = await processCharge(req.body);
    const response = successResponse(201, result);
    await idempotencyStore.set(idempotencyKey, {
      status: 'completed',
      response,
      expiresAt: Date.now() + 24 * 60 * 60 * 1000, // 24h TTL
    });
    return response;
  } catch (error) {
    await idempotencyStore.delete(idempotencyKey); // Allow retry on failure
    throw error;
  }
}