# 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](../playbooks/incidente-504-gitea-tunnel.md).

## 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 `504` intermitentes — validado con curl en loop
  contra `gitea.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.