89 lines
5.2 KiB
Markdown
89 lines
5.2 KiB
Markdown
# Integraciones HTTP — T11
|
|
|
|
El worker utiliza `RegisteredWorkerActions`: `INVOKE_INTEGRATION` invoca HTTP y
|
|
`REGISTER_DOCUMENT` verifica metadatos y guarda una referencia bajo fencing.
|
|
`NO_OP` existe exclusivamente como utilidad de simulación y no está registrado
|
|
en Spring ni en el worker; la publicación continúa rechazándolo.
|
|
|
|
## Configuración de despliegue
|
|
|
|
Se necesitan dos archivos confiables, fuera de los eventos/definiciones editables:
|
|
|
|
- `FLOW_CATALOG_PATH`: contratos JSON Schema, efectos, perfiles/versiones y políticas documentales.
|
|
- `INTEGRATION_ROUTES_PATH`: endpoint y límites para cada combinación exacta de integración, contrato, perfil y versión.
|
|
|
|
Los archivos por defecto en `config/` tienen registros vacíos: no habilitan llamadas.
|
|
Los ejemplos de `examples/integrations/` describen un protocolo local propuesto,
|
|
no contratos confirmados de proveedores. Sus dominios `.invalid` son marcadores.
|
|
Copiar/adaptar ambos archivos, mantener todas las versiones usadas por solicitudes
|
|
vigentes y configurar las rutas antes de habilitar `WORKER_ENABLED=true`.
|
|
Cambiar un default no modifica las versiones fijadas al publicar. No sustituir
|
|
el significado de una versión existente: crear otra versión/tupla.
|
|
|
|
Compose conserva un único servicio y PostgreSQL externo. Monta `./config:/app/config:ro`;
|
|
la ruta predeterminada dentro del contenedor es `/app/config/integration-routes.json`.
|
|
Los tokens se referencian por nombre de variable con `tokenEnvironment`.
|
|
Declarar explícitamente esa variable en el entorno del servicio Docker (un valor
|
|
en el .env de Compose no se transmite automáticamente al contenedor). No guardar
|
|
el token en los JSON, los flujos ni los eventos. Cadena vacía permite un endpoint
|
|
sin bearer cuando el contrato de despliegue lo requiera.
|
|
|
|
## Protocolo y límites
|
|
|
|
- POST JSON con inputs resueltos por el worker, validados contra el contrato.
|
|
- Headers: Idempotency-Key estable por ejecución/acción, X-Correlation-Id,
|
|
X-Integration-Profile y X-Profile-Version cuando corresponda; bearer opcional.
|
|
- HTTPS; HTTP solo loopback con perfil Spring `local` o `test`. Sin redirecciones,
|
|
userinfo, query o fragment en la URL.
|
|
- connectMs positivo; timeoutMs cubre headers y cuerpo completo, máximo 30 s y
|
|
menor que el lease. maxBytes limita memoria antes de superar 256 KiB.
|
|
- Respuesta JSON objeto, UTF-8 estricto, sin claves duplicadas ni coerción de
|
|
strings a números. Decimales conservan precisión.
|
|
- outputMappings mapea campos superiores de salida a JSON Pointers de la
|
|
respuesta. Vacío significa identidad. La salida normalizada debe cumplir schema.
|
|
- Contratos inline: no se resuelven referencias remotas desde el worker.
|
|
|
|
Un 2xx válido con `found=false` o `status=INVALID` es éxito técnico y resultado
|
|
de negocio negativo. Un 404 es error salvo `notFoundOutput` explícito, permitido
|
|
solo para contratos READ_ONLY; ese resultado también se valida. No habilitar esa
|
|
traducción sin confirmar el contrato real.
|
|
|
|
Timeout/429/500/502/503/504 son transitorios; con NON_IDEMPOTENT_WRITE se considera
|
|
efecto incierto. Una salida inválida tras escritura también es incierta. Los
|
|
códigos internos no exponen cuerpo remoto, URL o token. La clasificación no
|
|
garantiza idempotencia del proveedor: solo declarar IDEMPOTENT_WRITE si existe
|
|
garantía contractual para la clave enviada.
|
|
|
|
**T12:** el worker programa RETRY_WAIT para fallos transitorios seguros, con
|
|
backoff/jitter y Retry-After acotados, hasta el máximo publicado de tres intentos
|
|
por acción. Conserva checkpoints; efectos inciertos requieren conciliación.
|
|
Consultar RECONCILIATION.md para el endpoint y la semántica de A03.
|
|
|
|
## Documentos
|
|
|
|
REGISTER_DOCUMENT consulta el protocolo fijo `DOCUMENTS_METADATA` contrato `1`,
|
|
sin perfil, con documentId/requestId/businessScope. El servicio documental debe
|
|
responder identidad de documento/solicitud/ámbito, tipo, identificador de storage,
|
|
MIME, tamaño entero, checksum SHA-256 hexadecimal y scanStatus=CLEAN. El handler
|
|
compara pertenencia y política; no confía en metadatos enviados por el cliente.
|
|
|
|
La inserción en document_reference y el checkpoint SUCCEEDED comparten transacción
|
|
y fencing, con bloqueo de solicitud antes de ejecución. Una referencia existente
|
|
solo se reutiliza si coincide completamente. Fallo SQL revierte ambas escrituras.
|
|
No se descargan/suben archivos ni se ejecuta un antivirus: se verifica el dictamen
|
|
del servicio documental confiable. T13 completa eventos disponibles y tareas de front.
|
|
|
|
## Verificación reproducible
|
|
|
|
`mvnw.cmd test` ejecuta mocks HTTP loopback sin PostgreSQL ni proveedores reales.
|
|
`mvnw.cmd clean verify -Pmigration-tests-external` agrega PostgreSQL real utilizando
|
|
MIGRATION_TEST_DB_URL/USER/PASSWORD en el proceso y base exclusiva de pruebas.
|
|
Sin ese perfil, verify utiliza Testcontainers y requiere Docker.
|
|
|
|
HttpIntegrationTest prueba transporte y contratos; RegisterDocumentTest verifica
|
|
metadatos y carga de ejemplos; HttpIntegrationIT conecta publicación, API de
|
|
solicitudes/eventos, worker, HTTP y PostgreSQL con rollback inducido.
|
|
Los estados START/END del fixture representan los destinos de A01/A02; los flujos
|
|
demostrativos con nombres funcionales corresponden a T14. No hay integración real
|
|
aprobada de clientes, documentos, buró o Keycloak ni despliegue en server02:8787.
|