---
name: wait_for_port
kind: function
lang: bash
domain: infra
version: "1.0.0"
purity: impure
signature: "wait_for_port(host: string, port: int, timeout_seconds: int, interval_seconds: int) -> int"
description: "Hace polling TCP a host:puerto hasta que acepte conexiones o agote el timeout. Util para esperar a que un servicio (DB, API, container) este listo antes de ejecutar pasos siguientes."
tags: [tcp, wait, poll, port]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: host
    desc: "Hostname, IP o DNS del servicio a esperar (ej: localhost, 192.168.1.10, db.internal)"
  - name: port
    desc: "Puerto TCP a sondear (1-65535)"
  - name: timeout_seconds
    desc: "Tiempo maximo de espera en segundos antes de abortar. Default 30"
  - name: interval_seconds
    desc: "Intervalo en segundos entre intentos de conexion. Default 1"
output: "Exit 0 e imprime 'OK host:port (Ns)' en stdout cuando el puerto acepta conexiones. Exit 1 con mensaje TIMEOUT en stderr si se agota el tiempo. Exit 2 si el puerto es invalido. Exit 3 si el host esta vacio."
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/infra/wait_for_port.sh"
---

## Ejemplo

```bash
source bash/functions/infra/wait_for_port.sh

# Esperar PostgreSQL con timeout de 60s
wait_for_port localhost 5432 60

# Esperar Redis con intervalo de 2s
wait_for_port 192.168.1.10 6379 30 2

# Uso en pipeline de deploy
wait_for_port localhost 8080 45 && curl http://localhost:8080/health
```

## Notas

Detecta al inicio si `nc` esta disponible. Si no, usa el builtin `/dev/tcp` de bash (disponible en bash >= 3.0, no requiere herramientas externas).

Metodos en orden de prioridad:
1. `nc -z -w 2 <host> <port>` — netcat con timeout de 2s por intento
2. `exec 3<>/dev/tcp/<host>/<port>` — bash builtin TCP, no requiere nc

Cada intento fallido imprime `. waiting host:port elapsed=Ns` en stderr para visibilidad en logs de CI/CD.

Complementa `wait_for_http_bash_infra` (HTTP/HTTPS): esta funcion opera a nivel TCP puro, util cuando el servicio no expone HTTP o cuando se quiere verificar la capa de red antes de la aplicacion.

Codigos de salida:
- 0: puerto disponible
- 1: timeout agotado
- 2: puerto invalido (no numerico o fuera de 1-65535)
- 3: host vacio
---
