11
Datos y sistemas distribuidos

Sharding, cache y escalabilidad

Datos y sistemas distribuidos

Semana 11 — Sharding, cache y escalabilidad

Objetivos

  • Explicar cuándo hace falta sharding y comparar el sharding por rango y por hash, con sus efectos sobre las consultas, el rebalanceo y los hot spots.
  • Describir cómo llega una petición al shard correcto y qué se pierde al partir los datos (consultas y transacciones entre shards, índices secundarios).
  • Diseñar una cache con el patrón cache-aside: qué se guarda, con qué clave, cuánto dura y cómo se invalida.
  • Reconocer y evitar los modos de falla de una cache (datos viejos, estampida, dependencia de una cache caliente), y explicar por qué los servicios sin estado escalan hacia los lados.

Sesión A — Sharding: por rango, por hash, rebalanceo y hot spots

Lecturas:

  • Kleppmann y Riccomini, Designing Data-Intensive Applications (2.ª ed.), cap. 7 Sharding.
  • Lectura libre: Azure Architecture Center, Sharding pattern.

Lecturas complementarias:

Temas:

  • Replicar copia los mismos datos en varias máquinas; hacer sharding reparte datos distintos entre máquinas. Se combinan: cada shard tiene sus réplicas. La segunda edición del libro llama sharding a lo que la primera llamaba partitioning.
  • Cuándo hace falta: cuando los datos o las escrituras ya no caben en una máquina. Las lecturas se resuelven antes con réplicas y cache. El sharding es la táctica de escalabilidad más cara: complica las consultas, las transacciones y la operación, y casi no tiene vuelta atrás. Se agota primero lo demás (una máquina más grande, mejores índices, archivar lo viejo).
  • La clave de sharding decide todo: qué consultas tocan un solo shard y cuáles tienen que preguntarles a todos. Se elige por el patrón de acceso dominante. En Tinkuy, por event_id: todo lo de un evento vive junto y una compra toca un shard. En un sistema con varios clientes, por cliente (tenant).
  • Por rango de clave: los datos quedan ordenados y las consultas por rango son eficientes; el riesgo es que las claves que crecen con el tiempo (una fecha, un id secuencial) manden todas las escrituras al último shard.
  • Por hash de la clave: reparte parejo y pierde el orden, así que una consulta por rango pregunta a todos. Variantes: hash sobre un número fijo de shards lógicos que se asignan a nodos; consistent hashing.
  • Hot spots: una clave que concentra la carga no se arregla con ninguna función de hash. El concierto que agota en un minuto es un hot spot por definición: todo el tráfico va a un event_id. Opciones: aislar esa clave en su propio shard, o partirla con un sufijo y pagar al leer.
  • Rebalanceo: mover datos cuando se agregan nodos. Lo que no se hace: hash(clave) mod n, porque cambiar n mueve casi todas las claves. Lo que sí: muchos más shards lógicos que nodos, y mover shards enteros. Automático o manual: uno automático que se dispara por un nodo lento puede empeorar una sobrecarga.
  • Enrutar la petición: quién sabe en qué nodo está cada shard. El cliente, una capa de enrutamiento o cualquier nodo que reenvía; en todos los casos hace falta un registro de la asignación en el que todos estén de acuerdo.
  • Lo que se pierde: los JOIN y las transacciones entre shards, las restricciones de unicidad globales, y los índices secundarios, que o son locales (cada consulta por ese índice pregunta a todos los shards) o son globales (cada escritura actualiza otro shard, de forma asíncrona).
  • Error común: hacer sharding por adelantado. Se elige la clave antes de conocer los patrones de acceso, y una clave equivocada cuesta más que no tener sharding.

Sesión B — Cache y escalabilidad: cache-aside, invalidación, estampida, servicios sin estado

Lecturas:

  • Lecturas libres: Azure Architecture Center, Cache-Aside pattern; Site Reliability Engineering, cap. 22, Addressing Cascading Failures, la parte sobre arranque lento y caches frías.
  • Software Architecture in Practice, cap. 9 Performance, las tácticas de mantener varias copias de los datos y del cómputo.

Lecturas complementarias:

Temas:

  • Una cache guarda el resultado de algo caro para no repetirlo. Es un dato derivado (semana 9): se puede perder y reconstruir. Lo que da: menos latencia y menos carga sobre el origen. Lo que abre: una segunda copia que puede estar desactualizada, y un componente más que puede fallar.
  • Dónde puede haber una cache: en el navegador y la CDN (cabeceras HTTP), en el proceso (rápida, una por instancia, se pierde al reiniciar) y en un servicio compartido como Redis (una para todas las instancias, a un salto de red).
  • Qué conviene guardar: lo que se lee mucho más de lo que cambia, es caro de calcular y tolera estar un poco viejo. En Tinkuy: la lista de eventos y sus precios, sí; el estado de un asiento en plena venta, con mucho cuidado; el saldo de un pago, no.
  • Cache-aside: la aplicación busca en la cache; si no está (un miss), lee del origen, lo guarda y responde. Al escribir, actualiza el origen y borra la entrada. Otras: read-through y write-through (la cache se encarga), write-behind (se escribe en la cache y al origen después; rápido y con riesgo de perder datos).
  • Invalidación, el problema difícil. Por tiempo (TTL): simple y acota cuán viejo puede estar el dato; se elige según cuánto retraso tolera el negocio. Por evento: borrar al escribir; exacto, y hay que acordarse en cada lugar donde se escribe. Lo habitual es usar los dos: borrar al escribir y un TTL como red de seguridad.
  • Por qué borrar y no actualizar: dos escrituras concurrentes que actualizan la cache pueden dejarla con el valor más viejo; borrarla hace que la próxima lectura traiga el vigente. Aun así queda una carrera: una lectura que trajo el valor viejo justo antes de la escritura y lo guarda justo después del borrado. El TTL la acota.
  • Estampida: una entrada muy pedida expira y cientos de peticiones van al origen a la vez a recalcular lo mismo. Remedios: que solo una recalcule y las demás esperen o reciban el valor viejo (un lock o un lease), expiración con jitter para que no venzan todas juntas, y recalcular antes de que venza.
  • Depender de la cache: si el origen solo aguanta la carga con la cache caliente, entonces la cache dejó de ser una optimización y es parte de la capacidad. Cuando se reinicia, el sistema se cae. Hay que saber qué pasa con la cache vacía y con la cache caída (semana 6: degradar).
  • Memoria finita: política de desalojo (LRU, LFU) y qué claves entran. Cache negativa: guardar también “no existe”, para que las preguntas por algo inexistente no lleguen siempre al origen.
  • Escalar hacia los lados: más copias del servicio detrás de un load balancer. Requisito: que el servicio no guarde estado propio entre peticiones (sesiones, archivos, cache local que deba ser exacta); el estado va a un almacén compartido. Cualquier instancia atiende cualquier petición y cualquiera se puede apagar.
  • Load balancer: reparte (por turnos, a la menos ocupada) y deja de enviar a las instancias que no pasan el health check. Qué responde un health check: que el proceso vive, o que además puede hacer su trabajo.
  • Error común: guardar en la cache sin decidir cómo se invalida. El resultado es un TTL elegido al azar y un usuario que ve datos viejos sin que nadie sepa por cuánto tiempo.
  • Error común: cache en el proceso con varias instancias. Cada una tiene su copia y el usuario ve un valor distinto según a cuál llegue.

Laboratorio — Cache-aside con Redis en Tinkuy y una estampida

Referencias: Cache-Aside pattern; documentación de Redis. Material: code/week-11/. En parejas, sobre su copia de Tinkuy.

  1. Línea de base: make load-browse contra Tinkuy, anotando p95 y throughput de GET /events y de GET /events/:id.
  2. Decidir antes de programar: qué respuestas van a la cache, con qué clave (prefijo w11:), con qué TTL y qué las invalida. Escribirlo en la tabla de code/week-11/.
  3. Implementar cache-aside para el detalle de un evento usando el módulo de la carpeta como punto de partida. Medir de nuevo. Mirar en Redis qué quedó: redis-cli --scan --pattern 'w11:*', TTL, y los contadores de aciertos y fallos (INFO stats).
  4. Datos viejos: comprar una entrada y pedir el detalle del evento. ¿Cuántos asientos disponibles muestra? Agregar la invalidación al vender y repetir.
  5. La carrera: el script race.ts de la carpeta, sobre su propio servicio de ejemplo, deja elegir el orden de cinco pasos (los de una lectura lenta y los de una escritura con su invalidación). Encontrar el orden que deja la cache con un valor viejo a pesar de la invalidación, explicar por qué y qué lo acota. ¿Dónde podría pasar lo mismo en su Tinkuy?
  6. Estampida: poner un TTL de dos segundos a la lista de eventos y correr make load-browse. Contar con el script de la carpeta cuántas veces llega a PostgreSQL la consulta de la lista en el instante en que la entrada expira (el script filtra por un fragmento del texto de la consulta: elijan uno que solo tenga la de la lista).
  7. Remedio: que una sola petición recalcule (un lock con SET NX PX) mientras las demás reciben el valor anterior. Repetir la medición y comparar el número de consultas.
  8. Cache caída: en la semana 6 ya hicieron que una cache caída degrade a la base de datos en vez de dar error. Ahora la pregunta es de capacidad: svc kill redis con la carga corriendo. ¿PostgreSQL aguanta la carga completa? ¿Cuánto sube la latencia? Anotar qué significa eso para la capacidad del sistema y qué pasaría con el doble de usuarios.
  9. Sharding en papel: para la tabla seats con event_id como clave, sobre ocho shards, calcular con el script de la carpeta cómo se reparten los eventos de los datos de ejemplo por hash y por rango. ¿Qué pasa con el evento 1? ¿Qué consultas de Tinkuy tocarían más de un shard?

Entregas

Preguntas de repaso

  1. ¿Qué problema resuelve la replicación que el sharding no resuelve, y al revés?
  2. Una tabla de eventos de auditoría usa la fecha como clave de sharding por rango. ¿Qué pasa con las escrituras? Propongan otra clave y digan qué consulta se vuelve cara.
  3. ¿Por qué hash(clave) mod n es una mala forma de asignar claves a nodos cuando n cambia?
  4. En cache-aside, ¿por qué al escribir se borra la entrada en vez de actualizarla?
  5. Describan una estampida y dos formas de evitarla.
  6. Un sistema responde bien con la cache caliente y se cae cuando Redis se reinicia. ¿Qué error de diseño hay y cómo se detecta antes de producción?

Código de la semana

Compilar y probar dentro del contenedor del curso con make y make test.

Ejemplos (26)Errores (1)Pruebas (8)Laboratorio (1)Compilación (3)

Ejemplos

Los programas que usan los apuntes y la clase.

cache-decisions-template.mdDescargar cache-decisions-template.md
# Decisiones de cache

Una fila por cada respuesta que el sistema da. Se llena **antes** de programar:
si una celda no se puede llenar, esa respuesta todavía no puede ir a la cache.

| Respuesta | ¿Va a la cache? ¿Por qué? | Clave | TTL | Qué la invalida | Cuán vieja puede llegar a estar y quién lo nota | Con la cache vacía o caída |
|---|---|---|---|---|---|---|
| | | | | | | |
| | | | | | | |
| | | | | | | |

Cómo llenar cada columna:

- **Respuesta.** El endpoint o la consulta, con sus parámetros: `GET /products/:id`.
- **¿Va a la cache? ¿Por qué?** Sí o no, con el dato que lo justifica: cuántas
  veces se lee por cada vez que cambia, cuánto cuesta calcularla (medido) y si
  tolera estar vieja. "No" también es una decisión, y se escribe.
- **Clave.** Con el prefijo y con todo lo que hace que dos respuestas sean
  distintas (el id, los filtros). Si dos pedidos distintos producen la misma
  clave, uno de los dos va a recibir la respuesta del otro.
- **TTL.** Un número con su unidad, y de dónde sale: cuánto retraso tolera el
  negocio para ese dato, no "lo que se suele poner".
- **Qué la invalida.** Cada escritura que cambia esa respuesta, con el lugar
  del código donde ocurre. Si la lista es larga o no se puede completar, el
  TTL es la única garantía y tiene que ser corto.
- **Cuán vieja puede llegar a estar y quién lo nota.** El peor caso: si falla
  una invalidación, el dato viejo dura hasta que vence el TTL. Digan qué ve el
  usuario mientras tanto y si eso es aceptable.
- **Con la cache vacía o caída.** Qué pasa con la latencia y con la carga del
  origen justo después de reiniciar Redis, y mientras Redis no responde.
  ¿El origen aguanta? Con un número medido.

## Ejemplo: Qhatu

| Respuesta | ¿Va a la cache? ¿Por qué? | Clave | TTL | Qué la invalida | Cuán vieja puede llegar a estar y quién lo nota | Con la cache vacía o caída |
|---|---|---|---|---|---|---|
| `GET /products` | Sí. Es lo más pedido y lo más caro: suma todos los movimientos de stock | `w11:products` | 5 s | Una venta o un cambio de precio de cualquier producto (`sell` y `setPrice` en `src/service.ts`) | 5 s si se pierde una invalidación: alguien ve un stock que ya bajó. La venta misma no usa la cache, así que no se vende de más | Vacía: un solo recálculo si se usa single-flight. Caída: cada pedido va a PostgreSQL |
| `GET /products/:id` | Sí. Diez productos concentran la mayoría de las visitas | `w11:product:<id>` | 30 s ± 10 % | Una venta o un cambio de precio de ese producto | 30 s: un precio o un stock viejo en pantalla | Igual que la lista, repartido entre muchas claves |
| `GET /products/:id` de un id que no existe | Sí, como "no existe" | `w11:product:<id>` | 5 s | Nada (hoy no se crean productos); si se crearan, crear uno tendría que borrarla | 5 s: un producto recién creado aparece como inexistente | Cada pregunta llega a PostgreSQL |
| `POST /products/:id/sales` | No. Es una escritura y decide con el stock real | — | — | — | — | No depende de la cache |
race.tsDescargar race.ts
// La carrera entre una lectura y una escritura en cache-aside, paso a paso.
//
// Dos actores trabajan sobre el producto 1. El lector hace un cache-aside en
// tres pasos; el escritor cambia el precio en dos:
//
//   L1  el lector busca en la cache               E1  el escritor cambia el precio en PostgreSQL
//   L2  el lector lee el precio de PostgreSQL     E2  el escritor borra la entrada de la cache
//   L3  el lector guarda en la cache lo que leyó
//
// El orden lo deciden ustedes: los pasos se ejecutan uno por uno, en el orden
// en que se escriben. No hay esperas ni azar, así que el resultado se repite.
//
//   node race.ts L1 L2 L3 E1 E2            primero el lector, después el escritor
//   node race.ts --lease L1 L2 E1 E2 L3    lo mismo, con un lease al estilo de Memcache
//   node race.ts --writers A1 B1 B2 A2     dos escritores (A pone 470 y B pone 499)
//   node race.ts --writers --update A1 B1 B2 A2   ...que actualizan la cache en vez de borrarla
//
// Al final dice qué precio hay en PostgreSQL, cuál quedó en la cache y cuánto
// le queda de vida a la entrada.

import { parseArgs } from 'node:util';
import { closeCache, connectCache, type Cache } from './src/cache.ts';
import { changePrice, readProduct } from './src/catalog.ts';
import { closeDb, connectDb, type Db } from './src/db.ts';

export const PRODUCT_ID = 1;
export const OLD_PRICE = 455;
export const NEW_PRICE = 499;
const PRICE_A = 470;
const PRICE_B = 499;

export type RaceOptions = {
  /** El orden de los pasos, por ejemplo ['L1', 'L2', 'E1', 'E2', 'L3']. */
  steps: string[];
  /** Dos escritores (A1 A2 B1 B2) en vez de un lector y un escritor. */
  writers?: boolean;
  /** Los escritores actualizan la cache con su valor en vez de borrar la entrada. */
  update?: boolean;
  /** El lector guarda solo si nadie invalidó la entrada desde que la buscó. */
  lease?: boolean;
  ttlMs?: number;
};

export type RaceResult = {
  log: string[];
  originPrice: number;
  /** El precio en la cache, o null si no hay entrada. */
  cachedPrice: number | null;
  ttlMs: number;
  /** La cache tiene un precio que ya no es el de PostgreSQL. */
  stale: boolean;
};

// Guarda solo si el lease sigue siendo de quien lo pide. Un borrado se lo quita.
const SET_IF_LEASE = `
if redis.call('get', KEYS[2]) == ARGV[1] then
  redis.call('del', KEYS[2])
  return redis.call('set', KEYS[1], ARGV[2], 'PX', ARGV[3])
end
return false`;

function checkOrder(steps: string[], actors: Record<string, number>): void {
  const expected = Object.entries(actors).flatMap(([actor, count]) =>
    Array.from({ length: count }, (_, i) => `${actor}${i + 1}`),
  );
  if (steps.length !== expected.length || expected.some((step) => !steps.includes(step))) {
    throw new Error(`Hay que dar cada paso una vez: ${expected.join(' ')}`);
  }
  for (const [actor, count] of Object.entries(actors)) {
    for (let i = 1; i < count; i++) {
      if (steps.indexOf(`${actor}${i}`) > steps.indexOf(`${actor}${i + 1}`)) {
        throw new Error(`Los pasos de ${actor} van en orden: ${actor}${i} antes que ${actor}${i + 1}`);
      }
    }
  }
}

export async function runRace(db: Db, cache: Cache, options: RaceOptions): Promise<RaceResult> {
  const { redis } = cache;
  const key = `${cache.prefix}product:${PRODUCT_ID}:price`;
  const leaseKey = `${key}:lease`;
  const ttlMs = options.ttlMs ?? 30_000;
  const log: string[] = [];
  checkOrder(options.steps, options.writers ? { A: 2, B: 2 } : { L: 3, E: 2 });

  // Punto de partida: el precio viejo en PostgreSQL y nada en la cache.
  await changePrice(db, PRODUCT_ID, OLD_PRICE);
  await redis.del([key, leaseKey]);

  const readPrice = async (): Promise<number> => (await readProduct(db, PRODUCT_ID))!.priceCents;
  const write = async (who: string, price: number): Promise<void> => {
    await changePrice(db, PRODUCT_ID, price);
    log.push(`${who}1  UPDATE en PostgreSQL: el precio ahora es ${price}`);
  };
  const afterWrite = async (who: string, price: number): Promise<void> => {
    if (options.update) {
      await redis.set(key, String(price), { PX: ttlMs });
      log.push(`${who}2  SET en la cache: ${price}`);
    } else {
      await redis.del([key, leaseKey]);
      log.push(`${who}2  DEL en la cache`);
    }
  };

  // Lo que el lector lleva en la mano entre un paso y el siguiente.
  let found: string | null = null;
  let read: number | undefined;
  let lease: string | undefined;

  for (const step of options.steps) {
    if (step === 'L1') {
      found = await redis.get(key);
      log.push(`L1  GET en la cache: ${found === null ? 'no está (miss)' : found}`);
      if (found === null && options.lease) {
        lease = `lector-${PRODUCT_ID}`;
        await redis.set(leaseKey, lease, { NX: true, PX: 10_000 });
        log.push('L1  recibe un lease para guardar esta entrada');
      }
    } else if (step === 'L2') {
      if (found !== null) {
        log.push('L2  no hace falta: la cache respondió');
      } else {
        read = await readPrice();
        log.push(`L2  SELECT en PostgreSQL: lee ${read}`);
      }
    } else if (step === 'L3') {
      if (read === undefined) {
        log.push('L3  no hace falta: la cache respondió');
      } else if (options.lease) {
        const stored = await redis.eval(SET_IF_LEASE, { keys: [key, leaseKey], arguments: [lease!, String(read), String(ttlMs)] });
        log.push(stored === 'OK' ? `L3  SET en la cache: ${read} (el lease seguía vigente)` : `L3  la cache rechaza el SET de ${read}: el lease ya no existe`);
      } else {
        await redis.set(key, String(read), { PX: ttlMs });
        log.push(`L3  SET en la cache: ${read}, con TTL de ${ttlMs} ms`);
      }
    } else if (step === 'E1') await write('E', NEW_PRICE);
    else if (step === 'E2') await afterWrite('E', NEW_PRICE);
    else if (step === 'A1') await write('A', PRICE_A);
    else if (step === 'A2') await afterWrite('A', PRICE_A);
    else if (step === 'B1') await write('B', PRICE_B);
    else if (step === 'B2') await afterWrite('B', PRICE_B);
  }

  const originPrice = await readPrice();
  const cached = await redis.get(key);
  const remaining = cached === null ? 0 : await redis.pTTL(key);
  const cachedPrice = cached === null ? null : Number(cached);
  return { log, originPrice, cachedPrice, ttlMs: remaining, stale: cachedPrice !== null && cachedPrice !== originPrice };
}

if (import.meta.main) {
  const { values, positionals } = parseArgs({
    allowPositionals: true,
    options: {
      writers: { type: 'boolean', default: false },
      update: { type: 'boolean', default: false },
      lease: { type: 'boolean', default: false },
      ttl: { type: 'string', default: '30000' },
    },
  });
  const steps = positionals.length > 0 ? positionals : values.writers ? ['A1', 'A2', 'B1', 'B2'] : ['L1', 'L2', 'L3', 'E1', 'E2'];
  const db = connectDb(process.env.W11_DB ?? 'arq_w11');
  const cache = await connectCache(process.env.W11_PREFIX ?? 'w11:');
  try {
    const result = await runRace(db, cache, { steps, writers: values.writers, update: values.update, lease: values.lease, ttlMs: Number(values.ttl) });
    for (const line of result.log) console.log(line);
    console.log('');
    console.log(`PostgreSQL: ${result.originPrice}`);
    console.log(`Cache:      ${result.cachedPrice ?? 'sin entrada'}`);
    if (result.stale) console.log(`VIEJO: la cache va a responder ${result.cachedPrice} durante ${result.ttlMs} ms más, hasta que venza el TTL.`);
    else if (result.cachedPrice === null) console.log('Bien: la próxima lectura va a PostgreSQL y trae el precio vigente.');
    else console.log('Bien: la cache tiene el precio vigente.');
  } catch (error) {
    console.error((error as Error).message);
    process.exitCode = 2;
  } finally {
    await closeCache(cache);
    await closeDb(db);
  }
}
db/schema.sqlDescargar db/schema.sql
-- Qhatu: el catálogo de una bodega en línea. Es el ejemplo de la semana 11:
-- un servicio que se lee mucho más de lo que se escribe.
-- Los montos van en céntimos de sol, como enteros.

CREATE TABLE products (
    id          integer PRIMARY KEY,
    name        text    NOT NULL,
    category    text    NOT NULL,
    price_cents integer NOT NULL CHECK (price_cents > 0)
);

-- El stock no es una columna: es la suma de los movimientos del producto
-- (ingresos en positivo, ventas en negativo). Así nunca se pierde por qué el
-- stock es el que es, y a cambio cada lectura tiene que sumar.
CREATE TABLE stock_movements (
    id         bigint      PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    product_id integer     NOT NULL REFERENCES products (id),
    quantity   integer     NOT NULL CHECK (quantity <> 0),
    created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX stock_movements_product_idx ON stock_movements (product_id);
db/seed.sqlDescargar db/seed.sql
-- Datos de ejemplo de Qhatu. Son deterministas: no usan random() ni la hora.
-- 200 productos (20 productos por 10 presentaciones) y, por cada uno, un
-- ingreso de 2000 unidades y entre 300 y 499 ventas de una unidad.

INSERT INTO products (id, name, category, price_cents)
SELECT (b.i - 1) * 10 + s.j,
       b.name || ' ' || s.label,
       b.category,
       b.base_cents + s.j * 35
  FROM (VALUES
         (1,  'Arroz extra',        'abarrotes', 420),
         (2,  'Azúcar rubia',       'abarrotes', 380),
         (3,  'Aceite vegetal',     'abarrotes', 890),
         (4,  'Fideos tallarín',    'abarrotes', 310),
         (5,  'Lentejas',           'abarrotes', 650),
         (6,  'Leche evaporada',    'lácteos',   420),
         (7,  'Yogurt de fresa',    'lácteos',   590),
         (8,  'Queso fresco',       'lácteos',   1250),
         (9,  'Mantequilla',        'lácteos',   780),
         (10, 'Atún en conserva',   'conservas', 560),
         (11, 'Duraznos en almíbar','conservas', 940),
         (12, 'Galletas de soda',   'golosinas', 150),
         (13, 'Chocolate de taza',  'golosinas', 480),
         (14, 'Gaseosa amarilla',   'bebidas',   350),
         (15, 'Agua de mesa',       'bebidas',   180),
         (16, 'Chicha morada',      'bebidas',   520),
         (17, 'Detergente',         'limpieza',  1190),
         (18, 'Jabón de tocador',   'limpieza',  260),
         (19, 'Papel higiénico',    'limpieza',  890),
         (20, 'Lejía',              'limpieza',  330)
       ) AS b (i, name, category, base_cents)
 CROSS JOIN (VALUES
         (1, '250 g'), (2, '500 g'), (3, '750 g'), (4, '1 kg'), (5, '2 kg'),
         (6, 'pack x2'), (7, 'pack x4'), (8, 'pack x6'), (9, 'caja x12'), (10, 'caja x24')
       ) AS s (j, label);

INSERT INTO stock_movements (product_id, quantity)
SELECT id, 2000 FROM products ORDER BY id;

INSERT INTO stock_movements (product_id, quantity)
SELECT p.id, -1
  FROM products p
 CROSS JOIN LATERAL generate_series(1, 300 + (p.id * 37) % 200) AS g
 ORDER BY g, p.id;

ANALYZE;
load/browse.jsDescargar load/browse.js
// Gente mirando el catálogo de Qhatu: la lista de productos y el detalle de
// uno. La mayoría mira unos pocos productos de moda.
//
//   k6 run load/browse.js        (o make load, con make start en otra terminal)
//
//   BASE_URL=http://localhost:3000   dónde está Qhatu
//   VUS=50  DURATION=15s             cuántos usuarios y por cuánto tiempo (máximo 30 s)
//   ONLY_LIST=1                      solo piden la lista (para la estampida)
//   THINK=0.1                        segundos de pausa entre un pedido y el siguiente

import http from 'k6/http';
import { check, sleep } from 'k6';
import { Trend } from 'k6/metrics';

const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000';
const THINK = Number(__ENV.THINK || 0.1);
const ONLY_LIST = __ENV.ONLY_LIST === '1';
const PRODUCTS = 200;

export const options = {
  vus: Number(__ENV.VUS || 50),
  duration: __ENV.DURATION || '15s',
  summaryTrendStats: ['med', 'p(95)', 'p(99)', 'max'],
};

// http_req_duration junta los dos endpoints; estas métricas los separan.
const listDuration = new Trend('duration_list', true);
const detailDuration = new Trend('duration_detail', true);

export default function () {
  const list = http.get(`${BASE_URL}/products`, { tags: { name: 'GET /products' } });
  check(list, { 'GET /products responde 200': (r) => r.status === 200 });
  listDuration.add(list.timings.duration);
  sleep(THINK);
  if (ONLY_LIST) return;

  // Ocho de cada diez visitas van a los diez productos de moda.
  const id = Math.random() < 0.8 ? 1 + Math.floor(Math.random() * 10) : 1 + Math.floor(Math.random() * PRODUCTS);
  const detail = http.get(`${BASE_URL}/products/${id}`, { tags: { name: 'GET /products/:id' } });
  check(detail, { 'GET /products/:id responde 200': (r) => r.status === 200 });
  detailDuration.add(detail.timings.duration);
  sleep(THINK);
}
shards/assign.tsDescargar shards/assign.ts
// Reparte los datos de ejemplo de Tinkuy en 8 shards, usando event_id como
// clave: primero por hash y después por rango. Dice cuántos eventos y cuántos
// asientos le tocan a cada shard y dónde cae el evento 1. Al final prueba otra
// clave, el id del asiento, y dice qué se rompe con ella.
//
//   node shards/assign.ts     (o make shards)
//
// No hay 8 bases de datos: se lee de la copia de los datos que hizo `make` y
// se calcula a qué shard iría cada fila.

import pg from 'pg';
import { distribute, shardByHash, shardByRange } from './hash.ts';

export const SHARDS = 8;

export type EventSeats = { eventId: number; seats: number };

export async function loadEventSeats(pool: pg.Pool): Promise<EventSeats[]> {
  const result = await pool.query<{ event_id: number; seats: number }>(
    'SELECT event_id, count(*)::int AS seats FROM seats GROUP BY event_id ORDER BY event_id',
  );
  return result.rows.map((row) => ({ eventId: row.event_id, seats: row.seats }));
}

/** Rangos de igual cantidad de eventos: con 24 eventos y 8 shards, de tres en tres. */
export function evenRanges(maxKey: number, shards: number): number[] {
  return Array.from({ length: shards }, (_, i) => Math.ceil(((i + 1) * maxKey) / shards));
}

function printTable(title: string, events: EventSeats[], assign: (eventId: number) => number): void {
  const seats = distribute(events, SHARDS, (e) => assign(e.eventId), (e) => e.seats);
  const total = seats.reduce((sum, n) => sum + n, 0);
  console.log(title);
  console.log('shard  eventos                 asientos  % de los asientos');
  for (let shard = 0; shard < SHARDS; shard++) {
    const ids = events.filter((e) => assign(e.eventId) === shard).map((e) => e.eventId);
    const share = ((100 * seats[shard]!) / total).toFixed(1).replace('.', ',');
    console.log(`${String(shard).padStart(5)}  ${ids.join(' ').padEnd(22)}  ${String(seats[shard]).padStart(8)}  ${share.padStart(6)} %`);
  }
  const max = Math.max(...seats);
  const min = Math.min(...seats);
  console.log(`El shard más cargado tiene ${max} asientos y el menos cargado ${min}. El evento 1 está en el shard ${assign(1)}.`);
  console.log('');
}

if (import.meta.main) {
  const pool = new pg.Pool({ database: process.env.W11_DB ?? 'arq_w11' });
  try {
    const events = await loadEventSeats(pool);
    const totalSeats = events.reduce((sum, e) => sum + e.seats, 0);
    console.log(`${events.length} eventos y ${totalSeats} asientos en ${SHARDS} shards. Clave de sharding: event_id.`);
    console.log('');

    printTable('Por hash: shard = hash(event_id) mod 8', events, (id) => shardByHash(id, SHARDS));
    const bounds = evenRanges(events.length, SHARDS);
    printTable(`Por rango: tres eventos seguidos por shard (límites ${bounds.join(', ')})`, events, (id) => shardByRange(id, bounds));

    // Otra clave: el id del asiento. Reparte los asientos casi perfecto...
    const seats = await pool.query<{ id: number; event_id: number }>('SELECT id, event_id FROM seats');
    const bySeat = distribute(seats.rows, SHARDS, (row) => shardByHash(row.id, SHARDS), () => 1);
    console.log('Otra clave: shard = hash(seat_id) mod 8');
    console.log(`Asientos por shard: ${bySeat.join(', ')}`);

    // ...y a cambio separa lo que se usa junto.
    const eventOne = new Set(seats.rows.filter((row) => row.event_id === 1).map((row) => shardByHash(row.id, SHARDS)));
    console.log(`Los asientos del evento 1 quedan repartidos en ${eventOne.size} shards: pedir su mapa de asientos es preguntarles a todos.`);

    const orders = await pool.query<{ order_id: number; seat_ids: number[] }>(
      'SELECT order_id, array_agg(seat_id) AS seat_ids FROM order_items GROUP BY order_id',
    );
    const multiSeat = orders.rows.filter((order) => order.seat_ids.length > 1);
    const split = multiSeat.filter((order) => new Set(order.seat_ids.map((id) => shardByHash(id, SHARDS))).size > 1);
    console.log(
      `De las ${orders.rows.length} órdenes de ejemplo, ${multiSeat.length} llevan más de un asiento, ` +
        `y en ${split.length} de ellas los asientos caen en shards distintos: serían transacciones entre shards.`,
    );
  } finally {
    await pool.end();
  }
}
shards/hash.tsDescargar shards/hash.ts
// De una clave a un shard. Todo lo que hay aquí son funciones puras: dada la
// misma clave responden siempre lo mismo, en cualquier máquina y en cualquier
// versión del programa. Esa es la primera condición de una función de
// asignación: todos los que enrutan tienen que estar de acuerdo.

import { createHash } from 'node:crypto';

/**
 * Un entero de 32 bits a partir de la clave. No hace falta que el hash sea
 * criptográfico; hace falta que reparta parejo y que no cambie nunca. Por
 * eso no sirve el hash interno de un lenguaje, que puede cambiar entre
 * versiones o entre procesos.
 */
export function hash32(key: string | number): number {
  return createHash('md5').update(String(key)).digest().readUInt32BE(0);
}

/** Por hash: el shard es el resto de dividir el hash entre el número de shards. */
export function shardByHash(key: string | number, shards: number): number {
  return hash32(key) % shards;
}

/**
 * Por rango: `upperBounds[i]` es la clave más alta del shard i. Con
 * [3, 6, 9], las claves 1 a 3 van al shard 0, 4 a 6 al 1 y 7 a 9 al 2.
 */
export function shardByRange(key: number, upperBounds: readonly number[]): number {
  const shard = upperBounds.findIndex((bound) => key <= bound);
  if (shard === -1) throw new Error(`La clave ${key} queda fuera del último rango`);
  return shard;
}

/** Cuánto le tocó a cada shard: suma `weight` de cada fila en el shard que diga `assign`. */
export function distribute<Row>(rows: readonly Row[], shards: number, assign: (row: Row) => number, weight: (row: Row) => number): number[] {
  const totals = new Array<number>(shards).fill(0);
  for (const row of rows) totals[assign(row)]! += weight(row);
  return totals;
}
shards/rebalance.tsDescargar shards/rebalance.ts
// ¿Cuántas claves cambian de nodo cuando se agrega un nodo? Tres esquemas,
// con las mismas 100 000 claves, al pasar de 8 nodos a 9:
//
//   1. hash(k) mod n, con n = número de nodos.
//   2. Un número fijo de shards lógicos (1024) que se asignan a nodos: la
//      clave nunca cambia de shard; lo que se mueve son shards enteros.
//   3. Consistent hashing: nodos y claves en un mismo anillo.
//
//   node shards/rebalance.ts     (o make rebalance)

import { hash32 } from './hash.ts';

export const KEYS = 100_000;
export const LOGICAL_SHARDS = 1024;
const VIRTUAL_NODES = 128;

/** Una función que dice en qué nodo vive cada clave. */
export type Placement = (key: number) => number;

// --- 1. hash(k) mod n --------------------------------------------------

export function modN(nodes: number): Placement {
  return (key) => hash32(key) % nodes;
}

// --- 2. Shards lógicos -------------------------------------------------

/** El mapa shard lógico → nodo. Es el registro en el que todos tienen que estar de acuerdo. */
export type ShardMap = number[];

export function initialShardMap(nodes: number): ShardMap {
  return Array.from({ length: LOGICAL_SHARDS }, (_, shard) => shard % nodes);
}

/** Agrega un nodo: le pasa shards de los nodos que más tienen, hasta que le toque su parte. */
export function addNode(map: ShardMap, newNode: number): ShardMap {
  const next = [...map];
  const target = Math.floor(LOGICAL_SHARDS / (newNode + 1));
  const owned = new Map<number, number[]>();
  next.forEach((node, shard) => owned.set(node, [...(owned.get(node) ?? []), shard]));
  for (let moved = 0; moved < target; moved++) {
    const donor = [...owned.entries()].sort((a, b) => b[1].length - a[1].length || a[0] - b[0])[0]!;
    next[donor[1].pop()!] = newNode;
  }
  return next;
}

export function logicalShards(map: ShardMap): Placement {
  // La clave siempre cae en el mismo shard lógico: el 1024 no cambia nunca.
  return (key) => map[hash32(key) % LOGICAL_SHARDS]!;
}

// --- 3. Consistent hashing ---------------------------------------------

type Point = { position: number; node: number };

/** Cada nodo ocupa varios puntos del anillo, para que los tramos salgan parejos. */
export function ring(nodes: number): Point[] {
  const points: Point[] = [];
  for (let node = 0; node < nodes; node++) {
    for (let v = 0; v < VIRTUAL_NODES; v++) points.push({ position: hash32(`nodo-${node}-${v}`), node });
  }
  return points.sort((a, b) => a.position - b.position);
}

export function consistentHashing(points: Point[]): Placement {
  return (key) => {
    // A la clave le toca el primer punto en o después de su posición,
    // dando la vuelta al llegar al final. Búsqueda binaria.
    const position = hash32(key);
    let low = 0;
    let high = points.length;
    while (low < high) {
      const middle = (low + high) >> 1;
      if (points[middle]!.position < position) low = middle + 1;
      else high = middle;
    }
    return points[low % points.length]!.node;
  };
}

// --- La comparación -----------------------------------------------------

export type Move = {
  moved: number;
  /** De las que se movieron, cuántas fueron al nodo nuevo. */
  movedToNewNode: number;
  /** Claves por nodo después del cambio. */
  perNode: number[];
};

export function compare(before: Placement, after: Placement, nodesAfter: number, keys = KEYS): Move {
  const perNode = new Array<number>(nodesAfter).fill(0);
  let moved = 0;
  let movedToNewNode = 0;
  for (let key = 1; key <= keys; key++) {
    const to = after(key);
    perNode[to]!++;
    if (before(key) !== to) {
      moved++;
      if (to === nodesAfter - 1) movedToNewNode++;
    }
  }
  return { moved, movedToNewNode, perNode };
}

export function schemes(from: number, to: number): { name: string; move: Move }[] {
  const map = initialShardMap(from);
  let grown = map;
  for (let node = from; node < to; node++) grown = addNode(grown, node);
  return [
    { name: 'hash(k) mod n', move: compare(modN(from), modN(to), to) },
    { name: `${LOGICAL_SHARDS} shards lógicos`, move: compare(logicalShards(map), logicalShards(grown), to) },
    { name: 'consistent hashing', move: compare(consistentHashing(ring(from)), consistentHashing(ring(to)), to) },
  ];
}

if (import.meta.main) {
  const percent = (n: number): string => ((100 * n) / KEYS).toFixed(1).replace('.', ',').padStart(5) + ' %';
  console.log(`${KEYS} claves, de 8 nodos a 9. Lo mínimo que hay que mover para que el nodo nuevo tenga su parte es 1/9 = ${(100 / 9).toFixed(1).replace('.', ',')} %.`);
  console.log('');
  console.log('esquema                se mueven   van al nodo nuevo   claves por nodo después (mín. – máx.)');
  for (const { name, move } of schemes(8, 9)) {
    console.log(
      `${name.padEnd(21)}  ${percent(move.moved)}   ${percent(move.movedToNewNode)}             ` +
        `${Math.min(...move.perNode)} – ${Math.max(...move.perNode)}`,
    );
  }
  console.log('');
  const doubled = schemes(8, 16)[0]!.move;
  console.log(`Y con hash(k) mod n, duplicar de 8 a 16 nodos mueve ${percent(doubled.moved).trim()} de las claves.`);
}
shards/scatter.tsDescargar shards/scatter.ts
// ¿Qué consultas de Tinkuy tocarían un solo shard y cuáles todos?
//
// Se simulan 8 shards en memoria, con event_id como clave: cada fila de los
// datos de ejemplo va al shard que le toca a su evento. Después se ejecutan
// las lecturas de la API de Tinkuy contra esos shards y se cuenta a cuántos
// hubo que preguntarles. Una consulta que conoce el event_id va a un shard;
// una que no lo conoce tiene que preguntarles a todos y juntar las respuestas
// (scatter-gather).
//
//   node shards/scatter.ts     (o make scatter)

import pg from 'pg';
import { shardByHash } from './hash.ts';

export const SHARDS = 8;

type Seat = { id: number; eventId: number; status: string };
type Order = { id: number; eventId: number; status: string };
/** Lo que guarda un shard: las filas de los eventos que le tocaron. */
type Shard = { seats: Seat[]; orders: Order[] };

export type Cluster = {
  shards: Shard[];
  /** A cuántos shards se les preguntó desde el último reset. */
  touched: number;
};

export async function loadCluster(pool: pg.Pool): Promise<Cluster> {
  const shards: Shard[] = Array.from({ length: SHARDS }, () => ({ seats: [], orders: [] }));
  const seats = await pool.query<{ id: number; event_id: number; status: string }>('SELECT id, event_id, status FROM seats');
  for (const row of seats.rows) {
    shards[shardByHash(row.event_id, SHARDS)]!.seats.push({ id: row.id, eventId: row.event_id, status: row.status });
  }
  // Las órdenes llevan event_id, así que viven con su evento.
  const orders = await pool.query<{ id: number; event_id: number; status: string }>('SELECT id, event_id, status FROM orders');
  for (const row of orders.rows) {
    shards[shardByHash(row.event_id, SHARDS)]!.orders.push({ id: row.id, eventId: row.event_id, status: row.status });
  }
  return { shards, touched: 0 };
}

/** Con la clave: se le pregunta a un solo shard. */
function one<T>(cluster: Cluster, eventId: number, query: (shard: Shard) => T): T {
  cluster.touched += 1;
  return query(cluster.shards[shardByHash(eventId, SHARDS)]!);
}

/** Sin la clave: se les pregunta a todos y se juntan las respuestas. */
function all<T>(cluster: Cluster, query: (shard: Shard) => T[]): T[] {
  cluster.touched += cluster.shards.length;
  return cluster.shards.flatMap(query);
}

// Las lecturas de Tinkuy, como quedarían sobre los shards.

/** GET /events/:id — los asientos libres de un evento. */
export function availableSeats(cluster: Cluster, eventId: number): number {
  return one(cluster, eventId, (shard) => shard.seats.filter((s) => s.eventId === eventId && s.status === 'available').length);
}

/** GET /events/:id/seats — el mapa de asientos. */
export function seatsOfEvent(cluster: Cluster, eventId: number): Seat[] {
  return one(cluster, eventId, (shard) => shard.seats.filter((s) => s.eventId === eventId));
}

/** POST /orders — los asientos pedidos. El pedido trae el eventId: va a un shard. */
export function seatsForSale(cluster: Cluster, eventId: number, seatIds: number[]): Seat[] {
  return one(cluster, eventId, (shard) => shard.seats.filter((s) => seatIds.includes(s.id)));
}

/** GET /reports/sales?eventId= — las órdenes pagadas de un evento. */
export function paidOrders(cluster: Cluster, eventId: number): number {
  return one(cluster, eventId, (shard) => shard.orders.filter((o) => o.eventId === eventId && o.status === 'paid').length);
}

/** GET /events — los asientos libres de todos los eventos. No hay una clave: es la lista completa. */
export function availabilityOfAllEvents(cluster: Cluster): Map<number, number> {
  const pairs = all(cluster, (shard) => {
    const counts = new Map<number, number>();
    for (const seat of shard.seats) {
      if (seat.status === 'available') counts.set(seat.eventId, (counts.get(seat.eventId) ?? 0) + 1);
    }
    return [...counts.entries()];
  });
  return new Map(pairs);
}

/** GET /orders/:id — la consulta solo trae el id de la orden, que no es la clave. */
export function findOrder(cluster: Cluster, orderId: number): Order | undefined {
  return all(cluster, (shard) => shard.orders.filter((o) => o.id === orderId))[0];
}

if (import.meta.main) {
  const pool = new pg.Pool({ database: process.env.W11_DB ?? 'arq_w11' });
  try {
    const cluster = await loadCluster(pool);
    const rows: [string, string, () => unknown][] = [
      ['GET /events/:id', 'WHERE event_id = $1', () => availableSeats(cluster, 1)],
      ['GET /events/:id/seats', 'WHERE event_id = $1', () => seatsOfEvent(cluster, 1)],
      ['POST /orders', 'WHERE t.id = ANY($1), con el eventId del pedido', () => seatsForSale(cluster, 1, [1001, 1002])],
      ['GET /reports/sales?eventId=', 'WHERE o.event_id = $1', () => paidOrders(cluster, 2)],
      ['GET /events', 'sin filtro: todos los eventos', () => availabilityOfAllEvents(cluster)],
      ['GET /orders/:id', 'WHERE o.id = $1', () => findOrder(cluster, 1)],
    ];
    console.log(`Clave de sharding: event_id, ${SHARDS} shards.`);
    console.log('');
    console.log('endpoint                     la consulta filtra por                             shards');
    for (const [endpoint, filter, run] of rows) {
      cluster.touched = 0;
      run();
      const verdict = cluster.touched === 1 ? '1' : `${cluster.touched} (scatter-gather)`;
      console.log(`${endpoint.padEnd(27)}  ${filter.padEnd(49)}  ${verdict}`);
    }
  } finally {
    await pool.end();
  }
}
src/cache.tsDescargar src/cache.ts
// Cache-aside sobre Redis: la aplicación busca en la cache; si no está, lee
// del origen, guarda el resultado y responde. Al escribir, borra la entrada.
//
// La cache es un dato derivado: todo lo que hay aquí se puede perder. Por eso
// ninguna función de este archivo deja que un error de Redis llegue a quien
// llama (salvo que se pida con failure: 'closed', para ver qué pasa).

import { createClient } from 'redis';

export type RedisClient = ReturnType<typeof createClient>;

export type CacheStats = {
  hits: number;
  misses: number;
  /** Aciertos que respondieron "no existe" sin ir al origen. */
  negativeHits: number;
  /** Respuestas con el valor anterior mientras otro recalculaba (single-flight). */
  staleServed: number;
  /** Operaciones de Redis que fallaron. */
  errors: number;
};

export type Cache = {
  redis: RedisClient;
  prefix: string;
  failure: 'open' | 'closed';
  stats: CacheStats;
};

/** Lo que se guarda: el valor, o la marca de que el origen dijo "no existe". */
export type Entry<T> = { v: T } | { missing: true };

export async function connectCache(prefix = 'w11:', failure: 'open' | 'closed' = 'open'): Promise<Cache> {
  const redis = createClient({
    // Sin cola: si no hay conexión, cada comando falla al instante en vez de
    // quedarse esperando a que Redis vuelva. Una cache que hace esperar es
    // peor que no tener cache.
    disableOfflineQueue: true,
    socket: {
      connectTimeout: 500,
      // Sigue intentando reconectar, cada vez más espaciado, hasta 1 s.
      reconnectStrategy: (retries: number) => Math.min(1000, 50 * 2 ** retries),
    },
  }) as RedisClient;
  const cache: Cache = {
    redis,
    prefix,
    failure,
    stats: { hits: 0, misses: 0, negativeHits: 0, staleServed: 0, errors: 0 },
  };
  // Sin este listener, un error de conexión tumba el proceso.
  redis.on('error', () => {});
  await redis.connect();
  return cache;
}

export async function closeCache(cache: Cache): Promise<void> {
  // destroy() cierra también cuando Redis está caído; quit() se quedaría esperando.
  if (cache.redis.isReady) await cache.redis.quit();
  else cache.redis.destroy();
}

/**
 * Corre una operación de Redis. Si falla, cuenta el error y devuelve
 * `fallback`: para quien llama, una cache caída se ve como una cache vacía.
 */
export async function safely<T>(cache: Cache, operation: () => Promise<T>, fallback: T): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    cache.stats.errors++;
    if (cache.failure === 'closed') throw error;
    return fallback;
  }
}

/**
 * Un TTL con jitter: `baseMs` más o menos una fracción al azar. Con
 * spread = 0.1, un TTL de 60 s queda entre 54 s y 66 s. Así las entradas que
 * se guardaron juntas no vencen juntas.
 */
export function ttlWithJitter(baseMs: number, spread: number, random: () => number = Math.random): number {
  const factor = 1 - spread + 2 * spread * random();
  return Math.max(1, Math.round(baseMs * factor));
}

export function encode<T>(value: T | undefined): string {
  const entry: Entry<T> = value === undefined ? { missing: true } : { v: value };
  return JSON.stringify(entry);
}

export function decode<T>(raw: string): Entry<T> {
  return JSON.parse(raw) as Entry<T>;
}

export type AsideOptions = {
  /** Cuánto vive un "no existe". Sin esta opción (o con 0) no se guarda. */
  negativeTtlMs?: number;
};

/**
 * Cache-aside. `load` lee del origen y devuelve undefined si el dato no
 * existe.
 */
export async function cacheAside<T>(
  cache: Cache,
  key: string,
  ttlMs: number,
  load: () => Promise<T | undefined>,
  options: AsideOptions = {},
): Promise<T | undefined> {
  const fullKey = cache.prefix + key;

  // 1. Buscar en la cache.
  const raw = await safely(cache, () => cache.redis.get(fullKey), null);
  if (raw !== null) {
    const entry = decode<T>(raw);
    if ('missing' in entry) {
      cache.stats.negativeHits++;
      return undefined;
    }
    cache.stats.hits++;
    return entry.v;
  }

  // 2. No está: leer del origen.
  cache.stats.misses++;
  const value = await load();

  // 3. Guardar y responder. Siempre con TTL: es lo que acota cuánto puede
  //    durar un valor viejo si alguna invalidación no llega.
  const negativeTtlMs = options.negativeTtlMs ?? 0;
  if (value !== undefined) {
    await safely(cache, () => cache.redis.set(fullKey, encode(value), { PX: ttlMs }), null);
  } else if (negativeTtlMs > 0) {
    await safely(cache, () => cache.redis.set(fullKey, encode(undefined), { PX: negativeTtlMs }), null);
  }
  return value;
}

/** Borra entradas. Se llama después de escribir en el origen. */
export async function invalidate(cache: Cache, ...keys: string[]): Promise<void> {
  if (keys.length === 0) return;
  const fullKeys = keys.flatMap((key) => [cache.prefix + key, cache.prefix + key + FRESH_SUFFIX]);
  await safely(cache, () => cache.redis.del(fullKeys), 0);
}

/** Sufijo de la marca "este valor todavía está vigente" que usa single-flight.ts. */
export const FRESH_SUFFIX = ':fresh';
/** Sufijo del lock de quien está recalculando. */
export const LOCK_SUFFIX = ':lock';
src/catalog.tsDescargar src/catalog.ts
// El origen: lo que Qhatu sabe hacer contra PostgreSQL, sin cache.

import type { Db } from './db.ts';

export type Product = {
  id: number;
  name: string;
  category: string;
  priceCents: number;
  stock: number;
};

type ProductRow = { id: number; name: string; category: string; price_cents: number; stock: number };

const toProduct = (row: ProductRow): Product => ({
  id: row.id,
  name: row.name,
  category: row.category,
  priceCents: row.price_cents,
  stock: row.stock,
});

/** Un producto con su stock, o undefined si no existe. Suma los movimientos de ese producto. */
export async function readProduct(db: Db, id: number): Promise<Product | undefined> {
  db.originReads++;
  const result = await db.pool.query<ProductRow>(
    `SELECT p.id, p.name, p.category, p.price_cents,
            coalesce((SELECT sum(m.quantity) FROM stock_movements m WHERE m.product_id = p.id), 0)::int AS stock
       FROM products p
      WHERE p.id = $1`,
    [id],
  );
  const row = result.rows[0];
  return row ? toProduct(row) : undefined;
}

/** Todos los productos con su stock. Suma todos los movimientos: es la lectura cara. */
export async function readCatalog(db: Db): Promise<Product[]> {
  db.originReads++;
  const result = await db.pool.query<ProductRow>(
    `SELECT p.id, p.name, p.category, p.price_cents, coalesce(sum(m.quantity), 0)::int AS stock
       FROM products p
       LEFT JOIN stock_movements m ON m.product_id = p.id
      GROUP BY p.id
      ORDER BY p.id`,
  );
  return result.rows.map(toProduct);
}

export type SaleResult = 'sold' | 'not-found' | 'no-stock';

/** Registra una venta si hay stock. El FOR UPDATE pone en fila las ventas del mismo producto. */
export async function recordSale(db: Db, id: number, quantity: number): Promise<SaleResult> {
  const client = await db.pool.connect();
  try {
    await client.query('BEGIN');
    const product = await client.query('SELECT id FROM products WHERE id = $1 FOR UPDATE', [id]);
    if (product.rowCount === 0) {
      await client.query('ROLLBACK');
      return 'not-found';
    }
    const stock = await client.query<{ stock: number }>(
      'SELECT coalesce(sum(quantity), 0)::int AS stock FROM stock_movements WHERE product_id = $1',
      [id],
    );
    if (stock.rows[0]!.stock < quantity) {
      await client.query('ROLLBACK');
      return 'no-stock';
    }
    await client.query('INSERT INTO stock_movements (product_id, quantity) VALUES ($1, $2)', [id, -quantity]);
    await client.query('COMMIT');
    return 'sold';
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}

/** Cambia el precio. Devuelve false si el producto no existe. */
export async function changePrice(db: Db, id: number, priceCents: number): Promise<boolean> {
  const result = await db.pool.query('UPDATE products SET price_cents = $2 WHERE id = $1', [id, priceCents]);
  return result.rowCount === 1;
}
src/config.tsDescargar src/config.ts
// Configuración de Qhatu: todo sale de variables de entorno, con valores por
// omisión que sirven dentro del contenedor del curso.

function numberFromEnv(name: string, fallback: number): number {
  const raw = process.env[name];
  if (raw === undefined || raw === '') return fallback;
  const value = Number(raw);
  if (!Number.isFinite(value) || value < 0) {
    throw new Error(`La variable ${name} debe ser un número, y es "${raw}"`);
  }
  return value;
}

function oneOf<T extends string>(name: string, allowed: readonly T[], fallback: T): T {
  const raw = process.env[name];
  if (raw === undefined || raw === '') return fallback;
  if (!(allowed as readonly string[]).includes(raw)) {
    throw new Error(`La variable ${name} debe ser una de ${allowed.join(', ')}, y es "${raw}"`);
  }
  return raw as T;
}

export const CACHE_MODES = ['off', 'aside', 'single-flight'] as const;
export type CacheMode = (typeof CACHE_MODES)[number];

export type Settings = {
  port: number;
  database: string;
  /** Prefijo de todas las claves de Redis de la semana. */
  prefix: string;
  /** off: siempre al origen. aside: cache-aside. single-flight: además, solo uno recalcula. */
  cacheMode: CacheMode;
  /** Cuánto vive el detalle de un producto. */
  detailTtlMs: number;
  /** Cuánto vive la lista de productos. */
  listTtlMs: number;
  /** Cuánto vive un "no existe". 0 = no se guarda. */
  negativeTtlMs: number;
  /** Fracción del TTL que se reparte al azar: 0.1 es ±10 %. */
  jitter: number;
  /** Si una venta o un cambio de precio borra las entradas que quedaron viejas. */
  invalidateOnWrite: boolean;
  /** open: si Redis falla, se va al origen. closed: el error llega a quien llama. */
  cacheFailure: 'open' | 'closed';
  /** Imprime una línea de estadísticas por segundo. */
  statsLog: boolean;
};

export function settingsFromEnv(): Settings {
  return {
    port: numberFromEnv('PORT', 3000),
    database: process.env.W11_DB ?? 'arq_w11',
    prefix: process.env.W11_PREFIX ?? 'w11:',
    cacheMode: oneOf('CACHE_MODE', CACHE_MODES, 'aside'),
    detailTtlMs: numberFromEnv('DETAIL_TTL_MS', 30_000),
    listTtlMs: numberFromEnv('LIST_TTL_MS', 5_000),
    negativeTtlMs: numberFromEnv('NEGATIVE_TTL_MS', 5_000),
    jitter: numberFromEnv('JITTER', 0.1),
    invalidateOnWrite: process.env.INVALIDATE !== 'off',
    cacheFailure: oneOf('CACHE_FAILURE', ['open', 'closed'] as const, 'open'),
    statsLog: process.env.STATS_LOG === '1',
  };
}
src/db.tsDescargar src/db.ts
import pg from 'pg';

// El host y el usuario salen de PGHOST y PGUSER, que el contenedor ya define.

export type Db = {
  pool: pg.Pool;
  /** Cuántas lecturas del catálogo llegaron a PostgreSQL desde que arrancó. */
  originReads: number;
};

export function connectDb(database: string, max = 10): Db {
  return { pool: new pg.Pool({ database, max }), originReads: 0 };
}

export async function closeDb(db: Db): Promise<void> {
  await db.pool.end();
}
src/main.tsDescargar src/main.ts
// Arranca Qhatu:  node src/main.ts   (o make start)

import { closeCache, connectCache } from './cache.ts';
import { settingsFromEnv } from './config.ts';
import { closeDb, connectDb } from './db.ts';
import { createApp } from './server.ts';

const settings = settingsFromEnv();
const db = connectDb(settings.database);
const cache = await connectCache(settings.prefix, settings.cacheFailure);
const server = createApp({ db, cache, settings });

server.listen(settings.port, () => {
  console.log(
    `Qhatu en http://localhost:${settings.port}  cache=${settings.cacheMode}` +
      `  ttl lista=${settings.listTtlMs} ms  ttl detalle=${settings.detailTtlMs} ms` +
      `  invalidación=${settings.invalidateOnWrite ? 'sí' : 'no'}  si Redis falla=${settings.cacheFailure}`,
  );
});

async function shutdown(): Promise<void> {
  server.close();
  server.closeAllConnections();
  await closeCache(cache);
  await closeDb(db);
}
process.once('SIGINT', () => void shutdown());
process.once('SIGTERM', () => void shutdown());
src/server.tsDescargar src/server.ts
// El servidor HTTP de Qhatu, sobre node:http.
//
//   GET  /health               el proceso vive
//   GET  /ready                además puede hacer su trabajo (PostgreSQL responde)
//   GET  /products             la lista con su stock
//   GET  /products/:id         un producto
//   POST /products/:id/sales   { "quantity": 1 }      registra una venta
//   PUT  /products/:id/price   { "priceCents": 450 }  cambia el precio
//   GET  /stats                contadores de la cache y del origen
//
// El proceso no guarda nada propio entre una petición y otra: el estado está
// en PostgreSQL y en Redis. Por eso se pueden levantar varias copias.

import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
import { getProduct, listProducts, sell, setPrice, type Service } from './service.ts';

type Reply = { status: number; body: unknown };

async function readJson(request: IncomingMessage): Promise<Record<string, unknown>> {
  let text = '';
  for await (const chunk of request) text += chunk;
  try {
    const parsed: unknown = JSON.parse(text || '{}');
    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : {};
  } catch {
    return {};
  }
}

const error = (status: number, message: string): Reply => ({ status, body: { error: message } });

async function route(service: Service, request: IncomingMessage): Promise<Reply> {
  const path = new URL(request.url ?? '/', 'http://localhost').pathname;
  const method = request.method ?? 'GET';

  if (method === 'GET' && path === '/health') return { status: 200, body: { status: 'ok' } };

  if (method === 'GET' && path === '/ready') {
    // Redis no decide: sin cache el servicio responde igual, más lento. Si
    // este chequeo fallara con Redis caído, el load balancer sacaría a todas
    // las instancias a la vez.
    try {
      await service.db.pool.query('SELECT 1');
      return { status: 200, body: { status: 'ok', cache: service.cache.redis.isReady ? 'ok' : 'down' } };
    } catch {
      return { status: 503, body: { status: 'unavailable' } };
    }
  }

  if (method === 'GET' && path === '/stats') {
    return { status: 200, body: { cache: service.cache.stats, originReads: service.db.originReads } };
  }

  if (method === 'GET' && path === '/products') {
    return { status: 200, body: { products: await listProducts(service) } };
  }

  const match = /^\/products\/(\d{1,9})(\/sales|\/price)?$/.exec(path);
  if (!match) return error(404, 'No existe esa ruta');
  const id = Number(match[1]);
  const action = match[2];

  if (method === 'GET' && action === undefined) {
    const product = await getProduct(service, id);
    return product ? { status: 200, body: { product } } : error(404, `No existe el producto ${id}`);
  }

  if (method === 'POST' && action === '/sales') {
    const quantity = (await readJson(request)).quantity;
    if (typeof quantity !== 'number' || !Number.isInteger(quantity) || quantity < 1) {
      return error(422, 'quantity debe ser un entero positivo');
    }
    const result = await sell(service, id, quantity);
    if (result === 'not-found') return error(404, `No existe el producto ${id}`);
    if (result === 'no-stock') return error(409, 'No hay stock suficiente');
    return { status: 201, body: { sold: quantity } };
  }

  if (method === 'PUT' && action === '/price') {
    const priceCents = (await readJson(request)).priceCents;
    if (typeof priceCents !== 'number' || !Number.isInteger(priceCents) || priceCents < 1) {
      return error(422, 'priceCents debe ser un entero positivo');
    }
    return (await setPrice(service, id, priceCents))
      ? { status: 200, body: { priceCents } }
      : error(404, `No existe el producto ${id}`);
  }

  return error(404, 'No existe esa ruta');
}

/** Lo que pasó en el último segundo, para la línea de estadísticas. */
type Window = { requests: number; failed: number; durations: number[] };

function percentile(sorted: number[], p: number): number {
  if (sorted.length === 0) return 0;
  // Rango más cercano: el menor valor con al menos p % de los datos por debajo o iguales.
  return sorted[Math.max(0, Math.ceil((p / 100) * sorted.length) - 1)]!;
}

export function createApp(service: Service): Server {
  let window: Window = { requests: 0, failed: 0, durations: [] };
  let last = { ...service.cache.stats, originReads: service.db.originReads };
  let second = 0;

  const server = createServer((request: IncomingMessage, response: ServerResponse) => {
    const started = performance.now();
    route(service, request)
      .catch((): Reply => error(500, 'Error interno'))
      .then((reply) => {
        window.requests++;
        if (reply.status >= 500) window.failed++;
        window.durations.push(performance.now() - started);
        response.writeHead(reply.status, { 'content-type': 'application/json' });
        response.end(JSON.stringify(reply.body));
      });
  });

  if (service.settings.statsLog) {
    const timer = setInterval(() => {
      second++;
      const now = { ...service.cache.stats, originReads: service.db.originReads };
      const sorted = window.durations.sort((a, b) => a - b);
      console.log(
        `t=${String(second).padStart(2)}s  pedidos=${String(window.requests).padStart(4)}` +
          `  hits=${String(now.hits - last.hits).padStart(4)}` +
          `  viejos=${String(now.staleServed - last.staleServed).padStart(4)}` +
          `  origen=${String(now.originReads - last.originReads).padStart(4)}` +
          `  errores_cache=${String(now.errors - last.errors).padStart(4)}` +
          `  5xx=${String(window.failed).padStart(4)}` +
          `  p95=${percentile(sorted, 95).toFixed(1).replace('.', ',')} ms`,
      );
      window = { requests: 0, failed: 0, durations: [] };
      last = now;
    }, 1000);
    server.on('close', () => clearInterval(timer));
  }
  return server;
}
src/service.tsDescargar src/service.ts
// Qhatu con cache: aquí están las decisiones de la tabla (qué se guarda, con
// qué clave, cuánto dura y qué lo invalida), en un solo lugar.

import { cacheAside, invalidate, ttlWithJitter, type Cache } from './cache.ts';
import { changePrice, readCatalog, readProduct, recordSale, type Product, type SaleResult } from './catalog.ts';
import type { Settings } from './config.ts';
import type { Db } from './db.ts';
import { cacheAsideSingleFlight } from './single-flight.ts';

export type Service = { db: Db; cache: Cache; settings: Settings };

// Las claves. Con el prefijo quedan como w11:products y w11:product:17.
export const LIST_KEY = 'products';
export const productKey = (id: number): string => `product:${id}`;

/** El detalle de un producto. Clave por id; se guarda también "no existe". */
export async function getProduct(service: Service, id: number): Promise<Product | undefined> {
  const { db, cache, settings } = service;
  if (settings.cacheMode === 'off') return readProduct(db, id);
  return cacheAside(cache, productKey(id), ttlWithJitter(settings.detailTtlMs, settings.jitter), () => readProduct(db, id), {
    negativeTtlMs: settings.negativeTtlMs,
  });
}

/** La lista completa: una sola clave, la más pedida y la más cara de calcular. */
export async function listProducts(service: Service): Promise<Product[]> {
  const { db, cache, settings } = service;
  if (settings.cacheMode === 'off') return readCatalog(db);
  if (settings.cacheMode === 'single-flight') {
    return cacheAsideSingleFlight(cache, LIST_KEY, settings.listTtlMs, () => readCatalog(db), {
      staleMs: 10 * settings.listTtlMs,
      lockMs: 5_000,
    });
  }
  return (await cacheAside(cache, LIST_KEY, settings.listTtlMs, () => readCatalog(db))) ?? [];
}

/** Una venta cambia el stock: deja viejos el detalle del producto y la lista. */
export async function sell(service: Service, id: number, quantity: number): Promise<SaleResult> {
  const result = await recordSale(service.db, id, quantity);
  // Primero el origen, después la cache, y solo si el origen cambió.
  if (result === 'sold' && service.settings.invalidateOnWrite) {
    await invalidate(service.cache, productKey(id), LIST_KEY);
  }
  return result;
}

/** Un cambio de precio invalida las mismas dos entradas. */
export async function setPrice(service: Service, id: number, priceCents: number): Promise<boolean> {
  const changed = await changePrice(service.db, id, priceCents);
  if (changed && service.settings.invalidateOnWrite) {
    await invalidate(service.cache, productKey(id), LIST_KEY);
  }
  return changed;
}
src/single-flight.tsDescargar src/single-flight.ts
// Cache-aside en el que solo una petición recalcula una entrada vencida. Las
// demás reciben el valor anterior, y si no hay valor anterior, esperan.
//
// Cada entrada son dos claves:
//
//   w11:products         el valor, que vive ttl + stale
//   w11:products:fresh   una marca vacía, que vive ttl
//
// Mientras la marca existe, el valor está vigente. Cuando la marca vence, el
// valor sigue ahí un rato más (stale): es el "valor anterior" que se sirve
// mientras alguien recalcula. Quién recalcula lo decide un lock:
//
//   SET w11:products:lock <token> NX PX <lockMs>
//
// NX hace que solo uno lo obtenga; PX hace que el lock se suelte solo si quien
// lo tenía se cae antes de terminar. No es un lock de exclusión mutua: si dos
// llegan a recalcular a la vez no se rompe nada, solo se trabaja de más.

import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { decode, encode, safely, FRESH_SUFFIX, LOCK_SUFFIX, type Cache } from './cache.ts';

export type SingleFlightOptions = {
  /** Cuánto más que el TTL se conserva el valor para servirlo como anterior. */
  staleMs: number;
  /** Cuánto dura el lock si quien recalcula no lo suelta. */
  lockMs: number;
  /** Cada cuánto vuelve a mirar quien espera sin valor anterior. */
  pollMs?: number;
};

// Suelta el lock solo si todavía es de quien lo pide: si ya venció y lo tomó
// otro, no hay que borrárselo. Comparar y borrar tiene que ser atómico, y por
// eso va en un script que Redis ejecuta de una sola vez.
const RELEASE_LOCK = `
if redis.call('get', KEYS[1]) == ARGV[1] then
  return redis.call('del', KEYS[1])
end
return 0`;

export async function cacheAsideSingleFlight<T>(
  cache: Cache,
  key: string,
  ttlMs: number,
  load: () => Promise<T>,
  options: SingleFlightOptions,
): Promise<T> {
  const valueKey = cache.prefix + key;
  const freshKey = valueKey + FRESH_SUFFIX;
  const lockKey = valueKey + LOCK_SUFFIX;
  const pollMs = options.pollMs ?? 20;
  const deadline = Date.now() + options.lockMs;

  for (;;) {
    // 1. El valor y su marca, en un solo viaje.
    const [raw, fresh] = await safely(cache, () => cache.redis.mGet([valueKey, freshKey]), [null, null]);
    if (raw !== null && fresh !== null) {
      cache.stats.hits++;
      return (decode<T>(raw) as { v: T }).v;
    }

    // 2. Vencido o ausente: ¿me toca recalcular?
    const token = randomUUID();
    const locked = await safely(cache, () => cache.redis.set(lockKey, token, { NX: true, PX: options.lockMs }), null);
    if (locked === 'OK') {
      cache.stats.misses++;
      try {
        const value = await load();
        await safely(
          cache,
          () =>
            cache.redis
              .multi()
              .set(valueKey, encode(value), { PX: ttlMs + options.staleMs })
              .set(freshKey, '1', { PX: ttlMs })
              .exec(),
          null,
        );
        return value;
      } finally {
        await safely(cache, () => cache.redis.eval(RELEASE_LOCK, { keys: [lockKey], arguments: [token] }), null);
      }
    }

    // 3. Otro está recalculando. Si hay valor anterior, se responde con ese.
    if (raw !== null) {
      cache.stats.staleServed++;
      return (decode<T>(raw) as { v: T }).v;
    }

    // 4. No hay valor anterior (cache vacía, o Redis caído). Se espera un
    //    poco y se vuelve a mirar; pasado el plazo, se va al origen.
    if (!cache.redis.isReady || Date.now() >= deadline) {
      cache.stats.misses++;
      return load();
    }
    await sleep(pollMs);
  }
}
tools/compare.shDescargar tools/compare.sh
#!/usr/bin/env bash
# Mide Qhatu tres veces con la misma carga (50 usuarios, 15 segundos): sin
# cache, con cache-aside y con single-flight. Cada corrida empieza con la cache
# vacía. Al final de cada una dice cuántas lecturas llegaron a PostgreSQL.
set -uo pipefail
cd "$(dirname "$0")/.."
source tools/lib.sh

for mode in off aside single-flight; do
    node tools/flush.ts >/dev/null
    start_qhatu CACHE_MODE="$mode" || exit 1
    echo "== CACHE_MODE=$mode"
    run_k6 VUS=50 DURATION=15s
    curl -s "$BASE_URL/stats" | jq -r '"lecturas que llegaron a PostgreSQL: \(.originReads)   hits: \(.cache.hits)   misses: \(.cache.misses)"'
    stop_qhatu
done
tools/eviction.tsDescargar tools/eviction.ts
// Memoria finita: ¿qué hace Redis cuando se llena? Se le pone un límite de
// memoria 2 MB por encima de lo que usa ahora y se le escriben 5000 entradas
// de 1 KB (unos 5 MB), primero con la política noeviction (la que trae Redis
// por omisión) y después con allkeys-lru. Al final se restaura la
// configuración y se borran las entradas.
//
//   node tools/eviction.ts     (o make eviction)

import { createClient } from 'redis';

const ENTRIES = 5000;
const VALUE = 'x'.repeat(1024);
const PREFIX = (process.env.W11_PREFIX ?? 'w11:') + 'evict:';

const redis = createClient();
redis.on('error', () => {});
await redis.connect();

const info = async (section: string, field: string): Promise<number> => {
  const line = (await redis.info(section)).split('\r\n').find((l) => l.startsWith(field + ':'));
  return Number(line?.split(':')[1] ?? 0);
};

async function fill(policy: string): Promise<void> {
  await redis.configSet('maxmemory-policy', policy);
  const evictedBefore = await info('stats', 'evicted_keys');
  let rejected = 0;
  let firstError = '';
  for (let i = 0; i < ENTRIES; i++) {
    try {
      await redis.set(`${PREFIX}${policy}:${i}`, VALUE, { EX: 600 });
    } catch (error) {
      rejected++;
      firstError ||= (error as Error).message;
    }
  }
  let stored = 0;
  for await (const keys of redis.scanIterator({ MATCH: `${PREFIX}${policy}:*`, COUNT: 1000 })) stored += keys.length;
  const first = await redis.exists(`${PREFIX}${policy}:0`);
  const last = await redis.exists(`${PREFIX}${policy}:${ENTRIES - 1}`);
  console.log(`maxmemory-policy = ${policy}`);
  console.log(`  escrituras rechazadas: ${rejected}${firstError ? `  ("${firstError}")` : ''}`);
  console.log(`  entradas desalojadas:  ${(await info('stats', 'evicted_keys')) - evictedBefore}`);
  console.log(`  quedan ${stored} de ${ENTRIES}; la primera que se escribió ${first ? 'sigue' : 'ya no está'}, la última ${last ? 'está' : 'no entró'}`);
  for await (const keys of redis.scanIterator({ MATCH: `${PREFIX}${policy}:*`, COUNT: 1000 })) {
    if (keys.length > 0) await redis.del(keys);
  }
}

const previous = await redis.configGet('maxmemory-policy');
try {
  const used = await info('memory', 'used_memory');
  await redis.configSet('maxmemory', String(used + 2 * 1024 * 1024));
  console.log(`Límite: lo que Redis usa ahora más 2 MB. Se escriben ${ENTRIES} entradas de 1 KB.`);
  await fill('noeviction');
  await fill('allkeys-lru');
} finally {
  await redis.configSet('maxmemory', '0');
  await redis.configSet('maxmemory-policy', previous['maxmemory-policy'] ?? 'noeviction');
  await redis.quit();
}
tools/flush.tsDescargar tools/flush.ts
// Borra de Redis todas las claves de la semana (w11:*) y nada más.

import { createClient } from 'redis';

const redis = createClient();
redis.on('error', () => {});
try {
  await redis.connect();
  let deleted = 0;
  for await (const keys of redis.scanIterator({ MATCH: 'w11:*', COUNT: 1000 })) {
    if (keys.length > 0) deleted += await redis.del(keys);
  }
  if (deleted > 0) console.log(`Redis: ${deleted} claves w11:* borradas.`);
  await redis.quit();
} catch {
  console.error('Redis no responde: no se borró nada (svc start redis).');
  redis.destroy();
  process.exitCode = 1;
}
tools/jitter.tsDescargar tools/jitter.ts
// 1000 entradas guardadas en el mismo instante con un TTL de 60 segundos:
// ¿en qué segundo vence cada una? Primero con el TTL exacto y después con
// ±10 % de jitter. Los TTL se leen de Redis (PTTL); no se espera a que venzan.

import { closeCache, connectCache, ttlWithJitter, type Cache } from '../src/cache.ts';

const ENTRIES = 1000;
const TTL_MS = 60_000;

async function expirySeconds(cache: Cache, label: string, ttl: () => number): Promise<Map<number, number>> {
  const keys = Array.from({ length: ENTRIES }, (_, i) => `${cache.prefix}jitter:${label}:${i}`);
  const writes = cache.redis.multi();
  for (const key of keys) writes.set(key, '1', { PX: ttl() });
  await writes.exec();

  const reads = cache.redis.multi();
  for (const key of keys) reads.pTTL(key);
  const remaining = (await reads.exec()) as unknown as number[];
  await cache.redis.del(keys);

  const perSecond = new Map<number, number>();
  for (const ms of remaining) {
    const second = Math.ceil(ms / 1000);
    perSecond.set(second, (perSecond.get(second) ?? 0) + 1);
  }
  return perSecond;
}

function describe(title: string, perSecond: Map<number, number>): void {
  const seconds = [...perSecond.keys()].sort((a, b) => a - b);
  const busiest = Math.max(...perSecond.values());
  console.log(
    `${title}: vencen entre el segundo ${seconds[0]} y el ${seconds.at(-1)}; ` +
      `en el peor segundo vencen ${busiest} de ${ENTRIES}`,
  );
}

const cache = await connectCache(process.env.W11_PREFIX ?? 'w11:');
try {
  describe('TTL de 60 s exactos', await expirySeconds(cache, 'plain', () => TTL_MS));
  describe('TTL de 60 s ± 10 %  ', await expirySeconds(cache, 'jitter', () => ttlWithJitter(TTL_MS, 0.1)));
} finally {
  await closeCache(cache);
}
tools/lib.shDescargar tools/lib.sh
# Funciones que comparten los guiones de la semana. Se cargan con `source`.

PORT="${PORT:-3000}"
BASE_URL="http://localhost:$PORT"
mkdir -p build

# start_qhatu VAR=valor...   levanta Qhatu en segundo plano y espera a que responda.
start_qhatu() {
    : > build/qhatu.log
    env "$@" PORT="$PORT" node src/main.ts >> build/qhatu.log 2>&1 &
    QHATU_PID=$!
    for _ in $(seq 1 50); do
        curl -fs "$BASE_URL/health" >/dev/null 2>&1 && return 0
        sleep 0.1
    done
    echo "Qhatu no arrancó; revisen build/qhatu.log" >&2
    return 1
}

stop_qhatu() {
    [ -n "${QHATU_PID:-}" ] && kill "$QHATU_PID" 2>/dev/null && wait "$QHATU_PID" 2>/dev/null
    QHATU_PID=""
}

# run_k6 VAR=valor...   corre la carga y deja solo las líneas que interesan.
run_k6() {
    env "$@" BASE_URL="$BASE_URL" k6 run --quiet load/browse.js 2>&1 \
        | grep -E 'duration_list|duration_detail|http_reqs|http_req_failed' \
        | sed -E 's/^ +//; s/\.+:/:/'
}

trap stop_qhatu EXIT
tools/negative.tsDescargar tools/negative.ts
// 200 pedidos seguidos de un producto que no existe. Sin cache negativa, cada
// uno llega a PostgreSQL: "no existe" no deja nada en la cache, así que la
// siguiente pregunta vuelve a fallar. Con cache negativa, llega uno.

import { closeCache, connectCache } from '../src/cache.ts';
import { settingsFromEnv } from '../src/config.ts';
import { closeDb, connectDb } from '../src/db.ts';
import { getProduct, productKey, type Service } from '../src/service.ts';

const MISSING_ID = 999_999;
const REQUESTS = 200;

const base = settingsFromEnv();
const db = connectDb(base.database);
const cache = await connectCache(base.prefix);

async function run(negativeTtlMs: number): Promise<number> {
  const service: Service = { db, cache, settings: { ...base, cacheMode: 'aside', negativeTtlMs } };
  await cache.redis.del(cache.prefix + productKey(MISSING_ID));
  const before = db.originReads;
  for (let i = 0; i < REQUESTS; i++) {
    if ((await getProduct(service, MISSING_ID)) !== undefined) throw new Error('El producto no debería existir');
  }
  return db.originReads - before;
}

try {
  console.log(`${REQUESTS} pedidos de GET /products/${MISSING_ID}, que no existe:`);
  console.log(`  sin cache negativa:               ${await run(0)} consultas a PostgreSQL`);
  console.log(`  con cache negativa (TTL de 5 s):  ${await run(5_000)} consulta a PostgreSQL`);
  console.log(`  en Redis quedó: ${await cache.redis.get(cache.prefix + productKey(MISSING_ID))}`);
  await cache.redis.del(cache.prefix + productKey(MISSING_ID));
} finally {
  await closeCache(cache);
  await closeDb(db);
}
tools/pg-queries.tsDescargar tools/pg-queries.ts
// Cuenta las consultas que llegan a PostgreSQL, sin tocar la aplicación que
// las hace: le pide a PostgreSQL que registre cada sentencia en su log y
// después cuenta las líneas. Sirve para Qhatu y para Tinkuy.
//
//   node tools/pg-queries.ts on        empieza a registrar (log_statement = all)
//   node tools/pg-queries.ts report --db arq_w11 --match 'LEFT JOIN stock_movements'
//   node tools/pg-queries.ts off       deja de registrar
//
// report cuenta las consultas desde el último "on" y las agrupa en ráfagas.
// --match es un texto que la consulta debe contener; --gap, cuántos
// milisegundos sin consultas separan una ráfaga de la siguiente (por omisión, 300).
//
// Registrar todas las sentencias tiene un costo: es una herramienta de
// laboratorio, no algo que se deja encendido.

import { existsSync, mkdirSync, openSync, readFileSync, readSync, closeSync, statSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { parseArgs } from 'node:util';
import pg from 'pg';

const LOG_FILE = process.env.PG_LOG ?? '/var/log/course/postgres.log';
const OFFSET_FILE = join(import.meta.dirname, '..', 'build', 'pg-queries.offset');

export type LoggedQuery = { at: number; database: string; text: string };

/** Extrae las sentencias de un trozo del log (con log_line_prefix = '%m [%p] %d '). */
export function parseLog(log: string): LoggedQuery[] {
  const queries: LoggedQuery[] = [];
  const header = /^(\d{4}-\d\d-\d\d) (\d\d:\d\d:\d\d\.\d{3}) UTC \[\d+\] (\S*) LOG:  (?:execute [^:]*|statement): (.*)$/;
  let current: LoggedQuery | undefined;
  for (const line of log.split('\n')) {
    const match = header.exec(line);
    if (match) {
      current = { at: Date.parse(`${match[1]}T${match[2]}Z`), database: match[3]!, text: match[4]! };
      queries.push(current);
    } else if (line.startsWith('\t') && current) {
      // Una sentencia de varias líneas continúa con tabulador.
      current.text += ' ' + line.trim();
    } else {
      current = undefined;
    }
  }
  return queries;
}

export type Burst = { startMs: number; count: number; durationMs: number };

/**
 * Agrupa las consultas en ráfagas: una ráfaga termina cuando pasan más de
 * `gapMs` sin que llegue otra consulta. Una estampida se ve como una ráfaga
 * de muchas consultas; una entrada que recalcula uno solo, como ráfagas de una.
 */
export function bursts(queries: LoggedQuery[], gapMs: number): Burst[] {
  const result: Burst[] = [];
  const start = queries[0]?.at ?? 0;
  let previous = -Infinity;
  for (const query of queries) {
    const last = result.at(-1);
    if (last && query.at - previous <= gapMs) {
      last.count++;
      last.durationMs = query.at - start - last.startMs;
    } else {
      result.push({ startMs: query.at - start, count: 1, durationMs: 0 });
    }
    previous = query.at;
  }
  return result;
}

async function configure(statements: string[]): Promise<void> {
  const client = new pg.Client({ database: 'postgres' });
  await client.connect();
  try {
    for (const statement of statements) await client.query(statement);
    await client.query('SELECT pg_reload_conf()');
  } finally {
    await client.end();
  }
}

function readFrom(offset: number): string {
  const size = statSync(LOG_FILE).size;
  const buffer = Buffer.alloc(Math.max(0, size - offset));
  const fd = openSync(LOG_FILE, 'r');
  try {
    readSync(fd, buffer, 0, buffer.length, offset);
  } finally {
    closeSync(fd);
  }
  return buffer.toString('utf8');
}

if (import.meta.main) {
  const { values, positionals } = parseArgs({
    allowPositionals: true,
    options: {
      db: { type: 'string', default: 'arq_w11' },
      match: { type: 'string', default: 'SELECT' },
      gap: { type: 'string', default: '300' },
    },
  });
  const command = positionals[0];

  if (command === 'on') {
    await configure(["ALTER SYSTEM SET log_statement = 'all'", "ALTER SYSTEM SET log_line_prefix = '%m [%p] %d '"]);
    mkdirSync(dirname(OFFSET_FILE), { recursive: true });
    writeFileSync(OFFSET_FILE, String(statSync(LOG_FILE).size));
    console.log('PostgreSQL registra cada consulta desde ahora.');
  } else if (command === 'off') {
    await configure(['ALTER SYSTEM RESET log_statement', 'ALTER SYSTEM RESET log_line_prefix']);
    console.log('PostgreSQL dejó de registrar las consultas.');
  } else if (command === 'report') {
    const offset = existsSync(OFFSET_FILE) ? Number(readFileSync(OFFSET_FILE, 'utf8')) : 0;
    const needle = values.match.toLowerCase();
    const queries = parseLog(readFrom(offset)).filter(
      (query) => query.database === values.db && query.text.toLowerCase().includes(needle),
    );
    const found = bursts(queries, Number(values.gap));
    console.log(`Consultas a ${values.db} que contienen "${values.match}": ${queries.length}, en ${found.length} ráfagas`);
    if (found.length > 0) {
      console.log('ráfaga  empieza en  consultas  dura');
      found.forEach((burst, i) => {
        console.log(
          `${String(i + 1).padStart(6)}  ${(burst.startMs / 1000).toFixed(1).replace('.', ',').padStart(8)} s  ${String(burst.count).padStart(9)}  ${String(burst.durationMs).padStart(4)} ms`,
        );
      });
      const largest = Math.max(...found.map((burst) => burst.count));
      console.log(`La ráfaga más grande: ${largest} ${largest === 1 ? "consulta" : "consultas"}`);
    }
  } else {
    console.error('Uso: node tools/pg-queries.ts on | off | report [--db base] [--match texto] [--gap ms]');
    process.exitCode = 2;
  }
}
tools/redis-down.shDescargar tools/redis-down.sh
#!/usr/bin/env bash
# Redis se cae con la carga corriendo. 50 usuarios miran el catálogo durante
# 12 segundos; en el segundo 4 se mata Redis (svc kill redis) y en el 8 se
# vuelve a levantar, vacío. Se corre dos veces: con un servicio que deja pasar
# el error de la cache (CACHE_FAILURE=closed) y con uno que va al origen
# (CACHE_FAILURE=open). Cada línea es un segundo, contado por el servidor.
#
#   make redis-down                        las dos
#   make redis-down CACHE_FAILURE=open     solo una
set -uo pipefail
cd "$(dirname "$0")/.."
source tools/lib.sh

for failure in ${CACHE_FAILURE:-closed open}; do
    svc start redis >/dev/null
    node tools/flush.ts >/dev/null
    start_qhatu CACHE_MODE=aside CACHE_FAILURE="$failure" STATS_LOG=1 || exit 1
    echo "== CACHE_FAILURE=$failure"
    run_k6 VUS=50 DURATION=12s > build/k6-summary.txt &
    K6_PID=$!
    sleep 4;  svc kill redis;             echo "   (segundo 4: svc kill redis)" >> build/qhatu.log
    sleep 4;  svc start redis >/dev/null; echo "   (segundo 8: svc start redis)" >> build/qhatu.log
    wait "$K6_PID"
    stop_qhatu
    grep -E '^(t=| )' build/qhatu.log
    cat build/k6-summary.txt
    echo
done
tools/stampede.shDescargar tools/stampede.sh
#!/usr/bin/env bash
# La estampida, contada en PostgreSQL. La lista de productos vive 2 segundos y
# 50 usuarios la piden sin parar durante 9. Cada vez que la entrada vence,
# ¿cuántas veces se recalcula? Se mide con cache-aside y con single-flight.
set -uo pipefail
cd "$(dirname "$0")/.."
source tools/lib.sh

for mode in aside single-flight; do
    node tools/flush.ts >/dev/null
    node tools/pg-queries.ts on >/dev/null
    start_qhatu CACHE_MODE="$mode" LIST_TTL_MS=2000 || exit 1
    echo "== CACHE_MODE=$mode, la lista vence cada 2 segundos"
    run_k6 VUS=50 DURATION=9s ONLY_LIST=1 THINK=0.05
    stop_qhatu
    node tools/pg-queries.ts report --db "${W11_DB:-arq_w11}" --match 'LEFT JOIN stock_movements'
    node tools/pg-queries.ts off >/dev/null
    echo
done

Errores

Ejemplos con errores a propósito: no compilan, fallan o dan un resultado incorrecto. Los apuntes explican cada uno.

errors/local-cache.tsDescargar errors/local-cache.ts
// ERROR A PROPÓSITO: cache en la memoria del proceso, con dos instancias.
//
// Cada instancia de Qhatu guarda los precios en un Map propio. Al cambiar un
// precio, la instancia que atendió el cambio borra SU entrada; la otra no se
// entera. Detrás de un load balancer que reparte por turnos, quien recarga la
// página ve el precio nuevo y el viejo alternados.
//
//   node errors/local-cache.ts     (o make local-cache)

import { changePrice, readProduct } from '../src/catalog.ts';
import { closeDb, connectDb, type Db } from '../src/db.ts';

export type Instance = {
  name: string;
  getPrice(id: number): Promise<number | undefined>;
  setPrice(id: number, priceCents: number): Promise<void>;
};

export function createInstance(name: string, db: Db): Instance {
  // El estado que hace que esta instancia no sea intercambiable con otra.
  const local = new Map<number, number>();
  return {
    name,
    async getPrice(id) {
      const cached = local.get(id);
      if (cached !== undefined) return cached;
      const price = (await readProduct(db, id))?.priceCents;
      if (price !== undefined) local.set(id, price);
      return price;
    },
    async setPrice(id, priceCents) {
      await changePrice(db, id, priceCents);
      local.delete(id);
    },
  };
}

if (import.meta.main) {
  const db = connectDb(process.env.W11_DB ?? 'arq_w11');
  try {
    await changePrice(db, 2, 490);
    const instances = [createInstance('instancia A', db), createInstance('instancia B', db)];
    // El load balancer: por turnos.
    let turn = 0;
    const next = (): Instance => instances[turn++ % instances.length]!;

    for (let i = 0; i < 2; i++) {
      const instance = next();
      console.log(`GET /products/2 → ${instance.name} responde ${await instance.getPrice(2)}`);
    }
    const writer = next();
    await writer.setPrice(2, 550);
    console.log(`PUT /products/2/price 550 → lo atiende la ${writer.name}`);
    for (let i = 0; i < 4; i++) {
      const instance = next();
      console.log(`GET /products/2 → ${instance.name} responde ${await instance.getPrice(2)}`);
    }
    await changePrice(db, 2, 490);
  } finally {
    await closeDb(db);
  }
}

Pruebas

Comprueban lo que afirman los apuntes; se ejecutan con make test.

test/cache-module.test.tsDescargar test/cache-module.test.ts
// Lo que tiene que cumplir el módulo de cache del laboratorio.
//
//   make test-lab    lo comprueba sobre lab/cache-aside.ts (el de ustedes)
//   make test        lo comprueba sobre solution/cache-aside.ts, si está
//
// El punto de partida falla en cuatro de estas pruebas: cada paso del
// laboratorio hace pasar una o dos.

import assert from 'node:assert/strict';
import { existsSync } from 'node:fs';
import { join } from 'node:path';
import { after, before, beforeEach, test } from 'node:test';
import { setTimeout as sleep } from 'node:timers/promises';
import { clearKeys, createGate, until } from './helpers.ts';

type CacheModule = typeof import('../lab/cache-aside.ts');

const folder = process.env.CACHE_MODULE ?? 'solution';
const file = join(import.meta.dirname, '..', folder, 'cache-aside.ts');
const skip = existsSync(file) ? false : `no está ${folder}/cache-aside.ts`;
const PREFIX = (process.env.W11_PREFIX ?? 'w11:test:') + 'module:';

let module: CacheModule;
let cache: Awaited<ReturnType<CacheModule['connectCache']>>;

before(async () => {
  if (skip) return;
  module = (await import(file)) as CacheModule;
  cache = await module.connectCache(PREFIX);
});
beforeEach(async () => {
  if (!skip) await clearKeys(cache);
});
after(async () => {
  if (skip) return;
  await clearKeys(cache);
  await module.closeCache(cache);
});

/** Un origen que cuenta cuántas veces lo llaman. */
function counter<T>(value: T): { load: () => Promise<T>; calls: () => number } {
  let calls = 0;
  return {
    load: async () => {
      calls++;
      return value;
    },
    calls: () => calls,
  };
}

test('paso 3: la segunda lectura no llama al origen', { skip }, async () => {
  const origin = counter({ id: 1, title: 'Killa Sónica' });
  const first = await module.cacheAside(cache, 'event:1', 30_000, origin.load);
  const second = await module.cacheAside(cache, 'event:1', 30_000, origin.load);
  assert.deepEqual(second, first);
  assert.equal(origin.calls(), 1);
});

test('paso 3: la entrada queda en Redis con el prefijo y con TTL', { skip }, async () => {
  await module.cacheAside(cache, 'event:2', 30_000, counter('x').load);
  const ttl = await cache.redis.pTTL(PREFIX + 'event:2');
  assert.ok(ttl > 0 && ttl <= 30_000, `PTTL = ${ttl}`);
});

test('paso 4: después de invalidar, la lectura vuelve al origen', { skip }, async () => {
  const origin = counter('x');
  await module.cacheAside(cache, 'event:3', 30_000, origin.load);
  await module.invalidate(cache, 'event:3');
  await module.cacheAside(cache, 'event:3', 30_000, origin.load);
  assert.equal(origin.calls(), 2);
});

test('paso 7: con la entrada vencida, uno recalcula y los demás reciben el valor anterior', { skip }, async () => {
  const options = { staleMs: 60_000, lockMs: 5_000 };
  await module.cacheAsideSingleFlight(cache, 'events', 100, async () => 'anterior', options);
  // Se espera a que venza el TTL de 100 ms. Como no se sabe qué claves usa
  // cada solución, se pregunta hasta que una lectura llegue al origen.
  const gate = createGate();
  let loads = 0;
  const load = async (): Promise<string> => {
    loads++;
    await gate.wait;
    return 'nueva';
  };
  const pending: Promise<string>[] = [];
  await until(() => {
    pending.push(module.cacheAsideSingleFlight(cache, 'events', 100, load, options));
    return loads > 0;
  }, 'que la entrada venza y alguien recalcule');

  // Mientras el origen sigue detenido, llegan 20 lectores más.
  const readers = Array.from({ length: 20 }, () => module.cacheAsideSingleFlight(cache, 'events', 100, load, options));
  const timer = new AbortController();
  const timeout = sleep(2000, 'timeout' as const, { signal: timer.signal }).catch(() => 'timeout' as const);
  try {
    const early = await Promise.race([Promise.all(readers), timeout]);
    assert.notEqual(early, 'timeout', 'los 20 tenían que responder sin esperar al origen');
    assert.deepEqual(new Set(early as string[]), new Set(['anterior']));
    assert.equal(loads, 1, 'solo uno fue al origen');
  } finally {
    timer.abort();
    gate.open();
    await Promise.all([...pending, ...readers]);
  }
  assert.equal(loads, 1);
});

test('paso 7: invalidar también descarta el valor anterior', { skip }, async () => {
  const options = { staleMs: 60_000, lockMs: 5_000 };
  const origin = counter('x');
  await module.cacheAsideSingleFlight(cache, 'events', 30_000, origin.load, options);
  await module.invalidate(cache, 'events');
  await module.cacheAsideSingleFlight(cache, 'events', 30_000, origin.load, options);
  assert.equal(origin.calls(), 2);
});

test('paso 8: si Redis no responde, la lectura sale del origen y el error se cuenta', { skip }, async () => {
  const broken = await module.connectCache(PREFIX);
  broken.redis.destroy(); // desde aquí, todo comando a Redis falla
  const origin = counter('del origen');
  assert.equal(await module.cacheAside(broken, 'event:9', 30_000, origin.load), 'del origen');
  assert.equal(await module.cacheAsideSingleFlight(broken, 'event:9', 30_000, origin.load, { staleMs: 1000, lockMs: 1000 }), 'del origen');
  await module.invalidate(broken, 'event:9');
  assert.equal(origin.calls(), 2);
  assert.ok(broken.stats.errors > 0, 'stats.errors debe contar las fallas de Redis');
});

test('el módulo responde lo que devuelve el origen', { skip }, async () => {
  assert.deepEqual(await module.cacheAside(cache, 'event:5', 30_000, async () => ({ seats: 2000 })), { seats: 2000 });
});
test/cache.test.tsDescargar test/cache.test.ts
// Cache-aside, invalidación, cache negativa, jitter y Redis caído.

import assert from 'node:assert/strict';
import { after, before, beforeEach, test } from 'node:test';
import { cacheAside, connectCache, closeCache, ttlWithJitter } from '../src/cache.ts';
import { changePrice } from '../src/catalog.ts';
import { getProduct, listProducts, productKey, sell, setPrice, type Service } from '../src/service.ts';
import { clearKeys, closeService, createService, TEST_PREFIX } from './helpers.ts';

let service: Service;

before(async () => {
  service = await createService({ cacheMode: 'aside' });
});
beforeEach(async () => {
  await clearKeys(service.cache);
  await changePrice(service.db, 1, 455);
});
after(async () => {
  await closeService(service);
});

test('la primera lectura va al origen y la segunda sale de la cache', async () => {
  const before = service.db.originReads;
  const first = await getProduct(service, 1);
  const second = await getProduct(service, 1);
  assert.equal(service.db.originReads - before, 1);
  assert.deepEqual(second, first);
  assert.equal(first?.name, 'Arroz extra 250 g');
});

test('toda entrada se guarda con TTL', async () => {
  await getProduct(service, 1);
  const ttl = await service.cache.redis.pTTL(TEST_PREFIX + productKey(1));
  assert.ok(ttl > 0 && ttl <= service.settings.detailTtlMs, `TTL = ${ttl}`);
});

test('sin invalidación, una venta deja la cache con el stock viejo', async () => {
  const stale: Service = { ...service, settings: { ...service.settings, invalidateOnWrite: false } };
  const before = (await getProduct(stale, 3))!.stock;
  assert.equal(await sell(stale, 3, 1), 'sold');
  assert.equal((await getProduct(stale, 3))!.stock, before, 'la cache sigue respondiendo el stock anterior');
});

test('con invalidación, la lectura siguiente a una venta trae el stock nuevo', async () => {
  const beforeDetail = (await getProduct(service, 4))!.stock;
  const beforeList = (await listProducts(service)).find((p) => p.id === 4)!.stock;
  assert.equal(await sell(service, 4, 2), 'sold');
  assert.equal((await getProduct(service, 4))!.stock, beforeDetail - 2);
  assert.equal((await listProducts(service)).find((p) => p.id === 4)!.stock, beforeList - 2);
});

test('una venta que no ocurrió no invalida nada', async () => {
  await getProduct(service, 5);
  assert.equal(await sell(service, 5, 1_000_000), 'no-stock');
  assert.equal(await service.cache.redis.exists(TEST_PREFIX + productKey(5)), 1);
});

test('un cambio de precio invalida el detalle', async () => {
  assert.equal((await getProduct(service, 1))!.priceCents, 455);
  await setPrice(service, 1, 499);
  assert.equal((await getProduct(service, 1))!.priceCents, 499);
});

test('cache negativa: de 50 preguntas por algo que no existe, una llega al origen', async () => {
  const before = service.db.originReads;
  for (let i = 0; i < 50; i++) assert.equal(await getProduct(service, 999_999), undefined);
  assert.equal(service.db.originReads - before, 1);
});

test('sin cache negativa, las 50 llegan al origen', async () => {
  const plain: Service = { ...service, settings: { ...service.settings, negativeTtlMs: 0 } };
  const before = service.db.originReads;
  for (let i = 0; i < 50; i++) assert.equal(await getProduct(plain, 999_998), undefined);
  assert.equal(service.db.originReads - before, 50);
});

test('el jitter deja el TTL dentro de ±10 % y no siempre igual', () => {
  const ttls = Array.from({ length: 1000 }, () => ttlWithJitter(60_000, 0.1));
  assert.ok(Math.min(...ttls) >= 54_000 && Math.max(...ttls) <= 66_000);
  assert.ok(new Set(ttls).size > 900, 'casi todos distintos');
  // Con los extremos del generador se ven los límites exactos.
  assert.equal(ttlWithJitter(60_000, 0.1, () => 0), 54_000);
  assert.equal(ttlWithJitter(60_000, 0.1, () => 0.5), 60_000);
  assert.equal(ttlWithJitter(60_000, 0, () => 0.9), 60_000);
});

test('si Redis falla y la política es open, la lectura sale del origen', async () => {
  const cache = await connectCache(TEST_PREFIX, 'open');
  cache.redis.destroy(); // desde aquí, todo comando a Redis falla
  let loads = 0;
  const value = await cacheAside(cache, 'caida', 1000, async () => {
    loads++;
    return 'del origen';
  });
  assert.equal(value, 'del origen');
  assert.equal(loads, 1);
  assert.equal(cache.stats.errors, 2, 'falló el GET y falló el SET');
  await closeCache(cache);
});

test('si Redis falla y la política es closed, el error llega a quien llama', async () => {
  const cache = await connectCache(TEST_PREFIX, 'closed');
  cache.redis.destroy();
  await assert.rejects(cacheAside(cache, 'caida', 1000, async () => 'del origen'));
  await closeCache(cache);
});
test/helpers.tsDescargar test/helpers.ts
// Lo que comparten las pruebas: un servicio contra la base de datos y el
// prefijo de pruebas, y formas de esperar sin dormir a ciegas.

import { setTimeout as sleep } from 'node:timers/promises';
import { closeCache, connectCache, type Cache } from '../src/cache.ts';
import { settingsFromEnv, type Settings } from '../src/config.ts';
import { closeDb, connectDb } from '../src/db.ts';
import type { Service } from '../src/service.ts';

export const TEST_DB = process.env.W11_DB ?? 'arq_w11_test';
export const TEST_PREFIX = process.env.W11_PREFIX ?? 'w11:test:';

export async function createService(overrides: Partial<Settings> = {}): Promise<Service> {
  const settings: Settings = { ...settingsFromEnv(), database: TEST_DB, prefix: TEST_PREFIX, jitter: 0, ...overrides };
  const db = connectDb(settings.database);
  const cache = await connectCache(settings.prefix, settings.cacheFailure);
  await clearKeys(cache);
  return { db, cache, settings };
}

export async function closeService(service: Service): Promise<void> {
  if (service.cache.redis.isReady) await clearKeys(service.cache);
  await closeCache(service.cache);
  await closeDb(service.db);
}

/** Borra las claves del prefijo de pruebas. */
export async function clearKeys(cache: Pick<Cache, 'redis' | 'prefix'>): Promise<void> {
  for await (const keys of cache.redis.scanIterator({ MATCH: `${cache.prefix}*`, COUNT: 1000 })) {
    if (keys.length > 0) await cache.redis.del(keys);
  }
}

/** Espera a que `condition` se cumpla, mirando cada pocos milisegundos. Falla si pasa el plazo. */
export async function until(condition: () => boolean | Promise<boolean>, what: string, timeoutMs = 5000): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  while (!(await condition())) {
    if (Date.now() > deadline) throw new Error(`Se acabó el plazo esperando: ${what}`);
    await sleep(5);
  }
}

/** Una compuerta: quien hace `await gate.wait` queda detenido hasta `gate.open()`. */
export function createGate(): { wait: Promise<void>; open: () => void } {
  let open!: () => void;
  const wait = new Promise<void>((resolve) => {
    open = resolve;
  });
  return { wait, open };
}
test/race.test.tsDescargar test/race.test.ts
// La carrera de race.ts, con todos los órdenes posibles.

import assert from 'node:assert/strict';
import { after, before, test } from 'node:test';
import { runRace, NEW_PRICE, OLD_PRICE } from '../race.ts';
import type { Service } from '../src/service.ts';
import { closeService, createService, TEST_PREFIX, until } from './helpers.ts';

let service: Service;
before(async () => {
  service = await createService();
});
after(async () => {
  await closeService(service);
});

/** Todas las formas de mezclar dos secuencias sin cambiar el orden dentro de cada una. */
function interleavings(a: string[], b: string[]): string[][] {
  if (a.length === 0) return [b];
  if (b.length === 0) return [a];
  return [
    ...interleavings(a.slice(1), b).map((rest) => [a[0]!, ...rest]),
    ...interleavings(a, b.slice(1)).map((rest) => [b[0]!, ...rest]),
  ];
}

const READ_WRITE = interleavings(['L1', 'L2', 'L3'], ['E1', 'E2']);
const TWO_WRITERS = interleavings(['A1', 'A2'], ['B1', 'B2']);

test('borrando al escribir, la cache queda vieja solo si el lector leyó antes del cambio y guardó después del borrado', async () => {
  assert.equal(READ_WRITE.length, 10);
  const staleOrders: string[] = [];
  for (const steps of READ_WRITE) {
    const result = await runRace(service.db, service.cache, { steps });
    assert.equal(result.originPrice, NEW_PRICE);
    const expected = steps.indexOf('L2') < steps.indexOf('E1') && steps.indexOf('E2') < steps.indexOf('L3');
    assert.equal(result.stale, expected, steps.join(' '));
    if (result.stale) {
      assert.equal(result.cachedPrice, OLD_PRICE);
      staleOrders.push(steps.join(' '));
    }
  }
  assert.deepEqual(staleOrders, ['L1 L2 E1 E2 L3']);
});

test('el TTL acota la carrera: vencida la entrada, la cache deja de responder el precio viejo', async () => {
  const result = await runRace(service.db, service.cache, { steps: ['L1', 'L2', 'E1', 'E2', 'L3'], ttlMs: 150 });
  assert.equal(result.stale, true);
  assert.ok(result.ttlMs > 0 && result.ttlMs <= 150);
  const key = `${TEST_PREFIX}product:1:price`;
  await until(async () => (await service.cache.redis.get(key)) === null, 'que venza la entrada');
});

test('con un lease, ningún orden deja la cache vieja', async () => {
  for (const steps of READ_WRITE) {
    const result = await runRace(service.db, service.cache, { steps, lease: true });
    assert.equal(result.stale, false, steps.join(' '));
  }
});

test('dos escritores que actualizan la cache pueden dejarla con el valor que perdió', async () => {
  const staleOrders: string[] = [];
  for (const steps of TWO_WRITERS) {
    const result = await runRace(service.db, service.cache, { steps, writers: true, update: true });
    if (result.stale) staleOrders.push(steps.join(' '));
  }
  // El que escribió último en PostgreSQL no fue el último en escribir en la cache.
  assert.deepEqual(staleOrders.sort(), ['A1 B1 B2 A2', 'B1 A1 A2 B2']);
});

test('dos escritores que borran nunca la dejan vieja', async () => {
  for (const steps of TWO_WRITERS) {
    const result = await runRace(service.db, service.cache, { steps, writers: true });
    assert.equal(result.stale, false, steps.join(' '));
    assert.equal(result.cachedPrice, null);
  }
});

test('un orden imposible se rechaza', async () => {
  await assert.rejects(runRace(service.db, service.cache, { steps: ['L2', 'L1', 'L3', 'E1', 'E2'] }), /L1 antes que L2/);
  await assert.rejects(runRace(service.db, service.cache, { steps: ['L1', 'L2', 'L3'] }), /cada paso una vez/);
});
test/server.test.tsDescargar test/server.test.ts
// Qhatu por HTTP, con el servidor dentro del proceso de pruebas.

import assert from 'node:assert/strict';
import type { AddressInfo } from 'node:net';
import { after, before, test } from 'node:test';
import type { Server } from 'node:http';
import { createApp } from '../src/server.ts';
import type { Service } from '../src/service.ts';
import { closeService, createService } from './helpers.ts';

let service: Service;
let server: Server;
let base: string;

before(async () => {
  service = await createService({ cacheMode: 'single-flight' });
  server = createApp(service);
  await new Promise<void>((resolve) => server.listen(0, resolve));
  base = `http://localhost:${(server.address() as AddressInfo).port}`;
});
after(async () => {
  server.closeAllConnections();
  await new Promise((resolve) => server.close(resolve));
  await closeService(service);
});

const get = async (path: string): Promise<{ status: number; body: any }> => {
  const response = await fetch(base + path);
  return { status: response.status, body: await response.json() };
};

test('GET /products devuelve los 200 productos, y la segunda vez sin ir al origen', async () => {
  const first = await get('/products');
  assert.equal(first.status, 200);
  assert.equal(first.body.products.length, 200);
  const reads = service.db.originReads;
  await get('/products');
  assert.equal(service.db.originReads, reads);
});

test('GET /products/:id responde el producto, y 404 si no existe', async () => {
  const found = await get('/products/7');
  assert.equal(found.status, 200);
  assert.equal(found.body.product.id, 7);
  assert.equal((await get('/products/999999')).status, 404);
  assert.equal((await get('/nada')).status, 404);
});

test('después de una venta, el detalle y la lista muestran el stock nuevo', async () => {
  const before = (await get('/products/8')).body.product.stock;
  const sale = await fetch(`${base}/products/8/sales`, { method: 'POST', body: JSON.stringify({ quantity: 3 }) });
  assert.equal(sale.status, 201);
  assert.equal((await get('/products/8')).body.product.stock, before - 3);
  const list = (await get('/products')).body.products as { id: number; stock: number }[];
  assert.equal(list.find((p) => p.id === 8)!.stock, before - 3);
});

test('una venta sin cantidad válida responde 422', async () => {
  const sale = await fetch(`${base}/products/8/sales`, { method: 'POST', body: JSON.stringify({ quantity: 0 }) });
  assert.equal(sale.status, 422);
});

test('/health dice que el proceso vive y /ready que PostgreSQL responde', async () => {
  assert.deepEqual((await get('/health')).body, { status: 'ok' });
  assert.deepEqual((await get('/ready')).body, { status: 'ok', cache: 'ok' });
});
test/shards.test.tsDescargar test/shards.test.ts
// Lo que el capítulo afirma sobre sharding, comprobado con los datos de
// ejemplo de Tinkuy (semilla 7).

import assert from 'node:assert/strict';
import { after, before, test } from 'node:test';
import pg from 'pg';
import { evenRanges, loadEventSeats, SHARDS, type EventSeats } from '../shards/assign.ts';
import { distribute, hash32, shardByHash, shardByRange } from '../shards/hash.ts';
import { KEYS, schemes } from '../shards/rebalance.ts';
import { availabilityOfAllEvents, availableSeats, findOrder, loadCluster, paidOrders, seatsForSale, seatsOfEvent, type Cluster } from '../shards/scatter.ts';
import { TEST_DB } from './helpers.ts';

let pool: pg.Pool;
let events: EventSeats[];
let cluster: Cluster;
// Cada esquema recorre 100 000 claves: se calcula una sola vez.
const [modN, logical, consistent] = schemes(8, 9);

before(async () => {
  pool = new pg.Pool({ database: TEST_DB });
  events = await loadEventSeats(pool);
  cluster = await loadCluster(pool);
});
after(async () => {
  await pool.end();
});

test('el hash de una clave no cambia', () => {
  assert.equal(hash32(1), hash32('1'));
  assert.equal(hash32(1), 3301589560);
  assert.equal(shardByHash(1, 8), 0);
});

test('por rango, cada clave cae en el shard de su tramo', () => {
  const bounds = evenRanges(24, 8);
  assert.deepEqual(bounds, [3, 6, 9, 12, 15, 18, 21, 24]);
  assert.equal(shardByRange(1, bounds), 0);
  assert.equal(shardByRange(3, bounds), 0);
  assert.equal(shardByRange(4, bounds), 1);
  assert.equal(shardByRange(24, bounds), 7);
  assert.throws(() => shardByRange(25, bounds));
});

test('los datos de Tinkuy: 24 eventos, 13080 asientos, y el evento 1 tiene 2000', () => {
  assert.equal(events.length, 24);
  assert.equal(events.reduce((sum, e) => sum + e.seats, 0), 13080);
  assert.equal(events.find((e) => e.eventId === 1)!.seats, 2000);
});

test('ni por hash ni por rango se puede repartir el evento 1: su shard carga al menos sus 2000 asientos', () => {
  const byHash = distribute(events, SHARDS, (e) => shardByHash(e.eventId, SHARDS), (e) => e.seats);
  const byRange = distribute(events, SHARDS, (e) => shardByRange(e.eventId, evenRanges(24, SHARDS)), (e) => e.seats);
  for (const seats of [byHash, byRange]) {
    assert.equal(seats.reduce((sum, n) => sum + n, 0), 13080);
    assert.ok(Math.max(...seats) >= 2000);
  }
  // Con solo 24 claves, el hash no reparte parejo: el shard más cargado
  // tiene más de diez veces lo que el menos cargado.
  assert.ok(Math.max(...byHash) > 10 * Math.min(...byHash));
});

test('hash(k) mod n mueve casi todas las claves al pasar de 8 a 9 nodos', () => {
  assert.ok(modN!.move.moved / KEYS > 0.85, `se movió ${modN!.move.moved}`);
  // Y la mayoría de lo que se mueve va de un nodo viejo a otro nodo viejo.
  assert.ok(modN!.move.movedToNewNode < modN!.move.moved / 4);
});

test('con shards lógicos o consistent hashing se mueve cerca de 1/9, y solo hacia el nodo nuevo', () => {
  for (const { name, move } of [logical!, consistent!]) {
    const fraction = move.moved / KEYS;
    assert.ok(fraction > 0.08 && fraction < 0.15, `${name}: ${fraction}`);
    assert.equal(move.movedToNewNode, move.moved, `${name}: nada se mueve entre nodos viejos`);
  }
});

test('una consulta con event_id toca un shard y da lo mismo que la base de datos entera', async () => {
  cluster.touched = 0;
  const sharded = availableSeats(cluster, 1);
  assert.equal(cluster.touched, 1);
  const whole = await pool.query<{ n: number }>(`SELECT count(*)::int AS n FROM seats WHERE event_id = 1 AND status = 'available'`);
  assert.equal(sharded, whole.rows[0]!.n);

  cluster.touched = 0;
  assert.equal(seatsOfEvent(cluster, 1).length, 2000);
  assert.equal(seatsForSale(cluster, 1, [1001, 1002]).length, 2);
  const paid = await pool.query<{ n: number }>(`SELECT count(*)::int AS n FROM orders WHERE event_id = 2 AND status = 'paid'`);
  assert.equal(paidOrders(cluster, 2), paid.rows[0]!.n);
  assert.equal(cluster.touched, 3);
});

test('una consulta sin event_id les pregunta a los 8 shards', async () => {
  cluster.touched = 0;
  const availability = availabilityOfAllEvents(cluster);
  assert.equal(cluster.touched, 8);
  const whole = await pool.query<{ n: number }>(`SELECT count(*)::int AS n FROM seats WHERE status = 'available'`);
  assert.equal([...availability.values()].reduce((sum, n) => sum + n, 0), whole.rows[0]!.n);

  cluster.touched = 0;
  assert.equal(findOrder(cluster, 1)?.id, 1);
  assert.equal(cluster.touched, 8);
});
test/stampede.test.tsDescargar test/stampede.test.ts
// La estampida, sin depender del reloj: 30 lectores llegan mientras el origen
// todavía no respondió. El origen es una función que se queda detenida en una
// compuerta hasta que la prueba la abre.

import assert from 'node:assert/strict';
import { after, before, beforeEach, test } from 'node:test';
import { cacheAside, FRESH_SUFFIX, LOCK_SUFFIX } from '../src/cache.ts';
import type { Service } from '../src/service.ts';
import { cacheAsideSingleFlight } from '../src/single-flight.ts';
import { clearKeys, closeService, createGate, createService, TEST_PREFIX, until } from './helpers.ts';

const READERS = 30;
const OPTIONS = { staleMs: 60_000, lockMs: 5_000, pollMs: 5 };
let service: Service;

before(async () => {
  service = await createService();
});
beforeEach(async () => {
  await clearKeys(service.cache);
  Object.assign(service.cache.stats, { hits: 0, misses: 0, negativeHits: 0, staleServed: 0, errors: 0 });
});
after(async () => {
  await closeService(service);
});

test('cache-aside: los 30 lectores que no encuentran la entrada van todos al origen', async () => {
  const gate = createGate();
  let loads = 0;
  const load = async (): Promise<string> => {
    loads++;
    await gate.wait;
    return 'lista';
  };
  const readers = Array.from({ length: READERS }, () => cacheAside(service.cache, 'hot', 60_000, load));
  await until(() => loads === READERS, 'que los 30 lleguen al origen');
  gate.open();
  assert.deepEqual(new Set(await Promise.all(readers)), new Set(['lista']));
  assert.equal(loads, READERS);
});

test('single-flight con valor anterior: uno recalcula y 29 reciben el anterior sin esperar', async () => {
  // Una entrada vencida: el valor sigue ahí, la marca de vigencia ya no.
  await cacheAsideSingleFlight(service.cache, 'hot', 60_000, async () => 'anterior', OPTIONS);
  await service.cache.redis.del(TEST_PREFIX + 'hot' + FRESH_SUFFIX);

  const gate = createGate();
  let loads = 0;
  const load = async (): Promise<string> => {
    loads++;
    await gate.wait;
    return 'nueva';
  };
  const readers = Array.from({ length: READERS }, () => cacheAsideSingleFlight(service.cache, 'hot', 60_000, load, OPTIONS));

  // Los 29 responden mientras el origen sigue detenido.
  await until(() => service.cache.stats.staleServed === READERS - 1, 'que 29 reciban el valor anterior');
  assert.equal(loads, 1);
  gate.open();
  const values = await Promise.all(readers);
  assert.equal(values.filter((v) => v === 'anterior').length, READERS - 1);
  assert.equal(values.filter((v) => v === 'nueva').length, 1);
  assert.equal(loads, 1);

  // Y el siguiente lector ya encuentra la nueva, vigente.
  assert.equal(await cacheAsideSingleFlight(service.cache, 'hot', 60_000, load, OPTIONS), 'nueva');
  assert.equal(loads, 1);
});

test('single-flight con la cache vacía: uno recalcula y los demás esperan su resultado', async () => {
  const gate = createGate();
  let loads = 0;
  const load = async (): Promise<string> => {
    loads++;
    await gate.wait;
    return 'lista';
  };
  const readers = Array.from({ length: READERS }, () => cacheAsideSingleFlight(service.cache, 'cold', 60_000, load, OPTIONS));
  await until(() => loads === 1, 'que uno llegue al origen');
  await until(async () => (await service.cache.redis.exists(TEST_PREFIX + 'cold' + LOCK_SUFFIX)) === 1, 'que exista el lock');
  gate.open();
  assert.deepEqual(new Set(await Promise.all(readers)), new Set(['lista']));
  assert.equal(loads, 1);
  assert.equal(await service.cache.redis.exists(TEST_PREFIX + 'cold' + LOCK_SUFFIX), 0, 'el lock se soltó');
});

test('si quien tenía el lock se cae, el lock vence y otro recalcula', async () => {
  // Un lock que nadie va a soltar, como el de un proceso que murió a mitad.
  await service.cache.redis.set(TEST_PREFIX + 'orphan' + LOCK_SUFFIX, 'proceso-muerto', { PX: 200 });
  let loads = 0;
  const value = await cacheAsideSingleFlight(
    service.cache,
    'orphan',
    60_000,
    async () => {
      loads++;
      return 'lista';
    },
    OPTIONS,
  );
  assert.equal(value, 'lista');
  assert.equal(loads, 1);
});

test('soltar el lock no borra el lock de otro', async () => {
  const gate = createGate();
  const lockKey = TEST_PREFIX + 'slow' + LOCK_SUFFIX;
  const slow = cacheAsideSingleFlight(
    service.cache,
    'slow',
    60_000,
    async () => {
      await gate.wait;
      return 'lista';
    },
    OPTIONS,
  );
  await until(async () => (await service.cache.redis.exists(lockKey)) === 1, 'que exista el lock');
  // El lock del primero "vence" y lo toma otro proceso.
  await service.cache.redis.set(lockKey, 'otro-proceso', { PX: 5_000 });
  gate.open();
  await slow;
  assert.equal(await service.cache.redis.get(lockKey), 'otro-proceso');
});
test/tools.test.tsDescargar test/tools.test.ts
// El contador de consultas (tools/pg-queries.ts) y el error de la cache local.

import assert from 'node:assert/strict';
import { test } from 'node:test';
import { createInstance } from '../errors/local-cache.ts';
import { changePrice } from '../src/catalog.ts';
import { closeDb, connectDb } from '../src/db.ts';
import { bursts, parseLog } from '../tools/pg-queries.ts';
import { TEST_DB } from './helpers.ts';

const LOG = [
  '2026-11-16 06:38:00.280 UTC [164] arq_w11 LOG:  execute <unnamed>: SELECT p.id',
  '\t   FROM products p',
  "2026-11-16 06:38:00.280 UTC [164] arq_w11 DETAIL:  Parameters: $1 = '1'",
  '2026-11-16 06:38:00.290 UTC [165] arq_w11 LOG:  statement: SELECT 5',
  '2026-11-16 06:38:00.300 UTC [12]  LOG:  received SIGHUP, reloading configuration files',
  '2026-11-16 06:38:02.500 UTC [166] tinkuy LOG:  execute <unnamed>: SELECT 1',
  '2026-11-16 06:38:02.600 UTC [166] arq_w11 LOG:  statement: SELECT 6',
].join('\n');

test('parseLog saca las sentencias, con su base de datos y completas', () => {
  const queries = parseLog(LOG);
  assert.equal(queries.length, 4);
  assert.equal(queries[0]!.text, 'SELECT p.id FROM products p');
  assert.equal(queries[0]!.database, 'arq_w11');
  assert.equal(queries[2]!.database, 'tinkuy');
  assert.equal(queries[1]!.at - queries[0]!.at, 10);
});

test('bursts agrupa las consultas seguidas y separa las que llegan después de una pausa', () => {
  const queries = parseLog(LOG).filter((q) => q.database === 'arq_w11');
  assert.deepEqual(bursts(queries, 300), [
    { startMs: 0, count: 2, durationMs: 10 },
    { startMs: 2320, count: 1, durationMs: 0 },
  ]);
  assert.deepEqual(bursts([], 300), []);
});

test('cache en el proceso: después de un cambio, dos instancias responden precios distintos', async () => {
  const db = connectDb(TEST_DB);
  try {
    await changePrice(db, 2, 490);
    const a = createInstance('A', db);
    const b = createInstance('B', db);
    assert.equal(await a.getPrice(2), 490);
    assert.equal(await b.getPrice(2), 490);
    await a.setPrice(2, 550);
    assert.equal(await a.getPrice(2), 550);
    assert.equal(await b.getPrice(2), 490, 'B no se enteró del cambio');
    await changePrice(db, 2, 490);
  } finally {
    await closeDb(db);
  }
});

Laboratorio

Archivos de partida del laboratorio de la semana.

lab/cache-aside.tsDescargar lab/cache-aside.ts
// Módulo de cache del laboratorio: el punto de partida.
//
// Cópienlo a su Tinkuy (por ejemplo, a src/cache/cache-aside.ts) y complétenlo
// a medida que avanzan. Tal como está, ya se puede usar: ninguna función
// guarda nada todavía, así que todo va al origen y Tinkuy se comporta igual
// que antes. Cada PASO de los comentarios corresponde a un paso de la guía.
//
// Para saber si lo que escribieron cumple, en code/week-11:  make test-lab
//
// Convenciones: las claves llevan el prefijo w11: y los tiempos van en
// milisegundos. Lo que se guarda es JSON.

import { createClient } from 'redis';

export type RedisClient = ReturnType<typeof createClient>;

export type CacheStats = { hits: number; misses: number; staleServed: number; errors: number };

export type Cache = { redis: RedisClient; prefix: string; stats: CacheStats };

export async function connectCache(prefix = 'w11:'): Promise<Cache> {
  const redis = createClient({
    // Sin cola: si no hay conexión, cada comando falla al instante en vez de
    // quedarse esperando a que Redis vuelva.
    disableOfflineQueue: true,
    socket: { connectTimeout: 500, reconnectStrategy: (retries: number) => Math.min(1000, 50 * 2 ** retries) },
  }) as RedisClient;
  // Sin este listener, un error de conexión tumba el proceso.
  redis.on('error', () => {});
  await redis.connect();
  return { redis, prefix, stats: { hits: 0, misses: 0, staleServed: 0, errors: 0 } };
}

export async function closeCache(cache: Cache): Promise<void> {
  if (cache.redis.isReady) await cache.redis.quit();
  else cache.redis.destroy();
}

/**
 * Cache-aside: busca `key`; si no está, llama a `load`, guarda el resultado
 * con un TTL de `ttlMs` y lo devuelve.
 */
export async function cacheAside<T>(cache: Cache, key: string, ttlMs: number, load: () => Promise<T>): Promise<T> {
  // PASO 3. Tres cosas, en este orden:
  //   1. GET de cache.prefix + key. Si está, contar un hit y devolver el valor.
  //   2. Si no está, contar un miss y llamar a load().
  //   3. SET del resultado con PX: ttlMs, y devolverlo.
  //
  // PASO 8. ¿Qué pasa aquí si Redis no responde? Decidan qué debe recibir
  // quien llama, y cuenten el error en cache.stats.errors.
  void ttlMs;
  void key;
  cache.stats.misses++;
  return load();
}

/** Borra entradas. Se llama después de escribir en el origen. */
export async function invalidate(cache: Cache, ...keys: string[]): Promise<void> {
  // PASO 4. DEL de cada clave (con su prefijo). Si usan el paso 7, borren
  // también lo que ese paso guarde aparte.
  void cache;
  void keys;
}

export type SingleFlightOptions = {
  /** Cuánto más que el TTL se conserva el valor, para servirlo como anterior. */
  staleMs: number;
  /** Cuánto dura el lock si quien recalcula no lo suelta. */
  lockMs: number;
};

/**
 * Como cacheAside, pero cuando la entrada vence solo una petición llama a
 * `load`; las demás reciben el valor anterior.
 */
export async function cacheAsideSingleFlight<T>(
  cache: Cache,
  key: string,
  ttlMs: number,
  load: () => Promise<T>,
  options: SingleFlightOptions,
): Promise<T> {
  // PASO 7. Decisiones que tienen que tomar:
  //   - Cómo distinguir "vigente" de "vencido pero todavía disponible". Si la
  //     entrada desaparece al vencer, no hay valor anterior que servir.
  //   - Quién recalcula: SET <clave del lock> <token> NX PX lockMs. Solo uno
  //     recibe OK.
  //   - Qué recibe el que no obtuvo el lock: el valor anterior si lo hay
  //     (cuenten staleServed). ¿Y si no lo hay?
  //   - Soltar el lock al terminar, sin borrar el de otro.
  void options;
  return cacheAside(cache, key, ttlMs, load);
}

Compilación

Cómo se compilan y ejecutan los ejemplos.

MakefileDescargar Makefile
# Semana 11: sharding, cache y escalabilidad. El ejemplo es Qhatu, el catálogo
# de una bodega en línea: se lee mucho más de lo que se escribe.
# Se usa dentro del contenedor del curso.
#
#   make              crea la base de datos arq_w11 (Qhatu y una copia de los datos
#                     de ejemplo de Tinkuy) y borra las claves w11:* de Redis
#   make start        levanta Qhatu en http://localhost:3000 (ver las variables abajo)
#   make load         k6: 50 usuarios mirando el catálogo durante 15 segundos
#   make compare      mide Qhatu sin cache, con cache-aside y con single-flight
#   make race         la carrera entre una lectura y una escritura (race.ts)
#   make stampede     cuenta las consultas que llegan a PostgreSQL cuando vence la lista,
#                     con cache-aside y con single-flight
#   make jitter       1000 entradas guardadas a la vez: cuándo vencen sin y con jitter
#   make negative     200 pedidos de un producto que no existe, sin y con cache negativa
#   make eviction    qué hace Redis cuando se llena: noeviction y allkeys-lru
#   make redis-down   mata Redis con la carga corriendo (CACHE_FAILURE=open o closed)
#   make local-cache  el error de la semana: cache en el proceso con dos instancias
#   make shards       reparte los eventos y asientos de Tinkuy en 8 shards, por hash y por rango
#   make rebalance    cuántas claves se mueven al pasar de 8 a 9 nodos, con tres esquemas
#   make scatter      qué consultas de Tinkuy tocan un shard y cuáles todos
#   make test         revisa los tipos (tsc) y corre las pruebas (test/*.test.ts)
#   make test-lab     corre las pruebas del módulo del laboratorio (lab/cache-aside.ts)
#   make clean        borra las bases de datos, las claves w11:* y build/
#
# Para contar consultas en PostgreSQL desde otra aplicación (el laboratorio):
#   make pg-on                              empieza a registrar las consultas
#   make pg-report DB=tinkuy MATCH='FROM events'   cuántas hubo y en qué ráfagas
#   make pg-off                             deja de registrar
#
# Variables de make start:
#   CACHE_MODE=off|aside|single-flight   por omisión, aside
#   LIST_TTL_MS=5000  DETAIL_TTL_MS=30000  NEGATIVE_TTL_MS=5000  JITTER=0.1
#   INVALIDATE=off        las escrituras no borran nada de la cache
#   CACHE_FAILURE=closed  un error de Redis llega a quien llama
#   STATS_LOG=1           una línea de estadísticas por segundo

TINKUY ?= ../../tinkuy
DB ?= arq_w11
MATCH ?= SELECT
GAP ?= 300
# psql no avisa cuando la base de datos que se va a borrar todavía no existe.
PGOPTIONS = --client-min-messages=warning
export PGOPTIONS

.PHONY: all db start load compare race stampede jitter negative eviction redis-down local-cache \
        shards rebalance scatter pg-on pg-report pg-off test test-lab clean

all: db

# Nada de esto modifica el Tinkuy del curso (../../tinkuy): se trabaja sobre una copia.
build/tinkuy:
	mkdir -p build
	cp -r $(TINKUY) $@

# En arq_w11 viven las tablas de Qhatu y, para los ejercicios de sharding, los
# datos de ejemplo de Tinkuy (semilla 7), cargados por su propio programa.
db: build/tinkuy
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS arq_w11 WITH (FORCE)" -c "CREATE DATABASE arq_w11"
	@psql -q -d arq_w11 -v ON_ERROR_STOP=1 -f db/schema.sql -f db/seed.sql
	@psql -q -d arq_w11 -v ON_ERROR_STOP=1 -f build/tinkuy/db/schema.sql
	@cd build/tinkuy && TINKUY_DB=arq_w11 node db/seed.ts --seed 7 >/dev/null
	@node tools/flush.ts
	@psql -q -d arq_w11 -At -c "SELECT 'Qhatu: ' || (SELECT count(*) FROM products) || ' productos, ' || (SELECT count(*) FROM stock_movements) || ' movimientos de stock. Tinkuy: ' || (SELECT count(*) FROM events) || ' eventos, ' || (SELECT count(*) FROM seats) || ' asientos.'"

start:
	node src/main.ts

load:
	k6 run --quiet load/browse.js

compare:
	@bash tools/compare.sh

race:
	node race.ts L1 L2 E1 E2 L3

stampede:
	@bash tools/stampede.sh

jitter:
	@node tools/jitter.ts

negative:
	@node tools/negative.ts

eviction:
	@node tools/eviction.ts

redis-down:
	@bash tools/redis-down.sh

local-cache:
	@node errors/local-cache.ts

shards:
	@node shards/assign.ts

rebalance:
	@node shards/rebalance.ts

scatter:
	@node shards/scatter.ts

pg-on:
	@node tools/pg-queries.ts on

pg-report:
	@node tools/pg-queries.ts report --db "$(DB)" --match "$(MATCH)" --gap $(GAP)

pg-off:
	@node tools/pg-queries.ts off

# Las pruebas usan su propia base de datos y su propio prefijo de Redis, y
# levantan el servidor dentro del proceso: no necesitan nada corriendo ni
# tocan los datos de make start. Comparten la base, así que van una tras otra.
# La solución del laboratorio se prueba solo si está en la carpeta.
test: build/tinkuy
	tsc -p .
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS arq_w11_test WITH (FORCE)" -c "CREATE DATABASE arq_w11_test"
	@psql -q -d arq_w11_test -v ON_ERROR_STOP=1 -f db/schema.sql -f db/seed.sql
	@psql -q -d arq_w11_test -v ON_ERROR_STOP=1 -f build/tinkuy/db/schema.sql
	@cd build/tinkuy && TINKUY_DB=arq_w11_test node db/seed.ts --seed 7 >/dev/null
	W11_DB=arq_w11_test W11_PREFIX=w11:test: node --test --test-concurrency=1 "test/*.test.ts"

test-lab:
	W11_PREFIX=w11:lab: CACHE_MODULE=lab node --test --test-concurrency=1 test/cache-module.test.ts

clean:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS arq_w11 WITH (FORCE)" -c "DROP DATABASE IF EXISTS arq_w11_test WITH (FORCE)"
	@node tools/flush.ts || true
	rm -rf build
package.jsonDescargar package.json
{
  "name": "week-11",
  "private": true,
  "type": "module"
}
tsconfig.jsonDescargar tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["src", "tools", "shards", "errors", "lab", "solution", "test", "race.ts"]
}