13
Datos y sistemas distribuidos

Mensajería, eventos y consistencia

Datos y sistemas distribuidos

Semana 13 — Mensajería, eventos y consistencia

Objetivos

  • Comparar una cola de mensajes con un log, y elegir entre ellos según el orden, la retención y la forma de repartir el trabajo que un caso necesita.
  • Explicar las garantías de entrega (at-most-once, at-least-once) y por qué exactly-once se consigue con idempotencia y no con el broker solo.
  • Describir event sourcing y CQRS, y decir qué problema resuelve cada uno y qué complejidad agrega.
  • Distinguir los modelos de consistencia que un diseño puede ofrecer (linealizable, eventual) y explicar qué decide el consenso y por qué no se implementa a mano.

Sesión A — Mensajería: colas y logs, garantías de entrega y orden

Lecturas:

  • Kleppmann y Riccomini, Designing Data-Intensive Applications (2.ª ed.), cap. 12 Stream Processing: las secciones sobre sistemas de mensajería y sobre logs particionados.
  • Lectura libre: Kreps, Narkhede y Rao, Kafka: a Distributed Messaging System for Log Processing (2011), secciones 1 a 3.

Lecturas complementarias:

Temas:

  • Por qué poner un broker en medio: el productor no necesita que el consumidor esté arriba ni que sea rápido. El broker absorbe los picos (los mensajes esperan), desacopla en el tiempo y permite varios consumidores. A cambio, es un componente más que operar y del que depender, y quien publica deja de saber cuándo se procesó su mensaje.
  • Las dos preguntas que distinguen a los sistemas de mensajería: ¿qué pasa si el productor es más rápido que el consumidor? (descartar, encolar, o frenar al productor: backpressure) y ¿qué pasa si un nodo cae? (¿se pierden mensajes?).
  • Cola (el modelo de AMQP y de los brokers tradicionales): el broker asigna cada mensaje a un consumidor y lo borra cuando recibe la confirmación. Varios consumidores se reparten el trabajo (consumidores que compiten). Si uno no confirma, el mensaje se entrega a otro, y el orden deja de estar garantizado.
  • Log (el modelo de Kafka): los mensajes se agregan al final de un log que se conserva. Cada consumidor lleva su posición, el offset, y avanza a su ritmo. Leer no borra: un consumidor nuevo puede empezar desde el principio, y uno que falló puede volver atrás. El orden se garantiza dentro de una partición; para repartir el trabajo, el log se parte por clave y cada partición la lee un solo consumidor de cada consumer group.
  • Qué se elige. Cola: tareas independientes y caras, donde importa repartir y no el orden (enviar correos, generar un PDF). Log: cuando importa el orden por clave, cuando varios sistemas necesitan los mismos eventos, o cuando hay que poder reprocesar.
  • NATS JetStream, el broker del curso: un stream guarda los mensajes de un conjunto de subjects; un consumer lleva la posición y las confirmaciones de quien lee. Según la configuración se comporta como log (retención por límites, varios consumers independientes) o como cola (retención por trabajo, un consumer compartido).
  • Garantías de entrega. At-most-once (a lo más una vez): se envía y no se reintenta; puede perderse. At-least-once (al menos una vez): se reintenta hasta recibir la confirmación; puede duplicarse, porque la confirmación también se pierde. Exactly-once, como efecto: entrega at-least-once más un consumidor idempotente (semana 12). El broker no puede darla solo, porque no controla el efecto del consumidor.
  • Cuándo confirma el consumidor: antes de procesar (si muere, el mensaje se pierde) o después (si muere, se repite). Para no perder trabajo, después; por eso el procesamiento debe ser idempotente.
  • Orden: garantizado solo dentro de una partición o de un subject con un único consumidor activo. Con reintentos, un mensaje antiguo puede llegar después de uno nuevo. Diseñar para el desorden: clave de partición por entidad (todos los eventos de una orden van juntos), números de versión, o eventos que se pueden aplicar en cualquier orden.
  • Mensajes que nunca se procesan: tras varios intentos van a una dead letter queue, donde alguien los mira. Sin eso, un mensaje envenenado bloquea a los que vienen detrás o se reintenta para siempre.
  • En Tinkuy (P4): OrderPaid sale de la outbox a un stream; los consumidores de notificaciones y de reportes llevan cada uno su posición.
  • Error común: suponer que los mensajes llegan una vez y en orden porque en las pruebas siempre fue así. En las pruebas nada falla.
  • Error común: una cola sin límite. No elimina la sobrecarga; la esconde hasta que la memoria se acaba, y mientras tanto la latencia crece sin tope.

Sesión B — Event sourcing y CQRS · Consistencia y consenso para quien diseña

Lecturas:

  • Designing Data-Intensive Applications (2.ª ed.), cap. 3, la sección Event Sourcing and CQRS, y cap. 10 Consistency and Consensus: Linearizability y la introducción de Consensus.
  • Lectura libre: Martin Kleppmann, Please stop calling databases CP or AP (2015).

Lecturas complementarias:

Temas:

  • Event sourcing: en vez de guardar el estado actual y sobrescribirlo, se guarda la secuencia de eventos que lo produjeron (SeatReserved, OrderPaid, OrderRefunded), que nunca se modifican. El estado actual es un dato derivado: se obtiene aplicando los eventos en orden.
  • Lo que da: historia completa y auditable, la posibilidad de reconstruir el estado de cualquier momento, y de crear vistas nuevas a partir de eventos antiguos. Lo que cuesta: leer exige una vista materializada; los eventos son un contrato que vive para siempre (su evolución, semana 9); corregir un error es agregar otro evento, y borrar datos personales es difícil. Se justifica en dominios donde la historia es el negocio (contabilidad, pagos, inventario), no como estilo por defecto.
  • Evento y comando, de nuevo: un comando puede rechazarse; un evento ya ocurrió. Se valida el comando y, si pasa, se registra el evento.
  • CQRS: separar el modelo con que se escribe del modelo con que se lee. Las escrituras van a un modelo normalizado que protege los invariantes; las lecturas, a una o más vistas hechas para sus consultas, actualizadas a partir de los cambios. Sirve cuando leer y escribir tienen formas o cargas muy distintas. El precio: las vistas van atrasadas, así que hay consistencia eventual entre escribir y leer (el mismo problema que con una réplica, semana 10).
  • No van siempre juntos: se puede tener CQRS sin event sourcing (una vista de lectura alimentada por la outbox) y es lo más frecuente. En Tinkuy: el reporte de ventas como una vista que se actualiza con OrderPaid, en vez de una consulta pesada sobre las tablas transaccionales.
  • Consistencia: la palabra tiene varios significados (la C de ACID, la de las réplicas). Aquí: qué tan actual y coherente es lo que se lee de un sistema con varias copias.
  • Linealizabilidad: el sistema se comporta como si hubiera una sola copia y cada operación ocurriera en un instante entre su inicio y su fin. Una vez que alguien leyó un valor nuevo, nadie lee después uno viejo. Dónde hace falta de verdad: elegir un líder, hacer cumplir una restricción de unicidad (un asiento, un nombre de usuario), un lock distribuido. Dónde no: casi todo lo demás.
  • Lo que cuesta: latencia (hay que coordinar) y disponibilidad. Si la red se parte, una réplica que no puede hablar con las demás tiene que elegir entre responder con lo que tiene (y dejar de ser linealizable) o no responder (y dejar de estar disponible). Eso, y nada más, es lo que dice el teorema CAP. No sirve para clasificar bases de datos en dos casilleros: la mayoría no es ni lo uno ni lo otro, y en operación normal el trade-off real es entre consistencia y latencia.
  • Consenso: que varios nodos se pongan de acuerdo en un valor, o en un orden de operaciones, aunque algunos fallen. Es lo que hay detrás de elegir un líder sin split brain. Los algoritmos (Raft, Paxos) necesitan una mayoría para avanzar: con cinco nodos toleran dos caídos, y la parte minoritaria de una red partida se detiene.
  • Para quien diseña: el consenso no se implementa; se usa a través de un componente que ya lo resuelve (la base de datos, etcd, el propio broker). La decisión de arquitectura es qué datos lo necesitan, y mantenerlos pocos.
  • Diseñar con consistencia eventual: decir qué ve el usuario mientras tanto. “Su compra está en proceso” es una respuesta honesta; una pantalla que muestra un saldo viejo sin avisar no lo es.
  • Error común: aplicar event sourcing a todo el sistema. Se adopta por agregado, donde la historia importa.
  • Error común: pedir consistencia fuerte “por si acaso”. Cada dato que la exige ata la disponibilidad del sistema a la de un quórum.

Laboratorio — Outbox y consumidor idempotente con NATS JetStream

Referencias: NATS, JetStream y Consumers; Richardson, Transactional outbox. Material: code/week-13/. En parejas.

  1. Primer contacto: crear un stream W13_ORDERS para los subjects w13.orders.>, publicar tres mensajes con nats pub y leerlos con un consumer. Ver el estado con nats stream info y nats consumer info: mensajes guardados, entregados y pendientes de confirmación.
  2. Log o cola: crear dos consumers independientes sobre el mismo stream y comprobar que cada uno recibe todos los mensajes. Después, dos procesos que comparten un consumer: comprobar que se reparten los mensajes.
  3. El problema de la escritura doble: el programa errors/dual-write.ts guarda la orden y publica el evento. Correrlo cien veces con CRASH_BETWEEN=1, que mata el proceso entre las dos operaciones, y otras cien con CRASH_BETWEEN=0.5, que lo mata la mitad de las veces. Contar las órdenes guardadas y los eventos publicados en cada caso.
  4. Outbox: completar lab/outbox.ts para que el evento se inserte en la tabla outbox en la misma transacción que la orden, y lab/relay.ts para que publique lo pendiente y lo marque como enviado. Repetir las dos pruebas del paso 3: las cuentas deben coincidir también cuando el proceso muere la mitad de las veces.
  5. Duplicados: matar el relay justo después de publicar y antes de marcar (CRASH_AFTER_PUBLISH=1). Al reiniciarlo, ¿cuántas veces se publica ese evento? ¿Qué garantía de entrega tienen?
  6. Consumidor no idempotente: el consumidor de puntos suma 10 puntos por cada OrderPaid. Con los duplicados del paso anterior, ¿cuántos puntos tiene el comprador? Hacerlo idempotente guardando el id del evento procesado en la misma transacción que la suma.
  7. Reintentos y dead letter: hacer que el consumidor falle siempre con un mensaje concreto. Configurar el número máximo de entregas y observar qué pasa con ese mensaje y con los siguientes. Registrar el mensaje descartado en una tabla para revisarlo.
  8. Reprocesar: crear un consumer nuevo que lea el stream desde el principio y reconstruya, desde cero, la tabla del reporte de ventas. Comparar con la tabla original. ¿Qué tendría que cumplir el consumidor para que esto sea seguro?

Entregas

Sin entregas esta semana. P4 se entrega en la semana 14.

Preguntas de repaso

  1. Den un caso para una cola y otro para un log, y la propiedad que decide en cada uno.
  2. Un consumidor confirma el mensaje antes de procesarlo y el proceso muere a la mitad. ¿Qué garantía de entrega tiene el sistema? ¿Y si confirma después?
  3. ¿Por qué el broker no puede garantizar por sí solo exactly-once, es decir, que un efecto ocurra una sola vez?
  4. Los eventos OrderPaid y OrderRefunded de la misma orden llegan en orden inverso. Den dos formas de diseñar para que eso no rompa nada.
  5. ¿Qué problema resuelve CQRS y qué anomalía introduce? Relaciónenla con el retraso de replicación.
  6. Den un dato de Tinkuy que necesita linealizabilidad y dos que no. ¿Qué pagaría el sistema por pedírsela a los tres?

Código de la semana

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

Ejemplos (31)Errores (2)Pruebas (9)Laboratorio (6)Compilación (3)

Ejemplos

Los programas que usan los apuntes y la clase.

consensus/majority.tsDescargar consensus/majority.ts
// La aritmética de las mayorías, que es todo lo que un diseño necesita saber
// del consenso para contar nodos.

/** El menor número de nodos que es más de la mitad de n. */
export function majority(n: number): number {
  return Math.floor(n / 2) + 1;
}

/** Cuántos nodos pueden fallar sin que los demás dejen de formar una mayoría. */
export function tolerated(n: number): number {
  return n - majority(n);
}
consumers/dead-letter.tsDescargar consumers/dead-letter.ts
import type { Delivery } from '../shared/bus.ts';
import { db } from '../shared/db.ts';
import type { OrderPaid } from '../shared/events.ts';

// La dead letter de la semana es una tabla: ahí queda el mensaje que un
// consumidor dejó de intentar, con el motivo, para que una persona lo revise.

/** Devuelve la función que `startConsumer` llama cuando se agotan las entregas. */
export function recordDeadLetter(consumer: string) {
  return async (event: OrderPaid, delivery: Delivery, error: unknown): Promise<void> => {
    // ON CONFLICT: si el proceso muere después de registrar y antes de
    // descartar el mensaje, la siguiente entrega no lo registra dos veces.
    await db().query(
      `INSERT INTO dead_letters (consumer, stream_seq, subject, payload, deliveries, reason)
       VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (consumer, stream_seq) DO NOTHING`,
      [consumer, delivery.streamSeq, delivery.subject, JSON.stringify(event), delivery.deliveryCount, String(error)],
    );
  };
}
consumers/replay.tsDescargar consumers/replay.ts
import { consumerInfo, deleteConsumer, startConsumer, streamState } from '../shared/bus.ts';
import { db } from '../shared/db.ts';
import { setTimeout as sleep } from 'node:timers/promises';
import { addToSalesReport, type ReportTarget } from './report.ts';

// Reprocesar: un consumer nuevo lee el stream desde el primer mensaje y
// reconstruye el reporte de ventas en otra tabla, sales_report_rebuilt. El
// consumer `report` y su tabla no se tocan.

const REBUILD: ReportTarget = { table: 'sales_report_rebuilt', consumer: 'report-rebuild' };

/** Reconstruye sales_report_rebuilt desde cero. Devuelve cuántos mensajes leyó. */
export async function rebuildSalesReport(): Promise<number> {
  // Desde cero de verdad: la tabla vacía, sin memoria de eventos procesados y
  // con un consumer recién creado, que empieza en la secuencia 1.
  await db().query('TRUNCATE sales_report_rebuilt');
  await db().query('DELETE FROM processed_events WHERE consumer = $1', [REBUILD.consumer]);
  await deleteConsumer(REBUILD.consumer);

  const { messages } = await streamState();
  const consumer = await startConsumer(REBUILD.consumer, (event) => addToSalesReport(event, REBUILD));
  try {
    // Termina cuando el consumer ya no tiene nada por entregar ni por confirmar.
    for (;;) {
      const info = await consumerInfo(REBUILD.consumer);
      if (info.num_pending === 0 && info.num_ack_pending === 0) break;
      await sleep(20);
    }
  } finally {
    await consumer.stop();
  }
  return messages;
}

export type ReportDifference = { concert_id: number; table: string; orders: number; tickets: number; revenue_cents: number };

/** Las filas que están en una tabla y no en la otra. Vacío: las dos son iguales. */
export async function compareReports(): Promise<ReportDifference[]> {
  const result = await db().query<ReportDifference>(
    `(SELECT concert_id, 'sales_report' AS table, orders, tickets, revenue_cents::int AS revenue_cents
        FROM (SELECT * FROM sales_report EXCEPT SELECT * FROM sales_report_rebuilt) only_original)
     UNION ALL
     (SELECT concert_id, 'sales_report_rebuilt', orders, tickets, revenue_cents::int
        FROM (SELECT * FROM sales_report_rebuilt EXCEPT SELECT * FROM sales_report) only_rebuilt)
     ORDER BY concert_id, 2`,
  );
  return result.rows;
}
consumers/report.tsDescargar consumers/report.ts
import { inTransaction } from '../shared/db.ts';
import type { OrderPaid } from '../shared/events.ts';

// El consumidor del reporte de ventas: una fila por concierto con el número
// de órdenes, de entradas y lo recaudado. Es una vista de lectura: se arma
// solo con lo que traen los eventos, sin consultar la tabla orders.
//
// Es idempotente. El id del evento se inserta en processed_events en la misma
// transacción que la suma: si la transacción se confirma, quedan las dos
// cosas; si no, ninguna. Un evento repetido encuentra su id y no suma.

export type ReportTarget = {
  /** La tabla donde se acumula: la del reporte o la de la reconstrucción. */
  table: 'sales_report' | 'sales_report_rebuilt';
  /** El nombre con que este consumidor anota lo que ya procesó. */
  consumer: string;
};

export const SALES_REPORT: ReportTarget = { table: 'sales_report', consumer: 'report' };

export async function addToSalesReport(event: OrderPaid, target: ReportTarget = SALES_REPORT): Promise<void> {
  await inTransaction(async (client) => {
    const first = await client.query(
      'INSERT INTO processed_events (consumer, event_id) VALUES ($1, $2) ON CONFLICT DO NOTHING',
      [target.consumer, event.id],
    );
    if (first.rowCount === 0) return; // ya se procesó: no se suma de nuevo

    // El nombre de la tabla sale de la unión de arriba, nunca de un dato externo.
    await client.query(
      `INSERT INTO ${target.table} (concert_id, orders, tickets, revenue_cents) VALUES ($1, 1, $2, $3)
       ON CONFLICT (concert_id) DO UPDATE SET
         orders = ${target.table}.orders + 1,
         tickets = ${target.table}.tickets + EXCLUDED.tickets,
         revenue_cents = ${target.table}.revenue_cents + EXCLUDED.revenue_cents`,
      [event.concertId, event.quantity, event.totalCents],
    );
  });
}
db/schema.sqlDescargar db/schema.sql
-- Semana 13: una aplicación pequeña de venta de entradas para conciertos. No
-- es el esquema de Tinkuy: tiene lo justo para estudiar la outbox, los
-- consumidores idempotentes y el reprocesamiento.

-- Lo que es del servicio de órdenes.
CREATE TABLE concerts (
    id          integer PRIMARY KEY,
    title       text NOT NULL,
    price_cents integer NOT NULL CHECK (price_cents > 0)
);

CREATE TABLE orders (
    id          integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    concert_id  integer NOT NULL REFERENCES concerts (id),
    buyer_email text NOT NULL,
    quantity    integer NOT NULL CHECK (quantity BETWEEN 1 AND 6),
    total_cents integer NOT NULL,
    status      text NOT NULL CHECK (status IN ('paid')),
    created_at  timestamptz NOT NULL DEFAULT now()
);

-- La outbox: los eventos que el servicio de órdenes todavía debe publicar.
-- Vive en la misma base de datos que orders, y por eso una transacción puede
-- escribir en las dos. published_at es NULL mientras el relay no lo publicó.
CREATE TABLE outbox (
    id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    event_id     uuid NOT NULL UNIQUE,
    subject      text NOT NULL,
    payload      jsonb NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now(),
    published_at timestamptz
);

-- El relay solo busca lo pendiente: un índice parcial lo mantiene barato
-- aunque la tabla crezca.
CREATE INDEX outbox_pending ON outbox (id) WHERE published_at IS NULL;

-- Lo que es de cada consumidor. Ninguna de estas tablas tiene una clave
-- foránea hacia orders: cada consumidor guarda lo suyo y podría vivir en otra
-- base de datos.

-- Programa de puntos: el saldo de cada comprador.
CREATE TABLE loyalty_points (
    buyer_email text PRIMARY KEY,
    points      integer NOT NULL
);

-- Reportes: el acumulado de ventas por concierto. sales_report_rebuilt tiene
-- la misma forma: ahí escribe el consumidor que reconstruye el reporte.
CREATE TABLE sales_report (
    concert_id    integer PRIMARY KEY,
    orders        integer NOT NULL,
    tickets       integer NOT NULL,
    revenue_cents bigint NOT NULL
);

CREATE TABLE sales_report_rebuilt (LIKE sales_report INCLUDING ALL);

-- Los eventos que cada consumidor ya procesó. La fila se inserta en la misma
-- transacción que el efecto: o están las dos cosas o ninguna.
CREATE TABLE processed_events (
    consumer     text NOT NULL,
    event_id     uuid NOT NULL,
    processed_at timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (consumer, event_id)
);

-- Los mensajes que un consumidor dejó de intentar, para que alguien los revise.
CREATE TABLE dead_letters (
    id          integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    consumer    text NOT NULL,
    stream_seq  bigint NOT NULL,
    subject     text NOT NULL,
    payload     jsonb NOT NULL,
    deliveries  integer NOT NULL,
    reason      text NOT NULL,
    recorded_at timestamptz NOT NULL DEFAULT now(),
    UNIQUE (consumer, stream_seq)
);

INSERT INTO concerts (id, title, price_cents) VALUES
    (1, 'Killa Sónica en el Estadio Nacional', 16000),
    (2, 'Los Apus en Arequipa', 9000),
    (3, 'Noche de cumbia en Trujillo', 4500);
demos/ack-timing.tsDescargar demos/ack-timing.ts
import { spawn } from 'node:child_process';
import { closeBus, deleteStream, ensureConsumer } from '../shared/bus.ts';
import { freshStreamWith, untilIdle } from './helpers.ts';

// ¿Cuándo confirma el consumidor? Cinco mensajes y un proceso (tools/worker.ts)
// que muere mientras procesa el tercero. Después se inicia otro proceso con
// el mismo consumer. Se hace dos veces: confirmando antes de procesar y
// confirmando después.

type Run = { output: string[]; done: Promise<void>; stop(): void };

function startWorker(consumer: string, env: Record<string, string>): Run {
  const child = spawn('node', ['tools/worker.ts', consumer], { env: { ...process.env, ...env } });
  const output: string[] = [];
  child.stdout.on('data', (chunk: Buffer) => output.push(...chunk.toString().trimEnd().split('\n')));
  const done = new Promise<void>((resolve) => child.once('exit', () => resolve()));
  return { output, done, stop: () => child.kill('SIGTERM') };
}

/** Las secuencias que algún proceso terminó de procesar. */
function processed(lines: string[]): number[] {
  return lines.flatMap((line) => (/seq (\d+): orden \d+ procesada/.exec(line) ?? []).slice(1).map(Number));
}

async function scenario(title: string, consumer: string, env: Record<string, string>): Promise<void> {
  console.log(`\n== ${title}`);
  await freshStreamWith(5);
  await ensureConsumer(consumer);

  const first = startWorker(consumer, { ...env, CRASH_ON_SEQ: '3' });
  await first.done; // muere solo, en el mensaje 3
  console.log('-- primer proceso (muere mientras procesa la secuencia 3)');
  console.log(first.output.join('\n'));

  const second = startWorker(consumer, env);
  await untilIdle(consumer);
  second.stop();
  await second.done;
  console.log('-- segundo proceso, con el mismo consumer');
  console.log(second.output.join('\n') || '(no recibió nada)');

  const all = processed([...first.output, ...second.output]).sort((a, b) => a - b);
  const lost = [1, 2, 3, 4, 5].filter((seq) => !all.includes(seq));
  console.log(`-- procesados: ${all.join(' ')}; perdidos: ${lost.join(' ') || 'ninguno'}`);
}

await scenario('Confirmar ANTES de procesar (ACK_FIRST=1)', 'ack-first', { ACK_FIRST: '1' });
await scenario('Confirmar DESPUÉS de procesar', 'ack-last', {});
await deleteStream();
await closeBus();
demos/helpers.tsDescargar demos/helpers.ts
import { setTimeout as sleep } from 'node:timers/promises';
import { consumerInfo, deleteStream, ensureStream, publish } from '../shared/bus.ts';
import { newOrderPaid } from '../shared/events.ts';
import { settings } from '../shared/settings.ts';

// Lo que comparten los programas de demos/. Todos trabajan sobre el stream
// que diga W13_STREAM; el Makefile les pone W13_DEMO para no tocar W13_ORDERS.

/** Deja el stream vacío y publica `n` eventos OrderPaid: las órdenes 1 a n. */
export async function freshStreamWith(n: number): Promise<void> {
  await deleteStream();
  await ensureStream();
  for (let orderId = 1; orderId <= n; orderId += 1) {
    await publish(
      settings.subjects.paid,
      newOrderPaid({ orderId, concertId: 1, buyerEmail: 'rosa.quispe@correo.pe', quantity: 1, totalCents: 16000 }),
    );
  }
}

/** Espera a que el consumer no tenga nada por entregar ni por confirmar. */
export async function untilIdle(consumer: string): Promise<void> {
  for (;;) {
    const info = await consumerInfo(consumer);
    if (info.num_pending === 0 && info.num_ack_pending === 0) return;
    await sleep(50);
  }
}
demos/limits.tsDescargar demos/limits.ts
import { DiscardPolicy } from 'nats';
import { closeBus, connectBus } from '../shared/bus.ts';

// Una cola sin límite no existe: o el límite lo eligen ustedes, o lo elige el
// disco. Un stream con lugar para cinco mensajes recibe ocho, con las dos
// políticas de JetStream para cuando se llena.

const STREAM = 'W13_DEMO_LIMITS';
const { js, jsm } = await connectBus();

for (const discard of [DiscardPolicy.Old, DiscardPolicy.New]) {
  await jsm.streams.delete(STREAM).catch(() => undefined);
  await jsm.streams.add({ name: STREAM, subjects: ['w13limits.>'], max_msgs: 5, discard });
  console.log(`== max_msgs = 5, discard = ${discard}`);
  for (let i = 1; i <= 8; i += 1) {
    try {
      const ack = await js.publish('w13limits.orders', JSON.stringify({ i }));
      console.log(`mensaje ${i}: guardado con la secuencia ${ack.seq}`);
    } catch (error) {
      const detail = (error as { api_error?: { description: string } }).api_error?.description ?? String(error);
      console.log(`mensaje ${i}: RECHAZADO (${detail})`);
    }
  }
  const { state } = await jsm.streams.info(STREAM);
  console.log(`stream: ${state.messages} mensajes, de la secuencia ${state.first_seq} a la ${state.last_seq}`);
}
await jsm.streams.delete(STREAM);
await closeBus();
demos/max-deliveries.tsDescargar demos/max-deliveries.ts
import { closeBus, connectBus, consumerInfo, deleteStream, ensureConsumer } from '../shared/bus.ts';
import { settings } from '../shared/settings.ts';
import { freshStreamWith } from './helpers.ts';

// ¿Cómo avisa JetStream que un mensaje agotó sus entregas? Cuatro mensajes;
// el consumidor falla siempre con el segundo; el consumer tiene max_deliver = 3.
//
// Hay dos señales, y aquí se ven las dos:
// - cada entrega trae su número (deliveryCount): el consumidor puede saber
//   que está en la última;
// - el servidor publica un aviso (advisory) en un subject de sistema cuando
//   deja de entregar un mensaje.
//
// Este consumidor no usa startConsumer: solo confirma o devuelve el mensaje,
// como un proceso que no sabe nada de límites. El límite lo aplica el servidor.

const CONSUMER = 'poisoned';
const { nc, js } = await connectBus();
await freshStreamWith(4);
await ensureConsumer(CONSUMER, { maxDeliver: 3 });

const advisories = nc.subscribe(`$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.${settings.stream}.${CONSUMER}`, { max: 1 });
const advisory = (async () => {
  for await (const message of advisories) {
    console.log(`aviso del servidor en ${message.subject}`);
    console.log(`    ${message.string()}`);
  }
})();

const start = performance.now();
const messages = await (await js.consumers.get(settings.stream, CONSUMER)).consume({ max_messages: 1 });
const loop = (async () => {
  for await (const message of messages) {
    const ms = String(Math.round(performance.now() - start)).padStart(4);
    const orderId = message.json<{ orderId: number }>().orderId;
    if (orderId === 2) {
      console.log(`${ms} ms  seq ${message.seq}, deliveryCount ${message.info.deliveryCount}: falla, nak`);
      message.nak(settings.redeliveryDelayMs);
    } else {
      console.log(`${ms} ms  seq ${message.seq}, deliveryCount ${message.info.deliveryCount}: ack`);
      await message.ackAck();
    }
  }
})();

await advisory; // llega cuando el servidor decide no entregar más el mensaje 2
const info = await consumerInfo(CONSUMER);
console.log(
  `consumer: ack_floor.stream_seq ${info.ack_floor.stream_seq}, num_ack_pending ${info.num_ack_pending}, ` +
    `num_redelivered ${info.num_redelivered}, num_pending ${info.num_pending}`,
);
await messages.close();
await loop;
await deleteStream();
await closeBus();
demos/ordering.tsDescargar demos/ordering.ts
import { setTimeout as sleep } from 'node:timers/promises';
import { closeBus, deleteStream, startConsumer, type ConsumerOptions, type Handler, type RunningConsumer } from '../shared/bus.ts';
import { freshStreamWith, untilIdle } from './helpers.ts';

// ¿En qué orden se procesan los mensajes? Ocho mensajes en el stream, siempre
// en el mismo orden (secuencias 1 a 8), leídos de cuatro maneras.
//
// Los mensajes impares tardan 60 ms en procesarse y los pares 5 ms: no todos
// los trabajos duran lo mismo.

const workMs = (seq: number): number => (seq % 2 === 1 ? 60 : 5);

async function scenario(
  title: string,
  consumer: string,
  workers: number,
  options: ConsumerOptions,
  failFirstDeliveryOf?: number,
): Promise<void> {
  await freshStreamWith(8);
  const finished: string[] = [];
  const handler: Handler = async (_event, delivery) => {
    if (delivery.streamSeq === failFirstDeliveryOf && delivery.deliveryCount === 1) {
      throw new Error('falla la primera vez');
    }
    await sleep(workMs(delivery.streamSeq));
    finished.push(delivery.deliveryCount === 1 ? `${delivery.streamSeq}` : `${delivery.streamSeq}(entrega ${delivery.deliveryCount})`);
  };
  // Varios lectores del mismo consumer durable: el servidor reparte entre ellos.
  const running: RunningConsumer[] = [];
  for (let i = 0; i < workers; i += 1) running.push(await startConsumer(consumer, handler, options));
  await untilIdle(consumer);
  for (const worker of running) await worker.stop();
  console.log(`${title}\n    orden en que terminaron: ${finished.join(' ')}`);
}

await scenario('1. Un lector', 'one', 1, {});
await scenario('2. Tres lectores del mismo consumer', 'three', 3, {});
await scenario('3. Un lector; la secuencia 3 falla una vez y se reintenta a los 300 ms', 'retry', 1, {}, 3);
await scenario(
  '4. Lo mismo, con max_ack_pending = 1 (el servidor no entrega el siguiente sin confirmar el anterior)',
  'strict',
  1,
  { maxAckPending: 1 },
  3,
);
await deleteStream();
await closeBus();
es/event-store.tsDescargar es/event-store.ts
import { db, inTransaction } from '../shared/db.ts';
import { decide, fold, type OrderCommand, type OrderEvent, type OrderState } from './order.ts';

// El log de eventos, en PostgreSQL. Solo dos operaciones: leer la historia de
// un agregado y agregarle eventos al final.

export class ConcurrencyConflict extends Error {}

export type Stored = { position: number; version: number; event: OrderEvent };

/** La historia de un agregado, en orden. Con `upToVersion`, solo hasta esa versión. */
export async function load(aggregateId: string, upToVersion?: number): Promise<Stored[]> {
  const result = await db().query<{ position: string; version: number; type: string; data: object }>(
    `SELECT position, version, type, data FROM es_events
      WHERE aggregate_id = $1 AND version <= $2 ORDER BY version`,
    [aggregateId, upToVersion ?? 2_147_483_647],
  );
  return result.rows.map((row) => ({
    position: Number(row.position),
    version: row.version,
    event: { type: row.type, ...row.data } as OrderEvent,
  }));
}

/**
 * Agrega eventos al final de la historia de un agregado. `expectedVersion` es
 * la versión que vio quien decidió: si entretanto otro escribió, la
 * restricción UNIQUE (aggregate_id, version) rechaza la escritura. Es control
 * de concurrencia optimista.
 */
export async function append(aggregateId: string, expectedVersion: number, events: readonly OrderEvent[]): Promise<void> {
  try {
    await inTransaction(async (client) => {
      // Las escrituras al log van de una en una. Sin este lock, una
      // transacción podría recibir la posición 7, otra la 8, y confirmarse
      // primero la 8: una proyección que ya pasó por la 8 nunca vería la 7.
      // El precio: el log no admite escrituras en paralelo.
      await client.query("SELECT pg_advisory_xact_lock(hashtext('es_events'))");
      let version = expectedVersion;
      for (const event of events) {
        version += 1;
        const { type, ...data } = event;
        await client.query('INSERT INTO es_events (aggregate_id, version, type, data) VALUES ($1, $2, $3, $4)', [
          aggregateId,
          version,
          type,
          JSON.stringify(data),
        ]);
      }
    });
  } catch (error) {
    if ((error as { code?: string }).code === '23505') {
      throw new ConcurrencyConflict(`${aggregateId} ya no está en la versión ${expectedVersion}`);
    }
    throw error;
  }
}

/**
 * Atiende un comando: lee la historia, calcula el estado, decide y registra.
 * Si `decide` rechaza el comando, no se escribe nada.
 */
export async function handle(aggregateId: string, command: OrderCommand): Promise<OrderState> {
  const history = await load(aggregateId);
  const events = history.map((stored) => stored.event);
  const produced = decide(fold(events), command);
  await append(aggregateId, history.length, produced);
  return fold([...events, ...produced]);
}
es/main.tsDescargar es/main.ts
import { closeDb, db } from '../shared/db.ts';
import { handle, load } from './event-store.ts';
import { CommandRejected, fold } from './order.ts';
import { lag, projectConcertSales, readConcertSales, rebuild } from './projection.ts';

// make es: tres órdenes, su historia, y la vista de lectura atrasada, al día
// y reconstruida.

const show = (rows: object[]): void => (rows.length === 0 ? console.log('  (vacía)') : console.table(rows));

await db().query('TRUNCATE es_events, es_concert_sales, es_checkpoints RESTART IDENTITY');

await handle('order-1', { type: 'ReserveSeats', concertId: 1, buyerEmail: 'rosa.quispe@correo.pe', quantity: 2, priceCents: 16000 });
await handle('order-1', { type: 'PayOrder' });
await handle('order-2', { type: 'ReserveSeats', concertId: 1, buyerEmail: 'luis.mamani@correo.pe', quantity: 3, priceCents: 16000 });
await handle('order-3', { type: 'ReserveSeats', concertId: 2, buyerEmail: 'carmen.huaman@correo.pe', quantity: 1, priceCents: 9000 });
await handle('order-3', { type: 'PayOrder' });
await handle('order-1', { type: 'RefundOrder', reason: 'el comprador no puede asistir' });

console.log('== El log (es_events)');
const log = await db().query('SELECT position::int, aggregate_id, version, type FROM es_events ORDER BY position');
console.table(log.rows);

console.log('== La orden 1: su estado es el fold de su historia');
const history = await load('order-1');
for (const stored of history) console.log(`  v${stored.version} ${stored.event.type}`);
console.log('  estado actual:    ', JSON.stringify(fold(history.map((stored) => stored.event))));
const asOfV2 = await load('order-1', 2);
console.log('  estado en la v2:  ', JSON.stringify(fold(asOfV2.map((stored) => stored.event))));

console.log('== Un comando que se rechaza no deja evento');
try {
  await handle('order-2', { type: 'RefundOrder', reason: 'sin motivo' });
} catch (error) {
  if (!(error instanceof CommandRejected)) throw error;
  console.log(`  rechazado: ${error.message}`);
}
console.log(`  eventos de order-2: ${(await load('order-2')).length}`);

console.log('== La vista de lectura, antes de que corra la proyección');
console.log(`  eventos sin proyectar: ${await lag()}`);
show(await readConcertSales());

console.log('== La proyección aplica cuatro eventos');
await projectConcertSales(4);
console.log(`  eventos sin proyectar: ${await lag()}`);
show(await readConcertSales());

console.log('== La proyección se pone al día');
await projectConcertSales();
console.log(`  eventos sin proyectar: ${await lag()}`);
show(await readConcertSales());

console.log('== Se borra la vista y se reconstruye desde el primer evento');
console.log(`  eventos aplicados: ${await rebuild()}`);
show(await readConcertSales());

await closeDb();
es/order.tsDescargar es/order.ts
// Un agregado con event sourcing: la orden. Este archivo no toca la base de
// datos ni el reloj: son funciones puras sobre eventos, y por eso sus pruebas
// no necesitan nada.

// Los eventos: hechos, en pasado. Una vez guardados no cambian.
export type SeatsReserved = {
  type: 'SeatsReserved';
  concertId: number;
  buyerEmail: string;
  quantity: number;
  totalCents: number;
};
// OrderPaid y OrderRefunded repiten el concierto y los montos para que quien
// arme una vista no tenga que buscar el evento anterior de la misma orden.
export type OrderPaid = { type: 'OrderPaid'; concertId: number; quantity: number; totalCents: number };
export type OrderRefunded = { type: 'OrderRefunded'; concertId: number; quantity: number; totalCents: number; reason: string };
export type OrderEvent = SeatsReserved | OrderPaid | OrderRefunded;

// Los comandos: pedidos, en imperativo. Se pueden rechazar.
export type OrderCommand =
  | { type: 'ReserveSeats'; concertId: number; buyerEmail: string; quantity: number; priceCents: number }
  | { type: 'PayOrder' }
  | { type: 'RefundOrder'; reason: string };

// El estado: lo que hace falta saber para decidir sobre el siguiente comando.
export type OrderState =
  | { status: 'none' }
  | { status: 'reserved' | 'paid' | 'refunded'; concertId: number; buyerEmail: string; quantity: number; totalCents: number };

export const INITIAL: OrderState = { status: 'none' };

/** Aplica un evento al estado. No valida nada: el evento ya ocurrió. */
export function apply(state: OrderState, event: OrderEvent): OrderState {
  switch (event.type) {
    case 'SeatsReserved':
      return {
        status: 'reserved',
        concertId: event.concertId,
        buyerEmail: event.buyerEmail,
        quantity: event.quantity,
        totalCents: event.totalCents,
      };
    case 'OrderPaid':
      return state.status === 'none' ? state : { ...state, status: 'paid' };
    case 'OrderRefunded':
      return state.status === 'none' ? state : { ...state, status: 'refunded' };
  }
}

/** El estado actual es el fold de la historia: aplicar los eventos, en orden, desde el estado inicial. */
export function fold(events: readonly OrderEvent[]): OrderState {
  return events.reduce(apply, INITIAL);
}

export class CommandRejected extends Error {}

/**
 * Decide qué eventos produce un comando, dado el estado. Aquí viven los
 * invariantes: si el comando no se puede cumplir, se rechaza y no se registra
 * ningún evento.
 */
export function decide(state: OrderState, command: OrderCommand): OrderEvent[] {
  switch (command.type) {
    case 'ReserveSeats': {
      if (state.status !== 'none') throw new CommandRejected('La orden ya existe');
      if (command.quantity < 1 || command.quantity > 6) throw new CommandRejected('Se pueden reservar de 1 a 6 entradas');
      const { concertId, buyerEmail, quantity } = command;
      return [{ type: 'SeatsReserved', concertId, buyerEmail, quantity, totalCents: quantity * command.priceCents }];
    }
    case 'PayOrder': {
      if (state.status !== 'reserved') throw new CommandRejected(`No se puede pagar una orden en estado ${state.status}`);
      return [{ type: 'OrderPaid', concertId: state.concertId, quantity: state.quantity, totalCents: state.totalCents }];
    }
    case 'RefundOrder': {
      if (state.status !== 'paid') throw new CommandRejected(`No se puede devolver una orden en estado ${state.status}`);
      const { concertId, quantity, totalCents } = state;
      return [{ type: 'OrderRefunded', concertId, quantity, totalCents, reason: command.reason }];
    }
  }
}
es/projection.tsDescargar es/projection.ts
import { db, inTransaction } from '../shared/db.ts';
import type { OrderEvent } from './order.ts';

// La proyección: lee el log de eventos en orden y mantiene la vista
// es_concert_sales. Corre aparte de las escrituras, y por eso la vista va
// atrasada respecto del log hasta que la proyección la pone al día.

const NAME = 'concert-sales';

/** Cómo cambia la vista con cada evento: [reservadas, pagadas, recaudado]. */
function delta(event: OrderEvent): [number, number, number] {
  switch (event.type) {
    case 'SeatsReserved':
      return [event.quantity, 0, 0];
    case 'OrderPaid':
      return [-event.quantity, event.quantity, event.totalCents];
    case 'OrderRefunded':
      return [0, -event.quantity, -event.totalCents];
  }
}

/**
 * Aplica a la vista hasta `limit` eventos que todavía no vio. Devuelve cuántos
 * aplicó: 0 quiere decir que la vista está al día.
 *
 * La vista y el checkpoint se actualizan en la misma transacción: si el
 * proceso muere a la mitad, no queda un evento aplicado sin anotar ni anotado
 * sin aplicar. Es la misma idea que el consumidor idempotente.
 */
export async function projectConcertSales(limit = 100): Promise<number> {
  return inTransaction(async (client) => {
    await client.query('INSERT INTO es_checkpoints (projection, position) VALUES ($1, 0) ON CONFLICT DO NOTHING', [NAME]);
    // FOR UPDATE: dos procesos de la misma proyección no aplican el mismo evento.
    const checkpoint = await client.query<{ position: string }>(
      'SELECT position FROM es_checkpoints WHERE projection = $1 FOR UPDATE',
      [NAME],
    );
    const events = await client.query<{ position: string; type: string; data: object }>(
      'SELECT position, type, data FROM es_events WHERE position > $1 ORDER BY position LIMIT $2',
      [checkpoint.rows[0]!.position, limit],
    );
    for (const row of events.rows) {
      const event = { type: row.type, ...row.data } as OrderEvent;
      const [reserved, paid, revenue] = delta(event);
      await client.query(
        `INSERT INTO es_concert_sales (concert_id, reserved_tickets, paid_tickets, revenue_cents) VALUES ($1, $2, $3, $4)
         ON CONFLICT (concert_id) DO UPDATE SET
           reserved_tickets = es_concert_sales.reserved_tickets + EXCLUDED.reserved_tickets,
           paid_tickets = es_concert_sales.paid_tickets + EXCLUDED.paid_tickets,
           revenue_cents = es_concert_sales.revenue_cents + EXCLUDED.revenue_cents`,
        [event.concertId, reserved, paid, revenue],
      );
    }
    const last = events.rows.at(-1);
    if (last) await client.query('UPDATE es_checkpoints SET position = $2 WHERE projection = $1', [NAME, last.position]);
    return events.rows.length;
  });
}

/** Pone la vista al día. Devuelve cuántos eventos aplicó. */
export async function catchUp(): Promise<number> {
  let total = 0;
  for (let applied = await projectConcertSales(); applied > 0; applied = await projectConcertSales()) total += applied;
  return total;
}

/** Borra la vista y la calcula de nuevo desde el primer evento. */
export async function rebuild(): Promise<number> {
  await inTransaction(async (client) => {
    await client.query('TRUNCATE es_concert_sales');
    await client.query('DELETE FROM es_checkpoints WHERE projection = $1', [NAME]);
  });
  return catchUp();
}

/** Cuántos eventos del log todavía no están en la vista. */
export async function lag(): Promise<number> {
  const result = await db().query<{ n: string }>(
    `SELECT count(*) AS n FROM es_events
      WHERE position > coalesce((SELECT position FROM es_checkpoints WHERE projection = $1), 0)`,
    [NAME],
  );
  return Number(result.rows[0]!.n);
}

export type ConcertSales = { concert_id: number; reserved_tickets: number; paid_tickets: number; revenue_cents: number };

/** La consulta del lado de lectura: no toca el log. */
export async function readConcertSales(): Promise<ConcertSales[]> {
  const result = await db().query<ConcertSales>(
    'SELECT concert_id, reserved_tickets, paid_tickets, revenue_cents::int AS revenue_cents FROM es_concert_sales ORDER BY concert_id',
  );
  return result.rows;
}
es/schema.sqlDescargar es/schema.sql
-- Event sourcing en pequeño (Sesión B). Los nombres llevan el prefijo es_
-- para no mezclarse con las tablas de la outbox.

-- El log de eventos: la única tabla donde se escribe. Las filas no se
-- modifican ni se borran. Cada agregado (una orden) tiene su propia serie de
-- versiones: 1, 2, 3...
CREATE TABLE es_events (
    position     bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, -- orden global
    aggregate_id text NOT NULL,                                   -- 'order-17'
    version      integer NOT NULL CHECK (version > 0),
    type         text NOT NULL,
    data         jsonb NOT NULL,
    recorded_at  timestamptz NOT NULL DEFAULT now(),
    -- Dos comandos concurrentes sobre la misma orden intentan escribir la
    -- misma versión: uno de los dos choca con esta restricción.
    UNIQUE (aggregate_id, version)
);

-- La vista de lectura (el lado de las consultas en CQRS): ventas por
-- concierto. Es un dato derivado: se puede borrar y volver a calcular.
CREATE TABLE es_concert_sales (
    concert_id       integer PRIMARY KEY,
    reserved_tickets integer NOT NULL DEFAULT 0,
    paid_tickets     integer NOT NULL DEFAULT 0,
    revenue_cents    bigint NOT NULL DEFAULT 0
);

-- Hasta qué posición del log llegó cada proyección.
CREATE TABLE es_checkpoints (
    projection text PRIMARY KEY,
    position   bigint NOT NULL
);
ordering/order-status.tsDescargar ordering/order-status.ts
// Diseñar para el desorden. Una vista guarda el estado de cada orden a partir
// de sus eventos; los eventos pueden llegar en cualquier orden y repetidos.
// Dos maneras de aplicarlos.

export type StatusEvent = {
  orderId: number;
  /** El número del cambio dentro de la orden: 1, 2, 3... Lo pone quien produce el evento. */
  version: number;
  type: 'OrderPaid' | 'OrderRefunded';
};

export type StatusView = Map<number, { status: 'paid' | 'refunded'; version: number }>;

const statusOf = (event: StatusEvent): 'paid' | 'refunded' => (event.type === 'OrderPaid' ? 'paid' : 'refunded');

/** Ingenua: el último que llega gana. Correcta solo si los eventos llegan en orden. */
export function applyLastArrivalWins(view: StatusView, event: StatusEvent): void {
  view.set(event.orderId, { status: statusOf(event), version: event.version });
}

/**
 * Con versión: un evento se aplica solo si es más nuevo que lo que la vista
 * ya tiene. Uno antiguo o repetido se ignora. El resultado no depende del
 * orden de llegada.
 */
export function applyIfNewer(view: StatusView, event: StatusEvent): void {
  const current = view.get(event.orderId);
  if (current && current.version >= event.version) return;
  view.set(event.orderId, { status: statusOf(event), version: event.version });
}
shared/bus.tsDescargar shared/bus.ts
import {
  AckPolicy,
  connect,
  DeliverPolicy,
  nanos,
  type ConsumerInfo,
  type ConsumerMessages,
  type JetStreamClient,
  type JetStreamManager,
  type JsMsg,
  type NatsConnection,
} from 'nats';
import type { OrderPaid } from './events.ts';
import { log, settings } from './settings.ts';

// Todo lo que esta semana sabe de NATS JetStream está en este archivo.
//
// - Un stream guarda en disco cada mensaje publicado en sus subjects y le da
//   un número de secuencia: 1, 2, 3...
// - Un consumer durable es un cursor sobre el stream, guardado en el servidor:
//   recuerda qué mensajes entregó y cuáles le confirmaron (ack).

type Bus = { nc: NatsConnection; js: JetStreamClient; jsm: JetStreamManager };
let bus: Promise<Bus> | undefined;

export function connectBus(): Promise<Bus> {
  bus ??= (async () => {
    const nc = await connect({ servers: settings.natsServer });
    return { nc, js: nc.jetstream(), jsm: await nc.jetstreamManager() };
  })();
  return bus;
}

/** Cierra la conexión con NATS después de enviar lo pendiente. */
export async function closeBus(): Promise<void> {
  const open = bus;
  bus = undefined;
  if (open) await (await open).nc.drain();
}

/**
 * Crea el stream si no existe. Si ya existe (por ejemplo, porque lo crearon
 * con `nats stream add` en el paso 1 del laboratorio), lo deja como está.
 */
export async function ensureStream(): Promise<void> {
  const { jsm } = await connectBus();
  const exists = await jsm.streams.info(settings.stream).then(
    () => true,
    () => false,
  );
  if (!exists) await jsm.streams.add({ name: settings.stream, subjects: [settings.subjects.all] });
}

/** Borra el stream con sus mensajes y sus consumers. */
export async function deleteStream(): Promise<void> {
  const { jsm } = await connectBus();
  await jsm.streams.delete(settings.stream).catch(() => undefined);
}

/**
 * Publica y espera a que el stream confirme que guardó el mensaje. Devuelve
 * el número de secuencia que le tocó.
 *
 * Con `msgId`, el mensaje lleva la cabecera Nats-Msg-Id: si el stream ya
 * recibió otro con el mismo valor dentro de su ventana de duplicados (dos
 * minutos por omisión), no lo guarda de nuevo y `duplicate` es true.
 */
export async function publish(
  subject: string,
  event: OrderPaid,
  options: { msgId?: string } = {},
): Promise<{ seq: number; duplicate: boolean }> {
  const { js } = await connectBus();
  const ack = await js.publish(subject, JSON.stringify(event), options.msgId ? { msgID: options.msgId } : {});
  return { seq: ack.seq, duplicate: ack.duplicate };
}

/** Lo que el consumidor sabe de una entrega, además del evento. */
export type Delivery = {
  subject: string;
  /** La posición del mensaje en el stream. No cambia entre entregas. */
  streamSeq: number;
  /** 1 en la primera entrega, 2 en la primera reentrega... */
  deliveryCount: number;
};

export type Handler = (event: OrderPaid, delivery: Delivery) => Promise<void>;

export type ConsumerOptions = {
  /**
   * Cuántas veces, como máximo, entrega el servidor cada mensaje. Sin este
   * límite lo entrega hasta que alguien lo confirme: para siempre, si el
   * mensaje no se puede procesar.
   */
  maxDeliver?: number;
  /**
   * Se llama cuando el handler falló en la última entrega permitida, antes de
   * descartar el mensaje. Aquí se registra el mensaje en la dead letter.
   */
  onGiveUp?: (event: OrderPaid, delivery: Delivery, error: unknown) => Promise<void>;
  /** Confirmar antes de procesar: at-most-once. Por omisión se confirma después. */
  ackFirst?: boolean;
  /** Milisegundos que el servidor espera la confirmación. */
  ackWaitMs?: number;
  /**
   * Cuántos mensajes pueden estar entregados y sin confirmar a la vez. Con 1,
   * el servidor no entrega el siguiente hasta que se confirme el anterior.
   */
  maxAckPending?: number;
};

export type RunningConsumer = { stop(): Promise<void> };

/**
 * Crea el consumer durable `name`; empieza por el primer mensaje del stream.
 * Si ya existe, conserva su posición y solo le actualiza los límites.
 */
export async function ensureConsumer(name: string, options: ConsumerOptions = {}): Promise<void> {
  const { jsm } = await connectBus();
  const limits = {
    ack_wait: nanos(options.ackWaitMs ?? settings.ackWaitMs),
    // -1 es "sin límite", el valor por omisión del servidor.
    max_deliver: options.maxDeliver ?? -1,
    max_ack_pending: options.maxAckPending ?? 1000,
  };
  const exists = await jsm.consumers.info(settings.stream, name).then(
    () => true,
    () => false,
  );
  if (exists) {
    await jsm.consumers.update(settings.stream, name, limits);
    return;
  }
  await jsm.consumers.add(settings.stream, {
    durable_name: name,
    ack_policy: AckPolicy.Explicit,
    deliver_policy: DeliverPolicy.All,
    ...limits,
  });
}

function deliveryOf(message: JsMsg): Delivery {
  return { subject: message.subject, streamSeq: message.seq, deliveryCount: message.info.deliveryCount };
}

/**
 * Empieza a consumir con el consumer durable `name` y llama a `handler` con
 * cada evento, de uno en uno.
 *
 * - Si `handler` termina bien, se confirma el mensaje (ack).
 * - Si lanza un error y quedan entregas, se devuelve el mensaje (nak) y el
 *   servidor lo entrega otra vez después de una espera.
 * - Si lanza un error en la última entrega permitida, se llama a `onGiveUp` y
 *   se descarta el mensaje (term): el servidor no lo entrega más.
 *
 * La confirmación va después del trabajo: si el proceso muere entre las dos
 * cosas, el mensaje se entrega de nuevo. Es entrega at-least-once.
 */
export async function startConsumer(
  name: string,
  handler: Handler,
  options: ConsumerOptions = {},
): Promise<RunningConsumer> {
  const { js } = await connectBus();
  await ensureConsumer(name, options);
  const consumer = await js.consumers.get(settings.stream, name);
  // De uno en uno: no se pide el siguiente mensaje hasta terminar con el actual.
  const messages: ConsumerMessages = await consumer.consume({ max_messages: 1 });

  const loop = (async () => {
    for await (const message of messages) {
      const event = message.json<OrderPaid>();
      const delivery = deliveryOf(message);
      try {
        if (options.ackFirst) await message.ackAck();
        await handler(event, delivery);
        if (!options.ackFirst) await message.ackAck();
      } catch (error) {
        if (options.ackFirst) continue; // ya se confirmó: el mensaje se perdió
        const last = options.maxDeliver !== undefined && delivery.deliveryCount >= options.maxDeliver;
        log(name, `seq ${delivery.streamSeq}: la entrega ${delivery.deliveryCount} falló (${String(error)})`);
        if (last) {
          await options.onGiveUp?.(event, delivery, error);
          message.term('se agotaron las entregas');
        } else {
          message.nak(settings.redeliveryDelayMs);
        }
      }
    }
  })();

  return {
    async stop() {
      await messages.close();
      await loop;
    },
  };
}

/** El estado de un consumer durable, como lo ve el servidor. */
export async function consumerInfo(name: string): Promise<ConsumerInfo> {
  const { jsm } = await connectBus();
  return jsm.consumers.info(settings.stream, name);
}

/** Cuántos mensajes guarda el stream y cuál es su última secuencia. */
export async function streamState(): Promise<{ messages: number; lastSeq: number }> {
  const { jsm } = await connectBus();
  const info = await jsm.streams.info(settings.stream);
  return { messages: info.state.messages, lastSeq: info.state.last_seq };
}

/** Borra un consumer durable, si existe. */
export async function deleteConsumer(name: string): Promise<void> {
  const { jsm } = await connectBus();
  await jsm.consumers.delete(settings.stream, name).catch(() => undefined);
}

export type StoredMessage = { seq: number; subject: string; event: OrderPaid };

/**
 * Lee el stream completo, de la primera secuencia a la última, sin crear un
 * consumer ni confirmar nada. Sirve para contar en los experimentos; un
 * consumidor de verdad usa un consumer.
 */
export async function readStream(): Promise<StoredMessage[]> {
  const { jsm } = await connectBus();
  const { state } = await jsm.streams.info(settings.stream);
  const stored: StoredMessage[] = [];
  if (state.messages === 0) return stored;
  for (let seq = state.first_seq; seq <= state.last_seq; seq += 1) {
    const message = await jsm.streams.getMessage(settings.stream, { seq }).catch(() => undefined);
    if (message) stored.push({ seq, subject: message.subject, event: message.json<OrderPaid>() });
  }
  return stored;
}
shared/crash.tsDescargar shared/crash.ts
// Puntos de caída para los experimentos. Una variable de entorno decide si el
// proceso muere al pasar por un punto: "1" siempre, "0.3" tres de cada diez
// veces, sin definir nunca.
//
// El proceso se mata con SIGKILL, que no se puede atrapar: no corre ningún
// `finally`, no se cierra ninguna conexión con cuidado y no se hace ROLLBACK.
// Es lo más parecido a que se vaya la luz.

export function crashPoint(variable: string): void {
  const raw = process.env[variable];
  if (raw === undefined || raw === '') return;
  const probability = Number(raw);
  if (!Number.isFinite(probability) || probability < 0 || probability > 1) {
    throw new Error(`La variable ${variable} debe estar entre 0 y 1, y es "${raw}"`);
  }
  if (Math.random() < probability) process.kill(process.pid, 'SIGKILL');
}
shared/db.tsDescargar shared/db.ts
import pg from 'pg';
import { settings } from './settings.ts';

// Un pool por proceso. El host y el usuario salen de PGHOST y PGUSER, que el
// contenedor ya define.
let pool: pg.Pool | undefined;

export function db(): pg.Pool {
  pool ??= new pg.Pool({ database: settings.database, max: 5 });
  return pool;
}

/** Cierra el pool. Sin esto, el programa no termina. */
export async function closeDb(): Promise<void> {
  const open = pool;
  pool = undefined;
  await open?.end();
}

/**
 * Corre `work` dentro de una transacción: COMMIT si termina bien, ROLLBACK si
 * lanza un error. La conexión vuelve al pool en los dos casos.
 */
export async function inTransaction<T>(work: (client: pg.PoolClient) => Promise<T>): Promise<T> {
  const client = await db().connect();
  try {
    await client.query('BEGIN');
    const result = await work(client);
    await client.query('COMMIT');
    return result;
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}
shared/events.tsDescargar shared/events.ts
import { randomUUID } from 'node:crypto';

// El contrato entre el servicio de órdenes y sus consumidores. El campo `id`
// identifica al evento, no a la orden: lo genera quien lo crea, una sola vez,
// y viaja igual en cada publicación y en cada entrega. Con él un consumidor
// reconoce un duplicado.
export type OrderPaid = {
  id: string;
  type: 'OrderPaid';
  occurredAt: string;
  orderId: number;
  concertId: number;
  buyerEmail: string;
  quantity: number;
  totalCents: number;
};

export type PaidOrder = Omit<OrderPaid, 'id' | 'type' | 'occurredAt'>;

export function newOrderPaid(order: PaidOrder): OrderPaid {
  return { id: randomUUID(), type: 'OrderPaid', occurredAt: new Date().toISOString(), ...order };
}
shared/impl.tsDescargar shared/impl.ts
// Los programas de tools/ y las pruebas del laboratorio usan la versión de
// lab/ de los tres archivos que ustedes completan. Con W13_IMPL=solution usan
// la de solution/, si esa carpeta existe.

const IMPL = process.env.W13_IMPL ?? 'lab';
if (IMPL !== 'lab' && IMPL !== 'solution') throw new Error(`W13_IMPL debe ser lab o solution, y es "${IMPL}"`);

export const implName = IMPL;

export function loadOutbox(): Promise<typeof import('../lab/outbox.ts')> {
  return import(`../${IMPL}/outbox.ts`);
}

export function loadRelay(): Promise<typeof import('../lab/relay.ts')> {
  return import(`../${IMPL}/relay.ts`);
}

export function loadPoints(): Promise<typeof import('../lab/points.ts')> {
  return import(`../${IMPL}/points.ts`);
}
shared/orders.tsDescargar shared/orders.ts
import type pg from 'pg';
import type { PaidOrder } from './events.ts';

export type OrderInput = { concertId: number; buyerEmail: string; quantity: number };

/**
 * Inserta una orden pagada con la conexión que le pasan. No abre ni cierra la
 * transacción: eso lo decide quien llama, y esa decisión es el tema de la
 * semana.
 */
export async function insertPaidOrder(client: pg.ClientBase, input: OrderInput): Promise<PaidOrder> {
  const result = await client.query<{ id: number; total_cents: number }>(
    `INSERT INTO orders (concert_id, buyer_email, quantity, total_cents, status)
     SELECT c.id, $2, $3, c.price_cents * $3, 'paid' FROM concerts c WHERE c.id = $1
     RETURNING id, total_cents`,
    [input.concertId, input.buyerEmail, input.quantity],
  );
  const row = result.rows[0];
  if (!row) throw new Error(`No existe el concierto ${input.concertId}`);
  return { orderId: row.id, totalCents: row.total_cents, ...input };
}
shared/settings.tsDescargar shared/settings.ts
// Configuración de la semana: todo sale de variables de entorno. Las pruebas
// usan otra base de datos y otro stream para no tocar los datos de make demo.

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;
}

const subjectPrefix = process.env.W13_SUBJECT_PREFIX ?? 'w13.orders';

export const settings = {
  database: process.env.W13_DB ?? 'arq_w13',
  natsServer: process.env.NATS_URL ?? '127.0.0.1:4222',
  // El stream guarda todo lo que se publique en w13.orders.>
  stream: process.env.W13_STREAM ?? 'W13_ORDERS',
  subjectPrefix,
  subjects: {
    all: `${subjectPrefix}.>`,
    paid: `${subjectPrefix}.paid`,
  },
  // Cuánto espera el servidor una confirmación antes de entregar de nuevo.
  ackWaitMs: numberFromEnv('ACK_WAIT_MS', 5000),
  // Cuánto espera un consumidor antes de volver a recibir un mensaje que falló.
  redeliveryDelayMs: numberFromEnv('REDELIVERY_DELAY_MS', 1000),
  // Cada cuánto revisa el relay la tabla outbox.
  relayIntervalMs: numberFromEnv('RELAY_INTERVAL_MS', 200),
  logEnabled: process.env.W13_LOG !== 'off',
};

export function log(who: string, message: string): void {
  if (settings.logEnabled) console.log(`[${who}] ${message}`);
}
tools/buy.tsDescargar tools/buy.ts
import { closeBus, ensureStream } from '../shared/bus.ts';
import { closeDb } from '../shared/db.ts';
import { loadOutbox } from '../shared/impl.ts';
import type { OrderInput } from '../shared/orders.ts';

// Una compra por ejecución, para poder matar el proceso a la mitad.
//
//   PLACE=dual-write   usa errors/dual-write.ts
//   PLACE=outbox       usa lab/outbox.ts (o solution/, con W13_IMPL=solution)
//   I=7                el número de la compra: de él salen el comprador, el
//                      concierto y la cantidad, para que el reporte tenga variedad

const BUYERS = ['rosa.quispe@correo.pe', 'luis.mamani@correo.pe', 'carmen.huaman@correo.pe', 'jorge.ccori@correo.pe'];

const i = Number(process.env.I ?? 1);
const input: OrderInput = {
  buyerEmail: process.env.BUYER ?? BUYERS[i % BUYERS.length]!,
  concertId: (i % 3) + 1,
  quantity: (i % 4) + 1,
};

const place = process.env.PLACE ?? 'outbox';
const placeOrder =
  place === 'dual-write' ? (await import('../errors/dual-write.ts')).placeOrder : (await loadOutbox()).placeOrder;

await ensureStream();
const order = await placeOrder(input);
if (process.env.W13_LOG !== 'off') {
  console.log(`orden ${order.orderId}: ${order.quantity} entradas del concierto ${order.concertId} para ${order.buyerEmail}`);
}
await Promise.all([closeBus(), closeDb()]);
tools/consumer.tsDescargar tools/consumer.ts
import { recordDeadLetter } from '../consumers/dead-letter.ts';
import { addToSalesReport } from '../consumers/report.ts';
import { addPointsNaive } from '../errors/points-naive.ts';
import { closeBus, ensureStream, startConsumer, type Handler } from '../shared/bus.ts';
import { closeDb } from '../shared/db.ts';
import { loadPoints } from '../shared/impl.ts';
import { log } from '../shared/settings.ts';

// Un consumidor como proceso: consume hasta que le piden terminar (Ctrl+C).
//
//   node tools/consumer.ts points-naive    errors/points-naive.ts
//   node tools/consumer.ts points          lab/points.ts (o solution/)
//   node tools/consumer.ts report          consumers/report.ts
//
//   POISON_ORDER=3    el handler falla siempre con el evento de la orden 3
//   MAX_DELIVER=3     el servidor entrega cada mensaje 3 veces como máximo; al
//                     agotarse, el mensaje se registra en dead_letters

const which = process.argv[2] ?? 'points';
const handlers: Record<string, { consumer: string; load: () => Promise<Handler> }> = {
  'points-naive': { consumer: 'points', load: async () => addPointsNaive },
  points: { consumer: 'points', load: async () => (await loadPoints()).addPoints },
  report: { consumer: 'report', load: async () => (event) => addToSalesReport(event) },
};
const chosen = handlers[which];
if (!chosen) throw new Error(`No existe el consumidor "${which}". Opciones: ${Object.keys(handlers).join(', ')}`);

const work = await chosen.load();
const poison = process.env.POISON_ORDER ? Number(process.env.POISON_ORDER) : undefined;
const maxDeliver = process.env.MAX_DELIVER ? Number(process.env.MAX_DELIVER) : undefined;

const handler: Handler = async (event, delivery) => {
  if (event.orderId === poison) throw new Error(`no puedo procesar la orden ${event.orderId}`);
  await work(event, delivery);
  log(which, `seq ${delivery.streamSeq} (entrega ${delivery.deliveryCount}): orden ${event.orderId} procesada`);
};

await ensureStream();
const consumer = await startConsumer(chosen.consumer, handler, {
  ...(maxDeliver ? { maxDeliver, onGiveUp: recordDeadLetter(chosen.consumer) } : {}),
});
log(which, `esperando eventos con el consumer "${chosen.consumer}"`);

const stop = async (): Promise<void> => {
  await consumer.stop();
  await Promise.all([closeBus(), closeDb()]);
  log(which, 'detenido');
};
for (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => void stop());
tools/counts.tsDescargar tools/counts.ts
import { closeBus, ensureStream, readStream } from '../shared/bus.ts';
import { closeDb, db } from '../shared/db.ts';

// Las cuentas de los pasos 3 a 5: órdenes guardadas, filas de la outbox y
// eventos en el stream. Si el sistema es correcto, cada orden tiene su evento.

await ensureStream();
const orders = await db().query<{ n: string }>('SELECT count(*) AS n FROM orders');
const outbox = await db().query<{ total: string; pending: string }>(
  'SELECT count(*) AS total, count(*) FILTER (WHERE published_at IS NULL) AS pending FROM outbox',
);
const stored = await readStream();
const orderIds = new Set((await db().query<{ id: number }>('SELECT id FROM orders')).rows.map((row) => row.id));

const distinctEvents = new Set(stored.map((message) => message.event.id)).size;
const announced = new Set(stored.map((message) => message.event.orderId));
const ordersWithoutEvent = [...orderIds].filter((id) => !announced.has(id)).length;
const eventsWithoutOrder = [...announced].filter((id) => !orderIds.has(id)).length;

const line = (label: string, value: string | number): void => console.log(`${label.padEnd(34)}${String(value).padStart(5)}`);
line('órdenes guardadas', Number(orders.rows[0]!.n));
line('filas en la outbox', Number(outbox.rows[0]!.total));
line('  pendientes de publicar', Number(outbox.rows[0]!.pending));
line('mensajes en el stream', stored.length);
line('  eventos distintos', distinctEvents);
line('órdenes sin evento', ordersWithoutEvent);
line('eventos de órdenes que no existen', eventsWithoutOrder);

await Promise.all([closeBus(), closeDb()]);
tools/relay.tsDescargar tools/relay.ts
import { setTimeout as sleep } from 'node:timers/promises';
import { closeBus, ensureStream } from '../shared/bus.ts';
import { closeDb } from '../shared/db.ts';
import { implName, loadRelay } from '../shared/impl.ts';
import { log, settings } from '../shared/settings.ts';

// El proceso del relay. Sin argumentos revisa la outbox cada 200 ms hasta que
// lo detienen (Ctrl+C). Con "once" publica lo pendiente y termina.

const { relayOnce } = await loadRelay();
await ensureStream();

if (process.argv[2] === 'once') {
  let total = 0;
  for (let published = await relayOnce(); published > 0; published = await relayOnce()) total += published;
  log('relay', `${total} eventos publicados (${implName}/relay.ts)`);
} else {
  let running = true;
  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => (running = false));
  log('relay', `revisando la outbox cada ${settings.relayIntervalMs} ms (${implName}/relay.ts)`);
  while (running) {
    const published = await relayOnce();
    if (published > 0) log('relay', `${published} eventos publicados`);
    else await sleep(settings.relayIntervalMs);
  }
  log('relay', 'detenido');
}
await Promise.all([closeBus(), closeDb()]);
tools/repeat.shDescargar tools/repeat.sh
#!/usr/bin/env bash
# Corre N veces una compra, cada una en su propio proceso, y cuenta cuántos
# procesos terminaron bien y cuántos murieron.
#   tools/repeat.sh 100 dual-write
set -u
n="$1"; place="$2"
ok=0; dead=0
# 2>/dev/null en el bucle: bash avisa "Killed" cada vez que un proceso muere.
for i in $(seq 1 "$n"); do
    if (I="$i" PLACE="$place" W13_LOG=off node tools/buy.ts) >/dev/null 2>&1; then
        ok=$((ok + 1))
    else
        dead=$((dead + 1))
    fi
done 2>/dev/null
echo "$n compras ($place): $ok procesos terminaron bien, $dead murieron a la mitad"
tools/replay.tsDescargar tools/replay.ts
import { compareReports, rebuildSalesReport } from '../consumers/replay.ts';
import { closeBus, ensureStream } from '../shared/bus.ts';
import { closeDb, db } from '../shared/db.ts';

// Paso 8: reconstruye el reporte de ventas leyendo el stream desde el
// principio y lo compara con el reporte original.

await ensureStream();
const read = await rebuildSalesReport();
console.log(`Reconstruido con el consumer "report-rebuild": ${read} mensajes leídos desde la secuencia 1.`);

for (const table of ['sales_report', 'sales_report_rebuilt'] as const) {
  const rows = await db().query(`SELECT concert_id, orders, tickets, revenue_cents::int FROM ${table} ORDER BY concert_id`);
  console.log(`== ${table}`);
  console.table(rows.rows);
}
const differences = await compareReports();
if (differences.length === 0) console.log('Las dos tablas son iguales.');
else {
  console.log('Filas que están en una tabla y no en la otra:');
  console.table(differences);
}
await Promise.all([closeBus(), closeDb()]);
process.exitCode = differences.length === 0 ? 0 : 1;
tools/status.tsDescargar tools/status.ts
import { closeDb, db } from '../shared/db.ts';

// Lo que guardó cada consumidor, al lado de lo que dicen las órdenes.

const print = async (title: string, sql: string): Promise<void> => {
  const result = await db().query(sql);
  console.log(`== ${title}`);
  if (result.rows.length === 0) console.log('(vacío)');
  else console.table(result.rows);
};

await print(
  'órdenes y puntos por comprador (10 puntos por orden)',
  `SELECT o.buyer_email, count(*)::int AS orders, count(*)::int * 10 AS expected_points, coalesce(p.points, 0) AS points
     FROM orders o LEFT JOIN loyalty_points p USING (buyer_email)
    GROUP BY o.buyer_email, p.points ORDER BY o.buyer_email`,
);
await print(
  'reporte de ventas (sales_report)',
  'SELECT concert_id, orders, tickets, revenue_cents::int FROM sales_report ORDER BY concert_id',
);
await print(
  'dead letters',
  `SELECT consumer, stream_seq::int, payload->>'orderId' AS order_id, deliveries, reason FROM dead_letters ORDER BY id`,
);
await closeDb();
tools/worker.tsDescargar tools/worker.ts
import { setTimeout as sleep } from 'node:timers/promises';
import { closeBus, ensureStream, startConsumer } from '../shared/bus.ts';

// Un proceso que lee del stream con el consumer que le digan y cuenta qué
// recibió. No guarda nada: sirve para ver cómo reparte el servidor.
//
//   node tools/worker.ts reader-a     lee con el consumer durable "reader-a"
//
//   WORK_MS=200      cada mensaje "tarda" 200 ms en procesarse
//   ACK_FIRST=1      confirma antes de procesar (por omisión, después)
//   CRASH_ON_SEQ=3   muere mientras procesa el mensaje de secuencia 3

const name = process.argv[2] ?? 'reader';
const workMs = Number(process.env.WORK_MS ?? 0);
const crashOnSeq = process.env.CRASH_ON_SEQ ? Number(process.env.CRASH_ON_SEQ) : undefined;
const say = (text: string): void => console.log(`[proceso ${process.pid}, consumer ${name}] ${text}`);

await ensureStream();
const consumer = await startConsumer(
  name,
  async (event, delivery) => {
    say(`seq ${delivery.streamSeq} (entrega ${delivery.deliveryCount}): recibí la orden ${event.orderId}`);
    if (delivery.streamSeq === crashOnSeq) process.kill(process.pid, 'SIGKILL');
    await sleep(workMs);
    say(`seq ${delivery.streamSeq}: orden ${event.orderId} procesada`);
  },
  { ackFirst: process.env.ACK_FIRST === '1' },
);

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => void consumer.stop().then(closeBus));
}

Errores

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

errors/dual-write.tsDescargar errors/dual-write.ts
import { publish } from '../shared/bus.ts';
import { crashPoint } from '../shared/crash.ts';
import { inTransaction } from '../shared/db.ts';
import { newOrderPaid, type PaidOrder } from '../shared/events.ts';
import { insertPaidOrder, type OrderInput } from '../shared/orders.ts';
import { settings } from '../shared/settings.ts';

// La escritura doble: guardar la orden y publicar el evento son dos
// operaciones contra dos sistemas (PostgreSQL y NATS), y ninguna transacción
// cubre a las dos. Este archivo está mal a propósito.
//
//   CRASH_BETWEEN=1    el proceso muere entre las dos operaciones
//   PUBLISH_FIRST=1    publica antes de confirmar la transacción, en vez de después

/** Primero COMMIT, después publicar. Si muere en medio: orden sin evento. */
async function commitThenPublish(input: OrderInput): Promise<PaidOrder> {
  const order = await inTransaction((client) => insertPaidOrder(client, input));
  crashPoint('CRASH_BETWEEN');
  await publish(settings.subjects.paid, newOrderPaid(order));
  return order;
}

/** Primero publicar, después COMMIT. Si muere en medio: evento de una orden que no existe. */
async function publishThenCommit(input: OrderInput): Promise<PaidOrder> {
  return inTransaction(async (client) => {
    const order = await insertPaidOrder(client, input);
    await publish(settings.subjects.paid, newOrderPaid(order));
    crashPoint('CRASH_BETWEEN');
    return order;
  });
}

export function placeOrder(input: OrderInput): Promise<PaidOrder> {
  return process.env.PUBLISH_FIRST === '1' ? publishThenCommit(input) : commitThenPublish(input);
}
errors/points-naive.tsDescargar errors/points-naive.ts
import { db } from '../shared/db.ts';
import type { OrderPaid } from '../shared/events.ts';

// El consumidor de puntos, sin idempotencia: 10 puntos por cada OrderPaid que
// recibe. Si el mismo evento llega dos veces, suma dos veces. Este archivo
// está mal a propósito y no se corrige: la versión corregida es lab/points.ts.

export const POINTS_PER_ORDER = 10;

export async function addPointsNaive(event: OrderPaid): Promise<void> {
  await db().query(
    `INSERT INTO loyalty_points (buyer_email, points) VALUES ($1, $2)
     ON CONFLICT (buyer_email) DO UPDATE SET points = loyalty_points.points + EXCLUDED.points`,
    [event.buyerEmail, POINTS_PER_ORDER],
  );
}

Pruebas

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

consensus/majority.test.tsDescargar consensus/majority.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { majority, tolerated } from './majority.ts';

// Lo que los apuntes afirman de las mayorías, comprobado por enumeración.

test('con cinco nodos la mayoría es tres y se toleran dos caídos', () => {
  assert.equal(majority(5), 3);
  assert.equal(tolerated(5), 2);
});

test('un nodo más, si deja el total par, no tolera más fallas', () => {
  assert.deepEqual([3, 4, 5, 6].map(tolerated), [1, 1, 2, 2]);
});

test('dos mayorías cualesquiera del mismo grupo comparten al menos un nodo', () => {
  for (let n = 1; n <= 7; n += 1) {
    const subsets = Array.from({ length: 2 ** n }, (_, mask) => mask);
    const size = (mask: number): number => mask.toString(2).replaceAll('0', '').length;
    const majorities = subsets.filter((mask) => size(mask) >= majority(n));
    for (const a of majorities) for (const b of majorities) assert.notEqual(a & b, 0, `n = ${n}`);
  }
});

test('si la red se parte en dos, a lo más un lado tiene mayoría', () => {
  for (let n = 1; n <= 9; n += 1) {
    for (let left = 0; left <= n; left += 1) {
      const sidesWithMajority = [left, n - left].filter((side) => side >= majority(n)).length;
      assert.ok(sidesWithMajority <= 1, `n = ${n}, partición ${left} + ${n - left}`);
    }
  }
  // Con un número par puede no tenerla ninguno: 2 + 2 de 4.
  assert.equal([2, 2].filter((side) => side >= majority(4)).length, 0);
});
es/order.test.tsDescargar es/order.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { apply, CommandRejected, decide, fold, INITIAL, type OrderEvent } from './order.ts';

// El agregado, sin base de datos: estado = fold de los eventos.

const reserved: OrderEvent = { type: 'SeatsReserved', concertId: 1, buyerEmail: 'rosa.quispe@correo.pe', quantity: 2, totalCents: 32000 };
const paid: OrderEvent = { type: 'OrderPaid', concertId: 1, quantity: 2, totalCents: 32000 };
const refunded: OrderEvent = { type: 'OrderRefunded', concertId: 1, quantity: 2, totalCents: 32000, reason: 'no puede asistir' };

test('el estado es el fold de los eventos, y cada prefijo de la historia es un estado pasado', () => {
  assert.equal(fold([]).status, 'none');
  assert.equal(fold([reserved]).status, 'reserved');
  assert.equal(fold([reserved, paid]).status, 'paid');
  assert.deepEqual(fold([reserved, paid, refunded]), {
    status: 'refunded',
    concertId: 1,
    buyerEmail: 'rosa.quispe@correo.pe',
    quantity: 2,
    totalCents: 32000,
  });
});

test('fold es aplicar de uno en uno: fold(historia + e) = apply(fold(historia), e)', () => {
  assert.deepEqual(fold([reserved, paid, refunded]), apply(fold([reserved, paid]), refunded));
  assert.deepEqual(fold([reserved]), apply(INITIAL, reserved));
});

test('un comando válido produce eventos; decide no cambia el estado', () => {
  const state = fold([reserved]);
  assert.deepEqual(decide(state, { type: 'PayOrder' }), [paid]);
  assert.equal(state.status, 'reserved');
});

test('un comando que rompe un invariante se rechaza y no produce eventos', () => {
  assert.throws(() => decide(fold([reserved]), { type: 'RefundOrder', reason: 'x' }), CommandRejected);
  assert.throws(() => decide(fold([reserved, paid]), { type: 'PayOrder' }), CommandRejected, 'no se paga dos veces');
  assert.throws(() => decide(fold([reserved, paid, refunded]), { type: 'RefundOrder', reason: 'x' }), CommandRejected);
  assert.throws(
    () => decide(INITIAL, { type: 'ReserveSeats', concertId: 1, buyerEmail: 'a@b.pe', quantity: 7, priceCents: 100 }),
    CommandRejected,
  );
});
es/store.test.tsDescargar es/store.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { closeDb, db } from '../shared/db.ts';
import { append, ConcurrencyConflict, handle, load } from './event-store.ts';
import { CommandRejected, fold } from './order.ts';
import { catchUp, lag, projectConcertSales, readConcertSales, rebuild } from './projection.ts';

// El log de eventos y la proyección, con PostgreSQL.

const reserve = (concertId: number, quantity: number) =>
  ({ type: 'ReserveSeats', concertId, buyerEmail: 'rosa.quispe@correo.pe', quantity, priceCents: 10000 }) as const;

beforeEach(async () => {
  await db().query('TRUNCATE es_events, es_concert_sales, es_checkpoints RESTART IDENTITY');
});
after(closeDb);

test('el estado que devuelve handle es el fold de lo que quedó guardado', async () => {
  await handle('order-1', reserve(1, 2));
  const state = await handle('order-1', { type: 'PayOrder' });
  const history = await load('order-1');
  assert.deepEqual(history.map((stored) => [stored.version, stored.event.type]), [
    [1, 'SeatsReserved'],
    [2, 'OrderPaid'],
  ]);
  assert.deepEqual(state, fold(history.map((stored) => stored.event)));
});

test('se puede reconstruir el estado de cualquier momento: la historia hasta una versión', async () => {
  await handle('order-1', reserve(1, 2));
  await handle('order-1', { type: 'PayOrder' });
  await handle('order-1', { type: 'RefundOrder', reason: 'no puede asistir' });
  const asOf = async (version: number) => fold((await load('order-1', version)).map((stored) => stored.event)).status;
  assert.deepEqual([await asOf(1), await asOf(2), await asOf(3)], ['reserved', 'paid', 'refunded']);
});

test('un comando rechazado no escribe nada en el log', async () => {
  await handle('order-1', reserve(1, 2));
  await assert.rejects(handle('order-1', { type: 'RefundOrder', reason: 'x' }), CommandRejected);
  assert.equal((await load('order-1')).length, 1);
});

test('dos decisiones tomadas sobre la misma versión: la segunda escritura choca', async () => {
  await handle('order-1', reserve(1, 2));
  // Dos procesos leyeron la orden en la versión 1 y los dos decidieron cobrarla.
  const paid = { type: 'OrderPaid', concertId: 1, quantity: 2, totalCents: 20000 } as const;
  await append('order-1', 1, [paid]);
  await assert.rejects(append('order-1', 1, [paid]), ConcurrencyConflict);
  assert.equal((await load('order-1')).length, 2, 'un solo OrderPaid');
});

test('la vista va atrasada: lo recién escrito no está en ella hasta que corre la proyección', async () => {
  await handle('order-1', reserve(1, 2));
  await handle('order-1', { type: 'PayOrder' });
  // La escritura ya se confirmó, y quien lee la vista todavía no la ve.
  assert.deepEqual(await readConcertSales(), []);
  assert.equal(await lag(), 2);

  assert.equal(await projectConcertSales(1), 1); // a medio camino: reservada y sin pagar
  assert.deepEqual(await readConcertSales(), [{ concert_id: 1, reserved_tickets: 2, paid_tickets: 0, revenue_cents: 0 }]);

  assert.equal(await catchUp(), 1);
  assert.equal(await lag(), 0);
  assert.deepEqual(await readConcertSales(), [{ concert_id: 1, reserved_tickets: 0, paid_tickets: 2, revenue_cents: 20000 }]);
});

test('proyectar de nuevo sin eventos nuevos no cambia la vista', async () => {
  await handle('order-1', reserve(1, 2));
  await catchUp();
  const before = await readConcertSales();
  assert.equal(await projectConcertSales(), 0);
  assert.deepEqual(await readConcertSales(), before);
});

test('la vista reconstruida desde el primer evento es igual a la que se mantuvo evento a evento', async () => {
  await handle('order-1', reserve(1, 2));
  await catchUp();
  await handle('order-2', reserve(2, 3));
  await handle('order-1', { type: 'PayOrder' });
  await catchUp();
  await handle('order-2', { type: 'PayOrder' });
  await handle('order-1', { type: 'RefundOrder', reason: 'no puede asistir' });
  await catchUp();
  const incremental = await readConcertSales();

  assert.equal(await rebuild(), 5);
  assert.deepEqual(await readConcertSales(), incremental);
  assert.deepEqual(incremental, [
    { concert_id: 1, reserved_tickets: 0, paid_tickets: 0, revenue_cents: 0 },
    { concert_id: 2, reserved_tickets: 0, paid_tickets: 3, revenue_cents: 30000 },
  ]);
});
ordering/order-status.test.tsDescargar ordering/order-status.test.ts
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { applyIfNewer, applyLastArrivalWins, type StatusEvent, type StatusView } from './order-status.ts';

// La orden 7 se pagó (versión 1) y después se devolvió (versión 2). El estado
// correcto, llegue como llegue, es "refunded".

const paid: StatusEvent = { orderId: 7, version: 1, type: 'OrderPaid' };
const refunded: StatusEvent = { orderId: 7, version: 2, type: 'OrderRefunded' };

function run(apply: (view: StatusView, event: StatusEvent) => void, arrivals: StatusEvent[]): string | undefined {
  const view: StatusView = new Map();
  for (const event of arrivals) apply(view, event);
  return view.get(7)?.status;
}

test('si los eventos llegan en orden, las dos maneras dan lo mismo', () => {
  assert.equal(run(applyLastArrivalWins, [paid, refunded]), 'refunded');
  assert.equal(run(applyIfNewer, [paid, refunded]), 'refunded');
});

test('si llegan al revés, "el último que llega gana" deja pagada una orden devuelta', () => {
  assert.equal(run(applyLastArrivalWins, [refunded, paid]), 'paid');
});

test('con versión, el resultado no depende del orden ni de los duplicados', () => {
  const arrivals = [
    [paid, refunded],
    [refunded, paid],
    [paid, refunded, paid], // el reintento de un mensaje antiguo
    [refunded, paid, refunded, paid],
  ];
  for (const order of arrivals) assert.equal(run(applyIfNewer, order), 'refunded');
});
test/consumers.test.tsDescargar test/consumers.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { recordDeadLetter } from '../consumers/dead-letter.ts';
import { compareReports, rebuildSalesReport } from '../consumers/replay.ts';
import { addToSalesReport } from '../consumers/report.ts';
import { addPointsNaive } from '../errors/points-naive.ts';
import { closeBus, consumerInfo, publish, startConsumer, type Handler } from '../shared/bus.ts';
import { closeDb, db } from '../shared/db.ts';
import { settings } from '../shared/settings.ts';
import { count, eventually, paid, pointsOf, publishOrders, reset, ROSA } from './helpers.ts';

// Los consumidores de la semana: el de puntos sin idempotencia, el del
// reporte (idempotente), la dead letter y la reconstrucción del reporte.

beforeEach(reset);
after(async () => {
  await closeBus();
  await closeDb();
});

const idle = async (name: string): Promise<boolean> => {
  const info = await consumerInfo(name);
  return info.num_pending === 0 && info.num_ack_pending === 0;
};

type ReportRow = { concert_id: number; orders: number; tickets: number; revenue_cents: number };
async function report(table: 'sales_report' | 'sales_report_rebuilt' = 'sales_report'): Promise<ReportRow[]> {
  const result = await db().query<ReportRow>(
    `SELECT concert_id, orders, tickets, revenue_cents::int AS revenue_cents FROM ${table} ORDER BY concert_id`,
  );
  return result.rows;
}

test('sin idempotencia, un evento publicado dos veces suma los puntos dos veces', async () => {
  const event = paid(1);
  await publish(settings.subjects.paid, event);
  await publish(settings.subjects.paid, event); // el duplicado que deja el relay
  const consumer = await startConsumer('points', addPointsNaive);
  await eventually('se procesan los dos mensajes', () => idle('points'));
  await consumer.stop();
  assert.equal(await pointsOf(ROSA), 20, 'una orden, y 20 puntos en vez de 10');
});

test('sin idempotencia, una entrega repetida (el consumidor falla antes de confirmar) también suma dos veces', async () => {
  await publish(settings.subjects.paid, paid(1));
  const consumer = await startConsumer('points', async (event, delivery) => {
    await addPointsNaive(event);
    if (delivery.deliveryCount === 1) throw new Error('el proceso falla después del efecto y antes del ack');
  });
  await eventually('se confirma en la segunda entrega', () => idle('points'));
  await consumer.stop();
  assert.equal(await pointsOf(ROSA), 20);
});

test('el consumidor del reporte es idempotente: ni el duplicado ni la reentrega cuentan dos veces', async () => {
  const event = paid(1, 2);
  await publish(settings.subjects.paid, event);
  await publish(settings.subjects.paid, event);
  const consumer = await startConsumer('report', async (received, delivery) => {
    await addToSalesReport(received);
    if (delivery.streamSeq === 1 && delivery.deliveryCount === 1) throw new Error('falla antes del ack');
  });
  await eventually('se procesa todo', () => idle('report'));
  await consumer.stop();

  // Tres entregas (seq 1 dos veces, seq 2 una) y un solo efecto.
  assert.deepEqual(await report(), [{ concert_id: 1, orders: 1, tickets: 2, revenue_cents: 32000 }]);
  assert.equal(await count('processed_events'), 1);
});

test('el id procesado y el efecto van en la misma transacción: si el efecto falla, el id no queda', async () => {
  // Un evento con un concierto imposible para la columna: la suma falla.
  const broken = { ...paid(1), concertId: Number.NaN };
  await assert.rejects(addToSalesReport(broken));
  assert.equal(await count('processed_events'), 0, 'el ROLLBACK se llevó también el id');
  assert.deepEqual(await report(), []);
});

test('un mensaje envenenado, sin límite de entregas, se reintenta para siempre', async () => {
  await publishOrders(3);
  let attemptsOnPoison = 0;
  const handler: Handler = async (event) => {
    if (event.orderId === 2) {
      attemptsOnPoison += 1;
      throw new Error('no puedo procesar la orden 2');
    }
    await addPointsNaive(event);
  };
  const consumer = await startConsumer('points', handler);
  // Cinco intentos y contando: nadie lo va a detener.
  await eventually('cinco intentos', () => attemptsOnPoison >= 5);
  await consumer.stop();

  assert.equal(await pointsOf(ROSA), 20, 'las órdenes 1 y 3 sí se procesaron');
  assert.equal((await consumerInfo('points')).num_ack_pending, 1, 'la orden 2 sigue pendiente');
  assert.equal(await count('dead_letters'), 0);
});

test('con max_deliver = 3, el mensaje envenenado va a dead_letters y los demás se procesan', async () => {
  await publishOrders(3);
  let attemptsOnPoison = 0;
  const handler: Handler = async (event) => {
    if (event.orderId === 2) {
      attemptsOnPoison += 1;
      throw new Error('no puedo procesar la orden 2');
    }
    await addPointsNaive(event);
  };
  const consumer = await startConsumer('points', handler, { maxDeliver: 3, onGiveUp: recordDeadLetter('points') });
  await eventually('nada pendiente', () => idle('points'));
  await consumer.stop();

  assert.equal(attemptsOnPoison, 3);
  assert.equal(await pointsOf(ROSA), 20);
  const dead = await db().query<{ stream_seq: string; deliveries: number; order_id: string; reason: string }>(
    `SELECT stream_seq, deliveries, payload->>'orderId' AS order_id, reason FROM dead_letters`,
  );
  assert.equal(dead.rows.length, 1);
  assert.deepEqual(
    { ...dead.rows[0] },
    { stream_seq: '2', deliveries: 3, order_id: '2', reason: 'Error: no puedo procesar la orden 2' },
  );
});

test('reprocesar: el reporte reconstruido desde el inicio del stream es igual al original', async () => {
  const events = await publishOrders(12);
  // El stream tiene además un duplicado, como los que deja el relay.
  await publish(settings.subjects.paid, events[4]!);
  const consumer = await startConsumer('report', (event) => addToSalesReport(event));
  await eventually('el reporte original', () => idle('report'));
  const delivered = (await consumerInfo('report')).delivered.stream_seq;

  const read = await rebuildSalesReport();
  await consumer.stop();

  assert.equal(read, 13);
  assert.deepEqual(await compareReports(), []);
  assert.deepEqual(await report('sales_report_rebuilt'), await report());
  assert.equal((await report()).reduce((sum, row) => sum + row.orders, 0), 12, 'doce órdenes, no trece');
  // El consumer original no se movió: reconstruir fue trabajo de otro consumer.
  assert.equal((await consumerInfo('report')).delivered.stream_seq, delivered);
});

test('reprocesar dos veces da lo mismo, y un consumidor no idempotente no lo soportaría', async () => {
  const events = await publishOrders(6);
  await publish(settings.subjects.paid, events[0]!);
  await rebuildSalesReport();
  const once = await report('sales_report_rebuilt');
  await rebuildSalesReport();
  assert.deepEqual(await report('sales_report_rebuilt'), once);

  // El consumidor de puntos ingenuo, sobre el mismo stream: 7 mensajes, 6 órdenes.
  const consumer = await startConsumer('points', addPointsNaive);
  await eventually('puntos', () => idle('points'));
  await consumer.stop();
  assert.equal(await pointsOf(ROSA), 70, '70 puntos por 6 órdenes');
});
test/dual-write.test.tsDescargar test/dual-write.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { closeBus, readStream } from '../shared/bus.ts';
import { closeDb } from '../shared/db.ts';
import { count, reset, runNode } from './helpers.ts';

// La escritura doble (errors/dual-write.ts). Cada compra corre en su propio
// proceso, y el proceso muere de verdad (SIGKILL) entre las dos operaciones.

const buy = (env: Record<string, string>) => runNode('tools/buy.ts', [], { PLACE: 'dual-write', ...env });

beforeEach(reset);
after(async () => {
  await closeBus();
  await closeDb();
});

test('sin caídas, cada orden tiene su evento', async () => {
  for (let i = 1; i <= 3; i += 1) assert.equal((await buy({ I: String(i) })).code, 0);
  assert.equal(await count('orders'), 3);
  assert.equal((await readStream()).length, 3);
});

test('si el proceso muere después del COMMIT y antes de publicar, queda una orden sin evento', async () => {
  for (let i = 1; i <= 3; i += 1) assert.equal((await buy({ I: String(i), CRASH_BETWEEN: '1' })).signal, 'SIGKILL');
  assert.equal(await count('orders'), 3);
  assert.equal((await readStream()).length, 0);
});

test('publicar primero no lo arregla: queda un evento de una orden que no existe', async () => {
  assert.equal((await buy({ PUBLISH_FIRST: '1', CRASH_BETWEEN: '1' })).signal, 'SIGKILL');
  assert.equal(await count('orders'), 0);
  const stored = await readStream();
  assert.equal(stored.length, 1);
  assert.equal(stored[0]!.event.type, 'OrderPaid');
});
test/helpers.tsDescargar test/helpers.ts
import { spawn } from 'node:child_process';
import { setTimeout as sleep } from 'node:timers/promises';
import { deleteStream, ensureStream, publish } from '../shared/bus.ts';
import { db } from '../shared/db.ts';
import { newOrderPaid, type OrderPaid } from '../shared/events.ts';
import { settings } from '../shared/settings.ts';

/** Deja la base de datos y el stream de pruebas vacíos. */
export async function reset(): Promise<void> {
  await db().query(
    `TRUNCATE orders, outbox, loyalty_points, sales_report, sales_report_rebuilt, processed_events, dead_letters,
              es_events, es_concert_sales, es_checkpoints RESTART IDENTITY`,
  );
  await deleteStream();
  await ensureStream();
}

/** Espera, consultando cada 20 ms, a que `check` devuelva true. Falla si pasan 15 s. */
export async function eventually(what: string, check: () => Promise<boolean> | boolean): Promise<void> {
  const deadline = performance.now() + 15_000;
  while (!(await check())) {
    if (performance.now() > deadline) throw new Error(`No ocurrió en 15 s: ${what}`);
    await sleep(20);
  }
}

export const ROSA = 'rosa.quispe@correo.pe';

/** Un evento OrderPaid de Rosa: `quantity` entradas del concierto 1, a S/ 160 cada una. */
export function paid(orderId: number, quantity = 1, concertId = 1): OrderPaid {
  return newOrderPaid({ orderId, concertId, buyerEmail: ROSA, quantity, totalCents: quantity * 16000 });
}

/** Publica los eventos de las órdenes 1 a n y los devuelve. */
export async function publishOrders(n: number): Promise<OrderPaid[]> {
  const events: OrderPaid[] = [];
  for (let orderId = 1; orderId <= n; orderId += 1) {
    const event = paid(orderId, (orderId % 3) + 1, (orderId % 2) + 1);
    await publish(settings.subjects.paid, event);
    events.push(event);
  }
  return events;
}

export async function count(table: 'orders' | 'outbox' | 'dead_letters' | 'processed_events'): Promise<number> {
  const result = await db().query<{ n: string }>(`SELECT count(*) AS n FROM ${table}`);
  return Number(result.rows[0]!.n);
}

export async function pointsOf(email: string): Promise<number> {
  const result = await db().query<{ points: number }>('SELECT points FROM loyalty_points WHERE buyer_email = $1', [
    email,
  ]);
  return result.rows[0]?.points ?? 0;
}

export type Exit = { code: number | null; signal: NodeJS.Signals | null };

/**
 * Corre un programa de la semana en otro proceso, para poder matarlo de
 * verdad. No bloquea: el proceso de pruebas sigue atendiendo sus conexiones.
 */
export function runNode(script: string, args: string[], env: Record<string, string> = {}): Promise<Exit> {
  return new Promise((resolve, reject) => {
    const child = spawn('node', [script, ...args], { env: { ...process.env, ...env }, stdio: 'ignore' });
    child.once('error', reject);
    child.once('exit', (code, signal) => resolve({ code, signal }));
  });
}
test/jetstream.test.tsDescargar test/jetstream.test.ts
import assert from 'node:assert/strict';
import { setTimeout as sleep } from 'node:timers/promises';
import { after, beforeEach, test } from 'node:test';
import { AckPolicy, DiscardPolicy, RetentionPolicy } from 'nats';
import {
  closeBus,
  connectBus,
  consumerInfo,
  ensureConsumer,
  publish,
  startConsumer,
  streamState,
  type Handler,
} from '../shared/bus.ts';
import { closeDb } from '../shared/db.ts';
import { settings } from '../shared/settings.ts';
import { eventually, paid, publishOrders, reset } from './helpers.ts';

// Lo que los apuntes afirman de NATS JetStream, comprobado contra el servidor
// del contenedor. Las pruebas corren con ACK_WAIT_MS=1000 y
// REDELIVERY_DELAY_MS=100 para no esperar de más.

beforeEach(reset);
after(async () => {
  await closeBus();
  await closeDb();
});

const idle = async (name: string): Promise<boolean> => {
  const info = await consumerInfo(name);
  return info.num_pending === 0 && info.num_ack_pending === 0;
};

/** Un handler que anota las secuencias que terminó de procesar. */
function recorder(into: number[], workMs = 0): Handler {
  return async (_event, delivery) => {
    if (workMs > 0) await sleep(workMs);
    into.push(delivery.streamSeq);
  };
}

test('log: dos consumers independientes reciben, cada uno, todos los mensajes; leer no borra', async () => {
  await publishOrders(6);
  const a: number[] = [];
  const b: number[] = [];
  const readerA = await startConsumer('reader-a', recorder(a));
  await eventually('A termina', () => idle('reader-a'));
  // B llega cuando A ya leyó y confirmó todo, y aun así recibe los seis.
  const readerB = await startConsumer('reader-b', recorder(b));
  await eventually('B termina', () => idle('reader-b'));
  await readerA.stop();
  await readerB.stop();

  assert.deepEqual(a, [1, 2, 3, 4, 5, 6]);
  assert.deepEqual(b, [1, 2, 3, 4, 5, 6]);
  assert.equal((await streamState()).messages, 6);
});

test('cola: dos lectores del mismo consumer se reparten los mensajes; cada uno llega a uno solo', async () => {
  await publishOrders(20);
  const first: number[] = [];
  const second: number[] = [];
  const workerA = await startConsumer('shared', recorder(first, 5));
  const workerB = await startConsumer('shared', recorder(second, 5));
  await eventually('se procesan todos', () => idle('shared'));
  await workerA.stop();
  await workerB.stop();

  assert.ok(first.length > 0 && second.length > 0, `repartidos ${first.length} y ${second.length}`);
  assert.deepEqual([...first, ...second].sort((x, y) => x - y), Array.from({ length: 20 }, (_, i) => i + 1));
});

test('un consumer que se detiene sigue después donde se quedó: no vuelve a recibir lo confirmado', async () => {
  await publishOrders(3);
  const before: number[] = [];
  const firstRun = await startConsumer('resumes', recorder(before));
  await eventually('los tres primeros', () => idle('resumes'));
  await firstRun.stop();

  await publish(settings.subjects.paid, paid(4));
  await publish(settings.subjects.paid, paid(5));
  const afterRestart: number[] = [];
  const secondRun = await startConsumer('resumes', recorder(afterRestart));
  await eventually('los dos nuevos', () => idle('resumes'));
  await secondRun.stop();

  assert.deepEqual(before, [1, 2, 3]);
  assert.deepEqual(afterRestart, [4, 5]);
});

test('confirmar después (at-least-once): lo que no se confirmó se entrega de nuevo, con deliveryCount 2', async () => {
  await publishOrders(1);
  const deliveries: number[] = [];
  let effects = 0;
  const consumer = await startConsumer('at-least-once', async (_event, delivery) => {
    deliveries.push(delivery.deliveryCount);
    effects += 1; // el efecto ocurre...
    if (delivery.deliveryCount === 1) throw new Error('y el proceso falla antes de confirmar');
  });
  await eventually('se confirma', () => idle('at-least-once'));
  await consumer.stop();

  assert.deepEqual(deliveries, [1, 2]);
  assert.equal(effects, 2, 'el efecto se aplicó dos veces');
});

test('confirmar antes (at-most-once): si el trabajo falla después, el mensaje no vuelve', async () => {
  await publishOrders(2);
  const deliveries: number[] = [];
  let effects = 0;
  const consumer = await startConsumer(
    'at-most-once',
    async (_event, delivery) => {
      deliveries.push(delivery.streamSeq);
      if (delivery.streamSeq === 1) throw new Error('falla después de confirmar');
      effects += 1;
    },
    { ackFirst: true },
  );
  await eventually('nada pendiente', () => idle('at-most-once'));
  // Más que ack_wait (1 s en las pruebas): si fuera a volver, ya habría vuelto.
  await sleep(1500);
  await consumer.stop();

  assert.deepEqual(deliveries, [1, 2]);
  assert.equal(effects, 1, 'el efecto del mensaje 1 se perdió');
});

test('sin confirmación ni rechazo, el servidor reentrega cuando vence ack_wait', async () => {
  await publishOrders(1);
  await ensureConsumer('silent');
  const { js } = await connectBus();
  const consumer = await js.consumers.get(settings.stream, 'silent');
  const started = performance.now();
  const first = await consumer.next(); // se recibe y no se responde nada
  assert.equal(first?.info.deliveryCount, 1);
  const second = await consumer.next({ expires: 5000 });
  const waited = performance.now() - started;
  assert.equal(second?.info.deliveryCount, 2);
  assert.ok(waited >= 900, `la reentrega llegó a los ${waited.toFixed(0)} ms; ack_wait es 1000 ms`);
  second?.ack();
});

test('orden: un lector procesa en el orden del stream', async () => {
  await publishOrders(8);
  const finished: number[] = [];
  const consumer = await startConsumer('one', async (_event, delivery) => {
    await sleep(delivery.streamSeq % 2 === 1 ? 20 : 2);
    finished.push(delivery.streamSeq);
  });
  await eventually('termina', () => idle('one'));
  await consumer.stop();
  assert.deepEqual(finished, [1, 2, 3, 4, 5, 6, 7, 8]);
});

test('orden: con un reintento, un mensaje antiguo se procesa después de los nuevos', async () => {
  await publishOrders(4);
  const finished: number[] = [];
  const consumer = await startConsumer('retry', async (_event, delivery) => {
    if (delivery.streamSeq === 2 && delivery.deliveryCount === 1) throw new Error('falla una vez');
    finished.push(delivery.streamSeq);
  });
  await eventually('termina', () => idle('retry'));
  await consumer.stop();
  assert.deepEqual([...finished].sort(), [1, 2, 3, 4]);
  assert.equal(finished.at(-1), 2, `orden: ${finished.join(' ')}`);
});

test('orden: con max_ack_pending = 1 el reintento no se adelanta, y los demás esperan', async () => {
  await publishOrders(4);
  const finished: number[] = [];
  const consumer = await startConsumer(
    'strict',
    async (_event, delivery) => {
      if (delivery.streamSeq === 2 && delivery.deliveryCount === 1) throw new Error('falla una vez');
      finished.push(delivery.streamSeq);
    },
    { maxAckPending: 1 },
  );
  await eventually('termina', () => idle('strict'));
  await consumer.stop();
  assert.deepEqual(finished, [1, 2, 3, 4]);
});

test('Nats-Msg-Id: el stream descarta una publicación repetida dentro de su ventana de duplicados', async () => {
  const event = paid(1);
  const first = await publish(settings.subjects.paid, event, { msgId: event.id });
  const again = await publish(settings.subjects.paid, event, { msgId: event.id });
  assert.equal(first.duplicate, false);
  assert.equal(again.duplicate, true);
  assert.equal((await streamState()).messages, 1);

  // Sin la cabecera, el stream no tiene cómo saber que es el mismo evento.
  await publish(settings.subjects.paid, event);
  assert.equal((await streamState()).messages, 2);
});

test('un stream con límite: discard old borra lo más antiguo; discard new rechaza al productor', async () => {
  const { js, jsm } = await connectBus();
  const name = `${settings.stream}_LIMITS`;
  const subject = `${settings.subjectPrefix}limits.a`;
  try {
    for (const discard of [DiscardPolicy.Old, DiscardPolicy.New]) {
      await jsm.streams.delete(name).catch(() => undefined);
      await jsm.streams.add({ name, subjects: [subject], max_msgs: 3, discard });
      let rejected = 0;
      for (let i = 1; i <= 5; i += 1) await js.publish(subject, String(i)).catch(() => (rejected += 1));
      const { state } = await jsm.streams.info(name);
      if (discard === DiscardPolicy.Old) assert.deepEqual([rejected, state.first_seq, state.last_seq], [0, 3, 5]);
      else assert.deepEqual([rejected, state.first_seq, state.last_seq], [2, 1, 3]);
    }
  } finally {
    await jsm.streams.delete(name).catch(() => undefined);
  }
});

test('retención por trabajo (work queue): el mensaje confirmado se borra del stream', async () => {
  const { js, jsm } = await connectBus();
  const name = `${settings.stream}_WORK`;
  const subject = `${settings.subjectPrefix}work.a`;
  try {
    await jsm.streams.delete(name).catch(() => undefined);
    await jsm.streams.add({ name, subjects: [subject], retention: RetentionPolicy.Workqueue });
    for (let i = 1; i <= 3; i += 1) await js.publish(subject, String(i));
    await jsm.consumers.add(name, { durable_name: 'workers', ack_policy: AckPolicy.Explicit });
    const consumer = await js.consumers.get(name, 'workers');
    const message = await consumer.next();
    await message?.ackAck();
    assert.equal((await jsm.streams.info(name)).state.messages, 2);

    // Y no admite un segundo consumer sobre los mismos mensajes: es una cola.
    await assert.rejects(jsm.consumers.add(name, { durable_name: 'others', ack_policy: AckPolicy.Explicit }));
  } finally {
    await jsm.streams.delete(name).catch(() => undefined);
  }
});
test/outbox-order.test.tsDescargar test/outbox-order.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { closeBus } from '../shared/bus.ts';
import { closeDb, db } from '../shared/db.ts';
import { paid, reset } from './helpers.ts';

// Un detalle de la outbox que los apuntes mencionan: el id de una fila se
// asigna al insertarla, no al confirmar. Dos transacciones concurrentes
// pueden confirmarse en el orden contrario al de sus ids.

beforeEach(reset);
after(async () => {
  await closeBus();
  await closeDb();
});

const insert = 'INSERT INTO outbox (event_id, subject, payload) VALUES ($1, $2, $3) RETURNING id';
const row = (orderId: number): [string, string, string] => {
  const event = paid(orderId);
  return [event.id, 'w13test.orders.paid', JSON.stringify(event)];
};
const pendingIds = async (): Promise<number[]> =>
  (await db().query<{ id: string }>('SELECT id FROM outbox WHERE published_at IS NULL ORDER BY id')).rows.map((r) => Number(r.id));

test('la fila 2 puede hacerse visible antes que la 1: buscar "lo pendiente" no la pierde; buscar "id mayor que el último" sí', async () => {
  const slow = await db().connect();
  const fast = await db().connect();
  try {
    await slow.query('BEGIN');
    await slow.query(insert, row(1)); // recibe el id 1 y todavía no confirma
    await fast.query('BEGIN');
    await fast.query(insert, row(2)); // recibe el id 2...
    await fast.query('COMMIT'); // ...y confirma primero

    // El relay mira ahora: solo existe la fila 2. La publica y la marca.
    assert.deepEqual(await pendingIds(), [2]);
    await db().query('UPDATE outbox SET published_at = now() WHERE id = 2');
    const lastSeen = 2;

    await slow.query('COMMIT');

    // Un relay que busca lo pendiente encuentra la fila 1 (tarde y fuera de orden, pero la encuentra).
    assert.deepEqual(await pendingIds(), [1]);
    // Un relay que recordara "ya publiqué hasta el id 2" no la vería nunca.
    const afterCursor = await db().query('SELECT id FROM outbox WHERE id > $1', [lastSeen]);
    assert.equal(afterCursor.rowCount, 0);
  } finally {
    slow.release();
    fast.release();
  }
});

Laboratorio

Archivos de partida del laboratorio de la semana.

lab/outbox.test.tsDescargar lab/outbox.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { closeBus, readStream } from '../shared/bus.ts';
import { closeDb, db } from '../shared/db.ts';
import { loadOutbox } from '../shared/impl.ts';
import { count, reset, ROSA, runNode } from '../test/helpers.ts';

// Paso 4 del laboratorio: la compra con outbox. Fallan hasta que completen
// lab/outbox.ts.

const { placeOrder } = await loadOutbox();

beforeEach(reset);
after(async () => {
  await closeBus();
  await closeDb();
});

test('la compra deja la orden y, en la outbox, su evento sin publicar', async () => {
  const order = await placeOrder({ concertId: 1, buyerEmail: ROSA, quantity: 2 });
  const rows = await db().query<{ event_id: string; subject: string; payload: Record<string, unknown>; published_at: Date | null }>(
    'SELECT event_id, subject, payload, published_at FROM outbox',
  );
  assert.equal(rows.rows.length, 1);
  const row = rows.rows[0]!;
  assert.equal(row.published_at, null);
  assert.match(row.subject, /\.paid$/);
  assert.equal(row.payload.id, row.event_id, 'event_id es el id del evento');
  assert.equal(row.payload.type, 'OrderPaid');
  assert.equal(row.payload.orderId, order.orderId);
  assert.equal(row.payload.totalCents, 32000);
});

test('la compra no publica nada: eso es trabajo del relay', async () => {
  await placeOrder({ concertId: 1, buyerEmail: ROSA, quantity: 1 });
  assert.equal((await readStream()).length, 0);
});

test('si la compra falla, no queda ni la orden ni el evento', async () => {
  await assert.rejects(placeOrder({ concertId: 99, buyerEmail: ROSA, quantity: 1 }));
  assert.equal(await count('orders'), 0);
  assert.equal(await count('outbox'), 0);
});

test('si el proceso muere a la mitad de la compra, tampoco: las cuentas coinciden', async () => {
  const buy = (env: Record<string, string>) => runNode('tools/buy.ts', [], { PLACE: 'outbox', ...env });
  assert.equal((await buy({ I: '1' })).code, 0);
  assert.equal((await buy({ I: '2', CRASH_BETWEEN: '1' })).signal, 'SIGKILL');
  assert.equal((await buy({ I: '3' })).code, 0);
  assert.equal(await count('orders'), 2);
  assert.equal(await count('outbox'), 2);
});
lab/outbox.tsDescargar lab/outbox.ts
import { crashPoint } from '../shared/crash.ts';
import { inTransaction } from '../shared/db.ts';
import { type PaidOrder } from '../shared/events.ts';
import { insertPaidOrder, type OrderInput } from '../shared/orders.ts';

// Laboratorio, paso 4. La compra con outbox: el evento no se publica aquí; se
// guarda en la tabla outbox, en la misma transacción que la orden. Publicarlo
// es trabajo del relay (lab/relay.ts).
//
// Lo que deben completar está marcado con "PENDIENTE". Las pruebas de
// lab/outbox.test.ts (make test-lab) fallan hasta que esté hecho.
//
//   CRASH_BETWEEN=1    el proceso muere entre guardar la orden y guardar el evento

export async function placeOrder(input: OrderInput): Promise<PaidOrder> {
  return inTransaction(async (client) => {
    const order = await insertPaidOrder(client, input);
    crashPoint('CRASH_BETWEEN');

    // PENDIENTE: crear el evento con newOrderPaid(order) (shared/events.ts) e
    // insertarlo en la tabla outbox usando `client`, la conexión de esta
    // transacción, y no db(): con otra conexión sería otra transacción.
    // Columnas: event_id (el id del evento), subject (settings.subjects.paid)
    // y payload (el evento completo, como JSON).

    return order;
  });
}
lab/points.test.tsDescargar lab/points.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { closeBus, consumerInfo, publish, startConsumer } from '../shared/bus.ts';
import { closeDb, db } from '../shared/db.ts';
import { loadPoints } from '../shared/impl.ts';
import { settings } from '../shared/settings.ts';
import { eventually, paid, pointsOf, reset, ROSA } from '../test/helpers.ts';

// Paso 6 del laboratorio: el consumidor de puntos, idempotente. Fallan hasta
// que completen lab/points.ts.

const { addPoints } = await loadPoints();

const idle = async (): Promise<boolean> => {
  const info = await consumerInfo('points');
  return info.num_pending === 0 && info.num_ack_pending === 0;
};

beforeEach(reset);
after(async () => {
  await closeBus();
  await closeDb();
});

test('dos órdenes distintas suman 20 puntos', async () => {
  await addPoints(paid(1));
  await addPoints(paid(2));
  assert.equal(await pointsOf(ROSA), 20);
});

test('el mismo evento, publicado dos veces, suma una sola vez', async () => {
  const event = paid(1);
  await publish(settings.subjects.paid, event);
  await publish(settings.subjects.paid, event);
  const consumer = await startConsumer('points', addPoints);
  await eventually('se procesan los dos mensajes', idle);
  await consumer.stop();
  assert.equal(await pointsOf(ROSA), 10);
});

test('una entrega repetida (falla después del efecto y antes de confirmar) suma una sola vez', async () => {
  await publish(settings.subjects.paid, paid(1));
  const consumer = await startConsumer('points', async (event, delivery) => {
    await addPoints(event);
    if (delivery.deliveryCount === 1) throw new Error('falla antes del ack');
  });
  await eventually('se confirma en la segunda entrega', idle);
  await consumer.stop();
  assert.equal(await pointsOf(ROSA), 10);
});

test('el id del evento se guarda en la misma transacción que la suma', async () => {
  // Un comprador que la tabla no acepta (NULL): la suma falla, y el id del
  // evento no debe quedar anotado, o el reintento lo daría por procesado.
  const broken = { ...paid(1), buyerEmail: null as unknown as string };
  await assert.rejects(addPoints(broken));
  const noted = await db().query('SELECT 1 FROM processed_events WHERE event_id = $1', [broken.id]);
  assert.equal(noted.rowCount, 0);

  await addPoints(paid(2));
  const processed = await db().query('SELECT 1 FROM processed_events');
  assert.equal(processed.rowCount, 1, 'un evento procesado, un id anotado');
});
lab/points.tsDescargar lab/points.ts
import { db } from '../shared/db.ts';
import type { OrderPaid } from '../shared/events.ts';

// Laboratorio, paso 6. El consumidor de puntos: 10 puntos por cada OrderPaid.
// Así como está, suma otra vez cuando el mismo evento llega dos veces (es
// igual a errors/points-naive.ts). Háganlo idempotente: las pruebas de
// lab/points.test.ts (make test-lab) fallan hasta que lo sea.

export const POINTS_PER_ORDER = 10;
/** El nombre con que este consumidor anota lo que ya procesó. */
export const CONSUMER = 'points';

export async function addPoints(event: OrderPaid): Promise<void> {
  // PENDIENTE: anotar event.id en processed_events (con CONSUMER) en la misma
  // transacción que la suma, y no sumar si ya estaba anotado. Para la
  // transacción, inTransaction() de shared/db.ts. consumers/report.ts hace lo
  // mismo para el reporte de ventas.
  await db().query(
    `INSERT INTO loyalty_points (buyer_email, points) VALUES ($1, $2)
     ON CONFLICT (buyer_email) DO UPDATE SET points = loyalty_points.points + EXCLUDED.points`,
    [event.buyerEmail, POINTS_PER_ORDER],
  );
}
lab/relay.test.tsDescargar lab/relay.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { closeBus, readStream } from '../shared/bus.ts';
import { closeDb, db } from '../shared/db.ts';
import { loadRelay } from '../shared/impl.ts';
import { paid, reset, runNode } from '../test/helpers.ts';

// Pasos 4 y 5 del laboratorio: el relay. Fallan hasta que completen
// lab/relay.ts. Las filas de la outbox se insertan aquí directamente, para
// que estas pruebas no dependan de lab/outbox.ts.

const { relayOnce } = await loadRelay();

async function enqueue(n: number): Promise<string[]> {
  const ids: string[] = [];
  for (let orderId = 1; orderId <= n; orderId += 1) {
    const event = paid(orderId);
    await db().query('INSERT INTO outbox (event_id, subject, payload) VALUES ($1, $2, $3)', [
      event.id,
      `${process.env.W13_SUBJECT_PREFIX ?? 'w13.orders'}.paid`,
      JSON.stringify(event),
    ]);
    ids.push(event.id);
  }
  return ids;
}

const pending = async (): Promise<number> =>
  Number((await db().query<{ n: string }>('SELECT count(*) AS n FROM outbox WHERE published_at IS NULL')).rows[0]!.n);

beforeEach(reset);
after(async () => {
  await closeBus();
  await closeDb();
});

test('publica lo pendiente en el orden de la outbox y lo marca como enviado', async () => {
  const ids = await enqueue(3);
  assert.equal(await relayOnce(), 3);
  const stored = await readStream();
  assert.deepEqual(stored.map((message) => message.event.id), ids);
  assert.deepEqual(stored.map((message) => message.event.orderId), [1, 2, 3]);
  assert.equal(await pending(), 0);
});

test('lo que ya se marcó no se publica otra vez', async () => {
  await enqueue(2);
  await relayOnce();
  assert.equal(await relayOnce(), 0);
  assert.equal((await readStream()).length, 2);
});

test('si muere después de publicar y antes de marcar, al reiniciar publica ese evento otra vez', async () => {
  const ids = await enqueue(1);
  const crashed = await runNode('tools/relay.ts', ['once'], { CRASH_AFTER_PUBLISH: '1' });
  assert.equal(crashed.signal, 'SIGKILL');
  assert.equal((await readStream()).length, 1, 'el evento sí salió');
  assert.equal(await pending(), 1, 'y la fila quedó sin marcar');

  assert.equal(await relayOnce(), 1);
  const stored = await readStream();
  // At-least-once: dos mensajes en el stream, el mismo evento.
  assert.deepEqual(stored.map((message) => message.event.id), [ids[0], ids[0]]);
  assert.equal(await pending(), 0);
});
lab/relay.tsDescargar lab/relay.ts
// Laboratorio, paso 4. El relay: el proceso que lee la tabla outbox y publica
// en el stream lo que está pendiente.
//
// Lo que deben completar está marcado con "PENDIENTE". Las pruebas de
// lab/relay.test.ts (make test-lab) fallan hasta que esté hecho.
//
//   CRASH_AFTER_PUBLISH=1    el proceso muere después de publicar un evento y
//                            antes de marcarlo como enviado (paso 5)

/**
 * Publica los eventos pendientes de la outbox, en orden de id, y marca cada
 * uno como enviado. Devuelve cuántos publicó.
 */
export async function relayOnce(): Promise<number> {
  // PENDIENTE:
  // 1. Leer de outbox las filas con published_at IS NULL, ordenadas por id
  //    (con un LIMIT, para no traer la tabla entera).
  // 2. Por cada fila: publicar el payload en su subject con publish()
  //    (shared/bus.ts), que espera la confirmación del stream; después llamar
  //    a crashPoint('CRASH_AFTER_PUBLISH') (shared/crash.ts); y después poner
  //    published_at = now() en esa fila.
  // 3. Devolver el número de filas publicadas.
  //
  // Antes de escribirlo, decidan qué pasa si el proceso muere en cada línea.
  return 0;
}

Compilación

Cómo se compilan y ejecutan los ejemplos.

MakefileDescargar Makefile
# Semana 13: mensajería, eventos y consistencia. Una aplicación pequeña de
# venta de entradas con outbox, relay y consumidores sobre NATS JetStream, y
# un agregado con event sourcing. Se usa dentro del contenedor del curso.
#
#   make                 crea la base de datos arq_w13 y deja el stream W13_ORDERS vacío
#   make test            revisa los tipos (tsc) y corre las pruebas (test/*.test.ts, es/, ...)
#   make test-lab        las pruebas de lab/: fallan hasta que completen el laboratorio
#   make clean           borra las bases de datos, los streams y build/
#
# La escritura doble y la outbox (pasos 3 a 5 del laboratorio):
#   make dual-write N=100   N compras con errors/dual-write.ts, un proceso por compra
#   make outbox N=100       N compras con lab/outbox.ts
#   make relay              el relay, hasta Ctrl+C; make relay-once publica lo pendiente y termina
#   make counts             órdenes, filas de la outbox y eventos en el stream
# Variables: CRASH_BETWEEN=1 (o 0.5: la mitad de las veces), PUBLISH_FIRST=1,
# CRASH_AFTER_PUBLISH=1, RELAY_MSG_ID=1.
#
# Los consumidores (pasos 6 a 8):
#   make consumer C=points-naive   C puede ser points-naive, points o report
#   make status                    puntos, reporte y dead letters, al lado de las órdenes
#   make replay                    reconstruye el reporte desde el inicio del stream y compara
#   make info C=points             el estado de un consumer, con nats consumer info
# Variables: POISON_ORDER=3 (falla siempre con esa orden), MAX_DELIVER=3.
#
# Lo que JetStream garantiza, mostrado (demos/):
#   make worker C=shared           un proceso que lee con el consumer C y dice qué recibió
#   make demo-ack                  confirmar antes o después de procesar, con una caída en medio
#   make demo-order                el orden con uno y con tres procesos, y con un reintento
#   make demo-max-deliveries       cómo avisa el servidor que se agotaron las entregas
#   make demo-limits               un stream con límite: descartar lo viejo o rechazar lo nuevo
#
# Event sourcing y CQRS (Sesión B):
#   make es                        un agregado, su historia y su vista de lectura
#
# W13_IMPL=solution usa solution/ en vez de lab/ (si tienen esa carpeta).

N ?= 100
C ?= points
STREAM = W13_ORDERS
DB = arq_w13
# psql no avisa cuando la base de datos que se va a borrar todavía no existe.
PGOPTIONS = --client-min-messages=warning
export PGOPTIONS

TEST_ENV = W13_DB=$(DB)_test W13_STREAM=W13_TEST_ORDERS W13_SUBJECT_PREFIX=w13test.orders W13_LOG=off \
  REDELIVERY_DELAY_MS=100 ACK_WAIT_MS=1000
TESTS = "test/*.test.ts" "es/*.test.ts" "ordering/*.test.ts" "consensus/*.test.ts"

.PHONY: all db test test-lab test-db dual-write outbox relay relay-once counts consumer status replay info \
        worker demo-ack demo-order demo-max-deliveries demo-limits es clean

all: db

db:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS $(DB) WITH (FORCE)" -c "CREATE DATABASE $(DB)"
	@psql -q -d $(DB) -v ON_ERROR_STOP=1 -f db/schema.sql -f es/schema.sql
	@nats stream rm -f $(STREAM) >/dev/null 2>&1 || true
	@echo "Base de datos $(DB) recién creada; stream $(STREAM) borrado."

# Las pruebas usan su propia base de datos y su propio stream: no necesitan
# nada corriendo ni tocan los datos de los experimentos. Comparten la base de
# datos, así que los archivos corren uno después de otro.
test-db:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS $(DB)_test WITH (FORCE)" -c "CREATE DATABASE $(DB)_test"
	@psql -q -d $(DB)_test -v ON_ERROR_STOP=1 -f db/schema.sql -f es/schema.sql

# Si existe solution/, make test corre además las pruebas del laboratorio
# contra ella.
test: test-db
	tsc -p .
	$(TEST_ENV) node --test --test-concurrency=1 $(TESTS)
	@if [ -d solution ]; then \
	  echo "== las pruebas de lab/ con solution/"; \
	  $(TEST_ENV) W13_IMPL=solution node --test --test-concurrency=1 "lab/*.test.ts"; \
	fi

test-lab: test-db
	$(TEST_ENV) node --test --test-concurrency=1 "lab/*.test.ts"

dual-write:
	@bash tools/repeat.sh $(N) dual-write

outbox:
	@bash tools/repeat.sh $(N) outbox

relay:
	@node tools/relay.ts

relay-once:
	@node tools/relay.ts once

counts:
	@node tools/counts.ts

consumer:
	@node tools/consumer.ts $(C)

status:
	@node tools/status.ts

replay:
	@node tools/replay.ts

info:
	nats consumer info $(STREAM) $(C)

worker:
	@node tools/worker.ts $(C)

# Las demostraciones usan su propio stream, W13_DEMO, y lo borran al terminar.
DEMO_ENV = W13_STREAM=W13_DEMO W13_SUBJECT_PREFIX=w13demo.orders ACK_WAIT_MS=1000 REDELIVERY_DELAY_MS=300

demo-ack:
	@$(DEMO_ENV) node demos/ack-timing.ts

demo-order:
	@$(DEMO_ENV) W13_LOG=off node demos/ordering.ts

demo-max-deliveries:
	@$(DEMO_ENV) W13_LOG=off node demos/max-deliveries.ts

demo-limits:
	@node demos/limits.ts

es:
	@node es/main.ts

clean:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS $(DB) WITH (FORCE)" -c "DROP DATABASE IF EXISTS $(DB)_test WITH (FORCE)"
	@for s in $(STREAM) W13_TEST_ORDERS W13_DEMO; do nats stream rm -f $$s >/dev/null 2>&1 || true; done
	rm -rf build
package.jsonDescargar package.json
{
  "name": "week-13",
  "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": ["shared", "errors", "lab", "solution", "consumers", "demos", "es", "ordering", "consensus", "test", "tools"]
}