# Correction: Health check anchor-api HTTP 503 – causes et remédiation

**Date:** 2026-01-28
**Auteur:** Équipe 4NK

## Problème

Le health check de l’API d’ancrage renvoie HTTP 503, avec des messages du type « Health check a échoué (HTTP 503) » ou « L’API d’ancrage n’est pas accessible », sans indiquer la cause précise.

**Machine concernée :** 192.168.1.105 (bitcoin)  
**Domaine externe :** https://anchorage.certificator.4nkweb.com  
**Service :** anchorage-api (port 3010)

### Impact

- Monitoring ou dashboard marquent l’API comme indisponible sans distinguer « processus arrêté » et « pas prêt » (Bitcoin déconnecté, UTXOs verrouillés).
- L’utilisateur ne voit pas la raison du 503 (Bitcoin, mutex, UTXOs stale) pour agir.

## Root cause

1. **Causes du 503 côté api-anchorage** (`src/routes/health.js`) :
   - **GET /health** : 503 si Bitcoin RPC non connecté ou si `checkConnection()` lève.
   - **GET /health/detailed** : 503 si Bitcoin non connecté, ou UTXOs verrouillés depuis > 10 min (`stale_locks > 0`), ou plus de 10 UTXOs verrouillés.

2. **Causes côté consommateur** :
   - Le dashboard proxy renvoyait 200 avec un body réduit au lieu de transmettre le 503 et le body complet → le client ne voyait pas la raison.
   - Aucun endpoint de liveness (processus vivant) → impossible de distinguer « service down » et « service up mais not ready ».

## Correctifs

### 1. api-anchorage : endpoint de liveness

- **GET /health/live** : retourne toujours 200 tant que le processus tourne (sans vérifier Bitcoin ni mutex).
- Usage : monitoring / load-balancer pour ne pas considérer le service comme mort quand il renvoie 503 (readiness).
- Exclusion de l’auth API Key pour `/health/live` dans `server.js`.

### 2. signet-dashboard : propagation du 503 et du body

- Option **preserveStatus** dans `makeHttpRequest` : retourne `{ statusCode, body }` pour préserver le code HTTP et le body JSON.
- Route **GET /api/anchor/health/detailed** : appelle l’API d’ancrage avec `preserveStatus: true`, puis répond avec `res.status(result.statusCode).json(result.body)`.
- Effet : en cas de 503, le client reçoit 503 et le détail (bitcoin.connected, mutex, utxos, stale_locks).

### 3. signet-dashboard (hash-list.html) : affichage de la raison

- Si la réponse est 503 et que le body n’a pas la structure health (mutex, utxos, bitcoin), affichage d’un message d’erreur incluant `health.error` ou `health.message` et le code 503.
- Si la réponse est 503 mais que le body contient le health complet, affichage du panneau health normal avec mention « 503 - voir détails ci-dessous » pour l’état général.
- En cas d’exception (réseau, parse), affichage de « L’API d’ancrage n’est pas accessible » avec le message d’erreur.

## Modifications

**Motivations :**
- Rendre le 503 explicable (Bitcoin, mutex, UTXOs) et permettre une remédiation ciblée.
- Séparer liveness (processus up) et readiness (prêt à ancrer).

**Root causes :**
- 503 défini par l’API sans toujours être propagé avec son body ; pas de liveness.

**Correctifs :**
- GET /health/live dans api-anchorage ; propagation 503 + body dans le dashboard ; affichage de la raison dans hash-list.

**Pages affectées :**
- `api-anchorage/src/routes/health.js` (GET /health/live)
- `api-anchorage/src/server.js` (exclusion auth /health/live)
- `signet-dashboard/src/server.js` (preserveStatus, route health/detailed)
- `signet-dashboard/public/hash-list.html` (affichage erreur 503 et raison)

## Modalités de remédiation en production

Quand le health check renvoie 503 :

1. **Vérifier liveness** : `curl -s https://anchorage.certificator.4nkweb.com/health/live` → 200 si le processus tourne.
2. **Lire la cause** : `curl -s https://anchorage.certificator.4nkweb.com/health/detailed` (ou via le dashboard) et regarder :
   - `bitcoin.connected === false` → vérifier Bitcoin Core (RPC) sur 192.168.1.105.
   - `utxos.stale_locks > 0` ou `utxos.locked > 10` → déverrouiller les UTXOs (voir ci-dessous).
3. **Service arrêté** : sur la machine 192.168.1.105, `systemctl status anchorage-api` puis `sudo systemctl restart anchorage-api` si besoin.
4. **UTXOs verrouillés** : sur la machine hébergeant api-anchorage, exécuter `node unlock-utxos.mjs` dans le répertoire api-anchorage, ou utiliser le bouton « Déverrouiller les UTXOs » depuis le dashboard (hash-list) si l’API est de nouveau joignable.

## Modalités d’analyse

- Consulter les logs du service : `journalctl -u anchorage-api -n 100`.
- Vérifier le RPC Bitcoin : `bitcoin-cli -rpcconnect=... getblockchaininfo`.
- Appeler GET /health/detailed et interpréter `ok`, `bitcoin.connected`, `utxos.locked`, `utxos.stale_locks`.