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 /orders responde en menos de 7 s, llegue o no el cobro; toda orden en curso llega a paid o a failed a 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 /charges acepta la cabecera Idempotency-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ón nats://127.0.0.1:4222) y TINKUY_LOG, y toman el usuario de PostgreSQL de PGUSER, 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.md dice cuál es cada carpeta.
  • Solo el servicio de pagos llama a la pasarela. Las pruebas le dan al monolito una GATEWAY_URL donde no hay nadie.
  • make db crea 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 db tambié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) es orden-<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 /orders espera 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, que check sigue corriendo: con el sistema sano tienen que seguir recibiendo 201.
  • GET /orders/:id de una orden pending responde 200 con status: "pending" y tickets: []. Quien recibió 202 pregunta ahí.
  • Los asientos de una orden pending no 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 pending llega a paid (con sus entradas) o a failed (con sus asientos libres) en a lo más 20 segundos, sin que nadie la empuje. Vale también para las que quedaron pending mientras 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 un declined de la pasarela rechaza una orden.
  • La tabla payments de tinkuy sigue ahí, con una fila approved por cada orden pagada y una declined por 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 notifications antes 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 sigue pending, 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:

  1. Quién conoce la secuencia de la compra: orquestación o coreografía, y dónde vive el estado de la saga.
  2. 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.
  3. 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

  1. docs/adr/ tiene al menos doce ADR en total, con sus secciones.
  2. docs/measurements/p4.md tiene 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 siete escenarios.
  4. 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.
  5. docs/services.md tiene las líneas Servicio de pagos y Código compartido (una carpeta que existe, fuera de src/, o ninguno).

Dos procesos, dos bases de datos

  1. Imports. Con dependency-cruiser: ningún archivo de src/ importa algo de la carpeta del servicio de pagos, ninguno de esa carpeta importa algo de src/, y el código compartido no importa de ninguna de las dos.
  2. Aislamiento. El sistema se levanta con el monolito como el usuario tinkuy_check_monolith (que solo puede conectarse a tinkuy), el servicio de pagos como tinkuy_check_payments (solo a tinkuy_payments) y el monolito con una GATEWAY_URL muerta. Una compra con tarjeta responde 201 y una con tarjeta rechazada, 402; a la pasarela le llegan esos dos cobros, el primero con reference igual a orden-<id> y el monto de la orden; GET /health del servicio de pagos responde 200.
  3. 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

  1. La API sigue igual con todo sano: las diez pruebas de siempre.
  2. El servicio de pagos detenido. Una compra responde 202 en menos de 7 segundos, con la orden pending y sin entradas; GET /orders/:id dice 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.
  3. 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 asientos available, y una compra nueva por esos asientos responde 201.
  4. 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.
  5. La misma clave con otros asientos: 422. Y un pedido rechazado (402), repetido con su clave: 402 otra vez, con un solo cobro ejecutado.
  6. 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.
  7. 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 -9 al servicio de pagos. La pasarela los aprueba y nadie recibe la respuesta. El servicio vuelve: las ocho órdenes terminan paid en menos de 20 segundos, cada una con exactamente un cobro aprobado ejecutado.
  8. El servidor muere con ocho compras a medio hacer. Lo mismo, con kill -9 al monolito. Cuando vuelve, las ocho órdenes que alcanzó a registrar terminan paid, con un cobro cada una.
  9. 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é.
  10. NATS muere y vuelve (svc kill nats, svc start nats). Sin NATS, cinco compras responden 202 (o 503 con PAYMENTS_UNAVAILABLE) en menos de 7 segundos y GET /events responde 200. Cuando vuelve, las órdenes terminan paid en menos de 20 segundos y una compra nueva vuelve a responder 201.
  11. Al final: ninguna orden pending, las invariantes de P2, y cada orden pagada con su correo en notifications, 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 vence ack_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 maxReconnectAttempts y waitOnFirstConnect, y qué hace su proceso si NATS no está al arrancar.
  • Dos sistemas en un mismo NATS. Su make test y su make start comparten 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> y psql tinkuy -c 'SELECT status, count(*) FROM orders GROUP BY 1' dicen en qué quedó todo.
  • La latencia. Corran sale-opening.js de 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 pending terminó (webhooks, eventos del servidor). Consulta GET /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.