P4 · Pagos como servicio
Cubre: semanas 12 y 13 · En equipo
Tinkuy creció y ahora tiene un equipo de pagos. Ese equipo cambia su código más seguido que nadie (un medio nuevo, una regla del procesador), es el único que debería tocar datos de tarjetas, y cada vez que despliega tiene que desplegar el monolito entero. Y hay una cuenta pendiente desde P2: si el proceso muere entre tomar los asientos y cerrar la orden, esos asientos quedan tomados para siempre, y si la pasarela responde con un error nadie sabe si cobró.
En esta entrega los pagos salen del monolito a un servicio propio, con su base de datos, y la compra deja de ser una transacción: pasa a ser una saga.
El punto de partida es su propio P3.
1. El requisito que llega
Pagos se despliega y se cae sin tumbar la venta
- Atributo de calidad: disponibilidad
- Fuente del estímulo: el equipo de pagos, que despliega una versión nueva de su servicio, o una falla que mata un proceso
- Estímulo: el servicio de pagos se detiene 6 segundos en medio de una venta; o muere con cobros en vuelo; o muere el servidor con compras a medio hacer; o NATS se cae y vuelve
- Artefacto: la compra (
POST /orders), el servicio de pagos, la mensajería y las dos bases de datos - Entorno: en operación normal, con la pasarela respondiendo en 80 ms; el monolito y el servicio de pagos son dos procesos, cada uno con su base de datos
- Respuesta: nadie recibe un error; la compra responde como siempre si el cobro llega a tiempo, y si no, responde que la orden está en curso; cuando lo que se cayó vuelve, las órdenes en curso se completan solas
- Medida de la respuesta: 0 respuestas 5xx;
POST /ordersresponde en menos de 7 s, llegue o no el cobro; toda orden en curso llega apaido afaileda más tardar 20 s después de que todo vuelve a estar arriba; 0 asientos vendidos sin entrada o con dos entradas; exactamente 1 cobro aprobado ejecutado en la pasarela por cada orden pagada, y 0 por las demás
La última medida es la que cuesta. “Exactamente un cobro” con dos procesos que pueden morir por separado, un broker que entrega cada mensaje al menos una vez y un comprador que reintenta cuando no recibe respuesta: ninguna de esas piezas da exactamente una vez. El sistema completo tiene que darlo.
2. Lo que hay que saber de la pasarela
Una pasarela real no cobra dos veces el mismo pedido si uno se lo pide bien. Desde esta entrega, la pasarela de las pruebas tampoco:
POST /chargesacepta la cabeceraIdempotency-Key. El primer pedido con una clave se procesa normalmente. Un pedido posterior con la misma clave recibe la misma respuesta del primero y no se cobra otra vez; si el primero todavía está en curso, espera su respuesta.- Un pedido que la pasarela no pudo atender (respondió 5xx) no deja nada guardado: repetirlo con la misma clave es un intento nuevo.
- Sin la cabecera, la pasarela se comporta como siempre: cada pedido es un cobro.
La pasarela de make gateway (tools/fake-gateway.ts) no conoce la
cabecera. Para trabajar en esta entrega usen la de las pruebas, que además
anota todo lo que recibe:
GATEWAY_PORT=4000 node /work/projects/lib/recording-gateway.ts
curl -s localhost:4000/_charges | jq '.charges[] | {reference: .request.reference, status, replayed}'
curl -s -X POST localhost:4000/_config -H 'content-type: application/json' -d '{"latencyMs": 3000}'
curl -s -X POST localhost:4000/_config -H 'content-type: application/json' -d '{"failNext": 3}'
replayed: true quiere decir que ese pedido repitió una clave y recibió la
respuesta del primero: no es un cobro. Las pruebas cuentan los cobros
aprobados con replayed: false.
3. Lo que está fijo
Dos procesos, dos bases de datos
| Monolito | Servicio de pagos | |
|---|---|---|
| Arranca con | make start |
make payments |
| Puerto | PORT (3000) |
PAYMENTS_PORT (3001): solo GET /health, que responde 200 { "status": "ok" } |
| Base de datos | TINKUY_DB (tinkuy) |
PAYMENTS_DB (tinkuy_payments) |
| Habla con la pasarela | no | sí: GATEWAY_URL |
| Código | src/ |
una carpeta propia, fuera de src/ |
- Los dos respetan
NATS_URL(por omisiónnats://127.0.0.1:4222) yTINKUY_LOG, y toman el usuario de PostgreSQL dePGUSER, como hasta ahora. - Ninguno se conecta a la base de datos del otro. Las pruebas corren cada proceso con un usuario que solo puede entrar a la suya.
- Ninguno importa código del otro. Lo que compartan (el contrato de los
mensajes, por ejemplo) va en una tercera carpeta, que no importa nada de
los otros dos.
docs/services.mddice cuál es cada carpeta. - Solo el servicio de pagos llama a la pasarela. Las pruebas le dan al
monolito una
GATEWAY_URLdonde no hay nadie. make dbcrea las dos bases de datos con sus esquemas. Los procesos no crean ni cambian tablas al arrancar (los usuarios de las pruebas no pueden hacerlo).make dbtambién deja la mensajería sin restos de los datos anteriores, o el sistema descarta los mensajes de órdenes que no existen.- Cada proceso arranca aunque el otro, NATS o la pasarela no estén, y sigue vivo si se caen.
La mensajería
- El monolito y el servicio de pagos se hablan por NATS JetStream, en
streams cuyo nombre empieza con
TINKUY_. Una compra publica al menos dos mensajes: el pedido de cobro y su resultado. - La referencia de cada cobro en la pasarela (
reference) esorden-<id de la orden>, como hasta ahora. Las pruebas la usan para saber de qué orden es cada cobro.
La compra
Una orden nace pending y termina en paid o en failed. Los dos son
finales.
Respuesta de POST /orders |
Cuándo |
|---|---|
201, con la orden paid y sus entradas |
El cobro se aprobó antes de que venciera la espera |
402 PAYMENT_DECLINED |
La pasarela rechazó el cobro antes de que venciera la espera. La orden queda failed y sus asientos libres |
202, con la orden pending y tickets: [] |
Todavía no hay resultado. El cuerpo tiene la misma forma que el del 201 |
| 409, 404, 422 | Como siempre, y antes de crear nada |
- La espera.
POST /ordersespera el resultado del cobro lo que el equipo decida y responde siempre en menos de 7 segundos. Las pruebas de las entregas anteriores siguen esperando 201 y 402 con el sistema sano, y una de ellas (P2, punto 9) con la pasarela demorando 2 segundos: su espera tiene que cubrir eso. Lo mismo vale para sus scripts de k6 de P0, quechecksigue corriendo: con el sistema sano tienen que seguir recibiendo 201. GET /orders/:idde una ordenpendingresponde 200 constatus: "pending"ytickets: []. Quien recibió 202 pregunta ahí.- Los asientos de una orden
pendingno están en venta: otra orden que los pida recibe 409. - Se completa sola. Con el monolito, el servicio de pagos, NATS y la
pasarela arriba, toda orden
pendingllega apaid(con sus entradas) o afailed(con sus asientos libres) en a lo más 20 segundos, sin que nadie la empuje. Vale también para las que quedaronpendingmientras algo estaba caído, contando desde que volvió. - Una falla de la pasarela no es un rechazo. Si la pasarela responde 5xx
o no responde, la orden no pasa a
failed: el cobro se intenta de nuevo. Solo undeclinedde la pasarela rechaza una orden. - La tabla
paymentsdetinkuysigue ahí, con una filaapprovedpor cada orden pagada y unadeclinedpor cada rechazada: las invariantes de P2 la leen. Qué más guarde el servicio de pagos en su base de datos es decisión del equipo. - El correo de confirmación de cada orden pagada queda en
notificationsantes de 15 segundos, una sola vez por orden.
Idempotency-Key en POST /orders
- Cabecera opcional, de 1 a 100 caracteres. Sin ella, todo es como antes.
- Todos los pedidos con la misma clave y el mismo contenido son una sola
orden: el primero la crea, y los demás, lleguen a la vez o después,
reciben esa misma orden (el mismo
order.id) con el estado que tenga: 201 si ya está pagada, 202 si siguepending, 402 si fue rechazada. Nunca una segunda orden, nunca un segundo cobro, nunca un 409 por sus propios asientos. - La misma clave con otro contenido: 422 con
INVALID_INPUT.
Lo que no se mueve
- Los medios de pago siguen siendo plug-ins dentro de
src/, como en P1 (su prueba agrega un medio copiando un archivo ahí, y tiene que seguir pasando). El monolito valida los datos de pago y calcula la comisión al recibir el pedido; qué viaja hasta el servicio de pagos para que pueda cobrar es decisión del equipo. - Todo lo fijo de las entregas anteriores: la réplica, la cache y su cota,
el contrato de
buyer,make migrate.
503 con PAYMENTS_UNAVAILABLE. En esta entrega la respuesta a una falla
es 202. La entrega siguiente va a permitir además que, bajo una falla
sostenida, el sistema rechace compras de entrada con 503 y el código
PAYMENTS_UNAVAILABLE, sin crear la orden. Dos pruebas de esta entrega (la
venta de 12 segundos y la de NATS) ya toleran esa respuesta, para que sigan
pasando entonces. No hace falta implementarla ahora, y una compra aislada
con el servicio de pagos detenido tiene que responder 202.
4. Lo que deciden
Al menos tres ADR nuevos, cada uno con al menos dos alternativas comparadas:
- Quién conoce la secuencia de la compra: orquestación o coreografía, y dónde vive el estado de la saga.
- Los pasos de la saga y sus compensaciones: qué hace cada transacción
local, en qué orden, qué se deshace cuando un paso posterior falla, y
cuánto espera
POST /orders. - Las garantías de entrega y la idempotencia: cómo sale un mensaje de cada base de datos, qué pasa cuando llega dos veces a cada consumidor, y qué hace que el cobro ocurra una sola vez.
5. Lo que comprueban las pruebas públicas
check corre las pruebas de P0 a P3 y después p4.public.test.ts. Desde
esta entrega, todas las pruebas (también las de P0 a P3) levantan los dos
procesos: make start y make payments, en los puertos 3100 y 3101.
Documentos
docs/adr/tiene al menos doce ADR en total, con sus secciones.docs/measurements/p4.mdtieneMáquina,AntesyDespuésy al menos un bloque de código.docs/scenarios.mdpasa el revisor y tiene al menos siete escenarios.- Los diagramas C4 pasan el revisor, y el de contenedores tiene al menos
dos contenedores de Node.js, un almacén de datos que nombra
tinkuy_payments, y NATS. docs/services.mdtiene las líneasServicio de pagosyCódigo compartido(una carpeta que existe, fuera desrc/, oninguno).
Dos procesos, dos bases de datos
- Imports. Con dependency-cruiser: ningún archivo de
src/importa algo de la carpeta del servicio de pagos, ninguno de esa carpeta importa algo desrc/, y el código compartido no importa de ninguna de las dos. - Aislamiento. El sistema se levanta con el monolito como el usuario
tinkuy_check_monolith(que solo puede conectarse atinkuy), el servicio de pagos comotinkuy_check_payments(solo atinkuy_payments) y el monolito con unaGATEWAY_URLmuerta. Una compra con tarjeta responde 201 y una con tarjeta rechazada, 402; a la pasarela le llegan esos dos cobros, el primero conreferenceigual aorden-<id>y el monto de la orden;GET /healthdel servicio de pagos responde 200. - Mensajes. Hay al menos un stream
TINKUY_…, y una compra hace crecer en al menos 2 la cantidad de mensajes publicados en ellos.
La compra como saga
- La API sigue igual con todo sano: las diez pruebas de siempre.
- El servicio de pagos detenido. Una compra responde 202 en menos de 7
segundos, con la orden
pendingy sin entradas;GET /orders/:iddice lo mismo; otra orden por uno de sus asientos recibe 409; a la pasarela no le llegó nada. Se levanta el servicio: en menos de 20 segundos la orden estápaid, con sus entradas y un solo cobro aprobado ejecutado. - Un rechazo que llega tarde. Con la pasarela demorando 6 segundos,
una compra con una tarjeta que se rechaza responde 202. La orden termina
failed, sin entradas y con sus asientosavailable, y una compra nueva por esos asientos responde 201. - Diez pedidos con la misma clave, a la vez: todos responden 201 o 202
con el mismo
order.id; después, uno más responde 201 con esa orden y sus entradas. Una sola orden tiene esos asientos y la pasarela ejecutó un solo cobro aprobado. - La misma clave con otros asientos: 422. Y un pedido rechazado (402), repetido con su clave: 402 otra vez, con un solo cobro ejecutado.
- La pasarela falla tres veces (503) y después responde. La compra
responde 201 o 202 y la orden termina
paid. La pasarela recibió tres pedidos que respondió con 503 y ejecutó un solo cobro aprobado. - El servicio de pagos muere con ocho cobros en vuelo. Con la pasarela
demorando 3 segundos, ocho compras a la vez; cuando los ocho cobros
están en la pasarela,
kill -9al servicio de pagos. La pasarela los aprueba y nadie recibe la respuesta. El servicio vuelve: las ocho órdenes terminanpaiden menos de 20 segundos, cada una con exactamente un cobro aprobado ejecutado. - El servidor muere con ocho compras a medio hacer. Lo mismo, con
kill -9al monolito. Cuando vuelve, las ocho órdenes que alcanzó a registrar terminanpaid, con un cobro cada una. - Una venta de 12 segundos con 15 compradores, cada pedido con su
clave de idempotencia; a los 2 segundos muere el servicio de pagos y a
los 8 vuelve. Todas las respuestas son 201, 202, 402 o 409 (o 503 con
PAYMENTS_UNAVAILABLE), en menos de 7 segundos; al menos 20 % son 201 o 202, y hay algún 201 después de la vuelta. Todas las órdenes terminan en menos de 30 segundos. Se cumplen las invariantes de P2, hay exactamente un cobro aprobado ejecutado por cada orden pagada y ninguno por una orden que no lo esté. - NATS muere y vuelve (
svc kill nats,svc start nats). Sin NATS, cinco compras responden 202 (o 503 conPAYMENTS_UNAVAILABLE) en menos de 7 segundos yGET /eventsresponde 200. Cuando vuelve, las órdenes terminanpaiden menos de 20 segundos y una compra nueva vuelve a responder 201. - Al final: ninguna orden
pending, las invariantes de P2, y cada orden pagada con su correo ennotifications, uno solo.
Las pruebas no leen sus mensajes ni sus tablas nuevas: miran las respuestas, las nueve tablas de siempre y la libreta de la pasarela.
Al terminar dejan NATS arriba.
6. Cómo se comprueba
make -f /work/projects/p4-pagos/Makefile check
Corre make typecheck, make deps y make test de su repositorio y después
las pruebas públicas de P0 a P4. Tarda cerca de cuatro minutos; para trabajar solo
con las de esta entrega:
node --test --test-concurrency=1 /work/projects/p4-pagos/p4.public.test.ts
Sobre un P3 terminado y nada más, las pruebas de P4 terminan así (en la laptop de referencia):
P4 · documentos
✖ hay al menos doce ADR (los de P0 a P3, y tres de esta entrega), con sus secciones
docs/adr/ tiene 9 ADR con nombre NNNN-titulo.md y esta entrega pide al menos 12 en total
...
✖ los diagramas C4 pasan el revisor, y el de contenedores tiene los dos procesos, las dos bases de datos y NATS
docs/c4/containers.md: hay 1 contenedor(es) de Node.js y ahora son dos procesos (se reconocen por su columna Tecnología)
✖ docs/services.md dice dónde está el servicio de pagos y dónde el código compartido
docs/services.md: no existe
P4 · dos procesos, dos bases de datos
✖ el monolito no importa código del servicio de pagos, ni el servicio del monolito
docs/services.md: no existe
✖ cada proceso con un usuario que solo entra a su base de datos, y el servidor sin pasarela: la compra funciona
make db tiene que crear las bases de datos tinkuy y tinkuy_payments, y solo existe: tinkuy
✖ los mensajes pasan por streams de NATS JetStream cuyo nombre empieza con TINKUY_
el sistema no llegó a levantar
P4 · la compra como saga
✔ API: GET /health responde ok
...
✖ con el servicio de pagos detenido: 202 y pending; al volver, la orden queda pagada con un solo cobro
El Makefile del repositorio no tiene el objetivo payments
✖ un pago rechazado que llega tarde: la orden queda failed y sus asientos vuelven a la venta (6.0 s)
con la pasarela demorando 6 s, POST /orders respondió 402 {"error":{"code":"PAYMENT_DECLINED","message":"La pasarela rechazó el pago. No se hizo ningún cobro."}}
402 !== 202
✖ Idempotency-Key: diez pedidos con la misma clave son una sola orden y un solo cobro
un pedido con la clave respondió 409 {"error":{"code":"SEAT_NOT_AVAILABLE","message":"Ya no está disponible: asiento 7, 8"}}: se espera 201 (o 202)
...
✖ la pasarela falla tres veces seguidas (503) y después responde: la orden queda pagada con un solo cobro
POST /orders respondió 502 {"error":{"code":"GATEWAY_UNAVAILABLE","message":"La pasarela de pagos no pudo procesar el cobro"}}: una falla pasajera de la pasarela no es un error de quien compra
...
✖ el servidor muere con ocho compras a medio hacer: al volver, las ocho terminan y el estado es coherente (22.4 s)
las órdenes a medio hacer terminan cuando el servidor vuelve: pasaron 20 s y 8 de 8 órdenes siguen sin terminar (por ejemplo la 1322, en "pending")
...
✖ después de todo lo anterior: ninguna orden pending, ningún asiento perdido, un cobro aprobado por orden pagada y su correo (20.1 s)
todas las órdenes de este grupo terminan: pasaron 20 s y 8 de 356 órdenes siguen sin terminar (por ejemplo la 1322, en "pending")
28 pruebas: 10 pasan, 18 fallan
Las diez que pasan son las de la API: un P3 sano sigue respondiendo lo de
siempre. Lo demás falla por lo que falta, salvo una prueba que muestra lo
que hoy está mal: la del servidor que muere con ocho compras a medio hacer.
Esas ocho órdenes se quedaron en pending para siempre, con sus asientos
tomados y, del otro lado, ocho cobros aprobados en la pasarela. Es la cuenta
pendiente de P2, y es lo primero que conviene reproducir a mano.
7. Documentos
| Archivo | Contenido |
|---|---|
docs/adr/0010-… a 0012-… (o los números que sigan) |
Las decisiones de la sección 4. El segundo lleva la tabla de pasos y compensaciones (hay una de partida en templates/saga.md) |
docs/services.md |
Dónde vive cada proceso, cómo arranca y qué mensajes se envían (archivo de partida: templates/services.md) |
docs/scenarios.md |
El escenario de esta entrega, con las medidas que el equipo se compromete a cumplir |
docs/measurements/p4.md |
## Máquina, ## Antes y ## Después (archivo de partida: templates/measurements.md) |
docs/c4/ |
Al día: hay un proceso, una base de datos y un broker que antes no existían |
docs/data-ownership.md |
Al día con las tablas nuevas de tinkuy. Las de tinkuy_payments no van en la tabla (no son de ningún módulo de src/); digan en prosa cuáles son |
8. Pistas
- Dibujen primero la línea de tiempo. Los dos procesos, NATS y la pasarela en columnas; cada escritura y cada mensaje en su fila. Después marquen cada punto donde un proceso puede morir y contesten, para cada uno: qué quedó escrito, qué mensaje salió y quién retoma. El segundo ADR es ese dibujo.
- La semana 12 tiene las piezas: la saga con su orquestador (guía), la clave de idempotencia del lado de quien atiende y la outbox.
- La semana 13 tiene el laboratorio que más se parece a esta entrega:
outbox, relay y consumidor idempotente con NATS JetStream
(apuntes,
code/week-13/). Lean con cuidado cuándo confirma el consumidor: la reentrega de un mensaje sin confirmar ocurre cuando venceack_wait, y eso también vale para un consumidor que murió y volvió. Sus 20 segundos salen de ahí. - Exactly-once es un efecto, no una entrega. Para cada consumidor, pregúntense qué pasa si el mismo mensaje llega dos veces, y dos veces a la vez. La respuesta no tiene que ser la misma técnica en todos.
- El cobro es el efecto que no se puede deshacer. Miren los cuatro momentos en que el servicio de pagos puede morir alrededor del pedido a la pasarela, y qué sabe al volver en cada uno.
- El cliente de NATS se rinde. Por omisión intenta reconectar un número
limitado de veces y después cierra la conexión. Miren
maxReconnectAttemptsywaitOnFirstConnect, y qué hace su proceso si NATS no está al arrancar. - Dos sistemas en un mismo NATS. Su
make testy sumake startcomparten servidor. Si usan los mismos streams, las pruebas se comen los mensajes del sistema que tienen corriendo. - Para matar un proceso como lo hacen las pruebas:
pkill -9 -f payments(o el nombre de su archivo), y para NATS,svc kill nats.nats stream ls,nats consumer info <stream> <consumer>ypsql tinkuy -c 'SELECT status, count(*) FROM orders GROUP BY 1'dicen en qué quedó todo. - La latencia. Corran
sale-opening.jsde P2 antes y después: el cobro ahora da dos saltos por NATS, y el umbral de P2 sigue vigente. Si su relay solo mira la outbox cada cierto tiempo, ese tiempo se suma a cada compra.
9. Fuera de alcance
- La pasarela lenta o caída por mucho tiempo, timeouts y circuit breaker: P5. Aquí una falla de la pasarela solo se reintenta.
- Dead letter. Un mensaje que nunca se puede procesar se queda reintentando. Vale decir en el ADR qué harían.
- Devoluciones. La pasarela no las tiene; por eso el orden de los pasos importa.
- Avisarle a quien compra que su orden
pendingterminó (webhooks, eventos del servidor). ConsultaGET /orders/:id. - Varias instancias de cada proceso. Vale decir en el ADR qué pasaría con dos servicios de pagos leyendo del mismo consumer.
- Seguridad de los datos de tarjeta en los mensajes. Si viajan, díganlo en las consecuencias.