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:
- Documentación de NATS, JetStream y Consumers.
- Azure Architecture Center, Competing Consumers pattern.
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):
OrderPaidsale 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:
- Martin Fowler, Event Sourcing y CQRS.
- Azure Architecture Center, Event Sourcing pattern y CQRS pattern.
- Apuntes de Cambridge, secciones 6 y 7; el sitio de Raft, con su visualización.
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.
- Primer contacto: crear un stream
W13_ORDERSpara los subjectsw13.orders.>, publicar tres mensajes connats puby leerlos con un consumer. Ver el estado connats stream infoynats consumer info: mensajes guardados, entregados y pendientes de confirmación. - 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.
- El problema de la escritura doble: el programa
errors/dual-write.tsguarda la orden y publica el evento. Correrlo cien veces conCRASH_BETWEEN=1, que mata el proceso entre las dos operaciones, y otras cien conCRASH_BETWEEN=0.5, que lo mata la mitad de las veces. Contar las órdenes guardadas y los eventos publicados en cada caso. - Outbox: completar
lab/outbox.tspara que el evento se inserte en la tablaoutboxen la misma transacción que la orden, ylab/relay.tspara 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. - 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? - 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. - 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.
- 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
- Den un caso para una cola y otro para un log, y la propiedad que decide en cada uno.
- 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?
- ¿Por qué el broker no puede garantizar por sí solo exactly-once, es decir, que un efecto ocurra una sola vez?
- Los eventos
OrderPaidyOrderRefundedde la misma orden llegan en orden inverso. Den dos formas de diseñar para que eso no rompa nada. - ¿Qué problema resuelve CQRS y qué anomalía introduce? Relaciónenla con el retraso de replicación.
- 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.
// 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);
}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)],
);
};
}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;
}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],
);
});
}-- 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);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();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);
}
}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();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();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();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]);
}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();// 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 }];
}
}
}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;
}-- 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
);// 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 });
}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()]);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());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()]);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()]);#!/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"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;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();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.
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);
}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.
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);
});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,
);
});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 },
]);
});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');
});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');
});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');
});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 }));
});
}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);
}
});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.
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);
});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;
});
}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');
});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],
);
}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);
});// 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.
# 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{
"name": "week-13",
"private": true,
"type": "module"
}{
"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"]
}