# Monitoreo HetrixTools

## Propósito

Este endpoint permite que HetrixTools valide el estado básico de la aplicación desde fuera de la infraestructura.

El diseño actual prioriza:

- responder con texto plano simple
- validar que Laravel pueda consultar una tabla real de la base de datos
- verificar round-trip de cache
- verificar disponibilidad del disk público para uploads
- verificar que `public/storage` apunte al target correcto
- exponer el detalle de checks sólo en modo diagnóstico con secreto
- no exponer detalles internos cuando algo falla
- evitar cachear el resultado del monitoreo
- no depender de keywords específicas del proveedor

## Endpoint

`GET /healthcheck`

## Permisos y roles

No requiere autenticación.

Debe ser público porque HetrixTools necesita consultarlo desde sus propios nodos de monitoreo.

## Output

### Respuesta saludable

Sin secreto:

```text

```

Con secreto válido:

```text
db: OK
cache: OK
storage: OK
storage_link: OK
```

Status code: `200 OK`

### Respuesta no saludable

Sin secreto:

```text

```

Con secreto válido:

```text
db: X (QueryException)
cache: X (CacheMismatch)
storage: X (StorageUnavailable)
storage_link: X (LinkInvalid)
```

Status code: `503 Service Unavailable`

## Configuración recomendada en HetrixTools

- URL: `https://TU-DOMINIO/healthcheck`
- Expected status code: `200`
- Keyword: dejar vacío
- Frecuencia: `1 minuto`, si el plan lo permite
- Confirmar caída después de `2` o `3` fallos consecutivos para reducir falsos positivos

## Modo diagnóstico

Si definís un secreto en configuración, podés pedir detalle manualmente:

```text
GET /healthcheck?secret=TU_SECRETO
```

La clave recomendada es `services.healthcheck.secret`, alimentada desde `HEALTHCHECK_SECRET` para que CI/CD pueda inyectarla sin tocar código.

Este parámetro no cambia el criterio de salud del endpoint. Sólo habilita la impresión del resumen técnico de checks para una revisión manual o una herramienta interna:

- sin `secret`: body vacío, el monitor usa sólo `200/503`
- con `secret` válido: imprime el detalle `db`, `cache`, `storage` y `storage_link`
- con `secret` inválido: vuelve al comportamiento público y no imprime nada

Usá este modo sólo para diagnóstico manual o tooling interno. Al viajar en query string, el secreto puede aparecer en logs de proxies, balanceadores o historiales de herramientas si no controlás bien ese camino.

## Comportamiento de negocio

1. HetrixTools ejecuta un `GET` contra el endpoint.
2. El backend ejecuta una lectura mínima sobre la tabla real `admins`.
3. Ejecuta un round-trip efímero de cache.
4. Verifica que el disk público esté disponible para escritura.
5. Verifica que el link `public/storage` exista y apunte al target configurado.
6. Sin secreto válido, la respuesta no imprime detalle y el monitor usa sólo `200/503`.
7. Con secreto válido, la respuesta arma un listado simple por chequeo, por ejemplo `db: OK`.
8. Si falla alguno, registra la excepción en logs internos, devuelve `503` y sólo expone un error resumido en modo diagnóstico.

## Notas de seguridad

- El endpoint no devuelve host, credenciales, driver, stack trace ni mensaje de excepción.
- El modo público no imprime checks ni errores.
- El modo diagnóstico sólo expone el nombre lógico del chequeo y un error resumido de alto nivel.
- No se loguea payload de usuario porque el endpoint no recibe datos.

## Notas de performance

- La consulta de base usa `select id from admins limit 1` a través de `exists()`.
- El chequeo de cache escribe y elimina una key efímera.
- El chequeo de storage valida el root del disk `public` sin listar archivos ni leer contenidos.
- El chequeo de `storage_link` compara el symlink público con el target configurado en `filesystems.links`.
- La respuesta usa `Cache-Control: no-store, no-cache, must-revalidate` para evitar que proxies oculten caídas reales.

## Cómo correr los tests relacionados

Desde `copetrol-api-and-public`:

```bash
php8.1 artisan test --filter=HealthcheckTest
```