12
Datos y sistemas distribuidos

Transacciones: dentro de una base de datos y entre servicios

Datos y sistemas distribuidos

Semana 12 — Transacciones: dentro de una base de datos y entre servicios

Objetivos

  • Explicar qué garantiza una transacción (ACID) y qué anomalías permite cada nivel de aislamiento, y reconocer en un fragmento de código una condición de carrera que el nivel por defecto no evita.
  • Impedir que un recurso se venda dos veces de tres maneras (lock explícito, restricción de unicidad, aislamiento serializable) y comparar su costo.
  • Explicar por qué una transacción no cubre a dos servicios, qué ofrece two-phase commit y por qué casi nunca se usa entre servicios.
  • Diseñar una saga con sus compensaciones, y hacerla segura con idempotencia y con el patrón outbox.

Sesión A — Transacciones y niveles de aislamiento: cómo se vende dos veces un asiento

Lecturas:

  • Kleppmann y Riccomini, Designing Data-Intensive Applications (2.ª ed.), cap. 8 Transactions.
  • Lectura libre: documentación de PostgreSQL 18, Transaction Isolation y Explicit Locking.

Lecturas complementarias:

Temas:

  • Una transacción agrupa varias lecturas y escrituras en una unidad: o se aplican todas o ninguna. Simplifica el manejo de errores: ante una falla, se aborta y se reintenta. ACID: atomicidad (todo o nada, también ante una caída), consistencia (los invariantes de la aplicación se mantienen; depende del código, no solo de la base de datos), aislamiento (las transacciones concurrentes no se pisan) y durabilidad (lo confirmado no se pierde).
  • El aislamiento es donde están los trade-offs. El ideal es serializable: el resultado es el mismo que si las transacciones hubieran corrido una tras otra. Cuesta rendimiento, así que las bases de datos ofrecen niveles más débiles, y el nivel por defecto casi nunca es serializable.
  • Read committed (el nivel por defecto de PostgreSQL): no se leen datos sin confirmar ni se sobrescriben. Sigue permitiendo que dos lecturas de la misma transacción vean datos distintos.
  • Snapshot isolation (lo que PostgreSQL llama repeatable read): cada transacción ve una foto consistente de la base de datos, gracias al control de concurrencia multiversión (MVCC). Quien lee no bloquea a quien escribe.
  • Anomalías que los niveles débiles permiten. Actualización perdida: dos transacciones leen un valor, lo modifican y lo escriben; una pisa a la otra. Write skew: dos transacciones leen los mismos datos, deciden a partir de ellos y escriben en filas distintas, de modo que cada una invalida la premisa de la otra (dos médicos se quitan de la guardia a la vez). Fantasmas: la decisión dependía de que no existiera una fila, y otra transacción la inserta.
  • Cómo se vende dos veces un asiento: SELECT para ver que está disponible, y después UPDATE para marcarlo vendido. Entre los dos, otra transacción hizo lo mismo. Es un patrón de comprobar y después actuar; el nivel read committed no lo impide.
  • Tres maneras de impedirlo. Lock explícito: SELECT … FOR UPDATE bloquea las filas hasta el final de la transacción; simple, serializa a quienes compiten por el mismo asiento, y hay que tomar los locks siempre en el mismo orden para no caer en un deadlock. Operación atómica con condición: UPDATE seats SET status = 'sold' WHERE id = $1 AND status = 'available' y revisar cuántas filas cambió; o una restricción de unicidad que rechace el segundo ticket del mismo asiento. Aislamiento serializable: la base de datos detecta el conflicto y aborta una de las dos transacciones, que hay que reintentar.
  • Control de concurrencia optimista y pesimista: suponer que no habrá conflicto y comprobar al final (una columna de versión, serializable por snapshots), o bloquear por adelantado. Con poca contención gana el optimista; con mucha (la apertura de una venta), los reintentos lo hunden.
  • La transacción como recurso: mientras está abierta ocupa una conexión y mantiene locks. Una transacción que espera a un servicio externo retiene todo eso durante la espera. En Tinkuy, la pasarela se llama dentro de la transacción.
  • Error común: creer que “usar transacciones” basta. La pregunta es qué nivel de aislamiento, y qué anomalía de ese nivel le hace daño a este invariante.
  • Error común: comprobar el invariante en la aplicación (un if) sin nada en la base de datos que lo respalde. Con dos instancias del servicio, el if de una no ve a la otra.

Sesión B — Transacciones entre servicios: two-phase commit, sagas, idempotencia y outbox

Lecturas:

Lecturas complementarias:

  • Designing Data-Intensive Applications (2.ª ed.), cap. 9 The Trouble with Distributed Systems.
  • Hector Garcia-Molina y Kenneth Salem, Sagas (1987), secciones 1 y 2.
  • Unmesh Joshi, Two-Phase Commit e Idempotent Receiver.

Temas:

  • El problema: una compra reserva asientos (base de datos de órdenes) y cobra (servicio de pagos, o la pasarela, que es de otra empresa). No hay una transacción que cubra las dos cosas. Si se cobra y luego falla el registro, hay un cobro sin entrada; si se registra y falla el cobro, una entrada sin pago.
  • Lo que hace difícil a un sistema distribuido: las fallas son parciales (una parte funciona y otra no), la red puede perder o demorar un mensaje, y un timeout no dice si la operación se hizo. No se puede saber; solo se puede diseñar para que repetir sea seguro.
  • Two-phase commit: un coordinador pregunta a todos los participantes si pueden confirmar (preparar) y, si todos dicen que sí, les ordena confirmar. Da atomicidad entre varios nodos. Su precio: un participante que dijo que sí queda bloqueado, con sus locks, hasta que el coordinador le responda; si el coordinador cae en ese momento, espera indefinidamente. Además exige que todos los participantes hablen el mismo protocolo, y una pasarela de pagos externa no lo hace. Se usa dentro de una base de datos distribuida; entre servicios, casi nunca.
  • Saga: una secuencia de transacciones locales, cada una en su servicio. Si un paso falla, se ejecutan transacciones de compensación que deshacen el efecto de los anteriores (liberar los asientos, devolver el cobro). No hay aislamiento: los estados intermedios se ven desde afuera (un asiento “reservado” que quizá vuelva a estar libre). Por eso los estados intermedios se modelan de forma explícita: pending, paid, cancelled.
  • Diseñar una saga. El orden importa: primero los pasos que se pueden compensar, después el paso que no (el punto de no retorno), y al final los que no pueden fallar y solo se reintentan. No todo se compensa: un correo enviado no se retira; se envía otro.
  • Coordinación. Coreografía: cada servicio reacciona a los eventos del anterior; poco acoplamiento y el flujo no está escrito en ningún lado. Orquestación: un coordinador guarda el estado de la saga y envía comandos; el flujo y sus errores están en un solo lugar. Es la pareja broker y mediator de la semana 5.
  • Idempotencia: una operación es idempotente si aplicarla dos veces deja lo mismo que aplicarla una. Como un timeout obliga a reintentar sin saber si la primera vez se hizo, todo paso de una saga y todo consumidor de mensajes tiene que serlo. La técnica general: la clave de idempotencia. Quien llama genera un identificador único por operación y lo envía en cada reintento; quien recibe guarda la clave con el resultado, en la misma transacción que el efecto, y ante una clave repetida devuelve el resultado guardado.
  • El problema de la escritura doble: actualizar la base de datos y publicar un mensaje son dos operaciones; el proceso puede morir entre las dos. Si publica primero, anuncia algo que no pasó; si confirma primero, puede no anunciarlo nunca.
  • Outbox: en la misma transacción local que el cambio de estado, se inserta el mensaje en una tabla outbox. Un proceso aparte lee esa tabla y publica en el broker, y marca el mensaje como enviado. Si muere antes de marcar, lo publica de nuevo: la entrega es at-least-once, y por eso los consumidores son idempotentes.
  • En Tinkuy (P4): la compra pasa a ser una saga orquestada: reservar asientos (compensable), cobrar (el punto de no retorno), emitir las entradas y notificar (se reintentan). El cobro lleva una clave de idempotencia.
  • Trade-off: una saga cambia aislamiento por disponibilidad y autonomía. Si el invariante de verdad exige atomicidad, la primera opción es mantener esos datos en un mismo servicio y una misma base de datos.
  • Error común: partir en dos servicios datos que cambian en la misma transacción, y después intentar recuperar la transacción con una saga.

Laboratorio — No vender el mismo asiento dos veces, de tres maneras

Referencias: PostgreSQL 18, Explicit Locking y Transaction Isolation; Stripe, idempotency. Material: code/week-12/. En parejas.

  1. Ver el problema: en Tinkuy sin modificar, make oversell. Anotar cuántas órdenes tuvieron éxito para el mismo asiento y cuántos tickets existen.
  2. Reproducirlo a mano con dos sesiones de psql, siguiendo el guion de code/week-12/: las dos hacen BEGIN, leen el asiento como disponible, lo marcan vendido y confirman. Anotar el orden exacto de los pasos que produce la doble venta.
  3. Primera solución, lock explícito: SELECT … FOR UPDATE al leer los asientos. Repetir el guion: ¿qué hace la segunda sesión mientras la primera no confirma? Aplicarlo al código y correr la prueba de concurrencia de la carpeta.
  4. Deadlock: dos órdenes que piden los asientos A y B en orden inverso. Provocarlo con el guion, leer el error de PostgreSQL y corregirlo ordenando los ids antes de bloquear.
  5. Segunda solución, sin locks explícitos: UPDATE … WHERE status = 'available' revisando el número de filas, más una restricción UNIQUE sobre el asiento en los tickets. Correr la prueba de concurrencia.
  6. Tercera solución, SERIALIZABLE: correr la prueba y contar cuántas transacciones terminan con error de serialización (40001). Agregar el reintento. ¿Qué pasa con la latencia cuando 200 compradores compiten por 10 asientos?
  7. Medir las tres con make load-sale y llenar la tabla (con los 2 000 asientos del evento 1 hay poca contención y las tres van a medir parecido: repitan con el script de la carpeta, que hace competir a 200 compradores por 10 asientos): órdenes exitosas, ventas dobles (deben ser cero), p95 y errores. ¿Cuál elegirían para la apertura de una venta y por qué?
  8. Idempotencia: el cliente de code/week-12/ envía la misma compra dos veces porque la primera respuesta “se perdió”. Sin clave de idempotencia, ¿cuántos cobros hay en la pasarela simulada? Agregar la clave (cabecera Idempotency-Key, tabla con la clave y la respuesta, en la misma transacción) y repetir.

Entregas

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

Preguntas de repaso

  1. Dos transacciones en read committed ejecutan SELECT stock y después UPDATE … SET stock = <valor leído> - 1. ¿Qué anomalía ocurre y cómo se evita sin subir el nivel de aislamiento?
  2. Den un ejemplo de write skew en un sistema de reservas. ¿Por qué snapshot isolation no lo impide?
  3. Comparen SELECT … FOR UPDATE con SERIALIZABLE para la apertura de una venta con mucha contención.
  4. ¿Por qué two-phase commit no sirve para coordinar a Tinkuy con una pasarela de pagos externa? Den dos razones.
  5. Ordenen los pasos de una saga de compra (cobrar, reservar asientos, enviar el correo, emitir las entradas) y digan cuál es el punto de no retorno y qué compensación tiene cada paso anterior.
  6. Un servicio guarda la orden y luego publica OrderPaid. Describan la falla que deja a los demás servicios sin enterarse, y cómo la evita una outbox. ¿Qué garantía de entrega da y qué exige de los consumidores?

Código de la semana

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

Ejemplos (36)Errores (3)Pruebas (9)Laboratorio (3)Compilación (3)

Ejemplos

Los programas que usan los apuntes y la clase.

booking/conditional.tsDescargar booking/conditional.ts
import type pg from 'pg';
import { insertBookings, type BookingRequest, type BookingResult, type Charge } from './types.ts';

// Solución 2: sin lock explícito. No hay una lectura previa: el UPDATE lleva
// la condición y dice cuántas filas cambió. Comprobar y actuar son una sola
// sentencia, y la base de datos la ejecuta de forma atómica.
//
// La restricción UNIQUE de db/unique-booking.sql es la segunda línea de
// defensa: si alguna vez otro código inserta en bookings sin pasar por aquí,
// la base de datos rechaza la reserva repetida.

export async function bookConditional(pool: pg.Pool, request: BookingRequest, charge: Charge): Promise<BookingResult> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    // Una noche por sentencia y en orden de id: el UPDATE también toma un
    // lock sobre la fila que cambia, y el orden evita el deadlock.
    for (const nightId of [...request.nightIds].sort((x, y) => x - y)) {
      const marked = await client.query(
        `UPDATE room_nights SET status = 'booked' WHERE id = $1 AND status = 'available'`,
        [nightId],
      );
      if (marked.rowCount !== 1) {
        // 0 filas: la noche no existe o ya no está libre. Se deshace lo marcado.
        await client.query('ROLLBACK');
        return { booked: false, reason: 'not_available' };
      }
    }
    const bookingIds = await insertBookings(client, request);
    await charge(request);
    await client.query('COMMIT');
    return { booked: true, bookingIds };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}
booking/naive.tsDescargar booking/naive.ts
import type pg from 'pg';
import { insertBookings, unavailable, type BookingRequest, type BookingResult, type Charge, type NightRow } from './types.ts';

// La versión con el problema: comprobar y después actuar, en read committed.
// Es la misma forma que tiene la compra del Tinkuy inicial.

export async function bookNaive(pool: pg.Pool, request: BookingRequest, charge: Charge): Promise<BookingResult> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    // 1. Comprobar: ¿están libres?
    const nights = await client.query<NightRow>('SELECT id, status FROM room_nights WHERE id = ANY($1::int[])', [
      request.nightIds,
    ]);
    const problem = unavailable(nights.rows, request);
    if (problem) {
      await client.query('ROLLBACK');
      return problem;
    }
    await charge(request);
    // 2. Actuar: marcarlas. Entre el paso 1 y este, otra transacción pudo
    // haber leído lo mismo.
    await client.query(`UPDATE room_nights SET status = 'booked' WHERE id = ANY($1::int[])`, [request.nightIds]);
    const bookingIds = await insertBookings(client, request);
    await client.query('COMMIT');
    return { booked: true, bookingIds };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}
booking/retry.tsDescargar booking/retry.ts
import { setTimeout as sleep } from 'node:timers/promises';
import { DEADLOCK_DETECTED, SERIALIZATION_FAILURE, sqlState } from '../shared/db.ts';

// Reintentar una transacción completa cuando PostgreSQL la aborta por un
// conflicto con otra: 40001 (serialization_failure) o 40P01 (deadlock_detected).
// Cualquier otro error no se reintenta: repetirlo daría lo mismo.

export type RetryStats = { attempts: number; serializationFailures: number; deadlocks: number };

export function newRetryStats(): RetryStats {
  return { attempts: 0, serializationFailures: 0, deadlocks: 0 };
}

export class TooManyRetries extends Error {
  constructor(attempts: number) {
    super(`La transacción no pudo completarse en ${attempts} intentos`);
    this.name = 'TooManyRetries';
  }
}

export async function withRetry<T>(
  transaction: () => Promise<T>,
  stats: RetryStats = newRetryStats(),
  maxAttempts = 8,
): Promise<T> {
  for (let attempt = 1; ; attempt += 1) {
    stats.attempts += 1;
    try {
      return await transaction();
    } catch (error) {
      const code = sqlState(error);
      if (code === SERIALIZATION_FAILURE) stats.serializationFailures += 1;
      else if (code === DEADLOCK_DETECTED) stats.deadlocks += 1;
      else throw error;
      if (attempt >= maxAttempts) throw new TooManyRetries(attempt);
      // Backoff exponencial con jitter: si todas reintentan a la vez, vuelven a chocar.
      const ceiling = Math.min(200, 5 * 2 ** attempt);
      await sleep(Math.random() * ceiling);
    }
  }
}
booking/serializable.tsDescargar booking/serializable.ts
import type pg from 'pg';
import { withRetry, type RetryStats } from './retry.ts';
import { insertBookings, unavailable, type BookingRequest, type BookingResult, type Charge, type NightRow } from './types.ts';

// Solución 3: el mismo código de comprobar y después actuar, pero en una
// transacción SERIALIZABLE. No se bloquea nada por adelantado: PostgreSQL
// vigila lo que cada transacción leyó y escribió y, si el resultado no
// equivale a haberlas corrido una tras otra, aborta una con el error 40001.
// Esa transacción se repite completa.

async function attempt(pool: pg.Pool, request: BookingRequest, charge: Charge): Promise<BookingResult> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN ISOLATION LEVEL SERIALIZABLE');
    const nights = await client.query<NightRow>('SELECT id, status FROM room_nights WHERE id = ANY($1::int[])', [
      request.nightIds,
    ]);
    const problem = unavailable(nights.rows, request);
    if (problem) {
      await client.query('ROLLBACK');
      return problem;
    }
    await client.query(`UPDATE room_nights SET status = 'booked' WHERE id = ANY($1::int[])`, [request.nightIds]);
    const bookingIds = await insertBookings(client, request);
    // El cobro va después de las escrituras: si esta transacción va a
    // abortar por un conflicto en la fila, que sea antes de cobrar. Aun así,
    // en general el error 40001 puede llegar en el COMMIT: un efecto externo
    // dentro de una transacción que se reintenta tiene que ser idempotente.
    await charge(request);
    await client.query('COMMIT');
    return { booked: true, bookingIds };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}

export function bookSerializable(
  pool: pg.Pool,
  request: BookingRequest,
  charge: Charge,
  stats?: RetryStats,
): Promise<BookingResult> {
  return withRetry(() => attempt(pool, request, charge), stats);
}

/** Un solo intento, sin reintento: para ver el error 40001 tal como llega. */
export const bookSerializableOnce = attempt;
booking/server.tsDescargar booking/server.ts
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
import { setTimeout as sleep } from 'node:timers/promises';
import { addUniqueBooking, newPool, resetData, sqlState, UNIQUE_VIOLATION } from '../shared/db.ts';
import { bookConditional } from './conditional.ts';
import { bookNaive } from './naive.ts';
import { newRetryStats, TooManyRetries } from './retry.ts';
import { bookSerializable } from './serializable.ts';
import type { Book, BookingRequest } from './types.ts';
import { bookWithLock } from './with-lock.ts';

// El servidor de reservas del hospedaje, con la estrategia que diga STRATEGY.
// Sirve para comparar las cuatro versiones bajo la misma carga.
//
//   STRATEGY=lock node booking/server.ts      (o make serve STRATEGY=lock)
//
//   STRATEGY    naive | lock | conditional | serializable   (naive por omisión)
//   PORT        puerto (3000 por omisión)
//   NIGHTS      cuántas noches hay al empezar (300 por omisión)
//   CHARGE_MS   cuánto tarda el cobro simulado (20 por omisión)
//   POOL        conexiones del pool (20 por omisión)
//
//   POST /bookings   { "nightIds": [1, 2], "guest": "Rosa" } → 201, 409 o 500
//   GET  /stats      contadores del servidor y estado de la base de datos
//   POST /reset      vuelve a dejar todas las noches libres y los contadores en cero

const STRATEGIES = { naive: bookNaive, lock: bookWithLock, conditional: bookConditional } as const;
type StrategyName = keyof typeof STRATEGIES | 'serializable';

const strategy = (process.env.STRATEGY ?? 'naive') as StrategyName;
if (strategy !== 'serializable' && !(strategy in STRATEGIES)) {
  throw new Error(`STRATEGY debe ser naive, lock, conditional o serializable; llegó "${strategy}"`);
}
const port = Number(process.env.PORT ?? 3000);
const nights = Number(process.env.NIGHTS ?? 300);
const chargeMs = Number(process.env.CHARGE_MS ?? 20);
const pool = newPool(Number(process.env.POOL ?? 20));

let retries = newRetryStats();
let counters = { requests: 0, booked: 0, notAvailable: 0, errors: 0, charges: 0 };

const charge = async (): Promise<void> => {
  counters.charges += 1;
  await sleep(chargeMs);
};

const book: Book =
  strategy === 'serializable'
    ? (p, request, c) => bookSerializable(p, request, c, retries)
    : STRATEGIES[strategy];

async function reset(): Promise<void> {
  await resetData(nights);
  // La restricción acompaña a la solución 2; las demás corren sin ella.
  if (strategy === 'conditional') await addUniqueBooking();
  retries = newRetryStats();
  counters = { requests: 0, booked: 0, notAvailable: 0, errors: 0, charges: 0 };
}

async function stats(): Promise<unknown> {
  const result = await pool.query<{ booked_nights: number; bookings: number; double_booked: number }>(
    `SELECT (SELECT count(*)::int FROM room_nights WHERE status = 'booked') AS booked_nights,
            (SELECT count(*)::int FROM bookings) AS bookings,
            (SELECT count(*)::int FROM (SELECT 1 FROM bookings GROUP BY room_night_id HAVING count(*) > 1) AS d) AS double_booked`,
  );
  const db = result.rows[0]!;
  return {
    strategy,
    ...counters,
    transactions: strategy === 'serializable' ? retries.attempts : counters.requests,
    serializationFailures: retries.serializationFailures,
    deadlocksRetried: retries.deadlocks,
    bookedNights: db.booked_nights,
    bookings: db.bookings,
    doubleBookedNights: db.double_booked,
  };
}

function send(response: ServerResponse, status: number, body: unknown): void {
  const text = JSON.stringify(body);
  response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(text) });
  response.end(text);
}

async function readRequest(request: IncomingMessage): Promise<BookingRequest | undefined> {
  const chunks: Buffer[] = [];
  for await (const chunk of request) chunks.push(chunk as Buffer);
  try {
    const body = JSON.parse(Buffer.concat(chunks).toString('utf8')) as Partial<BookingRequest>;
    const ids = body.nightIds;
    const valid =
      Array.isArray(ids) && ids.length >= 1 && ids.length <= 6 && ids.every((id) => Number.isInteger(id)) &&
      new Set(ids).size === ids.length && typeof body.guest === 'string' && body.guest !== '';
    return valid ? { nightIds: ids, guest: body.guest! } : undefined;
  } catch {
    return undefined;
  }
}

async function handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
  const route = `${request.method} ${request.url}`;
  if (route === 'GET /stats') return send(response, 200, await stats());
  if (route === 'POST /reset') {
    await reset();
    return send(response, 200, { status: 'ok' });
  }
  if (route !== 'POST /bookings') return send(response, 404, { error: { code: 'NOT_FOUND' } });

  const input = await readRequest(request);
  if (!input) return send(response, 422, { error: { code: 'INVALID_INPUT' } });
  counters.requests += 1;
  try {
    const result = await book(pool, input, charge);
    if (result.booked) {
      counters.booked += 1;
      return send(response, 201, { bookingIds: result.bookingIds });
    }
    counters.notAvailable += 1;
    return send(response, 409, { error: { code: 'NOT_AVAILABLE' } });
  } catch (error) {
    if (sqlState(error) === UNIQUE_VIOLATION) {
      // La restricción rechazó una reserva repetida: para quien llama es lo mismo que "ya no está".
      counters.notAvailable += 1;
      return send(response, 409, { error: { code: 'NOT_AVAILABLE' } });
    }
    counters.errors += 1;
    const code = error instanceof TooManyRetries ? 'TOO_MANY_RETRIES' : (sqlState(error) ?? 'INTERNAL_ERROR');
    return send(response, error instanceof TooManyRetries ? 503 : 500, { error: { code } });
  }
}

await reset();
const server = createServer((request, response) => {
  handle(request, response).catch(() => send(response, 500, { error: { code: 'INTERNAL_ERROR' } }));
});
server.listen(port, '0.0.0.0', () => {
  console.log(`Reservas con la estrategia "${strategy}" en http://localhost:${port} (${nights} noches, cobro de ${chargeMs} ms)`);
});

const shutdown = (): void => {
  server.close(() => void pool.end().then(() => process.exit(0)));
  server.closeAllConnections();
};
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);
booking/types.tsDescargar booking/types.ts
import type pg from 'pg';

// Reservar una o varias noches. El invariante: una noche de una habitación
// tiene a lo más una reserva.

export type BookingRequest = { nightIds: number[]; guest: string };

export type BookingResult =
  | { booked: true; bookingIds: number[] }
  | { booked: false; reason: 'not_available' | 'not_found' };

/**
 * El cobro. Aquí es una función que recibe quien reserva, para que las
 * pruebas decidan cuánto tarda y cuenten cuántas veces se llamó. En las
 * cuatro versiones se llama con la transacción abierta, como en el Tinkuy
 * inicial: lo que cambia es qué tiene tomado la transacción mientras espera.
 */
export type Charge = (request: BookingRequest) => Promise<void>;

export type Book = (pool: pg.Pool, request: BookingRequest, charge: Charge) => Promise<BookingResult>;

export type NightRow = { id: number; status: 'available' | 'booked' };

/** Inserta una reserva por noche y devuelve sus ids. */
export async function insertBookings(client: pg.PoolClient, request: BookingRequest): Promise<number[]> {
  const ids: number[] = [];
  for (const nightId of request.nightIds) {
    const result = await client.query<{ id: number }>(
      'INSERT INTO bookings (room_night_id, guest) VALUES ($1, $2) RETURNING id',
      [nightId, request.guest],
    );
    ids.push(result.rows[0]!.id);
  }
  return ids;
}

/** ¿Están todas las noches pedidas, y están libres? */
export function unavailable(rows: NightRow[], request: BookingRequest): BookingResult | undefined {
  if (rows.length !== request.nightIds.length) return { booked: false, reason: 'not_found' };
  if (rows.some((row) => row.status !== 'available')) return { booked: false, reason: 'not_available' };
  return undefined;
}
booking/with-lock.tsDescargar booking/with-lock.ts
import type pg from 'pg';
import { insertBookings, unavailable, type BookingRequest, type BookingResult, type Charge, type NightRow } from './types.ts';

// Solución 1: lock explícito. La lectura toma un lock sobre cada fila y lo
// conserva hasta el COMMIT o el ROLLBACK. Quien llega después espera en su
// propia lectura y, cuando le toca, ve el estado que dejó el anterior.

export async function bookWithLock(pool: pg.Pool, request: BookingRequest, charge: Charge): Promise<BookingResult> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    // ORDER BY id: todas las transacciones toman los locks en el mismo
    // orden, pidan las noches en el orden que las pidan. Sin eso, dos
    // reservas con noches en común pueden esperarse una a la otra (deadlock).
    const nights = await client.query<NightRow>(
      'SELECT id, status FROM room_nights WHERE id = ANY($1::int[]) ORDER BY id FOR UPDATE',
      [request.nightIds],
    );
    const problem = unavailable(nights.rows, request);
    if (problem) {
      await client.query('ROLLBACK');
      return problem;
    }
    await charge(request); // con los locks tomados: nadie más avanza sobre estas noches
    await client.query(`UPDATE room_nights SET status = 'booked' WHERE id = ANY($1::int[])`, [request.nightIds]);
    const bookingIds = await insertBookings(client, request);
    await client.query('COMMIT');
    return { booked: true, bookingIds };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}
db/reset.sqlDescargar db/reset.sql
-- Deja los datos como al principio. Lo usan make db, los guiones y las pruebas.
-- La variable nights dice cuántas noches hay (300 por omisión: 10 habitaciones
-- por 30 noches, con ids del 1 al 300).
\if :{?nights}
\else
  \set nights 300
\endif

ALTER TABLE bookings DROP CONSTRAINT IF EXISTS bookings_one_per_night;
TRUNCATE bookings, room_nights, tour_purchases, tours, doctors, room_reservations, charges,
         idempotency_keys, purchase_keys, inventory_nights, vouchers, sagas, outbox RESTART IDENTITY;

INSERT INTO room_nights (id, room, night)
SELECT n, 101 + (n - 1) / 30, DATE '2027-07-01' + (n - 1) % 30
  FROM generate_series(1, :nights) AS n;

INSERT INTO tours (id, name, places_left) VALUES (1, 'Valle Sagrado', 10);

INSERT INTO doctors (name, on_call) VALUES ('Aurelia', true), ('Braulio', true);

INSERT INTO inventory_nights (id) SELECT n FROM generate_series(1, 10) AS n;
db/schema.sqlDescargar db/schema.sql
-- Esquema de la semana 12: un hospedaje pequeño. No es el de Tinkuy, pero el
-- problema es el mismo: un recurso que solo se puede vender una vez.

-- Una fila por cada noche de cada habitación. Reservar es pasar la fila de
-- 'available' a 'booked' y registrar la reserva en bookings.
CREATE TABLE room_nights (
    id     integer PRIMARY KEY,
    room   integer NOT NULL,
    night  date    NOT NULL,
    status text    NOT NULL DEFAULT 'available' CHECK (status IN ('available', 'booked')),
    UNIQUE (room, night)
);

-- A propósito, nada impide aquí dos reservas de la misma noche: esa
-- restricción es una de las soluciones (db/unique-booking.sql).
CREATE TABLE bookings (
    id            integer     PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    room_night_id integer     NOT NULL REFERENCES room_nights (id),
    guest         text        NOT NULL,
    created_at    timestamptz NOT NULL DEFAULT now()
);

-- Cupos de un tour: un contador que se lee y se vuelve a escribir
-- (la actualización perdida). version sirve para el control optimista:
-- cada escritura la aumenta, y quien escribe dice qué versión leyó.
CREATE TABLE tours (
    id          integer PRIMARY KEY,
    name        text    NOT NULL,
    places_left integer NOT NULL CHECK (places_left >= 0),
    version     integer NOT NULL DEFAULT 0
);

-- Los médicos de guardia: el ejemplo clásico de write skew. El invariante
-- (al menos uno de guardia) no cabe en una restricción de una sola fila.
CREATE TABLE doctors (
    name    text    PRIMARY KEY,
    on_call boolean NOT NULL
);

-- Reservas de la sala de reuniones del hospedaje, sin filas creadas por
-- adelantado: la decisión depende de que una fila NO exista (fantasmas).
CREATE TABLE room_reservations (
    id    integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    room  text    NOT NULL,
    day   date    NOT NULL,
    guest text    NOT NULL
);

-- El servicio de cobros (idempotency/): los cobros y las claves de
-- idempotencia viven en la misma base de datos, para poder escribirlos en
-- la misma transacción.
CREATE TABLE charges (
    id           integer     PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    reference    text        NOT NULL,
    amount_cents integer     NOT NULL CHECK (amount_cents > 0),
    status       text        NOT NULL DEFAULT 'approved' CHECK (status IN ('approved', 'refunded')),
    created_at   timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE idempotency_keys (
    key          text        PRIMARY KEY,
    request_hash text        NOT NULL,
    status_code  integer     NOT NULL,
    -- json y no jsonb: se devuelve el mismo texto que se respondió la primera vez.
    response     json        NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now()
);

-- La saga (saga/). Cada "servicio" tiene sus tablas y nunca toca las de otro.
-- Inventario: la noche pasa por un estado intermedio, 'held'.
CREATE TABLE inventory_nights (
    id      integer PRIMARY KEY,
    status  text    NOT NULL DEFAULT 'available' CHECK (status IN ('available', 'held', 'booked')),
    held_by text
);

-- Comprobantes: la entrada que recibe el huésped. Uno por saga.
CREATE TABLE vouchers (
    id      integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    saga_id text    NOT NULL UNIQUE,
    code    text    NOT NULL
);

-- El orquestador guarda en qué paso va cada saga, para poder retomarla.
CREATE TABLE sagas (
    id           text        PRIMARY KEY,
    night_id     integer     NOT NULL,
    guest        text        NOT NULL,
    amount_cents integer     NOT NULL,
    status       text        NOT NULL CHECK (status IN ('started', 'reserved', 'charged', 'completed', 'compensating', 'cancelled')),
    last_error   text,
    updated_at   timestamptz NOT NULL DEFAULT now()
);

-- Outbox (outbox/): el mensaje se inserta en la misma transacción que el
-- cambio de estado. Quien la lee y publica en el broker llega en la semana 13.
CREATE TABLE outbox (
    id           bigint      PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    topic        text        NOT NULL,
    payload      jsonb       NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now(),
    published_at timestamptz
);

-- El laboratorio (lab/): compras de cupos de un tour, y la tabla donde el
-- servicio de compras guardará sus claves de idempotencia.
CREATE TABLE tour_purchases (
    id        integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    tour_id   integer NOT NULL REFERENCES tours (id),
    guest     text    NOT NULL,
    charge_id integer NOT NULL
);

CREATE TABLE purchase_keys (
    key          text        PRIMARY KEY,
    request_hash text        NOT NULL,
    status_code  integer     NOT NULL,
    response     json        NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now()
);
db/unique-booking.sqlDescargar db/unique-booking.sql
-- La restricción que respalda el invariante en la base de datos: a lo más una
-- reserva por noche de habitación. Con ella, la segunda reserva de la misma
-- noche termina con el error 23505 (unique_violation), la haga quien la haga.
ALTER TABLE bookings ADD CONSTRAINT bookings_one_per_night UNIQUE (room_night_id);
guion/01-double-booking.sqlDescargar guion/01-double-booking.sql
-- Guion 1: la doble reserva, en read committed (el nivel por omisión).
--
-- Dos terminales, cada una con `psql arq_w12`: la sesión A y la sesión B.
-- Ejecuten cada sentencia en la sesión que indica la marca, en este orden.
-- Para verlo de corrido: make guion G=01. Para empezar de nuevo: make db.

-- [A]
BEGIN;
-- [B]
BEGIN;
-- Las dos comprueban que la noche 1 (habitación 101, 1 de julio) está libre.
-- [A]
SELECT id, room, night, status FROM room_nights WHERE id = 1;
-- [B]
SELECT id, room, night, status FROM room_nights WHERE id = 1;
-- A la reserva y confirma.
-- [A]
UPDATE room_nights SET status = 'booked' WHERE id = 1;
INSERT INTO bookings (room_night_id, guest) VALUES (1, 'Rosa');
-- B hace lo mismo, a partir de lo que leyó antes.
-- [B]
UPDATE room_nights SET status = 'booked' WHERE id = 1;
-- [A]
COMMIT;
-- [B]
INSERT INTO bookings (room_night_id, guest) VALUES (1, 'Juan');
COMMIT;
-- El resultado: una noche, dos reservas.
-- [A]
SELECT id, room_night_id, guest FROM bookings WHERE room_night_id = 1;
guion/02-for-update.sqlDescargar guion/02-for-update.sql
-- Guion 2: el mismo orden de pasos que el guion 1, con SELECT … FOR UPDATE.
-- Miren en qué paso se detiene la sesión B y qué ve cuando continúa.

-- [A]
BEGIN;
-- [B]
BEGIN;
-- [A]
SELECT id, status FROM room_nights WHERE id = 1 FOR UPDATE;
-- B se detiene en su lectura: la fila tiene un lock de A.
-- [B]
SELECT id, status FROM room_nights WHERE id = 1 FOR UPDATE;
-- [A]
UPDATE room_nights SET status = 'booked' WHERE id = 1;
INSERT INTO bookings (room_night_id, guest) VALUES (1, 'Rosa');
COMMIT;
-- B ve la noche reservada: la aplicación responde "ya no está disponible".
-- [B]
ROLLBACK;
-- [A]
SELECT id, room_night_id, guest FROM bookings WHERE room_night_id = 1;
guion/03-deadlock.sqlDescargar guion/03-deadlock.sql
-- Guion 3: deadlock. A reserva las noches 1 y 2; B, las noches 2 y 1.
-- Cada una bloquea su primera noche y después pide la que tiene la otra.
--
-- Una sesión que lleva 1 s esperando un lock (deadlock_timeout) revisa si
-- hay un ciclo de esperas. Aquí A revisa mucho más tarde, solo para que el
-- guion termine siempre igual: la que encuentra el ciclo, y aborta, es B.

-- [A]
BEGIN;
SET LOCAL deadlock_timeout = '60s';
-- [B]
BEGIN;
-- [A]
SELECT id, status FROM room_nights WHERE id = 1 FOR UPDATE;
-- [B]
SELECT id, status FROM room_nights WHERE id = 2 FOR UPDATE;
-- [A]
SELECT id, status FROM room_nights WHERE id = 2 FOR UPDATE;
-- Con este paso se cierra el ciclo: A espera a B y B espera a A.
-- [B]
SELECT id, status FROM room_nights WHERE id = 1 FOR UPDATE;
-- \errverbose repite el último error con su código SQLSTATE.
\errverbose
ROLLBACK;
-- Al abortar B, A recibió el lock que esperaba y puede terminar.
-- [A]
UPDATE room_nights SET status = 'booked' WHERE id IN (1, 2);
COMMIT;
guion/04-ordered-locks.sqlDescargar guion/04-ordered-locks.sql
-- Guion 4: las mismas dos reservas del guion 3, pero las dos sesiones
-- bloquean las noches en orden de id, las hayan pedido como las hayan pedido.

-- [A]
BEGIN;
-- [B]
BEGIN;
-- [A]
SELECT id, status FROM room_nights WHERE id IN (1, 2) ORDER BY id FOR UPDATE;
-- B pidió [2, 1], pero también empieza por la noche 1: espera sin tener nada.
-- [B]
SELECT id, status FROM room_nights WHERE id IN (2, 1) ORDER BY id FOR UPDATE;
-- [A]
UPDATE room_nights SET status = 'booked' WHERE id IN (1, 2);
COMMIT;
-- [B]
ROLLBACK;
guion/05-conditional-update.sqlDescargar guion/05-conditional-update.sql
-- Guion 5: sin lock explícito. El UPDATE lleva la condición, y la tabla de
-- reservas lleva una restricción UNIQUE.

-- [A]
ALTER TABLE bookings ADD CONSTRAINT bookings_one_per_night UNIQUE (room_night_id);
BEGIN;
-- [B]
BEGIN;
-- [A]
UPDATE room_nights SET status = 'booked' WHERE id = 1 AND status = 'available';
INSERT INTO bookings (room_night_id, guest) VALUES (1, 'Rosa');
-- El UPDATE de B espera a que A termine, y después vuelve a evaluar su WHERE.
-- [B]
UPDATE room_nights SET status = 'booked' WHERE id = 1 AND status = 'available';
-- [A]
COMMIT;
-- UPDATE 0: la aplicación responde "ya no está disponible".
-- Y si un programa descuidado insertara la reserva de todos modos:
-- [B]
INSERT INTO bookings (room_night_id, guest) VALUES (1, 'Juan');
ROLLBACK;
guion/06-serializable.sqlDescargar guion/06-serializable.sql
-- Guion 6: el guion 1 sin cambiar una sola sentencia, salvo el nivel de
-- aislamiento de las dos transacciones.

-- [A]
BEGIN ISOLATION LEVEL SERIALIZABLE;
-- [B]
BEGIN ISOLATION LEVEL SERIALIZABLE;
-- [A]
SELECT id, status FROM room_nights WHERE id = 1;
-- [B]
SELECT id, status FROM room_nights WHERE id = 1;
-- [A]
UPDATE room_nights SET status = 'booked' WHERE id = 1;
INSERT INTO bookings (room_night_id, guest) VALUES (1, 'Rosa');
-- [B]
UPDATE room_nights SET status = 'booked' WHERE id = 1;
-- [A]
COMMIT;
-- [B]
\errverbose
-- La transacción de B quedó abortada: lo único que acepta es ROLLBACK.
INSERT INTO bookings (room_night_id, guest) VALUES (1, 'Juan');
ROLLBACK;
-- [A]
SELECT id, room_night_id, guest FROM bookings WHERE room_night_id = 1;
guion/07-lost-update.sqlDescargar guion/07-lost-update.sql
-- Guion 7: la actualización perdida. El tour tiene 10 cupos; A y B venden
-- uno cada una, calculando el valor nuevo en la aplicación (10 - 1 = 9).

-- [A]
BEGIN;
-- [B]
BEGIN;
-- [A]
SELECT places_left FROM tours WHERE id = 1;
-- [B]
SELECT places_left FROM tours WHERE id = 1;
-- [A]
UPDATE tours SET places_left = 9 WHERE id = 1;
-- [B]
UPDATE tours SET places_left = 9 WHERE id = 1;
-- [A]
COMMIT;
-- [B]
COMMIT;
-- Se vendieron dos cupos y el contador bajó uno.
-- [A]
SELECT places_left FROM tours WHERE id = 1;
-- La versión que no pierde nada: el cálculo lo hace la base de datos.
UPDATE tours SET places_left = places_left - 1 WHERE id = 1 AND places_left > 0;
guion/08-write-skew.sqlDescargar guion/08-write-skew.sql
-- Guion 8: write skew con los médicos de guardia, en repeatable read (la
-- snapshot isolation de PostgreSQL). La regla: siempre queda al menos uno.

-- [A]
BEGIN ISOLATION LEVEL REPEATABLE READ;
-- [B]
BEGIN ISOLATION LEVEL REPEATABLE READ;
-- Cada médico comprueba que hay otro de guardia.
-- [A]
SELECT count(*) AS de_guardia FROM doctors WHERE on_call;
-- [B]
SELECT count(*) AS de_guardia FROM doctors WHERE on_call;
-- Y cada uno se retira. Escriben filas distintas: nadie espera a nadie.
-- [A]
UPDATE doctors SET on_call = false WHERE name = 'Aurelia';
-- [B]
UPDATE doctors SET on_call = false WHERE name = 'Braulio';
-- [A]
COMMIT;
-- [B]
COMMIT;
-- [A]
SELECT count(*) AS de_guardia FROM doctors WHERE on_call;
guion/09-write-skew-serializable.sqlDescargar guion/09-write-skew-serializable.sql
-- Guion 9: el guion 8 en serializable. Las sentencias son las mismas.

-- [A]
BEGIN ISOLATION LEVEL SERIALIZABLE;
-- [B]
BEGIN ISOLATION LEVEL SERIALIZABLE;
-- [A]
SELECT count(*) AS de_guardia FROM doctors WHERE on_call;
-- [B]
SELECT count(*) AS de_guardia FROM doctors WHERE on_call;
-- [A]
UPDATE doctors SET on_call = false WHERE name = 'Aurelia';
-- [B]
UPDATE doctors SET on_call = false WHERE name = 'Braulio';
-- [A]
COMMIT;
-- [B]
COMMIT;
\errverbose
-- [A]
SELECT count(*) AS de_guardia FROM doctors WHERE on_call;
guion/10-phantom.sqlDescargar guion/10-phantom.sql
-- Guion 10: un fantasma. La sala de reuniones no tiene una fila por día: una
-- reserva es una fila nueva. FOR UPDATE no tiene qué bloquear.

-- [A]
BEGIN;
-- [B]
BEGIN;
-- [A]
SELECT id FROM room_reservations WHERE room = 'sala' AND day = '2027-07-28' FOR UPDATE;
-- [B]
SELECT id FROM room_reservations WHERE room = 'sala' AND day = '2027-07-28' FOR UPDATE;
-- [A]
INSERT INTO room_reservations (room, day, guest) VALUES ('sala', '2027-07-28', 'Rosa');
-- [B]
INSERT INTO room_reservations (room, day, guest) VALUES ('sala', '2027-07-28', 'Juan');
-- [A]
COMMIT;
-- [B]
COMMIT;
-- [A]
SELECT id, room, day, guest FROM room_reservations;
harness/guion.tsDescargar harness/guion.ts
import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { setTimeout as sleep } from 'node:timers/promises';
import pg from 'pg';
import { DATABASE, resetData } from '../shared/db.ts';

// Ejecuta un guion de guion/*.sql con dos sesiones de psql de verdad, en el
// orden exacto del archivo, y muestra lo que respondería cada terminal.
//
//   node harness/guion.ts guion/01-double-booking.sql     (o make guion G=01)
//
// Formato del guion: una línea "-- [A]" o "-- [B]" dice a qué sesión
// pertenecen las sentencias que siguen. Los demás comentarios se muestran
// tal cual. Cada sentencia termina en ";"; un comando de psql (\errverbose)
// ocupa una línea.
//
// Cuando una sentencia queda detenida por un lock, el programa no espera un
// tiempo fijo: le pregunta a PostgreSQL (pg_blocking_pids) si esa sesión
// está bloqueada, lo anota y sigue con el paso siguiente.

type Step = { session: string; sql: string; notes: string[] };

export function parseGuion(text: string): Step[] {
  const steps: Step[] = [];
  let session: string | undefined;
  let notes: string[] = [];
  let statement: string[] = [];
  for (const line of text.split('\n')) {
    const marker = /^-- \[(\w+)\]\s*$/.exec(line);
    if (marker) {
      session = marker[1]!;
    } else if (line.startsWith('--')) {
      if (session) notes.push(line);
    } else if (line.trim() !== '') {
      if (!session) throw new Error(`Sentencia antes de la primera marca de sesión: ${line}`);
      statement.push(line);
      if (line.trimEnd().endsWith(';') || line.startsWith('\\')) {
        steps.push({ session, sql: statement.join('\n'), notes });
        statement = [];
        notes = [];
      }
    }
  }
  return steps;
}

type Psql = {
  name: string;
  pid: number;
  process: ChildProcessWithoutNullStreams;
  output: string;
  /** La marca que cierra la sentencia en curso, si hay una. */
  waitingFor: string | undefined;
};

async function openPsql(name: string): Promise<Psql> {
  // 2>&1: los errores salen por el mismo canal que los resultados, en orden.
  const child = spawn('sh', ['-c', `exec psql -X -d "${DATABASE}" 2>&1`], {
    env: { ...process.env, PGAPPNAME: `guion-${name}` },
  });
  const session: Psql = { name, pid: 0, process: child, output: '', waitingFor: undefined };
  child.stdout.on('data', (chunk: Buffer) => {
    session.output += chunk.toString('utf8');
  });
  child.stdin.write('\\t on\nSELECT pg_backend_pid();\n\\t off\n\\echo __LISTO__\n');
  while (!session.output.includes('__LISTO__')) await sleep(5);
  session.pid = Number(session.output.trim().split('\n')[0]);
  session.output = '';
  return session;
}

/** Si la sentencia en curso ya terminó, devuelve lo que imprimió psql. */
function take(session: Psql): string | undefined {
  const marker = session.waitingFor;
  if (!marker) return undefined;
  const end = session.output.indexOf(marker);
  if (end === -1) return undefined;
  const printed = session.output.slice(0, end);
  session.output = session.output.slice(end + marker.length + 1);
  session.waitingFor = undefined;
  return printed;
}

function show(text: string): void {
  const trimmed = text.replace(/\n+$/, '');
  if (trimmed !== '') console.log(trimmed);
}

export async function runGuion(file: string): Promise<void> {
  const steps = parseGuion(readFileSync(file, 'utf8'));
  await resetData();
  const observer = new pg.Client({ database: DATABASE });
  await observer.connect();
  const sessions = new Map<string, Psql>();
  for (const name of new Set(steps.map((step) => step.session))) sessions.set(name, await openPsql(name));
  const names = new Map([...sessions.values()].map((s) => [s.pid, s.name]));

  const blockers = async (session: Psql): Promise<string[]> => {
    const result = await observer.query<{ pids: number[] }>('SELECT pg_blocking_pids($1) AS pids', [session.pid]);
    return result.rows[0]!.pids.map((pid) => names.get(pid) ?? String(pid));
  };

  /** Espera a que la sentencia en curso termine o quede bloqueada. */
  const settle = async (session: Psql, announce: boolean): Promise<void> => {
    for (;;) {
      const printed = take(session);
      if (printed !== undefined) {
        if (!announce) console.log(`    (la sesión ${session.name} deja de esperar; su terminal muestra:)`);
        show(printed);
        return;
      }
      const blockedBy = await blockers(session);
      if (blockedBy.length > 0) {
        if (announce) console.log(`    (la sesión ${session.name} queda esperando: el lock lo tiene la sesión ${blockedBy.join(', ')})`);
        return;
      }
      await sleep(5);
    }
  };

  try {
    let n = 0;
    for (const step of steps) {
      const session = sessions.get(step.session)!;
      // Una sesión detenida no puede recibir otro paso: se espera a que termine.
      while (session.waitingFor) {
        await sleep(5);
        const printed = take(session);
        if (printed !== undefined) {
          console.log(`    (la sesión ${session.name} deja de esperar; su terminal muestra:)`);
          show(printed);
        }
      }
      for (const note of step.notes) console.log(note);
      console.log(`${session.name}=# ${step.sql.replaceAll('\n', `\n${session.name}-# `)}`);
      n += 1;
      session.waitingFor = `__FIN_${n}__`;
      session.process.stdin.write(`${step.sql}\n\\echo ${session.waitingFor}\n`);
      await settle(session, true);
      // ¿Este paso soltó a alguna otra sesión?
      for (const other of sessions.values()) {
        if (other !== session && other.waitingFor) await settle(other, false);
      }
    }
  } finally {
    for (const session of sessions.values()) {
      session.process.stdin.end('\\q\n');
      await new Promise((resolve) => session.process.once('close', resolve));
    }
    await observer.end();
  }
}

if (import.meta.main) {
  const file = process.argv[2];
  if (!file) {
    console.error('Uso: node harness/guion.ts guion/<archivo>.sql');
    process.exit(2);
  }
  await runGuion(file);
}
harness/sessions.tsDescargar harness/sessions.ts
import { setTimeout as sleep } from 'node:timers/promises';
import pg from 'pg';
import { DATABASE } from '../shared/db.ts';

// Dos (o más) sesiones manejadas paso a paso desde un solo programa. Sirve
// para escribir como prueba lo que en clase se hace con dos terminales de
// psql: "A lee, B lee, A escribe, B escribe". El orden lo fija la prueba, no
// el azar: no hay esperas con sleep para "darle tiempo" a la otra sesión.
//
// Una consulta puede quedar bloqueada por un lock de otra sesión. Por eso hay
// dos formas de ejecutar:
//
//   await a.run(sql)        espera el resultado; si falla, lanza el error
//   const p = b.start(sql)  envía la consulta y no espera
//   await b.waitsFor(a)     comprueba, preguntándole a PostgreSQL, que B
//                           quedó bloqueada por un lock que tiene A
//   await p.result          el resultado, cuando A la suelte

export type Outcome =
  | { ok: true; rows: Record<string, unknown>[]; rowCount: number }
  | { ok: false; code: string; message: string };

export type Pending = {
  /** Nunca se rechaza: un error de PostgreSQL llega como { ok: false, code }. */
  result: Promise<Outcome>;
  /** ¿Ya terminó? */
  settled(): boolean;
};

export class Session {
  readonly name: string;
  readonly pid: number;
  readonly #client: pg.Client;
  readonly #observer: pg.Client;

  private constructor(name: string, client: pg.Client, observer: pg.Client, pid: number) {
    this.name = name;
    this.#client = client;
    this.#observer = observer;
    this.pid = pid;
  }

  static async open(name: string): Promise<Session> {
    const client = new pg.Client({ database: DATABASE, application_name: `sesion-${name}` });
    // El observador es otra conexión: la sesión puede estar bloqueada.
    const observer = new pg.Client({ database: DATABASE, application_name: `observador-${name}` });
    await client.connect();
    await observer.connect();
    const result = await client.query<{ pid: number }>('SELECT pg_backend_pid() AS pid');
    return new Session(name, client, observer, result.rows[0]!.pid);
  }

  /** Envía la consulta y devuelve enseguida. */
  start(sql: string, params: unknown[] = []): Pending {
    let done = false;
    const result = this.#client.query(sql, params).then(
      (r): Outcome => ({ ok: true, rows: r.rows as Record<string, unknown>[], rowCount: r.rowCount ?? 0 }),
      (error: unknown): Outcome => ({
        ok: false,
        code: (error as { code?: string }).code ?? '?',
        message: (error as Error).message,
      }),
    );
    void result.then(() => {
      done = true;
    });
    return { result, settled: () => done };
  }

  /** Ejecuta y espera. Lanza el error de PostgreSQL si la consulta falla. */
  async run(sql: string, params: unknown[] = []): Promise<Record<string, unknown>[]> {
    const result = await this.#client.query(sql, params);
    return result.rows as Record<string, unknown>[];
  }

  /** Ejecuta y espera, y devuelve el resultado o el error como dato. */
  async attempt(sql: string, params: unknown[] = []): Promise<Outcome> {
    return this.start(sql, params).result;
  }

  /** Los pids de las sesiones cuyos locks tienen detenida a esta (vacío si no espera). */
  async blockedBy(): Promise<number[]> {
    const result = await this.#observer.query<{ pids: number[] }>('SELECT pg_blocking_pids($1) AS pids', [this.pid]);
    return result.rows[0]!.pids;
  }

  /**
   * Espera hasta que PostgreSQL diga que esta sesión está bloqueada por un
   * lock de `other`. No supone cuánto tarda: pregunta hasta que ocurre, y
   * falla si pasan 10 s o si la consulta termina sin haberse bloqueado.
   */
  async waitsFor(other: Session, pending?: Pending): Promise<void> {
    const deadline = performance.now() + 10_000;
    for (;;) {
      if ((await this.blockedBy()).includes(other.pid)) return;
      if (pending?.settled()) throw new Error(`La sesión ${this.name} terminó sin bloquearse`);
      if (performance.now() > deadline) throw new Error(`La sesión ${this.name} no quedó esperando a ${other.name}`);
      await sleep(5);
    }
  }

  async close(): Promise<void> {
    await this.#client.end();
    await this.#observer.end();
  }
}

/** Abre las sesiones, corre `fn` y las cierra siempre, aunque la prueba falle. */
export async function withSessions<T>(names: string[], fn: (...sessions: Session[]) => Promise<T>): Promise<T> {
  const sessions = await Promise.all(names.map((name) => Session.open(name)));
  try {
    return await fn(...sessions);
  } finally {
    // Una sesión con la transacción abierta o bloqueada se cierra igual.
    await Promise.all(sessions.map((session) => session.close().catch(() => undefined)));
  }
}
idempotency/charge-service.tsDescargar idempotency/charge-service.ts
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
import type { AddressInfo } from 'node:net';
import type pg from 'pg';
import { chargeIdempotent, chargePlain, countCharges, type ChargeInput, type Hooks, type Reply } from './charges.ts';

// El servicio de cobros: la "pasarela simulada" de la semana.
//
//   POST /charges        { "reference": "…", "amountCents": 18000 } → 201 { chargeId, status, amountCents }
//                        Con la cabecera Idempotency-Key, repetir el pedido no repite el cobro.
//   GET  /charges/count  cuántos cobros hay registrados

export type ChargeServiceOptions = {
  /** false: el servicio ignora la cabecera Idempotency-Key (para ver el problema). */
  idempotency: boolean;
  /** Cuántas respuestas se "pierden": el servicio cobra y corta la conexión sin responder. */
  loseResponses: number;
  hooks?: Hooks;
};

export type ChargeService = { url: string; close(): Promise<void> };

async function readInput(request: IncomingMessage): Promise<ChargeInput | undefined> {
  const chunks: Buffer[] = [];
  for await (const chunk of request) chunks.push(chunk as Buffer);
  try {
    const body = JSON.parse(Buffer.concat(chunks).toString('utf8')) as Partial<ChargeInput>;
    const valid = typeof body.reference === 'string' && body.reference !== '' && Number.isInteger(body.amountCents) && body.amountCents! > 0;
    return valid ? { reference: body.reference!, amountCents: body.amountCents! } : undefined;
  } catch {
    return undefined;
  }
}

function send(response: ServerResponse, reply: Reply): void {
  const text = JSON.stringify(reply.body);
  response.writeHead(reply.status, {
    'content-type': 'application/json; charset=utf-8',
    'content-length': Buffer.byteLength(text),
    // Para que quien llama pueda saber que recibió una respuesta guardada.
    ...(reply.replayed ? { 'idempotent-replayed': 'true' } : {}),
  });
  response.end(text);
}

export async function startChargeService(pool: pg.Pool, options: ChargeServiceOptions, port = 0): Promise<ChargeService> {
  let toLose = options.loseResponses;

  const handle = async (request: IncomingMessage, response: ServerResponse): Promise<void> => {
    if (request.method === 'GET' && request.url === '/charges/count') {
      return send(response, { status: 200, body: { charges: await countCharges(pool) } });
    }
    if (request.method !== 'POST' || request.url !== '/charges') {
      return send(response, { status: 404, body: { error: { code: 'NOT_FOUND' } } });
    }
    const input = await readInput(request);
    if (!input) return send(response, { status: 422, body: { error: { code: 'INVALID_INPUT' } } });

    const key = request.headers['idempotency-key'];
    const reply =
      options.idempotency && typeof key === 'string' && key !== ''
        ? await chargeIdempotent(pool, key, input, options.hooks)
        : await chargePlain(pool, input);

    if (toLose > 0) {
      // El cobro ya está confirmado en la base de datos; la respuesta no llega.
      toLose -= 1;
      request.socket.destroy();
      return;
    }
    send(response, reply);
  };

  const server = createServer((request, response) => {
    handle(request, response).catch(() => send(response, { status: 500, body: { error: { code: 'INTERNAL_ERROR' } } }));
  });
  await new Promise<void>((resolve) => server.listen(port, resolve));
  const address = server.address() as AddressInfo;
  return {
    url: `http://localhost:${address.port}`,
    close: () =>
      new Promise<void>((resolve) => {
        server.close(() => resolve());
        server.closeAllConnections();
      }),
  };
}
idempotency/charges.tsDescargar idempotency/charges.ts
import { createHash } from 'node:crypto';
import type pg from 'pg';

// El cobro, con y sin clave de idempotencia. Es la lógica del servicio de
// cobros (charge-service.ts la expone por HTTP).

export type ChargeInput = { reference: string; amountCents: number };
export type Reply = { status: number; body: Record<string, unknown>; replayed?: boolean };

/** Solo para las pruebas: se llama con la transacción abierta, justo antes del COMMIT. */
export type Hooks = { beforeCommit?: () => Promise<void> };

async function insertCharge(client: pg.PoolClient, input: ChargeInput): Promise<Reply> {
  const result = await client.query<{ id: number }>(
    'INSERT INTO charges (reference, amount_cents) VALUES ($1, $2) RETURNING id',
    [input.reference, input.amountCents],
  );
  return { status: 201, body: { chargeId: result.rows[0]!.id, status: 'approved', amountCents: input.amountCents } };
}

/** Sin clave: cada llamada es un cobro nuevo. Repetir el pedido es cobrar dos veces. */
export async function chargePlain(pool: pg.Pool, input: ChargeInput): Promise<Reply> {
  const client = await pool.connect();
  try {
    return await insertCharge(client, input);
  } finally {
    client.release();
  }
}

/** Para detectar que la misma clave llega con un pedido distinto. */
export function requestHash(input: unknown): string {
  return createHash('sha256').update(JSON.stringify(input)).digest('hex');
}

/**
 * Con clave: la primera vez cobra y guarda la respuesta; las siguientes
 * devuelven la respuesta guardada. La clave, el cobro y la respuesta se
 * escriben en UNA transacción: o quedan las tres cosas o ninguna.
 */
export async function chargeIdempotent(
  pool: pg.Pool,
  key: string,
  input: ChargeInput,
  hooks: Hooks = {},
): Promise<Reply> {
  const hash = requestHash(input);
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    // 1. Reclamar la clave. La clave primaria hace el trabajo: si otra
    //    transacción está insertando la misma clave y todavía no confirma,
    //    este INSERT espera a ver cómo termina.
    const claimed = await client.query(
      `INSERT INTO idempotency_keys (key, request_hash, status_code, response)
       VALUES ($1, $2, 0, '{}') ON CONFLICT (key) DO NOTHING`,
      [key, hash],
    );
    if (claimed.rowCount === 0) {
      // 2a. La clave ya existía: no se cobra. Se devuelve lo que se respondió la primera vez.
      const saved = await client.query<{ request_hash: string; status_code: number; response: Record<string, unknown> }>(
        'SELECT request_hash, status_code, response FROM idempotency_keys WHERE key = $1',
        [key],
      );
      await client.query('ROLLBACK');
      const first = saved.rows[0]!;
      if (first.request_hash !== hash) {
        return { status: 422, body: { error: { code: 'IDEMPOTENCY_KEY_REUSED', message: 'La clave ya se usó con otro pedido' } } };
      }
      return { status: first.status_code, body: first.response, replayed: true };
    }
    // 2b. La clave es nueva: el efecto, y su respuesta junto a la clave.
    const reply = await insertCharge(client, input);
    await client.query('UPDATE idempotency_keys SET status_code = $2, response = $3 WHERE key = $1', [
      key,
      reply.status,
      JSON.stringify(reply.body),
    ]);
    await hooks.beforeCommit?.();
    await client.query('COMMIT');
    return reply;
  } catch (error) {
    // Si algo falla, tampoco queda la clave: el reintento empieza de cero.
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}

export async function countCharges(pool: pg.Pool): Promise<number> {
  const result = await pool.query<{ n: number }>('SELECT count(*)::int AS n FROM charges');
  return result.rows[0]!.n;
}
idempotency/demo.tsDescargar idempotency/demo.ts
import { newPool, resetData } from '../shared/db.ts';
import { countCharges } from './charges.ts';
import { startChargeService } from './charge-service.ts';
import { newIdempotencyKey, postWithRetry } from './retry-client.ts';

// La respuesta perdida, tres veces: el servicio cobra, corta la conexión sin
// responder y el cliente reintenta.
//
//   node idempotency/demo.ts     (o make lost-response)

const pool = newPool();
const charge = { reference: 'reserva-1', amountCents: 18000 };

async function scenario(title: string, idempotency: boolean, key: string | undefined): Promise<void> {
  await resetData();
  const service = await startChargeService(pool, { idempotency, loseResponses: 1 });
  try {
    const result = await postWithRetry(`${service.url}/charges`, charge, { key });
    console.log(title);
    for (const a of result.attempts) console.log(`  intento ${a.attempt}: ${a.outcome}`);
    console.log(`  el cliente recibe: ${JSON.stringify(result.body)}`);
    console.log(`  cobros registrados en el servicio: ${await countCharges(pool)}`);
  } finally {
    await service.close();
  }
}

await scenario('Sin clave de idempotencia:', true, undefined);
await scenario('Con clave, pero el servicio la ignora:', false, newIdempotencyKey());
await scenario('Con clave de idempotencia:', true, newIdempotencyKey());
await pool.end();
idempotency/retry-client.tsDescargar idempotency/retry-client.ts
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';

// Un cliente que reintenta. Cuando no recibe respuesta no sabe si el pedido
// se procesó: lo único que puede hacer es repetirlo. Que repetirlo sea seguro
// depende de que envíe la MISMA clave de idempotencia en cada intento.

export type Attempt = { attempt: number; outcome: string };
export type RetryResult = { status: number; body: unknown; replayed: boolean; attempts: Attempt[] };

export type RetryOptions = {
  /** La clave de idempotencia. Se genera una vez por operación, no una por intento. */
  key?: string;
  maxAttempts?: number;
  timeoutMs?: number;
  baseDelayMs?: number;
};

export function newIdempotencyKey(): string {
  return randomUUID();
}

export async function postWithRetry(url: string, body: unknown, options: RetryOptions = {}): Promise<RetryResult> {
  const { key, maxAttempts = 4, timeoutMs = 1000, baseDelayMs = 20 } = options;
  const attempts: Attempt[] = [];
  for (let attempt = 1; ; attempt += 1) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: { 'content-type': 'application/json', ...(key ? { 'idempotency-key': key } : {}) },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(timeoutMs),
      });
      const replayed = response.headers.get('idempotent-replayed') === 'true';
      attempts.push({ attempt, outcome: `respuesta ${response.status}${replayed ? ' (guardada)' : ''}` });
      // Un 4xx es definitivo: repetir el mismo pedido daría lo mismo. Un 5xx se reintenta.
      if (response.status < 500 || attempt >= maxAttempts) {
        return { status: response.status, body: await response.json(), replayed, attempts };
      }
      await response.arrayBuffer();
    } catch (error) {
      const cause = (error as { cause?: { code?: string } }).cause?.code;
      attempts.push({ attempt, outcome: `sin respuesta (${(error as Error).name}${cause ? `, ${cause}` : ''})` });
      if (attempt >= maxAttempts) throw new Error(`Sin respuesta después de ${attempt} intentos`);
    }
    // Retry con backoff exponencial y jitter.
    await sleep(Math.random() * baseDelayMs * 2 ** attempt);
  }
}
load/opening.jsDescargar load/opening.js
// La apertura de reservas del hospedaje: 200 huéspedes durante 15 segundos
// sobre las noches que tenga el servidor (NIGHTS, 3000 por omisión). Cada uno pide una noche al azar o, tres de cada diez
// veces, dos noches seguidas en cualquier orden.
//
//   k6 run load/opening.js     (o make load, con make serve NIGHTS=3000 en otra terminal)
//   BASE_URL=http://localhost:3000
//
// El script solo mide: no define umbrales. Lo que interesa es comparar las
// estrategias entre sí, en la misma máquina.

import http from 'k6/http';
import { sleep } from 'k6';
import { Counter } from 'k6/metrics';

const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000';
const NIGHTS = Number(__ENV.NIGHTS || 3000);

export const options = {
  vus: 200,
  duration: '15s',
  summaryTrendStats: ['med', 'p(95)', 'p(99)', 'max'],
};

const booked = new Counter('bookings_ok'); // 201
const taken = new Counter('bookings_not_available'); // 409
const failed = new Counter('bookings_error'); // 5xx o sin respuesta

// Un 409 es una respuesta esperada (la noche ya no está), no un pedido fallido.
http.setResponseCallback(http.expectedStatuses(200, 201, 409));

// Antes de la carga: todas las noches libres y los contadores en cero.
export function setup() {
  const response = http.post(`${BASE_URL}/reset`);
  if (response.status !== 200) throw new Error(`POST /reset respondió ${response.status}`);
}

function pickNights() {
  const first = 1 + Math.floor(Math.random() * NIGHTS);
  if (Math.random() >= 0.3 || first === NIGHTS) return [first];
  return Math.random() < 0.5 ? [first, first + 1] : [first + 1, first];
}

export default function () {
  const body = JSON.stringify({ nightIds: pickNights(), guest: `Huésped ${__VU}` });
  const response = http.post(`${BASE_URL}/bookings`, body, {
    headers: { 'Content-Type': 'application/json' },
    tags: { name: 'POST /bookings' },
  });
  if (response.status === 201) booked.add(1);
  else if (response.status === 409) taken.add(1);
  else failed.add(1);
  sleep(0.1 + Math.random() * 0.2); // la persona mira el resultado y vuelve a intentar
}

// Después de la carga: lo que quedó en el servidor y en la base de datos.
export function teardown() {
  const s = http.get(`${BASE_URL}/stats`).json();
  console.log(
    `${s.strategy}: reservas=${s.bookings} noches_reservadas=${s.bookedNights} noches_con_reserva_doble=${s.doubleBookedNights} ` +
      `cobros=${s.charges} transacciones=${s.transactions} errores_40001=${s.serializationFailures} errores_5xx=${s.errors}`,
  );
}
outbox/book-with-outbox.tsDescargar outbox/book-with-outbox.ts
import type pg from 'pg';
import type { BookingRequest, BookingResult } from '../booking/types.ts';

// Outbox: el mensaje "se confirmó una reserva" se inserta en la tabla outbox
// en la MISMA transacción que la reserva. O quedan las dos cosas o ninguna.
// Publicarlo en el broker es trabajo de otro proceso, que lee esta tabla
// (semana 13); aquí llegamos hasta la tabla.

export type BookingConfirmed = { type: 'BookingConfirmed'; bookingId: number; roomNightId: number; guest: string };

/** Solo para las pruebas: se llama con la transacción abierta, justo antes del COMMIT. */
export type Hooks = { beforeCommit?: () => Promise<void> };

export async function bookWithOutbox(pool: pg.Pool, request: BookingRequest, hooks: Hooks = {}): Promise<BookingResult> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    const bookingIds: number[] = [];
    for (const nightId of [...request.nightIds].sort((x, y) => x - y)) {
      const marked = await client.query(
        `UPDATE room_nights SET status = 'booked' WHERE id = $1 AND status = 'available'`,
        [nightId],
      );
      if (marked.rowCount !== 1) {
        await client.query('ROLLBACK'); // también deshace los mensajes ya insertados
        return { booked: false, reason: 'not_available' };
      }
      const booking = await client.query<{ id: number }>(
        'INSERT INTO bookings (room_night_id, guest) VALUES ($1, $2) RETURNING id',
        [nightId, request.guest],
      );
      const bookingId = booking.rows[0]!.id;
      bookingIds.push(bookingId);
      const message: BookingConfirmed = { type: 'BookingConfirmed', bookingId, roomNightId: nightId, guest: request.guest };
      await client.query('INSERT INTO outbox (topic, payload) VALUES ($1, $2)', ['bookings.confirmed', JSON.stringify(message)]);
    }
    await hooks.beforeCommit?.();
    await client.query('COMMIT');
    return { booked: true, bookingIds };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}

/** Los mensajes que todavía nadie publicó, en el orden en que se escribieron. */
export async function pendingMessages(pool: pg.Pool): Promise<{ id: string; topic: string; payload: BookingConfirmed }[]> {
  const result = await pool.query<{ id: string; topic: string; payload: BookingConfirmed }>(
    'SELECT id, topic, payload FROM outbox WHERE published_at IS NULL ORDER BY id',
  );
  return result.rows;
}
saga/check.tsDescargar saga/check.ts
import type pg from 'pg';

// ¿Quedó todo consistente? Lo que la transacción daría sola, aquí hay que
// comprobarlo: para cada saga terminada, lo que dicen los tres participantes
// tiene que coincidir con cómo terminó.

export type SagaView = {
  id: string;
  status: string;
  night: string;
  heldBy: string | null;
  charges: number;
  vouchers: number;
};

export async function sagaViews(pool: pg.Pool): Promise<SagaView[]> {
  const result = await pool.query<{ id: string; status: string; night: string; held_by: string | null; charges: number; vouchers: number }>(
    `SELECT s.id, s.status, n.status AS night, n.held_by,
            (SELECT count(*)::int FROM charges c WHERE c.reference = s.id) AS charges,
            (SELECT count(*)::int FROM vouchers v WHERE v.saga_id = s.id) AS vouchers
       FROM sagas s JOIN inventory_nights n ON n.id = s.night_id
      ORDER BY s.id`,
  );
  return result.rows.map((row) => ({
    id: row.id, status: row.status, night: row.night, heldBy: row.held_by, charges: row.charges, vouchers: row.vouchers,
  }));
}

/** Devuelve las inconsistencias encontradas; vacío si no hay ninguna. */
export async function inconsistencies(pool: pg.Pool): Promise<string[]> {
  const problems: string[] = [];
  for (const saga of await sagaViews(pool)) {
    const mine = saga.heldBy === saga.id;
    if (saga.status === 'completed') {
      if (!(mine && saga.night === 'booked')) problems.push(`${saga.id}: completada, pero la noche no quedó reservada a su nombre`);
      if (saga.charges !== 1) problems.push(`${saga.id}: completada con ${saga.charges} cobros`);
      if (saga.vouchers !== 1) problems.push(`${saga.id}: completada con ${saga.vouchers} comprobantes`);
    } else if (saga.status === 'cancelled') {
      if (mine) problems.push(`${saga.id}: cancelada, pero la noche sigue a su nombre`);
      if (saga.charges !== 0) problems.push(`${saga.id}: cancelada con ${saga.charges} cobros`);
      if (saga.vouchers !== 0) problems.push(`${saga.id}: cancelada con ${saga.vouchers} comprobantes`);
    } else {
      problems.push(`${saga.id}: quedó a medias, en "${saga.status}"`);
    }
  }
  const orphans = await pool.query<{ id: number }>(
    `SELECT n.id FROM inventory_nights n
      WHERE n.status <> 'available'
        AND NOT EXISTS (SELECT 1 FROM sagas s WHERE s.id = n.held_by AND s.status NOT IN ('cancelled'))`,
  );
  for (const row of orphans.rows) problems.push(`la noche ${row.id} quedó apartada sin una saga viva`);
  return problems;
}
saga/demo.tsDescargar saga/demo.ts
import { newPool, resetData } from '../shared/db.ts';
import { sagaViews } from './check.ts';
import { Crash, Orchestrator } from './orchestrator.ts';
import { realParticipants } from './participants.ts';

// Tres sagas, y cómo queda cada participante al final.
//
//   node saga/demo.ts     (o make saga)

const pool = newPool();
await resetData();
const participants = realParticipants(pool);
const orchestrator = new Orchestrator(pool, participants);

const show = async (title: string): Promise<void> => {
  console.log(title);
  console.log('  saga         estado      noche      apartada por  cobros  comprobantes');
  for (const s of await sagaViews(pool)) {
    console.log(`  ${s.id.padEnd(11)}  ${s.status.padEnd(10)}  ${s.night.padEnd(9)}  ${(s.heldBy ?? '-').padEnd(12)}  ${String(s.charges).padStart(6)}  ${String(s.vouchers).padStart(12)}`);
  }
};

// 1. Todo sale bien.
await orchestrator.start({ id: 'saga-rosa', nightId: 1, guest: 'Rosa', amountCents: 18000 });
// 2. El pago se rechaza (la pasarela de juguete rechaza los montos que terminan en 13).
await orchestrator.start({ id: 'saga-juan', nightId: 2, guest: 'Juan', amountCents: 18013 });
// 3. El orquestador muere justo después de cobrar, antes de anotarlo.
let crashed = false;
const dying = new Orchestrator(pool, participants, {
  afterStep: (step) => {
    if (step === 'charge' && !crashed) {
      crashed = true;
      throw new Crash('caída después de cobrar');
    }
  },
});
await dying.start({ id: 'saga-ines', nightId: 3, guest: 'Inés', amountCents: 21000 }).catch((error: unknown) => {
  if (!(error instanceof Crash)) throw error;
});
await show('Después de la caída del orquestador:');

// Otro proceso arranca y retoma lo que quedó a medias.
await orchestrator.recover();
await show('Después de recover():');
await pool.end();
saga/orchestrator.tsDescargar saga/orchestrator.ts
import type pg from 'pg';
import type { Participants } from './participants.ts';

// Una saga orquestada: reservar una noche es apartar (inventario), cobrar
// (pagos) y emitir el comprobante (comprobantes). No hay una transacción que
// cubra los tres pasos: cada uno es una transacción local de su participante,
// y el orquestador anota en su propia tabla en qué paso va.
//
//   started ──hold──▶ reserved ──charge──▶ charged ──issue, confirm──▶ completed
//      │                  │
//      │ no hay noche     │ pago rechazado
//      ▼                  ▼
//   cancelled ◀──release── compensating
//
// - hold es compensable: su compensación es release.
// - charge es el punto de no retorno: una vez aprobado, la saga solo avanza.
// - issue y confirm no pueden fallar por una regla del negocio: se reintentan
//   hasta que salgan.

export type SagaStatus = 'started' | 'reserved' | 'charged' | 'completed' | 'compensating' | 'cancelled';
export type Saga = { id: string; nightId: number; guest: string; amountCents: number; status: SagaStatus; lastError: string | null };

/** Una falla técnica: no se sabe si el paso se hizo. Se reintenta. */
export class TransientError extends Error {}

/** El orquestador "muere" aquí. Solo lo lanzan las pruebas. */
export class Crash extends Error {}

export type OrchestratorOptions = {
  /** Intentos por paso antes de dejar la saga donde está, para retomarla después. */
  attemptsPerStep?: number;
  /** Las pruebas lo usan para matar al orquestador después de un paso y antes de anotarlo. */
  afterStep?: (step: 'hold' | 'charge' | 'issue' | 'confirm' | 'release') => void;
};

export class Orchestrator {
  readonly #pool: pg.Pool;
  readonly #participants: Participants;
  readonly #attempts: number;
  readonly #afterStep: NonNullable<OrchestratorOptions['afterStep']>;

  constructor(pool: pg.Pool, participants: Participants, options: OrchestratorOptions = {}) {
    this.#pool = pool;
    this.#participants = participants;
    this.#attempts = options.attemptsPerStep ?? 5;
    this.#afterStep = options.afterStep ?? (() => {});
  }

  /** Registra la saga y la ejecuta hasta donde pueda. */
  async start(input: { id: string; nightId: number; guest: string; amountCents: number }): Promise<Saga> {
    await this.#pool.query(
      `INSERT INTO sagas (id, night_id, guest, amount_cents, status) VALUES ($1, $2, $3, $4, 'started')`,
      [input.id, input.nightId, input.guest, input.amountCents],
    );
    return this.resume(input.id);
  }

  /**
   * Continúa una saga desde el estado anotado. Sirve igual para la primera
   * ejecución que para retomarla después de una caída: como cada paso es
   * idempotente, repetir el último no hace daño.
   */
  async resume(id: string): Promise<Saga> {
    for (;;) {
      const saga = await this.find(id);
      switch (saga.status) {
        case 'started': {
          const held = await this.#step('hold', () => this.#participants.hold(saga.nightId, saga.id));
          await this.#set(saga.id, held ? 'reserved' : 'cancelled', held ? null : 'la noche no está disponible');
          break;
        }
        case 'reserved': {
          const result = await this.#step('charge', () => this.#participants.charge(saga.id, saga.amountCents));
          // Aprobado: pasó el punto de no retorno. Rechazado: hay que deshacer lo anterior.
          await this.#set(saga.id, result === 'approved' ? 'charged' : 'compensating', result === 'approved' ? null : 'pago rechazado');
          break;
        }
        case 'charged': {
          await this.#step('issue', () => this.#participants.issue(saga.id));
          await this.#step('confirm', () => this.#participants.confirm(saga.nightId, saga.id));
          await this.#set(saga.id, 'completed', null);
          break;
        }
        case 'compensating': {
          await this.#step('release', () => this.#participants.release(saga.nightId, saga.id));
          await this.#set(saga.id, 'cancelled', saga.lastError);
          break;
        }
        case 'completed':
        case 'cancelled':
          return saga;
      }
    }
  }

  /** Retoma todas las sagas que quedaron a medias (después de una caída del orquestador). */
  async recover(): Promise<Saga[]> {
    const pending = await this.#pool.query<{ id: string }>(
      `SELECT id FROM sagas WHERE status NOT IN ('completed', 'cancelled') ORDER BY id`,
    );
    const sagas: Saga[] = [];
    for (const row of pending.rows) sagas.push(await this.resume(row.id));
    return sagas;
  }

  async find(id: string): Promise<Saga> {
    const result = await this.#pool.query<{
      id: string; night_id: number; guest: string; amount_cents: number; status: SagaStatus; last_error: string | null;
    }>('SELECT id, night_id, guest, amount_cents, status, last_error FROM sagas WHERE id = $1', [id]);
    const row = result.rows[0];
    if (!row) throw new Error(`No existe la saga ${id}`);
    return { id: row.id, nightId: row.night_id, guest: row.guest, amountCents: row.amount_cents, status: row.status, lastError: row.last_error };
  }

  /** Ejecuta un paso, repitiéndolo ante fallas técnicas. */
  async #step<T>(name: Parameters<NonNullable<OrchestratorOptions['afterStep']>>[0], action: () => Promise<T>): Promise<T> {
    for (let attempt = 1; ; attempt += 1) {
      try {
        const result = await action();
        this.#afterStep(name);
        return result;
      } catch (error) {
        if (!(error instanceof TransientError) || attempt >= this.#attempts) throw error;
      }
    }
  }

  async #set(id: string, status: SagaStatus, lastError: string | null): Promise<void> {
    await this.#pool.query('UPDATE sagas SET status = $2, last_error = $3, updated_at = now() WHERE id = $1', [id, status, lastError]);
  }
}
saga/participants.tsDescargar saga/participants.ts
import { randomBytes } from 'node:crypto';
import type pg from 'pg';
import { chargeIdempotent } from '../idempotency/charges.ts';

// Los tres participantes de la saga. En un sistema distribuido cada uno sería
// un servicio con su propia base de datos, y estas funciones serían llamadas
// por la red. Aquí son módulos con sus propias tablas y una regla: ninguno
// toca las tablas de otro, y ninguna transacción abarca a dos de ellos.
//
// Todas las operaciones son idempotentes: el orquestador las repite cuando no
// sabe si la vez anterior se hizo.

export type Participants = {
  /** Inventario: aparta la noche para esta saga. false si no está libre. */
  hold(nightId: number, sagaId: string): Promise<boolean>;
  /** Inventario: la compensación de hold. */
  release(nightId: number, sagaId: string): Promise<void>;
  /** Inventario: la noche apartada pasa a reservada. */
  confirm(nightId: number, sagaId: string): Promise<void>;
  /** Pagos: cobra. La clave de idempotencia es el id de la saga. */
  charge(sagaId: string, amountCents: number): Promise<'approved' | 'declined'>;
  /** Comprobantes: emite el comprobante de la reserva. */
  issue(sagaId: string): Promise<string>;
};

export function realParticipants(pool: pg.Pool): Participants {
  return {
    async hold(nightId, sagaId) {
      // "O held_by = esta saga": repetir el paso después de una respuesta perdida da lo mismo.
      const result = await pool.query(
        `UPDATE inventory_nights SET status = 'held', held_by = $2
          WHERE id = $1 AND (status = 'available' OR (status = 'held' AND held_by = $2))`,
        [nightId, sagaId],
      );
      return result.rowCount === 1;
    },
    async release(nightId, sagaId) {
      // Si ya se liberó, o nunca se apartó, cambia 0 filas y no pasa nada.
      await pool.query(
        `UPDATE inventory_nights SET status = 'available', held_by = NULL
          WHERE id = $1 AND status = 'held' AND held_by = $2`,
        [nightId, sagaId],
      );
    },
    async confirm(nightId, sagaId) {
      await pool.query(`UPDATE inventory_nights SET status = 'booked' WHERE id = $1 AND held_by = $2`, [nightId, sagaId]);
    },
    async charge(sagaId, amountCents) {
      // La pasarela de juguete rechaza los montos que terminan en 13 céntimos.
      if (amountCents % 100 === 13) return 'declined';
      await chargeIdempotent(pool, `saga-${sagaId}`, { reference: sagaId, amountCents });
      return 'approved';
    },
    async issue(sagaId) {
      // UNIQUE (saga_id): emitir dos veces deja un solo comprobante.
      await pool.query('INSERT INTO vouchers (saga_id, code) VALUES ($1, $2) ON CONFLICT (saga_id) DO NOTHING', [
        sagaId,
        `HSP-${randomBytes(4).toString('hex').toUpperCase()}`,
      ]);
      const result = await pool.query<{ code: string }>('SELECT code FROM vouchers WHERE saga_id = $1', [sagaId]);
      return result.rows[0]!.code;
    },
  };
}
shared/db.tsDescargar shared/db.ts
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import pg from 'pg';

// El host y el usuario salen de PGHOST y PGUSER, que el contenedor ya define.
// La base de datos sale de W12_DB, porque las pruebas usan otra.

export const DATABASE = process.env.W12_DB ?? 'arq_w12';

/** Un pool nuevo. Quien lo crea lo cierra con pool.end(); si no, el programa no termina. */
export function newPool(max = 10): pg.Pool {
  return new pg.Pool({ database: DATABASE, max });
}

const run = promisify(execFile);

/** Deja los datos como al principio (db/reset.sql), con `nights` noches libres. */
export async function resetData(nights = 300): Promise<void> {
  const file = new URL('../db/reset.sql', import.meta.url).pathname;
  await run('psql', ['-q', '-X', '-d', DATABASE, '-v', 'ON_ERROR_STOP=1', '-v', `nights=${nights}`, '-f', file], {
    env: { ...process.env, PGOPTIONS: '--client-min-messages=warning' },
  });
}

/** Agrega la restricción UNIQUE de db/unique-booking.sql. */
export async function addUniqueBooking(): Promise<void> {
  const file = new URL('../db/unique-booking.sql', import.meta.url).pathname;
  await run('psql', ['-q', '-X', '-d', DATABASE, '-v', 'ON_ERROR_STOP=1', '-f', file]);
}

/** El código SQLSTATE de un error de PostgreSQL ('40001', '40P01', '23505'…), o undefined. */
export function sqlState(error: unknown): string | undefined {
  const code = (error as { code?: unknown } | null)?.code;
  return typeof code === 'string' ? code : undefined;
}

export const SERIALIZATION_FAILURE = '40001';
export const DEADLOCK_DETECTED = '40P01';
export const UNIQUE_VIOLATION = '23505';
tools/burst.tsDescargar tools/burst.ts
// La apertura, en pequeño: BUYERS huéspedes piden al mismo tiempo una de las
// primeras HOT noches. Trabaja contra un servidor que ya está corriendo
// (make serve STRATEGY=…) y lo deja en cero antes de cada ronda.
//
//   node tools/burst.ts          (o make burst)
//
//   BASE_URL   dónde está el servidor (http://localhost:3000 por omisión)
//   BUYERS     pedidos simultáneos (200 por omisión)
//   HOT        noches por las que compiten (10 por omisión)
//   ROUNDS     cuántas veces se repite (5 por omisión)

const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const BUYERS = Number(process.env.BUYERS ?? 200);
const HOT = Number(process.env.HOT ?? 10);
const ROUNDS = Number(process.env.ROUNDS ?? 5);

type Stats = {
  strategy: string;
  charges: number;
  transactions: number;
  serializationFailures: number;
  bookings: number;
  doubleBookedNights: number;
};

/** Percentil por rango más cercano: el menor valor con al menos p % de las muestras por debajo o iguales. */
function percentile(sorted: number[], p: number): number {
  const rank = Math.max(1, Math.ceil((p / 100) * sorted.length));
  return sorted[rank - 1]!;
}

async function buy(buyer: number): Promise<{ status: number; ms: number }> {
  const start = performance.now();
  const response = await fetch(`${BASE_URL}/bookings`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ nightIds: [1 + (buyer % HOT)], guest: `Huésped ${buyer + 1}` }),
  });
  await response.arrayBuffer();
  return { status: response.status, ms: performance.now() - start };
}

console.log(`${BUYERS} pedidos simultáneos por ${HOT} noches, ${ROUNDS} rondas`);
console.log('ronda  estrategia     201  409  5xx  reservas  dobles  cobros  transacciones  40001   p50 ms   p95 ms   max ms');
for (let round = 1; round <= ROUNDS; round += 1) {
  await fetch(`${BASE_URL}/reset`, { method: 'POST' });
  const answers = await Promise.all(Array.from({ length: BUYERS }, (_, i) => buy(i)));
  const stats = (await (await fetch(`${BASE_URL}/stats`)).json()) as Stats;
  const count = (test: (status: number) => boolean): number => answers.filter((a) => test(a.status)).length;
  const times = answers.map((a) => a.ms).sort((x, y) => x - y);
  const cells = [
    String(round).padStart(5),
    `  ${stats.strategy.padEnd(12)}`,
    String(count((s) => s === 201)).padStart(5),
    String(count((s) => s === 409)).padStart(5),
    String(count((s) => s >= 500)).padStart(5),
    String(stats.bookings).padStart(10),
    String(stats.doubleBookedNights).padStart(8),
    String(stats.charges).padStart(8),
    String(stats.transactions).padStart(15),
    String(stats.serializationFailures).padStart(7),
    percentile(times, 50).toFixed(0).padStart(9),
    percentile(times, 95).toFixed(0).padStart(9),
    times.at(-1)!.toFixed(0).padStart(9),
  ];
  console.log(cells.join(''));
}
tools/compare.shDescargar tools/compare.sh
#!/usr/bin/env bash
# Corre la misma carga contra las cuatro estrategias, una después de otra, en
# un servidor propio (puerto 3012) que levanta y detiene aquí mismo.
#
#   bash tools/compare.sh burst     200 pedidos simultáneos por 10 noches, 5 rondas cada una
#   bash tools/compare.sh load      k6 load/opening.js (15 s, 3000 noches) con cada una
set -euo pipefail

mode="${1:-burst}"
export PORT=3012
export BASE_URL="http://localhost:$PORT"
mkdir -p build

if [ "$mode" = load ]; then export NIGHTS=3000; fi

for strategy in naive lock conditional serializable; do
  STRATEGY="$strategy" node booking/server.ts > "build/server-$strategy.log" 2>&1 &
  server=$!
  # Espera a que el servidor responda, sin suponer cuánto tarda.
  until curl -s -o /dev/null "$BASE_URL/stats"; do sleep 0.1; done
  if [ "$mode" = burst ]; then
    node tools/burst.ts | tail -n +2
  else
    k6 run --quiet load/opening.js 2>&1 | grep -E 'msg=|http_req_duration|http_req_failed|bookings_' | sed -E 's/^time=.*msg="(.*)" source=console$/== \1/' || true
  fi
  kill "$server"
  wait "$server" 2>/dev/null || true
done
tools/tinkuy-oversell.shDescargar tools/tinkuy-oversell.sh
#!/usr/bin/env bash
# El problema en el Tinkuy inicial: levanta la copia de build/tinkuy con su
# pasarela (puertos 3100 y 4100), corre make oversell y lo detiene todo.
# No modifica el Tinkuy del curso.
set -euo pipefail

cd build/tinkuy
export PORT=3100 GATEWAY_PORT=4100 GATEWAY_URL=http://localhost:4100 BASE_URL=http://localhost:3100 TINKUY_LOG=off
make --no-print-directory db
node tools/fake-gateway.ts > ../tinkuy-gateway.log 2>&1 &
gateway=$!
node src/main.ts > ../tinkuy-server.log 2>&1 &
server=$!
trap 'kill "$gateway" "$server" 2>/dev/null || true' EXIT
until curl -s -o /dev/null "$BASE_URL/health"; do sleep 0.1; done
make --no-print-directory oversell

Errores

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

errors/dual-write.tsDescargar errors/dual-write.ts
import type pg from 'pg';
import type { BookingRequest } from '../booking/types.ts';
import type { BookingConfirmed } from '../outbox/book-with-outbox.ts';

// ERROR A PROPÓSITO: la escritura doble. Guardar la reserva y publicar el
// mensaje son dos operaciones sobre dos sistemas, y el proceso puede morir
// entre una y otra. Ningún orden lo arregla:
//
//   publicar y después confirmar   si muere en medio, anunció una reserva que no existe
//   confirmar y después publicar   si muere en medio, la reserva existe y nadie se entera
//
// `dieInBetween` simula esa muerte: es lo que hace la prueba.

export type Publish = (message: BookingConfirmed) => Promise<void>;

async function insertBooking(client: pg.PoolClient, request: BookingRequest): Promise<BookingConfirmed> {
  const nightId = request.nightIds[0]!;
  await client.query(`UPDATE room_nights SET status = 'booked' WHERE id = $1 AND status = 'available'`, [nightId]);
  const booking = await client.query<{ id: number }>(
    'INSERT INTO bookings (room_night_id, guest) VALUES ($1, $2) RETURNING id',
    [nightId, request.guest],
  );
  return { type: 'BookingConfirmed', bookingId: booking.rows[0]!.id, roomNightId: nightId, guest: request.guest };
}

export async function publishThenCommit(pool: pg.Pool, request: BookingRequest, publish: Publish, dieInBetween = false): Promise<void> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    const message = await insertBooking(client, request);
    await publish(message);
    if (dieInBetween) throw new Error('el proceso murió antes del COMMIT');
    await client.query('COMMIT');
  } catch (error) {
    await client.query('ROLLBACK'); // lo que haría PostgreSQL al perder la conexión
    throw error;
  } finally {
    client.release();
  }
}

export async function commitThenPublish(pool: pg.Pool, request: BookingRequest, publish: Publish, dieInBetween = false): Promise<void> {
  const client = await pool.connect();
  let message: BookingConfirmed;
  try {
    await client.query('BEGIN');
    message = await insertBooking(client, request);
    await client.query('COMMIT');
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
  if (dieInBetween) throw new Error('el proceso murió después del COMMIT');
  await publish(message);
}
errors/lock-unordered.tsDescargar errors/lock-unordered.ts
import type pg from 'pg';
import { insertBookings, type BookingRequest, type BookingResult, type NightRow } from '../booking/types.ts';

// ERROR A PROPÓSITO: toma los locks en el orden en que llegaron los ids.
// Dos reservas que piden las mismas noches en orden inverso, [1, 2] y [2, 1],
// pueden quedar cada una con una noche y esperando la otra: un deadlock.
// PostgreSQL lo detecta y aborta a una con el error 40P01.
//
// `afterFirstLock` existe solo para que la prueba fije el orden de los pasos.

export async function bookLockUnordered(
  pool: pg.Pool,
  request: BookingRequest,
  afterFirstLock: () => Promise<void> = async () => {},
): Promise<BookingResult> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    let first = true;
    for (const nightId of request.nightIds) {
      const night = await client.query<NightRow>('SELECT id, status FROM room_nights WHERE id = $1 FOR UPDATE', [
        nightId,
      ]);
      if (night.rows[0]?.status !== 'available') {
        await client.query('ROLLBACK');
        return { booked: false, reason: 'not_available' };
      }
      if (first) await afterFirstLock();
      first = false;
    }
    await client.query(`UPDATE room_nights SET status = 'booked' WHERE id = ANY($1::int[])`, [request.nightIds]);
    const bookingIds = await insertBookings(client, request);
    await client.query('COMMIT');
    return { booked: true, bookingIds };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}
errors/serializable-charge-first.tsDescargar errors/serializable-charge-first.ts
import type pg from 'pg';
import { withRetry, type RetryStats } from '../booking/retry.ts';
import { insertBookings, unavailable, type BookingRequest, type BookingResult, type Charge, type NightRow } from '../booking/types.ts';

// ERROR A PROPÓSITO: cobra antes de escribir, dentro de una transacción
// SERIALIZABLE con reintento. Cuando PostgreSQL aborta la transacción, el
// ROLLBACK deshace lo que se escribió en la base de datos, pero el cobro ya
// salió hacia otro sistema y nadie lo deshace. El perdedor queda cobrado y
// sin reserva.

async function attempt(pool: pg.Pool, request: BookingRequest, charge: Charge): Promise<BookingResult> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN ISOLATION LEVEL SERIALIZABLE');
    const nights = await client.query<NightRow>('SELECT id, status FROM room_nights WHERE id = ANY($1::int[])', [
      request.nightIds,
    ]);
    const problem = unavailable(nights.rows, request);
    if (problem) {
      await client.query('ROLLBACK');
      return problem;
    }
    await charge(request); // demasiado pronto: todavía no se sabe si la transacción va a confirmar
    await client.query(`UPDATE room_nights SET status = 'booked' WHERE id = ANY($1::int[])`, [request.nightIds]);
    const bookingIds = await insertBookings(client, request);
    await client.query('COMMIT');
    return { booked: true, bookingIds };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}

export function bookSerializableChargeFirst(
  pool: pg.Pool,
  request: BookingRequest,
  charge: Charge,
  stats?: RetryStats,
): Promise<BookingResult> {
  return withRetry(() => attempt(pool, request, charge), stats);
}

Pruebas

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

test/anomalies.test.tsDescargar test/anomalies.test.ts
import assert from 'node:assert/strict';
import { beforeEach, test } from 'node:test';
import { withSessions, type Session } from '../harness/sessions.ts';
import { addUniqueBooking, resetData } from '../shared/db.ts';

// Las anomalías de la semana, reproducidas paso a paso: la doble reserva, el
// write skew de los médicos de guardia, los fantasmas y el deadlock. Y lo que
// hace con cada una cada nivel de aislamiento de PostgreSQL 18.

beforeEach(() => resetData());

const LEVELS = ['READ COMMITTED', 'REPEATABLE READ', 'SERIALIZABLE'] as const;

async function bookingsOfNight(session: Session, id: number): Promise<number> {
  const rows = await session.run('SELECT count(*)::int AS n FROM bookings WHERE room_night_id = $1', [id]);
  return Number(rows[0]!.n);
}

// ── La doble reserva: comprobar y después actuar ───────────────────────────

const check = 'SELECT status FROM room_nights WHERE id = 1';
const mark = `UPDATE room_nights SET status = 'booked' WHERE id = 1`;
const insert = 'INSERT INTO bookings (room_night_id, guest) VALUES (1, $1)';

test('read committed: las dos sesiones ven la noche libre y las dos la reservan', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await b.run('BEGIN');
    assert.deepEqual(await a.run(check), [{ status: 'available' }]);
    assert.deepEqual(await b.run(check), [{ status: 'available' }]);
    await a.run(mark);
    await a.run(insert, ['Rosa']);
    const pending = b.start(mark);
    await b.waitsFor(a, pending); // B espera el lock de la fila, nada más
    await a.run('COMMIT');
    // El UPDATE de B no tiene condición sobre status: marca de nuevo la fila.
    assert.deepEqual(await pending.result, { ok: true, rows: [], rowCount: 1 });
    await b.run(insert, ['Juan']);
    await b.run('COMMIT');
    assert.equal(await bookingsOfNight(a, 1), 2);
  });
});

test('el orden A completa y después B empieza no produce la doble reserva', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await a.run(check);
    await a.run(mark);
    await a.run(insert, ['Rosa']);
    await a.run('COMMIT');
    await b.run('BEGIN');
    assert.deepEqual(await b.run(check), [{ status: 'booked' }]); // B ve que ya no está y no sigue
    await b.run('ROLLBACK');
    assert.equal(await bookingsOfNight(a, 1), 1);
  });
});

for (const level of ['REPEATABLE READ', 'SERIALIZABLE'] as const) {
  test(`${level.toLowerCase()}: la segunda sesión aborta con 40001 al tocar la fila que la otra cambió`, async () => {
    await withSessions(['A', 'B'], async (a, b) => {
      await a.run(`BEGIN ISOLATION LEVEL ${level}`);
      await b.run(`BEGIN ISOLATION LEVEL ${level}`);
      await a.run(check);
      await b.run(check);
      await a.run(mark);
      await a.run(insert, ['Rosa']);
      const pending = b.start(mark);
      await b.waitsFor(a, pending);
      await a.run('COMMIT');
      const outcome = await pending.result;
      assert.equal(outcome.ok === false && outcome.code, '40001');
      assert.equal(outcome.ok === false && outcome.message, 'could not serialize access due to concurrent update');
      await b.run('ROLLBACK');
      assert.equal(await bookingsOfNight(a, 1), 1);
    });
  });
}

test('read committed + FOR UPDATE: la segunda sesión espera en la lectura y ve la noche ya reservada', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await b.run('BEGIN');
    assert.deepEqual(await a.run(`${check} FOR UPDATE`), [{ status: 'available' }]);
    const pending = b.start(`${check} FOR UPDATE`);
    await b.waitsFor(a, pending);
    await a.run(mark);
    await a.run(insert, ['Rosa']);
    await a.run('COMMIT');
    assert.deepEqual(await pending.result, { ok: true, rows: [{ status: 'booked' }], rowCount: 1 });
    await b.run('ROLLBACK'); // la aplicación responde "ya no está disponible"
    assert.equal(await bookingsOfNight(a, 1), 1);
  });
});

test('read committed + UPDATE con condición: la segunda sesión cambia 0 filas', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    const conditional = `${mark} AND status = 'available'`;
    await a.run('BEGIN');
    await b.run('BEGIN');
    assert.equal((await a.attempt(conditional)).ok, true);
    await a.run(insert, ['Rosa']);
    const pending = b.start(conditional);
    await b.waitsFor(a, pending);
    await a.run('COMMIT');
    assert.deepEqual(await pending.result, { ok: true, rows: [], rowCount: 0 });
    await b.run('ROLLBACK');
    assert.equal(await bookingsOfNight(a, 1), 1);
  });
});

test('la restricción UNIQUE rechaza la segunda reserva (23505) aunque el código no compruebe nada', async () => {
  await addUniqueBooking();
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await b.run('BEGIN');
    await a.run(insert, ['Rosa']);
    const pending = b.start(insert, ['Juan']);
    await b.waitsFor(a, pending); // el índice único hace esperar a B hasta saber si A confirma
    await a.run('COMMIT');
    const outcome = await pending.result;
    assert.equal(outcome.ok === false && outcome.code, '23505');
    await b.run('ROLLBACK');
    assert.equal(await bookingsOfNight(a, 1), 1);
  });
});

// ── Write skew: los médicos de guardia ─────────────────────────────────────

const onCall = 'SELECT count(*)::int AS on_call FROM doctors WHERE on_call';
const leave = 'UPDATE doctors SET on_call = false WHERE name = $1';

for (const level of ['READ COMMITTED', 'REPEATABLE READ'] as const) {
  test(`${level.toLowerCase()}: los dos médicos se retiran y nadie queda de guardia`, async () => {
    await withSessions(['A', 'B'], async (a, b) => {
      await a.run(`BEGIN ISOLATION LEVEL ${level}`);
      await b.run(`BEGIN ISOLATION LEVEL ${level}`);
      // Cada uno comprueba que hay otro médico de guardia…
      assert.deepEqual(await a.run(onCall), [{ on_call: 2 }]);
      assert.deepEqual(await b.run(onCall), [{ on_call: 2 }]);
      // …y se retira. Son filas distintas: ningún lock se cruza, nadie espera.
      await a.run(leave, ['Aurelia']);
      await b.run(leave, ['Braulio']);
      await a.run('COMMIT');
      await b.run('COMMIT');
      assert.deepEqual(await a.run(onCall), [{ on_call: 0 }]);
    });
  });
}

test('serializable: una de las dos transacciones de los médicos aborta con 40001', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL SERIALIZABLE');
    await b.run('BEGIN ISOLATION LEVEL SERIALIZABLE');
    await a.run(onCall);
    await b.run(onCall);
    await a.run(leave, ['Aurelia']);
    await b.run(leave, ['Braulio']); // tampoco aquí espera nadie
    assert.equal((await a.attempt('COMMIT')).ok, true);
    const outcome = await b.attempt('COMMIT');
    assert.deepEqual(outcome, {
      ok: false,
      code: '40001',
      message: 'could not serialize access due to read/write dependencies among transactions',
    });
    assert.deepEqual(await a.run(onCall), [{ on_call: 1 }]);
  });
});

test('read committed + FOR UPDATE sobre las filas leídas también impide el write skew de los médicos', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    const lockOnCall = 'SELECT name FROM doctors WHERE on_call ORDER BY name FOR UPDATE';
    await a.run('BEGIN');
    await b.run('BEGIN');
    assert.equal((await a.run(lockOnCall)).length, 2);
    const pending = b.start(lockOnCall);
    await b.waitsFor(a, pending);
    await a.run(leave, ['Aurelia']);
    await a.run('COMMIT');
    // B vuelve a evaluar on_call sobre las filas confirmadas: solo queda Braulio.
    assert.deepEqual(await pending.result, { ok: true, rows: [{ name: 'Braulio' }], rowCount: 1 });
    await b.run('ROLLBACK'); // con uno solo de guardia, la aplicación no deja retirarse
    assert.deepEqual(await a.run(onCall), [{ on_call: 1 }]);
  });
});

// ── Fantasmas: la decisión dependía de que una fila no existiera ───────────

const free = `SELECT count(*)::int AS taken FROM room_reservations WHERE room = 'sala' AND day = '2027-07-28'`;
const reserve = `INSERT INTO room_reservations (room, day, guest) VALUES ('sala', '2027-07-28', $1)`;

for (const level of ['READ COMMITTED', 'REPEATABLE READ'] as const) {
  test(`${level.toLowerCase()}: las dos sesiones ven la sala libre y las dos insertan su reserva`, async () => {
    await withSessions(['A', 'B'], async (a, b) => {
      await a.run(`BEGIN ISOLATION LEVEL ${level}`);
      await b.run(`BEGIN ISOLATION LEVEL ${level}`);
      assert.deepEqual(await a.run(free), [{ taken: 0 }]);
      assert.deepEqual(await b.run(free), [{ taken: 0 }]);
      await a.run(reserve, ['Rosa']);
      await b.run(reserve, ['Juan']); // dos INSERT de filas distintas no se esperan
      await a.run('COMMIT');
      await b.run('COMMIT');
      assert.deepEqual(await a.run(free), [{ taken: 2 }]);
    });
  });
}

test('FOR UPDATE no protege de un fantasma: no hay ninguna fila que bloquear', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    const lockExisting = `SELECT id FROM room_reservations WHERE room = 'sala' AND day = '2027-07-28' FOR UPDATE`;
    await a.run('BEGIN');
    await b.run('BEGIN');
    assert.deepEqual(await a.run(lockExisting), []);
    assert.deepEqual(await b.run(lockExisting), []); // B no espera: A no bloqueó nada
    await a.run(reserve, ['Rosa']);
    await b.run(reserve, ['Juan']);
    await a.run('COMMIT');
    await b.run('COMMIT');
    assert.deepEqual(await a.run(free), [{ taken: 2 }]);
  });
});

test('serializable: una de las dos reservas de la sala aborta con 40001', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL SERIALIZABLE');
    await b.run('BEGIN ISOLATION LEVEL SERIALIZABLE');
    await a.run(free);
    await b.run(free);
    await a.run(reserve, ['Rosa']);
    await b.run(reserve, ['Juan']);
    const first = await a.attempt('COMMIT');
    const second = await b.attempt('COMMIT');
    assert.equal(first.ok, true);
    assert.equal(second.ok === false && second.code, '40001');
    assert.deepEqual(await a.run(free), [{ taken: 1 }]);
  });
});

test('serializable solo protege si las dos transacciones lo usan', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL SERIALIZABLE');
    await b.run('BEGIN'); // read committed
    await a.run(free);
    await b.run(free);
    await a.run(reserve, ['Rosa']);
    await b.run(reserve, ['Juan']);
    assert.equal((await a.attempt('COMMIT')).ok, true);
    assert.equal((await b.attempt('COMMIT')).ok, true);
    assert.deepEqual(await a.run(free), [{ taken: 2 }]);
  });
});

// ── Deadlock ───────────────────────────────────────────────────────────────

const lockNight = 'SELECT id FROM room_nights WHERE id = $1 FOR UPDATE';

for (const level of LEVELS) {
  test(`${level.toLowerCase()}: dos sesiones que bloquean las noches 1 y 2 en orden inverso caen en un deadlock (40P01)`, async () => {
    await withSessions(['A', 'B'], async (a, b) => {
      for (const s of [a, b]) {
        await s.run(`BEGIN ISOLATION LEVEL ${level}`);
        // Por omisión PostgreSQL busca deadlocks después de 1 s de espera; aquí, antes.
        await s.run(`SET LOCAL deadlock_timeout = '100ms'`);
      }
      await a.run(lockNight, [1]);
      await b.run(lockNight, [2]);
      const waitingA = a.start(lockNight, [2]);
      await a.waitsFor(b, waitingA);
      const waitingB = b.start(lockNight, [1]); // se cierra el ciclo
      const outcomes = [await waitingA.result, await waitingB.result];
      // PostgreSQL aborta a una de las dos; la documentación no promete cuál.
      const victims = outcomes.filter((o) => !o.ok);
      assert.equal(victims.length, 1);
      assert.equal(victims[0]!.ok === false && victims[0]!.code, '40P01');
      assert.equal(victims[0]!.ok === false && victims[0]!.message, 'deadlock detected');
      await a.attempt('ROLLBACK');
      await b.attempt('ROLLBACK');
    });
  });
}

test('con los ids ordenados no hay ciclo: la segunda sesión espera en la primera noche y después sigue', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await b.run('BEGIN');
    await a.run(lockNight, [1]); // A pidió [1, 2]
    const waitingB = b.start(lockNight, [1]); // B pidió [2, 1] y también empieza por la 1
    await b.waitsFor(a, waitingB);
    await a.run(lockNight, [2]); // A nunca espera a B
    await a.run('COMMIT');
    assert.equal((await waitingB.result).ok, true);
    assert.equal((await b.attempt(lockNight, [2])).ok, true);
    await b.run('COMMIT');
  });
});

// ── Serializable aborta de más cuando vigila con poco detalle ──────────────

// A quiere una noche y B otra: no compiten por nada. PostgreSQL anota lo que
// cada transacción leyó con el detalle que le da el plan: la tabla entera si
// la recorrió completa, una página del índice si entró por el índice.
for (const [how, nights, other, setting, aborted] of [
  ['300 noches, recorrido secuencial', 300, 2, 'enable_indexscan = off', 1],
  ['300 noches, por el índice (todo el índice cabe en una página)', 300, 2, 'enable_seqscan = off', 1],
  ['3000 noches, por el índice, noches lejanas', 3000, 3000, 'enable_seqscan = off', 0],
] as const) {
  test(`serializable, dos reservas de noches distintas (${how}): ${aborted === 1 ? 'una aborta igual' : 'ninguna aborta'}`, async () => {
    await resetData(nights);
    await withSessions(['A', 'B'], async (a, b) => {
      for (const s of [a, b]) {
        await s.run('BEGIN ISOLATION LEVEL SERIALIZABLE');
        await s.run(`SET LOCAL ${setting}`);
        await s.run('SET LOCAL enable_bitmapscan = off');
      }
      await a.run('SELECT status FROM room_nights WHERE id = 1');
      await b.run('SELECT status FROM room_nights WHERE id = $1', [other]);
      await a.run(`UPDATE room_nights SET status = 'booked' WHERE id = 1`);
      await b.run(`UPDATE room_nights SET status = 'booked' WHERE id = $1`, [other]);
      const outcomes = [await a.attempt('COMMIT'), await b.attempt('COMMIT')];
      const failed = outcomes.filter((o) => !o.ok);
      assert.equal(failed.length, aborted);
      if (aborted === 1) assert.equal(failed[0]!.ok === false && failed[0]!.code, '40001');
    });
  });
}
test/concurrency.test.tsDescargar test/concurrency.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { bookConditional } from '../booking/conditional.ts';
import { bookNaive } from '../booking/naive.ts';
import { newRetryStats } from '../booking/retry.ts';
import { bookSerializable } from '../booking/serializable.ts';
import type { Book, BookingResult } from '../booking/types.ts';
import { bookWithLock } from '../booking/with-lock.ts';
import { addUniqueBooking, newPool, resetData } from '../shared/db.ts';
import { barrierCharge, bookingsPerNight, doubleBooked, instantCharge } from './helpers.ts';

// La prueba de concurrencia: muchos huéspedes a la vez sobre pocas noches.
// El invariante se revisa al final, en la base de datos.

const pool = newPool(10);
beforeEach(() => resetData());
after(() => pool.end());

const stats = newRetryStats();
const FIXES: [string, Book][] = [
  ['lock explícito', bookWithLock],
  ['UPDATE con condición', bookConditional],
  ['serializable con reintento', (p, request, charge) => bookSerializable(p, request, charge, stats)],
];

test('versión ingenua: 10 huéspedes que comprueban a la vez reservan 10 veces la misma noche', async () => {
  const charge = barrierCharge(10); // el pool tiene 10 conexiones: las 10 comprueban antes de cobrar
  const results = await Promise.all(
    Array.from({ length: 10 }, (_, i) => bookNaive(pool, { nightIds: [1], guest: `Huésped ${i + 1}` }, charge)),
  );
  assert.equal(results.filter((r) => r.booked).length, 10);
  assert.equal((await bookingsPerNight(pool)).get(1), 10);
});

for (const [name, book] of FIXES) {
  test(`${name}: 60 huéspedes, 4 noches: exactamente 4 reservas, una por noche`, async (t) => {
    if (name === 'UPDATE con condición') await addUniqueBooking();
    const charge = instantCharge();
    const results = await Promise.all(
      Array.from({ length: 60 }, (_, i) => book(pool, { nightIds: [1 + (i % 4)], guest: `Huésped ${i + 1}` }, charge)),
    );
    assert.equal(results.filter((r) => r.booked).length, 4);
    assert.equal(results.filter((r) => !r.booked && r.reason === 'not_available').length, 56);
    assert.deepEqual([...(await bookingsPerNight(pool)).entries()].sort(), [[1, 1], [2, 1], [3, 1], [4, 1]]);
    if (name === 'serializable con reintento') {
      // Una transacción serializable puede abortar en el COMMIT, después de
      // cobrar. Al repetirse, cobra otra vez: cuántas veces, depende de la corrida.
      assert.ok(charge.calls() >= 4);
      t.diagnostic(`cobros: ${charge.calls()} para 4 reservas; errores 40001: ${stats.serializationFailures}`);
    } else {
      assert.equal(charge.calls(), 4); // solo cobra quien reserva
    }
  });

  test(`${name}: 40 huéspedes que piden dos noches en órdenes distintas: ni ventas dobles ni errores`, async () => {
    if (name === 'UPDATE con condición') await addUniqueBooking();
    const charge = instantCharge();
    // Seis noches en anillo: cada pedido comparte noches con otros, y la
    // mitad las pide en orden inverso.
    const requests = Array.from({ length: 40 }, (_, i) => {
      const x = 1 + (i % 6);
      const y = 1 + ((i + 1) % 6);
      return { nightIds: i % 2 === 0 ? [x, y] : [y, x], guest: `Huésped ${i + 1}` };
    });
    const results: BookingResult[] = await Promise.all(requests.map((request) => book(pool, request, charge)));
    const booked = results.filter((r) => r.booked).length;
    assert.ok(booked >= 1 && booked <= 3, `reservas: ${booked}`); // seis noches alcanzan para tres pedidos a lo más
    assert.equal(await doubleBooked(pool), 0);
    const nights = await pool.query<{ n: number }>(`SELECT count(*)::int AS n FROM room_nights WHERE status = 'booked'`);
    const bookings = await pool.query<{ n: number }>('SELECT count(*)::int AS n FROM bookings');
    assert.equal(nights.rows[0]!.n, booked * 2);
    assert.equal(bookings.rows[0]!.n, booked * 2);
  });
}
test/fixes.test.tsDescargar test/fixes.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { bookConditional } from '../booking/conditional.ts';
import { bookNaive } from '../booking/naive.ts';
import { newRetryStats } from '../booking/retry.ts';
import { bookSerializable, bookSerializableOnce } from '../booking/serializable.ts';
import type { Book } from '../booking/types.ts';
import { bookWithLock } from '../booking/with-lock.ts';
import { bookLockUnordered } from '../errors/lock-unordered.ts';
import { bookSerializableChargeFirst } from '../errors/serializable-charge-first.ts';
import { addUniqueBooking, newPool, resetData, sqlState } from '../shared/db.ts';
import { barrierCharge, bookingsPerNight, eventually, latchCharge, waitingForLock } from './helpers.ts';

// La versión con el problema y las tres soluciones, como funciones. El cobro
// que reciben es el punto donde la prueba fija el orden de los pasos.

const pool = newPool();
beforeEach(() => resetData());
after(() => pool.end());

const rosa = { nightIds: [1], guest: 'Rosa' };
const juan = { nightIds: [1], guest: 'Juan' };

test('versión ingenua: si las dos comprueban antes de que alguna escriba, las dos reservan la misma noche', async () => {
  const charge = barrierCharge(2); // nadie cobra hasta que las dos hayan comprobado
  const results = await Promise.all([bookNaive(pool, rosa, charge), bookNaive(pool, juan, charge)]);
  assert.deepEqual(results.map((r) => r.booked), [true, true]);
  assert.equal((await bookingsPerNight(pool)).get(1), 2);
  assert.equal(charge.calls(), 2);
});

test('versión ingenua con la restricción UNIQUE: la base de datos rechaza la segunda, que ya había cobrado', async () => {
  await addUniqueBooking();
  const charge = barrierCharge(2);
  const results = await Promise.allSettled([bookNaive(pool, rosa, charge), bookNaive(pool, juan, charge)]);
  const rejected = results.filter((r) => r.status === 'rejected');
  assert.equal(rejected.length, 1);
  assert.equal(sqlState(rejected[0]!.reason), '23505');
  assert.equal((await bookingsPerNight(pool)).get(1), 1);
  assert.equal(charge.calls(), 2); // el invariante se salvó; el cobro de más, no
});

// Con las soluciones 1 y 2, la segunda transacción no llega a cobrar: queda
// detenida por un lock mientras la primera sigue abierta.
for (const [name, book] of [
  ['lock explícito', bookWithLock],
  ['UPDATE con condición', bookConditional],
] as [string, Book][]) {
  test(`${name}: la segunda espera a la primera y después recibe "no disponible"`, async () => {
    const charge = latchCharge();
    const first = book(pool, rosa, charge);
    await eventually('la primera llega al cobro', () => charge.calls() === 1);
    const second = book(pool, juan, charge);
    await eventually('la segunda queda esperando un lock', async () => (await waitingForLock(pool)) === 1);
    assert.equal(charge.calls(), 1);
    charge.release();
    assert.deepEqual((await first).booked, true);
    assert.deepEqual(await second, { booked: false, reason: 'not_available' });
    assert.equal((await bookingsPerNight(pool)).get(1), 1);
    assert.equal(charge.calls(), 1);
  });

  test(`${name}: si la primera falla y hace ROLLBACK, la segunda sí reserva`, async () => {
    let calls = 0;
    let release: () => void = () => {};
    const released = new Promise<void>((resolve) => (release = resolve));
    const charge = async (): Promise<void> => {
      calls += 1;
      if (calls > 1) return;
      await released;
      throw new Error('pago rechazado');
    };
    const first = book(pool, rosa, charge);
    await eventually('la primera llega al cobro', () => calls === 1);
    const second = book(pool, juan, charge);
    await eventually('la segunda queda esperando un lock', async () => (await waitingForLock(pool)) === 1);
    release();
    const [failed, booked] = await Promise.allSettled([first, second]);
    assert.match(String(failed.status === 'rejected' && failed.reason), /pago rechazado/);
    assert.equal(booked.status === 'fulfilled' && booked.value.booked, true);
    const bookings = await pool.query('SELECT guest FROM bookings');
    assert.deepEqual(bookings.rows, [{ guest: 'Juan' }]);
  });
}

test('serializable, un solo intento: la segunda transacción termina con el error 40001', async () => {
  const charge = latchCharge();
  const first = bookSerializableOnce(pool, rosa, charge);
  await eventually('la primera llega al cobro', () => charge.calls() === 1);
  const second = bookSerializableOnce(pool, juan, charge);
  await eventually('la segunda queda esperando en su UPDATE', async () => (await waitingForLock(pool)) === 1);
  charge.release();
  const [winner, loser] = await Promise.allSettled([first, second]);
  assert.equal(winner.status === 'fulfilled' && winner.value.booked, true);
  assert.equal(loser.status === 'rejected' && sqlState(loser.reason), '40001');
  assert.equal((await bookingsPerNight(pool)).get(1), 1);
});

test('serializable con reintento: la segunda se repite, ve la noche reservada y responde "no disponible"', async () => {
  const charge = latchCharge();
  const stats = newRetryStats();
  const first = bookSerializable(pool, rosa, charge, stats);
  await eventually('la primera llega al cobro', () => charge.calls() === 1);
  const second = bookSerializable(pool, juan, charge, stats);
  await eventually('la segunda queda esperando en su UPDATE', async () => (await waitingForLock(pool)) === 1);
  charge.release();
  assert.equal((await first).booked, true);
  assert.deepEqual(await second, { booked: false, reason: 'not_available' });
  assert.deepEqual(stats, { attempts: 3, serializationFailures: 1, deadlocks: 0 });
  assert.equal((await bookingsPerNight(pool)).get(1), 1);
  assert.equal(charge.calls(), 1);
});

test('error: cobrar antes de escribir en una transacción que se reintenta deja un cobro sin reserva', async () => {
  const charge = barrierCharge(2); // las dos comprobaron y las dos cobran
  const stats = newRetryStats();
  const results = await Promise.all([
    bookSerializableChargeFirst(pool, rosa, charge, stats),
    bookSerializableChargeFirst(pool, juan, charge, stats),
  ]);
  assert.equal(results.filter((r) => r.booked).length, 1);
  assert.equal(stats.serializationFailures, 1);
  assert.equal((await bookingsPerNight(pool)).get(1), 1); // el invariante se cumple…
  assert.equal(charge.calls(), 2); // …y hay dos cobros para una sola reserva
});

// ── Deadlock ───────────────────────────────────────────────────────────────

test('error: locks en el orden del pedido; [1, 2] y [2, 1] terminan en un deadlock (40P01)', async () => {
  let arrived = 0;
  let open: () => void = () => {};
  const both = new Promise<void>((resolve) => (open = resolve));
  // Cada reserva bloquea su primera noche y espera a que la otra bloquee la suya.
  const afterFirstLock = async (): Promise<void> => {
    arrived += 1;
    if (arrived === 2) open();
    await both;
  };
  const results = await Promise.allSettled([
    bookLockUnordered(pool, { nightIds: [1, 2], guest: 'Rosa' }, afterFirstLock),
    bookLockUnordered(pool, { nightIds: [2, 1], guest: 'Juan' }, afterFirstLock),
  ]);
  const rejected = results.filter((r) => r.status === 'rejected');
  assert.equal(rejected.length, 1);
  assert.equal(sqlState(rejected[0]!.reason), '40P01');
  // La que sobrevivió reservó las dos noches; la víctima no dejó nada.
  const perNight = await bookingsPerNight(pool);
  assert.deepEqual([perNight.get(1), perNight.get(2)], [1, 1]);
});

test('lock explícito con ids ordenados: [1, 2] y [2, 1] no caen en un deadlock', async () => {
  const charge = latchCharge();
  const first = bookWithLock(pool, { nightIds: [1, 2], guest: 'Rosa' }, charge);
  await eventually('la primera llega al cobro', () => charge.calls() === 1);
  const second = bookWithLock(pool, { nightIds: [2, 1], guest: 'Juan' }, charge);
  await eventually('la segunda queda esperando un lock', async () => (await waitingForLock(pool)) === 1);
  charge.release();
  assert.equal((await first).booked, true);
  assert.deepEqual(await second, { booked: false, reason: 'not_available' });
});
test/guion.test.tsDescargar test/guion.test.ts
import assert from 'node:assert/strict';
import { execFile } from 'node:child_process';
import { test } from 'node:test';
import { promisify } from 'node:util';
import { parseGuion } from '../harness/guion.ts';

// Los guiones de guion/ se ejecutan con dos sesiones de psql y se revisa que
// cada uno termine como dicen los apuntes.

const run = promisify(execFile);

async function guion(name: string): Promise<string> {
  const runner = new URL('../harness/guion.ts', import.meta.url).pathname;
  const file = new URL(`../guion/${name}.sql`, import.meta.url).pathname;
  const { stdout } = await run('node', [runner, file]);
  return stdout;
}

const waits = (session: string, holder: string): string =>
  `(la sesión ${session} queda esperando: el lock lo tiene la sesión ${holder})`;

test('el formato del guion: marcas de sesión, comentarios y sentencias', () => {
  const steps = parseGuion('-- título\n\n-- [A]\nBEGIN;\n-- una nota\n-- [B]\nSELECT 1\n  AS uno;\n\\errverbose\n');
  assert.deepEqual(steps, [
    { session: 'A', sql: 'BEGIN;', notes: [] },
    { session: 'B', sql: 'SELECT 1\n  AS uno;', notes: ['-- una nota'] },
    { session: 'B', sql: '\\errverbose', notes: [] },
  ]);
});

test('guion 1: en read committed, B espera solo el lock de la fila y quedan dos reservas', async () => {
  const out = await guion('01-double-booking');
  assert.ok(out.includes(waits('B', 'A')));
  assert.match(out, /1 \| Rosa\n\s+2 \|\s+1 \| Juan\n\(2 rows\)/);
});

test('guion 2: con FOR UPDATE, B espera en la lectura y ve la noche reservada', async () => {
  const out = await guion('02-for-update');
  const blocked = out.indexOf(waits('B', 'A'));
  assert.ok(blocked > out.indexOf('B=# SELECT id, status FROM room_nights WHERE id = 1 FOR UPDATE;'));
  assert.ok(blocked < out.indexOf('A=# UPDATE'));
  assert.match(out, /1 \| booked\n\(1 row\)/);
  assert.match(out, /1 \| Rosa\n\(1 row\)/);
});

test('guion 3: el deadlock termina con el error 40P01 en B, y A sigue', async () => {
  const out = await guion('03-deadlock');
  assert.ok(out.includes(waits('A', 'B')));
  assert.ok(out.includes(waits('B', 'A')));
  assert.ok(out.includes('ERROR:  40P01: deadlock detected'));
  assert.match(out, /A=# COMMIT;\nCOMMIT/);
});

test('guion 4: con los ids ordenados no hay deadlock', async () => {
  const out = await guion('04-ordered-locks');
  assert.ok(out.includes(waits('B', 'A')));
  assert.ok(!out.includes('ERROR'));
  assert.match(out, /2 \| booked\n\(2 rows\)/);
});

test('guion 5: el UPDATE con condición cambia 0 filas y la restricción UNIQUE rechaza el INSERT', async () => {
  const out = await guion('05-conditional-update');
  assert.ok(out.includes(waits('B', 'A')));
  assert.ok(out.includes('UPDATE 0'));
  assert.ok(out.includes('duplicate key value violates unique constraint "bookings_one_per_night"'));
});

test('guion 6: en serializable, B termina con el error 40001', async () => {
  const out = await guion('06-serializable');
  assert.ok(out.includes('ERROR:  40001: could not serialize access due to concurrent update'));
  assert.ok(out.includes('current transaction is aborted'));
  assert.match(out, /1 \| Rosa\n\(1 row\)/);
});

test('guion 7: se venden dos cupos y el contador baja uno', async () => {
  const out = await guion('07-lost-update');
  assert.match(out, /A=# SELECT places_left FROM tours WHERE id = 1;\n places_left \n-+\n\s+9\n/);
});

test('guion 8: en repeatable read, nadie espera y no queda ningún médico de guardia', async () => {
  const out = await guion('08-write-skew');
  assert.ok(!out.includes('queda esperando'));
  assert.ok(!out.includes('ERROR'));
  assert.match(out, /de_guardia \n-+\n\s+0\n\(1 row\)\n$/);
});

test('guion 9: en serializable, el segundo COMMIT falla con 40001 y queda un médico', async () => {
  const out = await guion('09-write-skew-serializable');
  assert.ok(out.includes('ERROR:  40001: could not serialize access due to read/write dependencies among transactions'));
  assert.match(out, /de_guardia \n-+\n\s+1\n\(1 row\)\n$/);
});

test('guion 10: FOR UPDATE no bloquea nada cuando no hay filas, y la sala queda con dos reservas', async () => {
  const out = await guion('10-phantom');
  assert.ok(!out.includes('queda esperando'));
  assert.match(out, /Juan\n\(2 rows\)\n$/);
});
test/helpers.tsDescargar test/helpers.ts
import { setTimeout as sleep } from 'node:timers/promises';
import type pg from 'pg';
import type { BookingRequest, Charge } from '../booking/types.ts';

// Piezas para fijar el orden de los pasos en las pruebas sin usar esperas a
// ciegas: se espera a que ocurra algo, no un tiempo.

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

export type CountingCharge = Charge & { calls(): number };

/** Un cobro que no espera a nadie y cuenta cuántas veces lo llamaron. */
export function instantCharge(): CountingCharge {
  let calls = 0;
  const charge = async (_request: BookingRequest): Promise<void> => {
    calls += 1;
  };
  return Object.assign(charge, { calls: () => calls });
}

/**
 * Un cobro que no termina hasta que `n` transacciones hayan llegado a él.
 * Así la prueba garantiza que las `n` ya pasaron lo que cada versión hace
 * antes de cobrar. Las llamadas posteriores a la número `n` no esperan.
 */
export function barrierCharge(n: number): CountingCharge {
  let calls = 0;
  let open: () => void = () => {};
  const allArrived = new Promise<void>((resolve) => {
    open = resolve;
  });
  const charge = async (_request: BookingRequest): Promise<void> => {
    calls += 1;
    if (calls >= n) open();
    await allArrived;
  };
  return Object.assign(charge, { calls: () => calls });
}

export type LatchCharge = CountingCharge & { release(): void };

/** Un cobro que se queda esperando hasta que la prueba llame a release(). */
export function latchCharge(): LatchCharge {
  let calls = 0;
  let release: () => void = () => {};
  const released = new Promise<void>((resolve) => {
    release = resolve;
  });
  const charge = async (_request: BookingRequest): Promise<void> => {
    calls += 1;
    await released;
  };
  return Object.assign(charge, { calls: () => calls, release });
}

/** Cuántas sesiones de esta base de datos están detenidas esperando un lock. */
export async function waitingForLock(pool: pg.Pool): Promise<number> {
  const result = await pool.query<{ n: number }>(
    `SELECT count(*)::int AS n FROM pg_stat_activity
      WHERE datname = current_database() AND wait_event_type = 'Lock'`,
  );
  return result.rows[0]!.n;
}

export async function bookingsPerNight(pool: pg.Pool): Promise<Map<number, number>> {
  const result = await pool.query<{ room_night_id: number; n: number }>(
    'SELECT room_night_id, count(*)::int AS n FROM bookings GROUP BY room_night_id',
  );
  return new Map(result.rows.map((row) => [row.room_night_id, row.n]));
}

/** Noches con más de una reserva: el invariante roto. */
export async function doubleBooked(pool: pg.Pool): Promise<number> {
  return [...(await bookingsPerNight(pool)).values()].filter((n) => n > 1).length;
}
test/idempotency.test.tsDescargar test/idempotency.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { chargeIdempotent, countCharges } from '../idempotency/charges.ts';
import { startChargeService } from '../idempotency/charge-service.ts';
import { newIdempotencyKey, postWithRetry } from '../idempotency/retry-client.ts';
import { newPool, resetData } from '../shared/db.ts';
import { eventually, waitingForLock } from './helpers.ts';

const pool = newPool();
beforeEach(() => resetData());
after(() => pool.end());

const input = { reference: 'reserva-1', amountCents: 18000 };

const keys = async (): Promise<number> =>
  (await pool.query<{ n: number }>('SELECT count(*)::int AS n FROM idempotency_keys')).rows[0]!.n;

test('sin clave, la respuesta perdida y el reintento dejan dos cobros', async () => {
  const service = await startChargeService(pool, { idempotency: true, loseResponses: 1 });
  try {
    const result = await postWithRetry(`${service.url}/charges`, input);
    assert.equal(result.status, 201);
    assert.equal(result.attempts.length, 2);
    assert.match(result.attempts[0]!.outcome, /^sin respuesta/);
    assert.equal(await countCharges(pool), 2);
  } finally {
    await service.close();
  }
});

test('con clave, la respuesta perdida y el reintento dejan un cobro, y el cliente recibe la respuesta guardada', async () => {
  const service = await startChargeService(pool, { idempotency: true, loseResponses: 1 });
  try {
    const result = await postWithRetry(`${service.url}/charges`, input, { key: newIdempotencyKey() });
    assert.equal(result.status, 201);
    assert.equal(result.replayed, true);
    assert.deepEqual(result.body, { chargeId: 1, status: 'approved', amountCents: 18000 });
    assert.equal(await countCharges(pool), 1);
  } finally {
    await service.close();
  }
});

test('aunque se pierdan tres respuestas seguidas, sigue habiendo un solo cobro', async () => {
  const service = await startChargeService(pool, { idempotency: true, loseResponses: 3 });
  try {
    const result = await postWithRetry(`${service.url}/charges`, input, { key: newIdempotencyKey(), baseDelayMs: 2 });
    assert.equal(result.attempts.length, 4);
    assert.equal(await countCharges(pool), 1);
  } finally {
    await service.close();
  }
});

test('la clave va en la cabecera: un cliente que genera una clave nueva en cada intento cobra dos veces', async () => {
  const service = await startChargeService(pool, { idempotency: true, loseResponses: 1 });
  try {
    const url = `${service.url}/charges`;
    await assert.rejects(postWithRetry(url, input, { key: newIdempotencyKey(), maxAttempts: 1 }));
    await postWithRetry(url, input, { key: newIdempotencyKey(), maxAttempts: 1 });
    assert.equal(await countCharges(pool), 2);
  } finally {
    await service.close();
  }
});

test('dos operaciones distintas llevan claves distintas y son dos cobros', async () => {
  await chargeIdempotent(pool, 'clave-a', input);
  await chargeIdempotent(pool, 'clave-b', input);
  assert.equal(await countCharges(pool), 2);
});

test('la misma clave con otro pedido se rechaza con 422 y no cobra', async () => {
  await chargeIdempotent(pool, 'clave-a', input);
  const reply = await chargeIdempotent(pool, 'clave-a', { reference: 'reserva-1', amountCents: 99000 });
  assert.equal(reply.status, 422);
  assert.equal(await countCharges(pool), 1);
});

test('duplicados concurrentes: el segundo espera a que el primero confirme y recibe su misma respuesta', async () => {
  let arrived = false;
  let release: () => void = () => {};
  const released = new Promise<void>((resolve) => (release = resolve));
  const first = chargeIdempotent(pool, 'clave-a', input, {
    beforeCommit: async () => {
      arrived = true;
      await released;
    },
  });
  await eventually('el primero llega al final de su transacción', () => arrived);
  const second = chargeIdempotent(pool, 'clave-a', input);
  // El segundo está detenido en su INSERT de la clave: la clave primaria lo hace esperar.
  await eventually('el segundo queda esperando', async () => (await waitingForLock(pool)) === 1);
  release();
  const [a, b] = await Promise.all([first, second]);
  assert.deepEqual(b.body, a.body);
  assert.equal(b.replayed, true);
  assert.equal(await countCharges(pool), 1);
});

test('20 pedidos simultáneos con la misma clave: un cobro y 20 respuestas iguales', async () => {
  const replies = await Promise.all(Array.from({ length: 20 }, () => chargeIdempotent(pool, 'clave-a', input)));
  assert.equal(new Set(replies.map((r) => JSON.stringify(r.body))).size, 1);
  assert.equal(replies.filter((r) => !r.replayed).length, 1);
  assert.equal(await countCharges(pool), 1);
});

test('si la transacción del cobro falla, no queda ni el cobro ni la clave: el reintento cobra', async () => {
  const failing = chargeIdempotent(pool, 'clave-a', input, {
    beforeCommit: async () => {
      throw new Error('el proceso murió antes del COMMIT');
    },
  });
  await assert.rejects(failing, /murió/);
  assert.equal(await countCharges(pool), 0);
  assert.equal(await keys(), 0);
  const retry = await chargeIdempotent(pool, 'clave-a', input);
  assert.equal(retry.status, 201);
  assert.equal(retry.replayed, undefined);
  assert.equal(await countCharges(pool), 1);
});
test/isolation.test.tsDescargar test/isolation.test.ts
import assert from 'node:assert/strict';
import { beforeEach, test } from 'node:test';
import { withSessions } from '../harness/sessions.ts';
import { resetData } from '../shared/db.ts';

// Lo que cada nivel de aislamiento de PostgreSQL 18 deja ver y lo que no.
// Cada prueba es un guion de dos sesiones, A y B, con el orden fijado.

beforeEach(() => resetData());

const placesLeft = 'SELECT places_left FROM tours WHERE id = 1';

test('read committed: nunca se lee un dato sin confirmar (no hay lecturas sucias)', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await a.run('UPDATE tours SET places_left = 3 WHERE id = 1');
    // B lee mientras A todavía no confirma: ve el valor anterior y no espera.
    assert.deepEqual(await b.run(placesLeft), [{ places_left: 10 }]);
    await a.run('ROLLBACK');
    assert.deepEqual(await b.run(placesLeft), [{ places_left: 10 }]);
  });
});

test('read committed: dos lecturas de la misma transacción pueden ver datos distintos', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN'); // read committed es el nivel por omisión
    assert.deepEqual(await a.run('SHOW transaction_isolation'), [{ transaction_isolation: 'read committed' }]);
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 10 }]);
    await b.run('UPDATE tours SET places_left = 9 WHERE id = 1'); // B confirma sola (autocommit)
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 9 }]);
    await a.run('COMMIT');
  });
});

test('repeatable read: la transacción ve siempre la misma foto', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL REPEATABLE READ');
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 10 }]);
    await b.run('UPDATE tours SET places_left = 9 WHERE id = 1');
    await b.run(`INSERT INTO tours (id, name, places_left) VALUES (2, 'Maras y Moray', 8)`);
    // Ni el cambio ni la fila nueva: en PostgreSQL este nivel tampoco muestra fantasmas.
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 10 }]);
    assert.deepEqual(await a.run('SELECT count(*)::int AS tours FROM tours'), [{ tours: 1 }]);
    await a.run('COMMIT');
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 9 }]);
  });
});

test('repeatable read: la foto se toma en la primera consulta, no en el BEGIN', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL REPEATABLE READ');
    await b.run('UPDATE tours SET places_left = 9 WHERE id = 1'); // después del BEGIN de A
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 9 }]);
    await a.run('COMMIT');
  });
});

test('quien lee no bloquea a quien escribe, ni al revés', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL REPEATABLE READ');
    await a.run(placesLeft); // A tiene una foto abierta
    await b.run('UPDATE tours SET places_left = 9 WHERE id = 1'); // B escribe sin esperar
    await b.run('BEGIN');
    await b.run('UPDATE tours SET places_left = 8 WHERE id = 1'); // sin confirmar
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 10 }]); // A lee sin esperar
    await b.run('COMMIT');
    await a.run('COMMIT');
  });
});

// ── Actualización perdida ──────────────────────────────────────────────────

test('read committed: leer, calcular en la aplicación y escribir pierde una actualización', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await b.run('BEGIN');
    const [seenByA] = await a.run(placesLeft);
    const [seenByB] = await b.run(placesLeft);
    await a.run('UPDATE tours SET places_left = $1 WHERE id = 1', [Number(seenByA!.places_left) - 1]);
    const pending = b.start('UPDATE tours SET places_left = $1 WHERE id = 1', [Number(seenByB!.places_left) - 1]);
    await b.waitsFor(a, pending); // no se sobrescribe un dato sin confirmar: B espera
    await a.run('COMMIT');
    assert.equal((await pending.result).ok, true);
    await b.run('COMMIT');
    // Se vendieron dos cupos y el contador bajó uno.
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 9 }]);
  });
});

test('read committed: el UPDATE atómico (places_left = places_left - 1) no pierde nada', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await b.run('BEGIN');
    await a.run('UPDATE tours SET places_left = places_left - 1 WHERE id = 1');
    const pending = b.start('UPDATE tours SET places_left = places_left - 1 WHERE id = 1');
    await b.waitsFor(a, pending);
    await a.run('COMMIT');
    await pending.result; // B recalcula sobre la fila ya confirmada por A
    await b.run('COMMIT');
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 8 }]);
  });
});

test('read committed: con SELECT … FOR UPDATE, la segunda lectura espera y ve el valor nuevo', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await b.run('BEGIN');
    const [seenByA] = await a.run(`${placesLeft} FOR UPDATE`);
    const pending = b.start(`${placesLeft} FOR UPDATE`);
    await b.waitsFor(a, pending);
    await a.run('UPDATE tours SET places_left = $1 WHERE id = 1', [Number(seenByA!.places_left) - 1]);
    await a.run('COMMIT');
    const seenByB = await pending.result;
    assert.deepEqual(seenByB, { ok: true, rows: [{ places_left: 9 }], rowCount: 1 });
    await b.run('UPDATE tours SET places_left = 8 WHERE id = 1');
    await b.run('COMMIT');
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 8 }]);
  });
});

test('repeatable read: la actualización perdida se detecta y la segunda transacción aborta con 40001', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL REPEATABLE READ');
    await b.run('BEGIN ISOLATION LEVEL REPEATABLE READ');
    await a.run(placesLeft);
    await b.run(placesLeft);
    await a.run('UPDATE tours SET places_left = 9 WHERE id = 1');
    const pending = b.start('UPDATE tours SET places_left = 9 WHERE id = 1');
    await b.waitsFor(a, pending);
    await a.run('COMMIT');
    const outcome = await pending.result;
    assert.deepEqual(outcome, {
      ok: false,
      code: '40001',
      message: 'could not serialize access due to concurrent update',
    });
    // La transacción de B quedó abortada: solo acepta ROLLBACK.
    const next = await b.attempt(placesLeft);
    assert.equal(next.ok === false && next.code, '25P02');
    await b.run('ROLLBACK');
    assert.deepEqual(await a.run(placesLeft), [{ places_left: 9 }]);
  });
});

test('repeatable read: si la primera hace ROLLBACK, la segunda sigue sin error', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN ISOLATION LEVEL REPEATABLE READ');
    await b.run('BEGIN ISOLATION LEVEL REPEATABLE READ');
    await b.run(placesLeft);
    await a.run('UPDATE tours SET places_left = 9 WHERE id = 1');
    const pending = b.start('UPDATE tours SET places_left = 9 WHERE id = 1');
    await b.waitsFor(a, pending);
    await a.run('ROLLBACK');
    assert.equal((await pending.result).ok, true);
    await b.run('COMMIT');
  });
});

test('read committed + columna de versión: quien escribe sobre una versión vieja cambia 0 filas y se entera', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    const read = 'SELECT places_left, version FROM tours WHERE id = 1';
    const write = 'UPDATE tours SET places_left = $1, version = version + 1 WHERE id = 1 AND version = $2';
    const [seenByA] = await a.run(read);
    const [seenByB] = await b.run(read);
    // Sin transacción explícita y sin locks: cada sentencia confirma sola.
    const first = await a.attempt(write, [Number(seenByA!.places_left) - 1, seenByA!.version]);
    const second = await b.attempt(write, [Number(seenByB!.places_left) - 1, seenByB!.version]);
    assert.equal(first.ok && first.rowCount, 1);
    assert.equal(second.ok && second.rowCount, 0); // B tiene que leer de nuevo y repetir
    const [again] = await b.run(read);
    assert.deepEqual(again, { places_left: 9, version: 1 });
    const retry = await b.attempt(write, [Number(again!.places_left) - 1, again!.version]);
    assert.equal(retry.ok && retry.rowCount, 1);
    assert.deepEqual(await a.run(read), [{ places_left: 8, version: 2 }]);
  });
});

// ── Lo que bloquea SELECT … FOR UPDATE ─────────────────────────────────────

const night1 = 'SELECT status FROM room_nights WHERE id = 1';

test('FOR UPDATE no detiene a un SELECT normal', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await a.run(`${night1} FOR UPDATE`);
    assert.deepEqual(await b.run(night1), [{ status: 'available' }]);
    assert.deepEqual(await b.blockedBy(), []);
    await a.run('COMMIT');
  });
});

for (const [what, sql] of [
  ['otro SELECT … FOR UPDATE', `${night1} FOR UPDATE`],
  ['un SELECT … FOR SHARE', `${night1} FOR SHARE`],
  ['un UPDATE', `UPDATE room_nights SET status = 'booked' WHERE id = 1`],
  ['un DELETE', 'DELETE FROM room_nights WHERE id = 1'],
] as const) {
  test(`FOR UPDATE detiene a ${what} sobre la misma fila, hasta el final de la transacción`, async () => {
    await withSessions(['A', 'B'], async (a, b) => {
      await a.run('BEGIN');
      await a.run(`${night1} FOR UPDATE`);
      await b.run('BEGIN');
      const pending = b.start(sql);
      await b.waitsFor(a, pending);
      // Otra consulta de A no suelta el lock: solo COMMIT o ROLLBACK.
      await a.run('SELECT 1');
      assert.equal(pending.settled(), false);
      await a.run('COMMIT');
      assert.equal((await pending.result).ok, true);
      await b.run('ROLLBACK');
    });
  });
}

test('FOR UPDATE solo bloquea las filas que devolvió: otra fila sigue libre', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await a.run(`${night1} FOR UPDATE`);
    await b.run('BEGIN');
    assert.deepEqual(await b.run('SELECT status FROM room_nights WHERE id = 2 FOR UPDATE'), [{ status: 'available' }]);
    await b.run('COMMIT');
    await a.run('COMMIT');
  });
});

test('NOWAIT falla en vez de esperar (55P03) y SKIP LOCKED se salta la fila', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    await a.run('BEGIN');
    await a.run(`${night1} FOR UPDATE`);
    const nowait = await b.attempt(`${night1} FOR UPDATE NOWAIT`);
    assert.equal(nowait.ok === false && nowait.code, '55P03');
    const skipped = await b.run('SELECT id FROM room_nights WHERE id IN (1, 2) ORDER BY id FOR UPDATE SKIP LOCKED');
    assert.deepEqual(skipped, [{ id: 2 }]);
    await a.run('COMMIT');
  });
});

// ── Read committed vuelve a evaluar el WHERE después de esperar ────────────

test('read committed: un UPDATE que esperó vuelve a evaluar su WHERE sobre la fila nueva', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    const book = `UPDATE room_nights SET status = 'booked' WHERE id = 1 AND status = 'available'`;
    await a.run('BEGIN');
    await b.run('BEGIN');
    assert.equal((await a.attempt(book)).ok, true);
    const pending = b.start(book);
    await b.waitsFor(a, pending);
    await a.run('COMMIT');
    // La fila ya no cumple status = 'available': B no cambia ninguna.
    assert.deepEqual(await pending.result, { ok: true, rows: [], rowCount: 0 });
    await b.run('COMMIT');
  });
});

test('read committed: si la primera hace ROLLBACK, el UPDATE que esperaba sí cambia la fila', async () => {
  await withSessions(['A', 'B'], async (a, b) => {
    const book = `UPDATE room_nights SET status = 'booked' WHERE id = 1 AND status = 'available'`;
    await a.run('BEGIN');
    await b.run('BEGIN');
    await a.run(book);
    const pending = b.start(book);
    await b.waitsFor(a, pending);
    await a.run('ROLLBACK');
    assert.deepEqual(await pending.result, { ok: true, rows: [], rowCount: 1 });
    await b.run('COMMIT');
  });
});
test/outbox.test.tsDescargar test/outbox.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { commitThenPublish, publishThenCommit } from '../errors/dual-write.ts';
import { bookWithOutbox, pendingMessages, type BookingConfirmed } from '../outbox/book-with-outbox.ts';
import { newPool, resetData } from '../shared/db.ts';

const pool = newPool();
beforeEach(() => resetData());
after(() => pool.end());

const rosa = { nightIds: [1], guest: 'Rosa' };
const bookings = async (): Promise<number> =>
  (await pool.query<{ n: number }>('SELECT count(*)::int AS n FROM bookings')).rows[0]!.n;

/** Un broker de mentira: una lista en memoria. */
function fakeBroker(): { published: BookingConfirmed[]; publish(message: BookingConfirmed): Promise<void> } {
  const published: BookingConfirmed[] = [];
  return { published, publish: async (message) => void published.push(message) };
}

test('escritura doble, publicar y después confirmar: si el proceso muere en medio, se anunció una reserva que no existe', async () => {
  const broker = fakeBroker();
  await assert.rejects(publishThenCommit(pool, rosa, broker.publish, true));
  assert.equal(broker.published.length, 1);
  assert.equal(await bookings(), 0);
});

test('escritura doble, confirmar y después publicar: si el proceso muere en medio, la reserva existe y nadie se entera', async () => {
  const broker = fakeBroker();
  await assert.rejects(commitThenPublish(pool, rosa, broker.publish, true));
  assert.equal(await bookings(), 1);
  assert.equal(broker.published.length, 0);
});

test('outbox: la reserva y su mensaje quedan en la misma transacción', async () => {
  const result = await bookWithOutbox(pool, { nightIds: [2, 1], guest: 'Rosa' });
  assert.equal(result.booked, true);
  assert.equal(await bookings(), 2);
  assert.deepEqual(await pendingMessages(pool), [
    { id: '1', topic: 'bookings.confirmed', payload: { type: 'BookingConfirmed', bookingId: 1, roomNightId: 1, guest: 'Rosa' } },
    { id: '2', topic: 'bookings.confirmed', payload: { type: 'BookingConfirmed', bookingId: 2, roomNightId: 2, guest: 'Rosa' } },
  ]);
});

test('outbox: si el proceso muere antes del COMMIT, no queda ni la reserva ni el mensaje', async () => {
  const dying = bookWithOutbox(pool, rosa, {
    beforeCommit: async () => {
      throw new Error('el proceso murió antes del COMMIT');
    },
  });
  await assert.rejects(dying, /murió/);
  assert.equal(await bookings(), 0);
  assert.deepEqual(await pendingMessages(pool), []);
});

test('outbox: una reserva que no se puede hacer tampoco deja mensajes, ni siquiera de las noches que sí estaban libres', async () => {
  await bookWithOutbox(pool, { nightIds: [2], guest: 'Juan' });
  const result = await bookWithOutbox(pool, { nightIds: [1, 2], guest: 'Rosa' });
  assert.deepEqual(result, { booked: false, reason: 'not_available' });
  assert.equal((await pendingMessages(pool)).length, 1); // solo el de Juan
});

test('outbox: lo que se ve desde otra sesión antes del COMMIT es nada; después, las dos cosas a la vez', async () => {
  let release: () => void = () => {};
  const paused = new Promise<void>((resolve) => (release = resolve));
  let reached: () => void = () => {};
  const atCommit = new Promise<void>((resolve) => (reached = resolve));
  const booking = bookWithOutbox(pool, rosa, {
    beforeCommit: async () => {
      reached();
      await paused;
    },
  });
  await atCommit;
  assert.deepEqual([await bookings(), (await pendingMessages(pool)).length], [0, 0]);
  release();
  await booking;
  assert.deepEqual([await bookings(), (await pendingMessages(pool)).length], [1, 1]);
});
test/saga.test.tsDescargar test/saga.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { inconsistencies, sagaViews } from '../saga/check.ts';
import { Crash, Orchestrator, TransientError } from '../saga/orchestrator.ts';
import { realParticipants, type Participants } from '../saga/participants.ts';
import { newPool, resetData } from '../shared/db.ts';

// La saga con fallas inyectadas en cada paso. En todos los casos se revisa el
// estado final de los tres participantes, no solo el del orquestador.

const pool = newPool();
beforeEach(() => resetData());
after(() => pool.end());

const real = realParticipants(pool);
const rosa = { id: 'saga-rosa', nightId: 1, guest: 'Rosa', amountCents: 18000 };
type StepName = keyof Participants;
const STEPS: StepName[] = ['hold', 'charge', 'issue', 'confirm'];

/**
 * Envuelve un paso para que falle las primeras `times` veces. 'before': el
 * pedido se pierde y el paso no se hace. 'after': el paso se hace y lo que
 * se pierde es la respuesta.
 */
function flaky(step: StepName, when: 'before' | 'after', times: number): Participants {
  let left = times;
  const original = real[step] as (...args: unknown[]) => Promise<unknown>;
  const wrapped = async (...args: unknown[]): Promise<unknown> => {
    if (left > 0 && when === 'before') {
      left -= 1;
      throw new TransientError(`${step}: el pedido se perdió`);
    }
    const result = await original(...args);
    if (left > 0) {
      left -= 1;
      throw new TransientError(`${step}: la respuesta se perdió`);
    }
    return result;
  };
  return { ...real, [step]: wrapped };
}

test('camino feliz: noche reservada, un cobro, un comprobante', async () => {
  const saga = await new Orchestrator(pool, real).start(rosa);
  assert.equal(saga.status, 'completed');
  assert.deepEqual(await sagaViews(pool), [
    { id: 'saga-rosa', status: 'completed', night: 'booked', heldBy: 'saga-rosa', charges: 1, vouchers: 1 },
  ]);
  assert.deepEqual(await inconsistencies(pool), []);
});

test('falla el primer paso (la noche no está libre): no hay nada que compensar', async () => {
  await pool.query(`UPDATE inventory_nights SET status = 'booked', held_by = 'otra' WHERE id = 1`);
  const saga = await new Orchestrator(pool, real).start(rosa);
  assert.equal(saga.status, 'cancelled');
  assert.equal(saga.lastError, 'la noche no está disponible');
  const [view] = await sagaViews(pool);
  assert.deepEqual([view!.charges, view!.vouchers, view!.heldBy], [0, 0, 'otra']);
});

test('falla el cobro (pago rechazado): la compensación libera la noche', async () => {
  const saga = await new Orchestrator(pool, real).start({ ...rosa, amountCents: 18013 });
  assert.equal(saga.status, 'cancelled');
  assert.equal(saga.lastError, 'pago rechazado');
  assert.deepEqual(await sagaViews(pool), [
    { id: 'saga-rosa', status: 'cancelled', night: 'available', heldBy: null, charges: 0, vouchers: 0 },
  ]);
  assert.deepEqual(await inconsistencies(pool), []);
});

for (const step of STEPS) {
  for (const when of ['before', 'after'] as const) {
    test(`falla técnica en ${step} (${when === 'before' ? 'se pierde el pedido' : 'se pierde la respuesta'}) dos veces: se reintenta y termina bien`, async () => {
      const saga = await new Orchestrator(pool, flaky(step, when, 2)).start(rosa);
      assert.equal(saga.status, 'completed');
      assert.deepEqual(await inconsistencies(pool), []); // en particular: un solo cobro, un solo comprobante
    });
  }
}

test('falla técnica en la compensación: release se reintenta hasta liberar la noche', async () => {
  const saga = await new Orchestrator(pool, flaky('release', 'after', 2)).start({ ...rosa, amountCents: 18013 });
  assert.equal(saga.status, 'cancelled');
  assert.deepEqual(await inconsistencies(pool), []);
});

for (const step of ['hold', 'charge', 'issue', 'confirm'] as const) {
  test(`el orquestador muere después de ${step} y antes de anotarlo: al retomar, termina bien`, async () => {
    let crashed = false;
    const dying = new Orchestrator(pool, real, {
      afterStep: (name) => {
        if (name === step && !crashed) {
          crashed = true;
          throw new Crash(`caída después de ${step}`);
        }
      },
    });
    await assert.rejects(dying.start(rosa), Crash);
    // A medias: es justo el estado que una transacción nunca dejaría ver.
    assert.notDeepEqual(await inconsistencies(pool), []);
    // Otro proceso arranca, lee la tabla sagas y continúa.
    const [saga] = await new Orchestrator(pool, real).recover();
    assert.equal(saga!.status, 'completed');
    assert.deepEqual(await inconsistencies(pool), []);
  });
}

test('el orquestador muere en plena compensación: al retomar, la noche queda libre', async () => {
  let crashed = false;
  const dying = new Orchestrator(pool, real, {
    afterStep: (name) => {
      if (name === 'release' && !crashed) {
        crashed = true;
        throw new Crash('caída después de release');
      }
    },
  });
  await assert.rejects(dying.start({ ...rosa, amountCents: 18013 }), Crash);
  const [saga] = await new Orchestrator(pool, real).recover();
  assert.equal(saga!.status, 'cancelled');
  assert.deepEqual(await inconsistencies(pool), []);
});

test('después del punto de no retorno la saga no compensa: si issue sigue fallando, queda en "charged" para retomarla', async () => {
  const stubborn = new Orchestrator(pool, flaky('issue', 'before', 100), { attemptsPerStep: 3 });
  await assert.rejects(stubborn.start(rosa), TransientError);
  const [view] = await sagaViews(pool);
  assert.deepEqual(view, { id: 'saga-rosa', status: 'charged', night: 'held', heldBy: 'saga-rosa', charges: 1, vouchers: 0 });
  // Cuando el servicio de comprobantes vuelve, la saga termina.
  const [saga] = await new Orchestrator(pool, real).recover();
  assert.equal(saga!.status, 'completed');
  assert.deepEqual(await inconsistencies(pool), []);
});

test('sin aislamiento: otra saga ve la noche apartada y se cancela, aunque la primera termine cancelándose también', async () => {
  let release: () => void = () => {};
  const paused = new Promise<void>((resolve) => (release = resolve));
  let atCharge: () => void = () => {};
  const reachedCharge = new Promise<void>((resolve) => (atCharge = resolve));
  const slowCharge: Participants = {
    ...real,
    charge: async (sagaId, amountCents) => {
      if (sagaId === 'saga-rosa') {
        atCharge();
        await paused; // Rosa está pagando
      }
      return real.charge(sagaId, amountCents);
    },
  };
  const first = new Orchestrator(pool, slowCharge).start({ ...rosa, amountCents: 18013 }); // su pago será rechazado
  await reachedCharge;
  // El estado intermedio se ve desde afuera: para Juan, la noche no está.
  const second = await new Orchestrator(pool, slowCharge).start({ id: 'saga-juan', nightId: 1, guest: 'Juan', amountCents: 18000 });
  assert.equal(second.status, 'cancelled');
  release();
  assert.equal((await first).status, 'cancelled');
  // Consistente, y sin embargo nadie se quedó con la noche.
  assert.deepEqual(await inconsistencies(pool), []);
  const night = await pool.query('SELECT status FROM inventory_nights WHERE id = 1');
  assert.deepEqual(night.rows, [{ status: 'available' }]);
});

test('dos sagas por la misma noche a la vez: una la reserva y la otra se cancela', async () => {
  const orchestrator = new Orchestrator(pool, real);
  const sagas = await Promise.all([
    orchestrator.start(rosa),
    orchestrator.start({ id: 'saga-juan', nightId: 1, guest: 'Juan', amountCents: 18000 }),
  ]);
  assert.deepEqual(sagas.map((s) => s.status).sort(), ['cancelled', 'completed']);
  assert.deepEqual(await inconsistencies(pool), []);
});

Laboratorio

Archivos de partida del laboratorio de la semana.

lab/lost-response.tsDescargar lab/lost-response.ts
import { startChargeService } from '../idempotency/charge-service.ts';
import { countCharges } from '../idempotency/charges.ts';
import { newIdempotencyKey, postWithRetry } from '../idempotency/retry-client.ts';
import { newPool, resetData } from '../shared/db.ts';
import { startPurchaseService } from './purchase-service.ts';

// El cliente del paso 8: compra un cupo del tour, la primera respuesta "se
// pierde" y reintenta con la misma clave de idempotencia.
//
//   node lab/lost-response.ts     (o make lab-lost-response)
//
// Antes de completar lab/purchase-service.ts muestra dos compras y dos
// cobros; después, una y uno.

const pool = newPool();
await resetData();
const chargesPool = newPool(); // el servicio de cobros tiene su propio pool
const charges = await startChargeService(chargesPool, { idempotency: true, loseResponses: 0 });
const purchases = await startPurchaseService(pool, { chargesUrl: charges.url, loseResponses: 1 });
try {
  const result = await postWithRetry(`${purchases.url}/purchases`, { tourId: 1, guest: 'Rosa' }, { key: newIdempotencyKey() });
  for (const a of result.attempts) console.log(`intento ${a.attempt}: ${a.outcome}`);
  console.log(`el cliente recibe: ${JSON.stringify(result.body)}`);
  const made = await pool.query<{ n: number }>('SELECT count(*)::int AS n FROM tour_purchases');
  const tour = await pool.query<{ places_left: number }>('SELECT places_left FROM tours WHERE id = 1');
  console.log(`compras registradas: ${made.rows[0]!.n}`);
  console.log(`cupos que quedan (había 10): ${tour.rows[0]!.places_left}`);
  console.log(`cobros en el servicio de cobros: ${await countCharges(pool)}`);
} finally {
  await purchases.close();
  await charges.close();
  await pool.end();
  await chargesPool.end();
}
lab/purchase-service.tsDescargar lab/purchase-service.ts
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
import type { AddressInfo } from 'node:net';
import type pg from 'pg';

// LABORATORIO, paso 8. El servicio de compras del hospedaje: vende un cupo de
// un tour y lo cobra en el servicio de cobros (idempotency/charge-service.ts).
//
//   POST /purchases  { "tourId": 1, "guest": "Rosa" } → 201 { purchaseId, chargeId, placesLeft }
//                                                       409 si no quedan cupos
//
// Como está, repetir un pedido es comprar otra vez: si la respuesta se pierde
// y el cliente reintenta, quedan dos compras y dos cobros.
//
// Lo que hay que hacer (las pruebas de lab/purchase.test.ts dicen cuándo está):
//
//   1. Leer la cabecera Idempotency-Key.
//   2. Guardar la clave con la respuesta en la tabla purchase_keys, en la
//      MISMA transacción que la compra. Ante una clave repetida, devolver la
//      respuesta guardada sin comprar ni cobrar de nuevo.
//   3. Dos pedidos simultáneos con la misma clave deben dar una sola compra.
//   4. Pensar qué pasa si este servicio muere después de cobrar y antes de su
//      COMMIT: al reintentar, la compra se hace de nuevo. ¿Cómo evitan que el
//      servicio de cobros cobre otra vez?
//
// No cambien la interfaz HTTP ni la firma de startPurchaseService.

export type PurchaseServiceOptions = {
  /** Dónde está el servicio de cobros. */
  chargesUrl: string;
  /** Cuántas respuestas se "pierden": el servicio compra y corta la conexión sin responder. */
  loseResponses: number;
  /** Solo para las pruebas: se llama con la transacción abierta, justo antes del COMMIT. */
  beforeCommit?: () => Promise<void>;
};

export type PurchaseService = { url: string; close(): Promise<void> };

type Input = { tourId: number; guest: string };
type Reply = { status: number; body: Record<string, unknown> };

const TOUR_PRICE_CENTS = 12000;

async function readInput(request: IncomingMessage): Promise<Input | undefined> {
  const chunks: Buffer[] = [];
  for await (const chunk of request) chunks.push(chunk as Buffer);
  try {
    const body = JSON.parse(Buffer.concat(chunks).toString('utf8')) as Partial<Input>;
    const valid = Number.isInteger(body.tourId) && typeof body.guest === 'string' && body.guest !== '';
    return valid ? { tourId: body.tourId!, guest: body.guest! } : undefined;
  } catch {
    return undefined;
  }
}

function send(response: ServerResponse, reply: Reply): void {
  const text = JSON.stringify(reply.body);
  response.writeHead(reply.status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(text) });
  response.end(text);
}

async function charge(chargesUrl: string, reference: string): Promise<number> {
  const response = await fetch(`${chargesUrl}/charges`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ reference, amountCents: TOUR_PRICE_CENTS }),
  });
  if (response.status !== 201) throw new Error(`El servicio de cobros respondió ${response.status}`);
  return ((await response.json()) as { chargeId: number }).chargeId;
}

async function purchase(pool: pg.Pool, input: Input, options: PurchaseServiceOptions): Promise<Reply> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    const tour = await client.query<{ places_left: number }>(
      'UPDATE tours SET places_left = places_left - 1 WHERE id = $1 AND places_left > 0 RETURNING places_left',
      [input.tourId],
    );
    if (tour.rowCount !== 1) {
      await client.query('ROLLBACK');
      return { status: 409, body: { error: { code: 'SOLD_OUT' } } };
    }
    const chargeId = await charge(options.chargesUrl, `tour-${input.tourId}-${input.guest}`);
    const inserted = await client.query<{ id: number }>(
      'INSERT INTO tour_purchases (tour_id, guest, charge_id) VALUES ($1, $2, $3) RETURNING id',
      [input.tourId, input.guest, chargeId],
    );
    await options.beforeCommit?.();
    await client.query('COMMIT');
    return { status: 201, body: { purchaseId: inserted.rows[0]!.id, chargeId, placesLeft: tour.rows[0]!.places_left } };
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}

export async function startPurchaseService(pool: pg.Pool, options: PurchaseServiceOptions): Promise<PurchaseService> {
  let toLose = options.loseResponses;

  const handle = async (request: IncomingMessage, response: ServerResponse): Promise<void> => {
    if (request.method !== 'POST' || request.url !== '/purchases') {
      return send(response, { status: 404, body: { error: { code: 'NOT_FOUND' } } });
    }
    const input = await readInput(request);
    if (!input) return send(response, { status: 422, body: { error: { code: 'INVALID_INPUT' } } });
    const reply = await purchase(pool, input, options);
    if (toLose > 0 && reply.status === 201) {
      toLose -= 1;
      request.socket.destroy(); // la compra está hecha; la respuesta no llega
      return;
    }
    send(response, reply);
  };

  const server = createServer((request, response) => {
    handle(request, response).catch(() => send(response, { status: 500, body: { error: { code: 'INTERNAL_ERROR' } } }));
  });
  await new Promise<void>((resolve) => server.listen(0, resolve));
  const address = server.address() as AddressInfo;
  return {
    url: `http://localhost:${address.port}`,
    close: () =>
      new Promise<void>((resolve) => {
        server.close(() => resolve());
        server.closeAllConnections();
      }),
  };
}
lab/purchase.test.tsDescargar lab/purchase.test.ts
import assert from 'node:assert/strict';
import { after, beforeEach, test } from 'node:test';
import { startChargeService, type ChargeService } from '../idempotency/charge-service.ts';
import { countCharges } from '../idempotency/charges.ts';
import { newIdempotencyKey, postWithRetry } from '../idempotency/retry-client.ts';
import { newPool, resetData } from '../shared/db.ts';
import type * as PurchaseModule from './purchase-service.ts';

// Las pruebas del paso 8 del laboratorio. Corren contra lab/purchase-service.ts:
//
//   make lab-test
//
// Con el archivo como viene, las dos primeras pasan y las demás fallan.

const implementation = process.env.IMPL ?? 'lab';
const { startPurchaseService } = (await import(`../${implementation}/purchase-service.ts`)) as typeof PurchaseModule;

const pool = newPool();
// El servicio de cobros es otro servicio: tiene su propio pool. Si compartiera
// el del servicio de compras, diez compras esperando con su transacción
// abierta lo dejarían sin conexiones para cobrar.
const chargesPool = newPool();
let charges: ChargeService;
beforeEach(async () => {
  await resetData();
  charges = await startChargeService(chargesPool, { idempotency: true, loseResponses: 0 });
});
after(async () => {
  await pool.end();
  await chargesPool.end();
});

const rosa = { tourId: 1, guest: 'Rosa' };

async function state(): Promise<{ purchases: number; placesLeft: number; charges: number }> {
  const purchases = await pool.query<{ n: number }>('SELECT count(*)::int AS n FROM tour_purchases');
  const tour = await pool.query<{ places_left: number }>('SELECT places_left FROM tours WHERE id = 1');
  return { purchases: purchases.rows[0]!.n, placesLeft: tour.rows[0]!.places_left, charges: await countCharges(pool) };
}

async function withService<T>(
  options: Partial<PurchaseModule.PurchaseServiceOptions>,
  fn: (url: string) => Promise<T>,
): Promise<T> {
  const service = await startPurchaseService(pool, { chargesUrl: charges.url, loseResponses: 0, ...options });
  try {
    return await fn(`${service.url}/purchases`);
  } finally {
    await service.close();
    await charges.close();
  }
}

test('una compra: un cupo menos, una compra, un cobro', async () => {
  await withService({}, async (url) => {
    const result = await postWithRetry(url, rosa);
    assert.equal(result.status, 201);
    assert.deepEqual(await state(), { purchases: 1, placesLeft: 9, charges: 1 });
  });
});

test('dos compras con claves distintas son dos compras', async () => {
  await withService({}, async (url) => {
    await postWithRetry(url, rosa, { key: newIdempotencyKey() });
    await postWithRetry(url, rosa, { key: newIdempotencyKey() });
    assert.deepEqual(await state(), { purchases: 2, placesLeft: 8, charges: 2 });
  });
});

test('la respuesta se pierde y el cliente reintenta con la misma clave: una compra y un cobro', async () => {
  await withService({ loseResponses: 1 }, async (url) => {
    const result = await postWithRetry(url, rosa, { key: newIdempotencyKey() });
    assert.equal(result.attempts.length, 2);
    assert.equal(result.status, 201);
    assert.deepEqual(result.body, { purchaseId: 1, chargeId: 1, placesLeft: 9 });
    assert.deepEqual(await state(), { purchases: 1, placesLeft: 9, charges: 1 });
  });
});

test('diez pedidos simultáneos con la misma clave: una compra y diez respuestas iguales', async () => {
  await withService({}, async (url) => {
    const key = newIdempotencyKey();
    const results = await Promise.all(Array.from({ length: 10 }, () => postWithRetry(url, rosa, { key })));
    assert.equal(new Set(results.map((r) => JSON.stringify(r.body))).size, 1);
    assert.deepEqual(await state(), { purchases: 1, placesLeft: 9, charges: 1 });
  });
});

test('la misma clave con otro pedido se rechaza con 422', async () => {
  await withService({}, async (url) => {
    const key = newIdempotencyKey();
    await postWithRetry(url, rosa, { key });
    const other = await postWithRetry(url, { tourId: 1, guest: 'Juan' }, { key });
    assert.equal(other.status, 422);
    assert.deepEqual(await state(), { purchases: 1, placesLeft: 9, charges: 1 });
  });
});

test('el servicio muere después de cobrar y antes de su COMMIT: el reintento compra, y no hay un segundo cobro', async () => {
  let first = true;
  const beforeCommit = async (): Promise<void> => {
    if (!first) return;
    first = false;
    throw new Error('el proceso murió antes del COMMIT');
  };
  await withService({ beforeCommit }, async (url) => {
    const result = await postWithRetry(url, rosa, { key: newIdempotencyKey() });
    assert.equal(result.attempts.length, 2); // un 500 y después un 201
    assert.equal(result.status, 201);
    assert.deepEqual(await state(), { purchases: 1, placesLeft: 9, charges: 1 });
  });
});

Compilación

Cómo se compilan y ejecutan los ejemplos.

MakefileDescargar Makefile
# Semana 12: transacciones, dentro de una base de datos y entre servicios.
# El ejemplo es un hospedaje pequeño (noches de habitación, cupos de un tour),
# no Tinkuy. Se usa dentro del contenedor del curso.
#
#   make                 crea la base de datos arq_w12 con sus datos de ejemplo
#   make test            revisa los tipos (tsc) y corre las pruebas (test/*.test.ts)
#   make guion G=01      ejecuta un guion de guion/ con dos sesiones de psql
#                        (01 doble reserva, 02 FOR UPDATE, 03 deadlock, 04 locks en
#                        orden, 05 UPDATE con condición, 06 serializable, 07
#                        actualización perdida, 08 y 09 write skew, 10 fantasma)
#   make guiones         los ejecuta todos
#   make serve STRATEGY=lock   el servidor de reservas en http://localhost:3000
#                        (naive, lock, conditional o serializable; NIGHTS=3000 para make load)
#   make burst           200 pedidos simultáneos por 10 noches, 5 rondas, contra make serve
#   make load            k6: 200 huéspedes durante 15 s, contra make serve NIGHTS=3000
#   make activity        qué está haciendo cada conexión de arq_w12 en este momento
#   make compare-burst   make burst con las cuatro estrategias, una tras otra
#   make compare-load    make load con las cuatro estrategias, una tras otra
#   make lost-response   la respuesta perdida, con y sin clave de idempotencia
#   make saga            tres sagas: una completa, una compensada y una retomada
#   make tinkuy-oversell el problema en el Tinkuy inicial (una copia en build/tinkuy)
#   make lab-test        las pruebas del paso 8 del laboratorio (lab/purchase-service.ts)
#   make lab-lost-response   el cliente del paso 8
#   make clean           borra las bases de datos y build/
#
# make guion, make lost-response, make saga y make lab-lost-response dejan los
# datos de arq_w12 como al principio antes de empezar.

G ?= 01
STRATEGY ?= naive
TINKUY ?= ../../tinkuy
# psql no avisa cuando la base de datos que se va a borrar todavía no existe.
PGOPTIONS = --client-min-messages=warning
export PGOPTIONS STRATEGY

.PHONY: all db test-db test guion guiones serve burst load activity compare-burst compare-load lost-response saga \
        tinkuy-oversell lab-test lab-lost-response clean

all: db

db:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS arq_w12 WITH (FORCE)" -c "CREATE DATABASE arq_w12"
	@psql -q -d arq_w12 -v ON_ERROR_STOP=1 -f db/schema.sql
	@psql -q -d arq_w12 -v ON_ERROR_STOP=1 -f db/reset.sql
	@echo "Base de datos arq_w12 recién creada: 300 noches libres, un tour con 10 cupos, dos médicos de guardia."

# La base de datos de las pruebas se crea aquí, y cada prueba la deja como al
# principio antes de empezar. Los archivos comparten la base de datos: corren
# uno después de otro.
test-db:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS arq_w12_test WITH (FORCE)" -c "CREATE DATABASE arq_w12_test"
	@psql -q -d arq_w12_test -v ON_ERROR_STOP=1 -f db/schema.sql

test: test-db
	tsc -p .
	W12_DB=arq_w12_test node --test --test-concurrency=1 "test/*.test.ts"

guion:
	@node harness/guion.ts $(firstword $(wildcard guion/$(G)*.sql))

guiones:
	@for g in guion/*.sql; do echo "== $$g"; node harness/guion.ts $$g; echo; done

serve:
	node booking/server.ts

burst:
	@node tools/burst.ts

load:
	k6 run load/opening.js

# idle in transaction: la conexión tiene una transacción abierta y no está
# ejecutando nada; espera a la aplicación (que, a su vez, espera el cobro).
activity:
	@psql -d arq_w12 -c "SELECT state, wait_event_type AS espera, count(*) AS conexiones FROM pg_stat_activity WHERE datname = 'arq_w12' AND pid <> pg_backend_pid() GROUP BY 1, 2 ORDER BY 3 DESC"

compare-burst:
	@bash tools/compare.sh burst

compare-load:
	@bash tools/compare.sh load

lost-response:
	@node idempotency/demo.ts

saga:
	@node saga/demo.ts

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

tinkuy-oversell: build/tinkuy
	@bash tools/tinkuy-oversell.sh

lab-test: test-db
	W12_DB=arq_w12_test node --test --test-concurrency=1 "lab/*.test.ts"

lab-lost-response:
	@node lab/lost-response.ts

clean:
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS arq_w12 WITH (FORCE)" -c "DROP DATABASE IF EXISTS arq_w12_test WITH (FORCE)"
	@psql -q -d postgres -c "DROP DATABASE IF EXISTS tinkuy WITH (FORCE)" -c "DROP DATABASE IF EXISTS tinkuy_test WITH (FORCE)"
	rm -rf build
package.jsonDescargar package.json
{
  "name": "week-12",
  "private": true,
  "type": "module"
}
tsconfig.jsonDescargar tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["shared", "harness", "booking", "errors", "idempotency", "saga", "outbox", "tools", "test", "lab", "solution"]
}