ADR 0003 — Por qué HTTP/2 sobre QUIC para el transporte del túnel de Cloudflare¶
Estado: aceptada Fecha: 2026-08 (ventana del incidente documentado abajo)
TODO (fase 2+): expandir la narrativa; el contexto/decisión ya están fundamentados en un incidente real, solo falta pulir la redacción y agregar los datos de validación completos.
Contexto¶
cloudflared (el proceso que abre el túnel hacia Cloudflare) usaba
QUIC (UDP) como protocolo de transporte por defecto para sus 4
conexiones hacia el edge de Cloudflare. Una de esas conexiones sufría
fallos recurrentes de "control stream" cada 2-6 minutos, causando
504 Gateway Timeout intermitentes en todos los subdominios detrás
del túnel (Gitea, Argo CD, la tienda, etc.), no solo uno.
Diagnóstico completo en el playbook del incidente.
Opciones consideradas¶
| Opción | A favor | En contra |
|---|---|---|
| QUIC (default) | Menor latencia teórica, multiplexing sin head-of-line blocking | Sensible a NAT/firewall doméstico; causaba el 504 intermitente real |
| HTTP/2 sobre TCP | Estable en redes domésticas con NAT agresivo | Ligeramente más latencia teórica que QUIC |
Decisión¶
Forzar TUNNEL_TRANSPORT_PROTOCOL=http2 en la configuración del
contenedor cloudflared, en vez de dejar el default (QUIC/UDP).
Consecuencias¶
- Se eliminaron los
504intermitentes — validado con curl en loop contragitea.cruzcloud.net: ~0.37–0.4s de latencia estable por 24+ minutos sin un solo error. - Se renuncia a la ventaja teórica de latencia de QUIC, aceptable en un lab doméstico donde la estabilidad importa más que microsegundos.
- Si en el futuro cambia el hardware de red (router, NAT) podría valer la pena revisar si QUIC vuelve a ser viable — no hay una razón de fondo para excluirlo para siempre, solo evidencia de que falló en esta red concreta.