P2 · La apertura de ventas

Cubre: semanas 5 a 7 (la semana 12 vuelve sobre esta entrega) · En equipo

Tinkuy consiguió el concierto del año: Killa Sónica en el Estadio Nacional. El día que se abre la venta, miles de personas van a estar en la página a la misma hora, todas detrás de los mismos asientos. El sistema, como está, no llega: responde con errores cuando hay muchos pedidos a la vez, la lista de eventos tarda segundos, y vende el mismo asiento a dos personas.

El punto de partida es su propio P1.

1. El requisito que llega

La apertura de ventas

  • Atributo de calidad: rendimiento
  • Fuente del estímulo: 200 compradores y 50 visitantes
  • Estímulo: durante 30 segundos, cada comprador envía órdenes de 1 o 2 asientos al azar del evento que abre su venta, con una pausa de 0,5 a 1,5 segundos entre intentos; mientras tanto, cada visitante pide la lista de eventos y el detalle de ese evento, una vez por segundo
  • Artefacto: la compra (POST /orders), el catálogo (GET /events) y la base de datos
  • Entorno: pico de carga: el evento recién abre, con todos sus asientos libres; la pasarela responde en 80 ms y no hay ninguna falla
  • Respuesta: cada orden se acepta (201) o se rechaza porque algún asiento ya no está (409); el catálogo sigue respondiendo; cada asiento se vende una sola vez, y todo cobro aprobado corresponde a una orden pagada
  • Medida de la respuesta: p95 de POST /orders menor que 900 ms, p95 de GET /events menor que 300 ms, 0 respuestas 5xx o pedidos sin respuesta, 0 asientos con más de una entrada y 0 cobros aprobados sin su orden pagada

Las dos primeras medidas son de rendimiento y las dos últimas de corrección. Van juntas a propósito: es fácil cumplir unas rompiendo las otras. Un sistema que hace pasar las compras de una en una no vende nada dos veces y no llega al p95; uno que no espera a nadie llega al p95 y vende de más.

Los umbrales de latencia valen para una laptop corriente. Si su máquina es más lenta, make calibrate los ajusta (sección 6).

2. Lo que hay que saber para no vender dos veces

La semana 12 estudia las transacciones a fondo. Esta entrega llega antes, así que aquí va lo necesario.

El problema. La compra de Tinkuy lee el estado de los asientos, y si están libres sigue adelante: cobra, y al final los marca como vendidos. Eso es check-then-act: una decisión tomada con un dato que puede haber cambiado cuando se actúa. Dos órdenes para el asiento 1001 que llegan casi juntas leen las dos available, las dos cobran y las dos emiten su entrada. Que todo ocurra “dentro de una transacción” no lo evita: con el aislamiento por omisión de PostgreSQL (read committed), una transacción no ve lo que otra todavía no confirmó, y nada le impide leer una fila que otra está por cambiar. make oversell lo muestra en dos segundos.

Las salidas. Hay varias, y todas existen en sistemas reales:

Opción La idea Lo que hay que mirar
Lock pesimista Leer los asientos con SELECT ... FOR UPDATE: la segunda transacción espera a que la primera termine y recién entonces lee Cuánto dura la espera (lo que dure la transacción de quien llegó primero) y en qué orden se toman los locks cuando una orden tiene varios asientos
Actualización condicional No leer antes: UPDATE seats SET status = 'sold' WHERE id = ... AND status = 'available' y mirar cuántas filas cambió Qué se hace cuando cambió menos filas de las pedidas, y cómo se distingue “ya no está” de “no existe”
Restricción única Que la base de datos lo impida: un índice único hace fallar la segunda inserción En qué momento falla, y qué pasó antes de ese momento (¿ya se cobró?)
Aislamiento serializable BEGIN ISOLATION LEVEL SERIALIZABLE: PostgreSQL aborta una de las dos transacciones con el error 40001 Quién reintenta la transacción abortada, cuántas veces, y cuánto trabajo se repite bajo carga

Dos cosas más que van a encontrar por el camino:

  • Deadlock. Si una orden toma el asiento aa y espera el bb mientras otra tiene el bb y espera el aa, ninguna avanza. PostgreSQL lo detecta después de un segundo y aborta una con el error 40P01, que hoy termina en un 500. Se evita, o se maneja.
  • La pasarela dentro de la transacción. Hoy la compra llama a la pasarela con la transacción abierta. Mientras la pasarela responde, esa transacción retiene una conexión y, según lo que decidan arriba, también locks. Con 80 ms apenas se nota; con una pasarela lenta, todo lo que espera esos locks espera también a la pasarela. La pasarela sigue en el camino del pedido en esta entrega (sacarla es P4), pero ya no se la llama con una transacción abierta.

No hay una opción correcta. Hay una que el equipo elige, mide y justifica.

3. Lo que está fijo

  • La API no cambia: mismas rutas, mismos cuerpos y mismos códigos de estado. POST /orders sigue respondiendo 201 con la orden pagada y sus entradas, 402 si la pasarela rechaza el pago, 409 con SEAT_NOT_AVAILABLE si algún asiento ya no está, y 422 si los datos no son válidos.
  • Todo o nada: una orden de varios asientos se lleva todos o ninguno.
  • El cobro se hace durante el pedido (hasta P4, que lo cambia), en la pasarela, y la respuesta ya dice si se aprobó. No hay órdenes que queden pending cuando el sistema está en reposo.
  • Sin transacción abierta mientras responde la pasarela. Con la pasarela demorando 2 segundos, ninguna sesión de PostgreSQL de su sistema puede pasar 1 segundo o más en estado idle in transaction.
  • Ningún cobro aprobado sin orden pagada. La pasarela de prueba no tiene devoluciones: si cobran y después descubren que el asiento ya no estaba, no hay cómo deshacerlo.
  • Un pago rechazado deja los asientos libres y la orden en failed, como hasta ahora.
  • El correo de confirmación de cada orden pagada queda registrado en notifications. Puede salir después de la respuesta; las pruebas le dan hasta 15 segundos.
  • Las nueve tablas conservan su nombre y sus columnas; pueden agregar columnas, índices, restricciones y tablas (y declararlas en docs/data-ownership.md). Lo fijo de P0 y P1 sigue fijo: make check con make deps, los límites entre módulos y los medios de pago como plug-ins.
  • Solo lo que trae el contenedor. Redis está ahí, y usarlo es una decisión que se justifica como cualquier otra; lo que no se puede es guardar en él (ni en la memoria del proceso) la verdad sobre qué asiento está vendido: esa vive en PostgreSQL, y las pruebas la leen ahí.

4. Lo que deciden

Al menos tres ADR nuevos, cada uno con al menos dos alternativas comparadas y, donde se pueda, con la medición que respalda la elección:

  1. Cómo se evita vender un asiento dos veces, y en qué orden ocurren tomar el asiento, cobrar y emitir la entrada.
  2. Cómo se manejan las conexiones a la base de datos.
  3. Qué se hizo con GET /events.

5. Lo que comprueban las pruebas públicas

check corre las pruebas de P0 y de P1 y después p2.public.test.ts, que tiene tres grupos.

Documentos

  1. docs/adr/ tiene al menos seis ADR en total, con sus secciones.
  2. docs/measurements/p2.md tiene las secciones Máquina, Antes y Después y al menos un bloque de código.
  3. docs/scenarios.md pasa el revisor y tiene al menos cinco escenarios.
  4. Los tres diagramas C4 siguen pasando el revisor.

Concurrencia. Todas las órdenes son sobre el evento en venta con más asientos libres, con compradores y celulares distintos.

  1. Un asiento, 40 órdenes a la vez, cinco veces (cada vez con otro asiento). Cada vez: exactamente un 201 y 39 respuestas 409 con SEAT_NOT_AVAILABLE, una sola entrada para ese asiento y un solo cobro aprobado en la pasarela.
  2. Tres asientos, 20 órdenes a la vez que piden los mismos tres: un 201 y 19 respuestas 409, y las tres entradas son de la misma orden.
  3. Asientos en común en orden contrario. Para 20 pares de asientos (a,b)(a, b), tres órdenes piden [a, b] y tres piden [b, a], las 120 a la vez. Todas las respuestas son 201 o 409, y de las seis órdenes de cada par exactamente una recibe 201.
  4. Pago rechazado con otros esperando. Diez órdenes a la vez para un asiento, todas con una tarjeta que la pasarela rechaza: todas las respuestas son 402 o 409, con al menos un 402; el asiento queda available, y una orden más, con un pago válido, lo compra (201).
  5. La pasarela lenta. Con la pasarela demorando 2 segundos, diez órdenes de asientos distintos a la vez: las diez responden 201. Mientras esperan, la prueba consulta pg_stat_activity cada 100 ms: ninguna sesión de la base de datos tinkuy llega a 1 000 ms en estado idle in transaction.
  6. El estado después de todo eso: ningún asiento con más de una entrada ni en más de una orden pagada; todo asiento sold tiene su entrada y todo asiento con entrada está sold; todo ítem de una orden pagada tiene su entrada; ninguna entrada es de una orden que no está pagada; toda orden pagada tiene exactamente un cobro aprobado y todo cobro aprobado es de una orden pagada; ninguna orden quedó pending.

La apertura de ventas. Desde datos recién cargados, corre sale-opening.js con k6: es la carga del escenario.

  1. Los umbrales del script se cumplen:

    Métrica Umbral
    http_req_duration{name:POST /orders} (todos los intentos de compra) p(95)<900
    purchase_duration (solo las compras que terminaron en 201) p(95)<900
    http_req_duration{name:GET /events} p(95)<300
    unexpected_responses (un POST /orders que no es 201 ni 409, o un GET que no es 200) rate==0

    Los dos umbrales de latencia se multiplican por el factor de calibración.

  2. Al terminar, con el sistema en reposo: las invariantes del punto 10; en el evento, asientos vendidos = entradas = ítems de órdenes pagadas; los cobros que la pasarela aprobó durante la corrida son tantos como las órdenes pagadas; y se vendió al menos 60 % de los asientos del evento (un sistema que responde 409 a todo cumple la latencia y no vende).

  3. Cada orden pagada tiene su fila en notifications, a más tardar 15 segundos después.

Las pruebas no miran cómo lo hicieron: no buscan FOR UPDATE en su código ni un pool en db.ts. Miran lo que el sistema responde y cómo queda la base de datos.

En la revisión se repiten con otra semilla, así que el evento y los asientos salen de consultas, no de ids fijos. Las pruebas de concurrencia dependen de cómo caen los pedidos en el tiempo: una condición de carrera puede no aparecer en una corrida. Antes de entregar, corran check varias veces.

6. Cómo se comprueba

make -f /work/projects/p2-apertura-de-ventas/Makefile check

Corre make typecheck, make deps y make test de su repositorio y después las pruebas públicas de P0, P1 y P2. Como siempre, borran y vuelven a crear la base de datos tinkuy y usan los puertos 3100 y 4100. Tarda entre dos y tres minutos; para trabajar solo con las de esta entrega:

node --test --test-concurrency=1 /work/projects/p2-apertura-de-ventas/p2.public.test.ts

Calibrar. Los umbrales de latencia se fijaron en una laptop corriente con margen. Si en su máquina no alcanzan por poco, antes de cambiar su diseño midan la máquina:

make -f /work/projects/p2-apertura-de-ventas/Makefile calibrate

calibrate levanta un servidor mínimo que no tiene nada de su código (una transacción corta, una consulta de agregación y una lista de 600 filas por pedido), le manda 12 000 pedidos con k6, cinco veces, y compara la mediana de pedidos atendidos por segundo con la de la máquina de referencia. El cociente, nunca menor que 1 ni mayor que 5, es el factor por el que se multiplican los umbrales de latencia mientras el contenedor siga abierto. Los umbrales de corrección no se calibran: cero es cero en cualquier máquina. La salida de calibrate se copia en docs/measurements/p2.md; cada corrida de las pruebas dice con qué factor corrió.

Sobre un P1 terminado y nada más, las pruebas de P2 terminan así (en la laptop de referencia):

P2 · documentos
  ✖ hay al menos seis ADR (los de P0 y P1, y tres de esta entrega), con sus secciones
      docs/adr/ tiene 3 ADR con nombre NNNN-titulo.md y esta entrega pide al menos 6 en total
  ✖ docs/measurements/p2.md tiene la máquina, el antes y el después
      docs/measurements/p2.md: no existe
  ✖ docs/scenarios.md pasa el revisor y tiene al menos cinco escenarios
      hay 4 escenarios: los de P0 y P1 son cuatro, y esta entrega agrega el suyo
  ✔ los tres diagramas C4 siguen pasando el revisor

P2 · concurrencia
  ✖ 40 órdenes a la vez para un mismo asiento, cinco veces: cada vez, un 201 y 39 respuestas 409 (5.1 s)
      ronda 1, asiento 1: respuestas por código de estado
      + actual - expected

        {
      +   '201': 40
      -   '201': 1,
      -   '409': 39
        }

  ✖ 20 órdenes a la vez por los mismos tres asientos: una sola se los lleva (2.6 s)
      ...
  ✖ órdenes con asientos en común y en orden contrario: ningún 5xx, y cada par de asientos queda para una sola orden (1.0 s)
      hubo 21 respuesta(s) 500: solo se esperan 201 y 409
  ✔ pago rechazado con otros esperando el mismo asiento: nadie lo compra, y el asiento vuelve a estar libre
  ✖ con la pasarela demorando 2 s, ninguna transacción queda abierta esperándola (2.2 s)
      una sesión pasó 1964 ms con una transacción abierta y sin hacer nada (pg_stat_activity, estado "idle in transaction") mientras la pasarela demoraba: el límite es 1000 ms
      · la sesión que más tiempo pasó "idle in transaction": 1964 ms
  ✖ después de todo lo anterior, el estado es coherente y hay un cobro aprobado por cada orden pagada
      40 asiento(s) tienen más de una entrada: se vendieron dos veces
      40 asiento(s) están en más de una orden pagada

P2 · la apertura de ventas
  ✖ 200 compradores y 50 visitantes durante 30 s: los umbrales del escenario se cumplen (32.0 s)
      unexpected_responses: se pedía rate==0 y salió 0.015
      http_req_duration{name:GET /events}: se pedía p(95)<300 y salió 631.685
      · factor de calibración 1.0 (la variable TINKUY_FACTOR): p95 de la compra < 900 ms, p95 de GET /events < 300 ms
      · p95 de POST /orders 305 ms, de las compras 521 ms, de GET /events 632 ms; 1370 órdenes pagadas, 4173 respuestas 409
  ✔ cada orden pagada en la apertura tiene su correo de confirmación registrado

12 pruebas: 3 pasan, 9 fallan

Tres cosas para notar. En esa corrida, la compra cumplió su umbral de latencia: lo que falló en la apertura fueron los errores y la lista de eventos. En otras corridas del mismo sistema, el p95 de la compra pasó de 3 segundos: un sistema al borde no falla siempre igual. Y la prueba del pago rechazado ya pasa, porque hoy nadie toma un asiento antes de pagar; tiene que seguir pasando con su diseño nuevo.

7. Documentos

Archivo Contenido
docs/adr/0004-… a 0006-… (o los números que sigan) Las decisiones de la sección 4
docs/scenarios.md El escenario de la apertura, con la medida que el equipo se compromete a cumplir
docs/measurements/p2.md ## Máquina (con la salida de make calibrate), ## Antes (la apertura sobre su P1: el resumen de k6, qué no se cumple, cuántos asientos quedaron con dos entradas) y ## Después. Si compararon alternativas, una medición por alternativa (archivo de partida: templates/measurements.md)
docs/c4/ Al día. Si agregaron una pieza (un pool, una cache), aparece en la descripción o en una flecha
docs/data-ownership.md Al día, si agregaron tablas

8. Pistas

  • Midan primero. Corran sale-opening.js contra su P1 antes de cambiar nada y guarden el resumen: es su sección Antes, y dice por dónde empezar. Miren también /var/log/course/postgres.log después de la corrida.
  • Un problema a la vez. Hay al menos tres, casi independientes: las conexiones, la lista de eventos y la venta doble. Si los arreglan juntos no van a saber qué cambio movió qué número, y sus ADR necesitan eso.
  • Las conexiones. Es el laboratorio de la semana 6: pool de conexiones, medir antes y después. El tamaño del pool es una decisión que se mide, no un número que se copia.
  • La lista de eventos. Cuenten cuántas consultas hace un GET /events. La semana 6 también trata la cache; antes de poner una, pregúntense qué tan viejo puede ser el número de asientos libres durante una apertura, y si hay una salida más simple.
  • La venta doble. make oversell es la prueba más corta. Empiecen por un solo asiento y, cuando funcione, piensen en las órdenes de varios asientos.
  • El orden de los pasos. Dibujen la compra como una línea de tiempo: qué se lee, qué se escribe, cuándo se cobra, cuándo hay una transacción abierta y qué pasa si el pedido de al lado llega en cada punto. La decisión más importante de la entrega está en ese dibujo, no en una cláusula de SQL.
  • Mirar a PostgreSQL mientras trabaja. En otra terminal, durante la carga: SELECT state, count(*) FROM pg_stat_activity WHERE datname = 'tinkuy' GROUP BY state. Y para ver la pasarela lenta: GATEWAY_LATENCY_MS=2000 make gateway.
  • Los ADR. El laboratorio de la semana 7 trabaja el template. Una alternativa descartada con su medición vale más que una elegida sin ninguna.

9. Fuera de alcance

  • Que el proceso muera a mitad de una compra. Según su diseño, puede quedar un asiento tomado sin entrada o un cobro sin orden. Anótenlo en las consecuencias de su ADR; resolverlo es P4 y P5.
  • La pasarela caída o lenta como escenario de disponibilidad: P5. Aquí solo se pide no esperar a la pasarela con una transacción abierta.
  • Más de un proceso de Tinkuy. La entrega corre con un solo make start. Vale decir en el ADR si su diseño seguiría siendo correcto con dos.
  • Réplicas de lectura y cache distribuida: P3.