P3 · Lecturas que escalan
Cubre: semanas 9 a 11 · En equipo
La apertura de ventas salió bien, y ahora Tinkuy tiene otro problema: por cada persona que compra hay cientos mirando. La lista de eventos, el detalle de cada evento y el reporte que piden los organizadores salen todos del mismo servidor de PostgreSQL que atiende la compra. Cuando ese servidor está ocupado, o cuando haya que detenerlo unos minutos, el catálogo se va con él.
En esta entrega las lecturas dejan de depender del principal. Y llega, además, el primer cambio de contrato con clientes en uso: facturación necesita el nombre y los apellidos de quien compra por separado.
El punto de partida es su propio P2.
1. El requisito que llega
El catálogo con el principal ocupado
- Atributo de calidad: escalabilidad
- Fuente del estímulo: 50 visitantes, mientras 100 compradores compran y 4 organizadores piden el reporte de ventas
- Estímulo: durante 20 segundos, cada visitante pide la lista de eventos y el detalle del evento en venta una vez por segundo; cada comprador envía una orden de un asiento cada segundo, y cada organizador pide el reporte del evento cinco veces por segundo
- Artefacto: el catálogo (
GET /eventsyGET /events/:id) y los almacenes de datos de los que sale - Entorno: el principal ocupado con la venta y los reportes; en el contenedor hay una réplica de PostgreSQL (puerto 5433) y Redis, y cualquiera de los dos puede faltar
- Respuesta: el catálogo se atiende sin preguntarle al principal; después de una compra muestra la disponibilidad nueva dentro de una cota que el equipo declara; quien compra encuentra su orden de inmediato; sin Redis o sin réplica, el sistema sigue respondiendo
- Medida de la respuesta: p95 de
GET /eventsy deGET /events/:idmenor que 300 ms; a lo más 10 % de las lecturas del catálogo terminan en una consulta al principal; la disponibilidad que muestra el catálogo tiene a lo más segundos de atraso, con declarado por el equipo, también con la réplica 8 segundos atrasada; 0 respuestas distintas de 200 enGET /orders/:idjusto después de la compra, en 200 compras seguidas; 0 respuestas 5xx con Redis caído o con la réplica detenida
Una advertencia honesta sobre la primera medida: en una laptop, con 13 000 asientos, el principal aguanta. El p95 del catálogo de un buen P2 ya está bajo los 300 ms, y lo más probable es que al terminar esta entrega no haya mejorado. Lo que cambia es de quién depende el catálogo, y eso se mide con las otras cuatro: son cuentas y cotas, no latencias. El umbral de latencia se queda para que la solución no lo empeore.
Las otras cuatro tiran en direcciones contrarias, y por eso van juntas. Mandar todas las lecturas a la réplica cumple la segunda y rompe la cuarta: quien compra no encuentra su orden. Una cache con un TTL largo cumple la segunda y rompe la tercera. Leer todo del principal cumple la tercera y la cuarta y no cumple la segunda.
El cambio de contrato. buyer.name pasa a ser buyer.givenName y
buyer.familyName. La aplicación móvil que ya está publicada sigue enviando
y leyendo buyer.name, y nadie puede obligar a sus usuarios a actualizarla
hoy. Los dos clientes tienen que poder comprar y leer durante todo el
cambio, y las órdenes que ya existen se migran con la venta abierta.
2. Lo que está fijo
Los servicios
- La réplica es la de
pg-replica create: PostgreSQL en el puerto 5433 del contenedor, con replicación asíncrona. Redis está en el 6379. El sistema arranca y funciona con los dos, con uno solo o con ninguno: las pruebas de P0 a P2 corren sin réplica. - Sin Redis (
svc kill redis) y sin réplica (pg-replica stop), el catálogo y la compra siguen respondiendo, sin ningún 5xx y con cada lectura del catálogo en menos de 2 segundos. Cuando el servicio vuelve, el sistema lo vuelve a usar sin que nadie lo reinicie. make dbdeja el sistema coherente con los datos que carga: si algo de la base de datos anterior queda guardado fuera de PostgreSQL (en Redis, por ejemplo),make dblo borra.- La verdad sigue en el principal. Las pruebas leen ahí qué asiento está vendido y qué orden existe.
Las lecturas
-
GET /orders/:idde una orden quePOST /ordersacaba de responder la devuelve siempre, con su estado y sus entradas, por más atrasada que esté la réplica. -
La disponibilidad que muestran
GET /eventsyGET /events/:id(availableSeats, también por sección) puede ir atrasada, y el equipo declara cuánto como máximo. La declaración va en el escenario de esta entrega, endocs/scenarios.md, en una línea que las pruebas leen:- **Cota de desactualización:** 3 sTiene que ser mayor que 0 y de a lo más 5 s. Vale siempre: con todo sano, con la réplica atrasada, sin Redis y sin réplica.
-
El resto de la API no cambia.
El contrato de buyer
-
POST /ordersaceptabuyeren dos formas:Cliente Envía Nuevo { "email": "…", "givenName": "Luz María", "familyName": "Condori Huamán" }Antiguo { "email": "…", "name": "Rosa Quispe Mamani" }givenNameyfamilyNametienen entre 1 y 80 caracteres cada uno. Si llega alguno de los dos, se usa la forma nueva (yname, si también viene, se ignora): con uno solo, o con uno vacío, la respuesta es 422. Sin ninguna de las dos formas, 422. -
Toda respuesta que trae
buyer(POST /ordersyGET /orders/:id) trae los tres campos, para los dos clientes y para las órdenes de antes del cambio:{ "email": "…", "name": "Rosa Quispe Mamani", "givenName": "Rosa", "familyName": "Quispe Mamani" } -
Hay una sola regla para pasar de una forma a la otra. De
namea las partes:givenNamees lo que va antes del primer espacio yfamilyName, el resto (vacío si no hay espacio). De las partes aname:givenName, un espacio yfamilyName. -
En la base de datos, la tabla
ordersgana dos columnas de texto,buyer_given_nameybuyer_family_name, que en esta entrega admiten NULL. La columnabuyer_namese queda. Toda orden nueva escribe las tres. -
make migratellena las dos columnas nuevas en las órdenes que no las tienen, con la regla de arriba. Corre con el sistema arriba y la venta abierta, en lotes de a lo más 500 filas, cada lote en su propia transacción; si encuentra una fila tomada por otra transacción, espera, no falla; se puede interrumpir y volver a correr, y termina con código 0 cuando no queda nada por migrar. RespetaTINKUY_DB, comomake start. -
La fase de contraer (quitar
buyer.nameybuyer_name) no se hace en esta entrega. Su ADR dice qué tendría que ser cierto para hacerla.
Lo fijo de las entregas anteriores sigue fijo.
3. Lo que deciden
Al menos tres ADR nuevos, cada uno con al menos dos alternativas comparadas:
- Qué lectura va a dónde: cuáles al principal, cuáles a la réplica y cuáles a una cache, y cómo se garantiza que quien compra vea su compra.
- Qué se guarda en la cache y cómo deja de estar ahí, y de dónde sale el número de su cota de desactualización.
- Cómo se cambia el contrato de
buyer: qué hace cada fase, en qué orden se despliega y cuándo se podría contraer.
El enunciado no pide una réplica y una cache: pide las medidas del escenario. Se pueden cumplir de más de una manera, y en el ADR se nota quién eligió y quién copió.
4. Lo que comprueban las pruebas públicas
check corre las pruebas de P0, P1 y P2 y después p3.public.test.ts, que
tiene tres grupos.
Documentos
docs/adr/tiene al menos nueve ADR en total, con sus secciones.docs/measurements/p3.mdtiene las seccionesMáquina,AntesyDespuésy al menos un bloque de código.docs/scenarios.mdpasa el revisor, tiene al menos seis escenarios y declara la cota de desactualización.- Los tres diagramas C4 siguen pasando el revisor.
Lecturas. Las pruebas crean una réplica nueva (pg-replica create),
se aseguran de que Redis esté arriba y levantan su sistema.
-
La API sigue igual: las diez pruebas de siempre, ahora con réplica y Redis.
-
El catálogo casi no le pregunta al principal. 20 visitantes piden
GET /eventsyGET /events/:id(del evento en venta con más asientos libres) durante 5 segundos, sin ninguna compra. Las pruebas cuentan, enpg_stat_user_tablesdel principal, las consultas que leyeron la tablaeventsen ese tiempo: tienen que ser a lo más 10 % de las lecturas hechas. Todas responden 200, y se completan al menos 400. -
La cota. Cinco veces: una compra de dos asientos (201) y, desde ese momento,
GET /eventsyGET /events/:idcada 50 ms hasta que los dos muestren la disponibilidad que hay en la base de datos (en el evento, y sumando sus secciones). Tiene que ocurrir antes de la cota declarada. -
El escenario con carga.
catalog-busy.jscon k6: 100 compradores (la mitad clientes antiguos y la mitad nuevos), 4 organizadores y 50 visitantes durante 20 segundos.Métrica Umbral http_req_duration{name:GET /events}p(95)<300http_req_duration{name:GET /events/:id}p(95)<300unexpected_responses(una compra que no es 201 ni 409, o unGETque no es 200)rate==0Los dos umbrales de latencia se multiplican por el factor de calibración. Al terminar se comprueban las invariantes de la venta de P2.
-
Read-your-writes con la réplica atrasada. Desde datos recién cargados, las pruebas hacen que la réplica aplique cada transacción 8 segundos tarde (
recovery_min_apply_delay) y hacen 200 compras seguidas, una de cada dos como cliente nuevo. Después de cada 201 pidenGET /orders/:id: tiene que responder 200, con la ordenpaidy las mismas entradas. Y con la réplica todavía atrasada, la prueba de la cota (punto 7), tres veces. -
Sin Redis.
svc kill redis; 100 lecturas del catálogo, todas 200 y ninguna de más de 2 segundos; una compra, y la cota. Despuéssvc start redis, y lo mismo otra vez. -
Sin réplica. Igual que el punto 10, con
pg-replica stopypg-replica start.
El contrato de buyer
- Un cliente nuevo compra con
givenNameyfamilyName: 201, y la respuesta yGET /orders/:idtraen los tres campos. - Un cliente antiguo compra con
name: 201, y recibenametal como lo envió, congivenNameyfamilyNamesegún la regla. - Una orden de cliente nuevo queda en la tabla con sus tres columnas.
- Sin nombre, con una sola de las partes nuevas o con una vacía: 422 con
INVALID_INPUT. - La migración. Las pruebas dejan en NULL las dos columnas nuevas de
todas las órdenes de los datos de ejemplo (son más de 1 000): así
estaban el día en que se expandió. Entonces:
- una de esas órdenes se lee con
GET /orders/:idy ya trae los tres campos, con la regla; - otra transacción toma una fila del medio de la tabla
(
SELECT … FOR UPDATE) y no la suelta; se lanzamake migrate, y en menos de 30 segundos tiene que haber al menos un lote confirmado (órdenes migradas) sin que la migración haya terminado ni fallado; - con la migración a medias, un cliente antiguo y uno nuevo compran: 201 los dos;
- la fila se suelta, y
make migratetermina con código 0 y ninguna orden queda sin migrar; todas quedaron partidas según la regla; make migratecorre otra vez y termina con código 0.
- una de esas órdenes se lee con
Las pruebas no miran cómo lo hicieron: no buscan Redis en su código ni un segundo pool. Cuentan consultas en el principal, miden tiempos contra la cota que ustedes declararon y apagan cosas.
Al terminar dejan Redis arriba y destruyen la réplica (pg-replica destroy). Si estaban trabajando con una, vuelvan a crearla.
5. Cómo se comprueba
make -f /work/projects/p3-lecturas/Makefile check
Corre make typecheck, make deps y make test de su repositorio y después
las pruebas públicas de P0 a P3. Tarda cerca de tres minutos; para trabajar
solo con las de esta entrega:
node --test --test-concurrency=1 /work/projects/p3-lecturas/p3.public.test.ts
make -f /work/projects/p3-lecturas/Makefile calibrate mide la máquina,
como en P2; aquí solo afecta a los dos umbrales del punto 8.
Sobre un P2 terminado y nada más, las pruebas de P3 terminan así (en la laptop de referencia):
P3 · documentos
✖ hay al menos nueve ADR (los de P0 a P2, y tres de esta entrega), con sus secciones
docs/adr/ tiene 6 ADR con nombre NNNN-titulo.md y esta entrega pide al menos 9 en total
✖ docs/measurements/p3.md tiene la máquina, el antes y el después
docs/measurements/p3.md: no existe
✖ docs/scenarios.md pasa el revisor, tiene al menos seis escenarios y declara la cota de desactualización
hay 5 escenarios: los de P0 a P2 son cinco, y esta entrega agrega el suyo
✔ los tres diagramas C4 siguen pasando el revisor
P3 · lecturas: réplica y cache
✔ API: GET /health responde ok
...
✖ el catálogo casi no le pregunta al principal: a lo más 10 de cada 100 lecturas llegan a su tabla events (5.0 s)
de 3176 lecturas del catálogo (GET /events y GET /events/1), 2717 terminaron en una consulta a la tabla events del principal: se pide que sean a lo más 10 %
· 3176 lecturas del catálogo en 5 s; consultas a la tabla events del principal en ese tiempo: 2717
✖ después de una compra, la disponibilidad del catálogo se pone al día dentro de la cota declarada (cinco veces)
docs/scenarios.md: falta la línea "- **Cota de desactualización:** N s" en el escenario de las lecturas
✖ 100 compradores y 4 reportes sin pausa durante 20 s: el catálogo mantiene su p95 (21.8 s)
unexpected_responses: se pedía rate==0 y salió 0.242
· factor de calibración 1.0 (la variable TINKUY_FACTOR): p95 de GET /events y de GET /events/:id < 300 ms
· p95 de GET /events 8 ms, de GET /events/:id 7 ms, de GET /reports/sales 6 ms; 739 órdenes pagadas, 392 reportes
✖ con la réplica 8 s atrasada: quien compra encuentra su orden de inmediato (200 compras) y la cota se sigue cumpliendo
docs/scenarios.md: falta la línea "- **Cota de desactualización:** N s" en el escenario de las lecturas
...
P3 · el contrato de buyer: name, givenName y familyName
✖ cliente nuevo: envía givenName y familyName, y recibe los dos y también name
{"error":{"code":"INVALID_INPUT","message":"buyer.name debe tener entre 1 y 80 caracteres"}}
422 !== 201
✖ cliente antiguo: envía name y lo recibe igual, con givenName y familyName ya separados
...
✔ sin nombre, o con solo una de las dos partes nuevas, la respuesta es 422
✖ make migrate llena las columnas nuevas por lotes, con una fila tomada y la venta abierta
no se pudo dejar en NULL buyer_given_name y buyer_family_name: en esta entrega las dos columnas existen y admiten NULL (error: column "buyer_given_name" of relation "orders" does not exist)
25 pruebas: 12 pasan, 13 fallan
Tres cosas para notar. El p95 del catálogo ya se cumple, como se dijo: lo
que falla en la carga es que la mitad de los compradores, los clientes
nuevos, reciben 422. De 3 176 lecturas, 2 717 llegaron al principal: es el
número que esta entrega tiene que llevar casi a cero. Y cuatro pruebas
fallan aquí porque falta declarar la cota. Con la cota declarada y sin
cambiar nada más, un P2 que lee todo del principal pasa tres de ellas (la
cota, sin Redis y sin réplica); la cuarta, la de la réplica atrasada, pide
además el contrato nuevo de buyer, porque la mitad de sus compradores son
clientes nuevos. Las cuatro tienen que seguir pasando cuando las lecturas se
muden.
6. Documentos
| Archivo | Contenido |
|---|---|
docs/adr/0007-… a 0009-… (o los números que sigan) |
Las decisiones de la sección 3 |
docs/scenarios.md |
El escenario de esta entrega, con la línea Cota de desactualización y la medida que el equipo se compromete a cumplir |
docs/measurements/p3.md |
## Máquina, ## Antes (sobre su P2: el resumen de k6 de catalog-busy.js y cuántas lecturas llegan al principal) y ## Después, con lo que mide cada parte de la cota (archivo de partida: templates/measurements.md) |
docs/c4/ |
Al día: la réplica y la cache son almacenes de datos nuevos, y hay flechas que antes no existían |
docs/data-ownership.md |
Al día, si agregaron tablas |
7. Pistas
- Midan primero. Con una réplica creada, corran
catalog-busy.jscontra su P2 y mirenpg_stat_user_tablesen el principal (puerto 5432) y en la réplica (5433) antes y después. Es su secciónAntes. - Una lista antes que código. Escriban todas las lecturas del sistema y,
al lado de cada una, quién la pide, qué tan viejo puede ser el dato y qué
pasa si es más viejo que eso. De esa tabla sale el primer ADR. Es el
laboratorio de la semana 10, y las tres maneras
de dar read-your-writes están en sus
apuntes, con
code/week-10/read-your-writes.ts. - De dónde sale la cota. No es un número que se elige: es una suma. Cada pieza que puede entregar un dato viejo aporta su parte. Si no pueden escribir la suma, todavía no conocen su cota.
- La réplica atrasada. Para provocar el retraso a mano:
psql -p 5433 -c "ALTER SYSTEM SET recovery_min_apply_delay = '8s'" -c "SELECT pg_reload_conf()", yALTER SYSTEM RESET recovery_min_apply_delaypara quitarlo.pg-replica lagmuestra cuánto falta. Pregúntense cómo se entera su sistema de que la réplica está atrasada, y qué hace mientras tanto. - La cache. Cache-aside, sus formas de invalidar, la carrera que queda y
la estampida están en los apuntes de la semana 11
y en
code/week-11/src/. Dos procesos de pruebas (el suyo ymake test) comparten el mismo Redis: piensen en sus claves. - Redis caído no es Redis lento.
svc kill redishace que la conexión falle de inmediato. Un cliente que encola los comandos hasta reconectar convierte esa falla en una espera. Miren qué hace el suyo (code/week-11/tools/redis-down.shlo muestra). - El contrato. Expandir, migrar y contraer, con una columna de otra
tabla, está en los
apuntes de la semana 9
y en
code/week-09/expand-contract/. El orden de los despliegues importa: ¿qué pasa si el código que lee las columnas nuevas sale antes de que existan? - La migración. Prueben la suya como la prueba pública: en una terminal,
psql tinkuy,BEGINySELECT id FROM orders WHERE id = 650 FOR UPDATE; en otra,make migrate; en una tercera, cuenten las filas que faltan.
8. Fuera de alcance
- Failover. Si el principal cae, nadie promueve la réplica. Vale decir en el ADR qué seguiría respondiendo.
- Más de una réplica, y sharding. La semana 11 lo estudia; Tinkuy no lo necesita todavía.
- Contraer. Ni quitar
buyer.namede la API ni borrarbuyer_name. - Más de un proceso de Tinkuy. Sigue corriendo un solo
make start. Si su cache vive en la memoria del proceso, el ADR dice qué pasaría con dos. - La pasarela. Sacarla del pedido es P4; que falle, P5.