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 /events y GET /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 /events y de GET /events/:id menor 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 NN segundos de atraso, con N≤5N \le 5 declarado por el equipo, también con la réplica 8 segundos atrasada; 0 respuestas distintas de 200 en GET /orders/:id justo 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 db deja 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 db lo borra.
  • La verdad sigue en el principal. Las pruebas leen ahí qué asiento está vendido y qué orden existe.

Las lecturas

  • GET /orders/:id de una orden que POST /orders acaba 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 /events y GET /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, en docs/scenarios.md, en una línea que las pruebas leen:

    - **Cota de desactualización:** 3 s

    Tiene 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 /orders acepta buyer en dos formas:

    Cliente Envía
    Nuevo { "email": "…", "givenName": "Luz María", "familyName": "Condori Huamán" }
    Antiguo { "email": "…", "name": "Rosa Quispe Mamani" }

    givenName y familyName tienen entre 1 y 80 caracteres cada uno. Si llega alguno de los dos, se usa la forma nueva (y name, 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 /orders y GET /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 name a las partes: givenName es lo que va antes del primer espacio y familyName, el resto (vacío si no hay espacio). De las partes a name: givenName, un espacio y familyName.

  • En la base de datos, la tabla orders gana dos columnas de texto, buyer_given_name y buyer_family_name, que en esta entrega admiten NULL. La columna buyer_name se queda. Toda orden nueva escribe las tres.

  • make migrate llena 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. Respeta TINKUY_DB, como make start.

  • La fase de contraer (quitar buyer.name y buyer_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:

  1. 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.
  2. 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.
  3. 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

  1. docs/adr/ tiene al menos nueve ADR en total, con sus secciones.
  2. docs/measurements/p3.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, tiene al menos seis escenarios y declara la cota de desactualización.
  4. 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.

  1. La API sigue igual: las diez pruebas de siempre, ahora con réplica y Redis.

  2. El catálogo casi no le pregunta al principal. 20 visitantes piden GET /events y GET /events/:id (del evento en venta con más asientos libres) durante 5 segundos, sin ninguna compra. Las pruebas cuentan, en pg_stat_user_tables del principal, las consultas que leyeron la tabla events en ese tiempo: tienen que ser a lo más 10 % de las lecturas hechas. Todas responden 200, y se completan al menos 400.

  3. La cota. Cinco veces: una compra de dos asientos (201) y, desde ese momento, GET /events y GET /events/:id cada 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.

  4. El escenario con carga. catalog-busy.js con 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)<300
    http_req_duration{name:GET /events/:id} p(95)<300
    unexpected_responses (una compra 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. Al terminar se comprueban las invariantes de la venta de P2.

  5. 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 piden GET /orders/:id: tiene que responder 200, con la orden paid y las mismas entradas. Y con la réplica todavía atrasada, la prueba de la cota (punto 7), tres veces.

  6. 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és svc start redis, y lo mismo otra vez.

  7. Sin réplica. Igual que el punto 10, con pg-replica stop y pg-replica start.

El contrato de buyer

  1. Un cliente nuevo compra con givenName y familyName: 201, y la respuesta y GET /orders/:id traen los tres campos.
  2. Un cliente antiguo compra con name: 201, y recibe name tal como lo envió, con givenName y familyName según la regla.
  3. Una orden de cliente nuevo queda en la tabla con sus tres columnas.
  4. Sin nombre, con una sola de las partes nuevas o con una vacía: 422 con INVALID_INPUT.
  5. 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/:id y 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 lanza make 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 migrate termina con código 0 y ninguna orden queda sin migrar; todas quedaron partidas según la regla;
    • make migrate corre otra vez y termina con código 0.

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.js contra su P2 y miren pg_stat_user_tables en el principal (puerto 5432) y en la réplica (5433) antes y después. Es su sección Antes.
  • 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()", y ALTER SYSTEM RESET recovery_min_apply_delay para quitarlo. pg-replica lag muestra 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 y make test) comparten el mismo Redis: piensen en sus claves.
  • Redis caído no es Redis lento. svc kill redis hace 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.sh lo 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, BEGIN y SELECT 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.name de la API ni borrar buyer_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.