anchorage_layer_simple/fixKnowledge/api-anchorage-mutex-timeout-blocked.md

# Correction: Mutex bloqué causant des timeouts dans l'API d'ancrage

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

## Problème

L'API d'ancrage Bitcoin ne répondait plus correctement. Toutes les requêtes d'ancrage échouaient avec des erreurs de timeout de mutex après 180 secondes (3 minutes).

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

### Symptômes

- **Erreurs répétées:** Des centaines d'erreurs `Mutex acquisition timeout after 180000ms` dans les logs
- **UTXOs verrouillés:** 22 UTXOs restaient verrouillés dans la base de données (`is_locked_in_mutex = 1`)
- **API non fonctionnelle:** Les requêtes d'ancrage échouaient systématiquement
- **Blocage du mutex:** Le mutex était bloqué depuis une requête d'ancrage à 12:29:40 qui n'avait jamais libéré le mutex

### Impact

- **Indisponibilité:** L'API d'ancrage ne pouvait plus traiter de nouvelles requêtes
- **UTXOs inutilisables:** 22 UTXOs étaient verrouillés et non disponibles pour de nouvelles transactions
- **Requêtes en attente:** Toutes les nouvelles requêtes attendaient le timeout de 3 minutes avant d'échouer

## Root cause

Une requête d'ancrage reçue à 12:29:40 (`test-deploy-1769599785`) a acquis le mutex mais s'est bloquée avant d'atteindre le bloc `finally` qui libère le mutex. Le mutex est resté bloqué indéfiniment, empêchant toutes les requêtes suivantes de s'exécuter.

**Causes possibles:**
1. **Appel RPC Bitcoin bloqué:** Un appel RPC vers Bitcoin Core n'a jamais répondu (timeout ou blocage réseau)
2. **Opération asynchrone non résolue:** Une Promise n'a jamais été résolue ou rejetée
3. **Erreur non gérée:** Une erreur s'est produite avant d'atteindre le bloc `finally`

**Code concerné:**
- `api-anchorage/src/bitcoin-rpc.js` : Méthode `createAnchorTransaction()` ligne 230
- Le mutex est acquis ligne 232 avec `await this.acquireUtxoMutex()`
- Le mutex devrait être libéré dans le bloc `finally` ligne 908-914, mais si l'opération se bloque avant, le `finally` n'est jamais atteint

## Correctifs

### Solution immédiate (appliquée)

1. **Redémarrage du service:** Redémarrage forcé du service `anchorage-api` pour libérer le mutex en mémoire
   ```bash
   sudo systemctl restart anchorage-api
   ```

2. **Déverrouillage des UTXOs dans la base de données:** Le redémarrage libère le mutex en mémoire, mais les UTXOs restent verrouillés dans la base de données. Il faut les déverrouiller manuellement :
   ```bash
   cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
   node unlock-utxos.mjs
   ```
   
   Ou directement avec SQL :
   ```sql
   UPDATE utxos SET is_locked_in_mutex = 0 WHERE is_locked_in_mutex = 1;
   ```

3. **Vérification:** Après redémarrage et déverrouillage, l'API répond correctement et les UTXOs sont disponibles

### Solutions préventives à implémenter

1. **Timeout sur les appels RPC Bitcoin:** Ajouter des timeouts explicites sur tous les appels RPC pour éviter les blocages indéfinis
2. **Libération forcée du mutex:** Implémenter un mécanisme de libération automatique du mutex après un certain délai même si l'opération est en cours
3. **Monitoring des opérations longues:** Logger les opérations qui prennent plus de 30 secondes pour identifier les blocages potentiels
4. **Health check amélioré:** Vérifier l'état du mutex dans le health check et signaler si des UTXOs sont verrouillés depuis trop longtemps

## Modifications

### Fichiers concernés

- `api-anchorage/src/bitcoin-rpc.js` : Méthode `createAnchorTransaction()` et gestion du mutex
- `api-anchorage/src/routes/anchor.js` : Gestion des erreurs et timeouts

### Modifications recommandées (à implémenter)

1. **Ajouter des timeouts sur les appels RPC:**
   ```javascript
   // Dans bitcoin-rpc.js, ajouter des timeouts sur tous les appels RPC
   const rpcCallWithTimeout = async (method, params, timeoutMs = 30000) => {
     return Promise.race([
       this.client[method](...params),
       new Promise((_, reject) => 
         setTimeout(() => reject(new Error(`RPC timeout: ${method}`)), timeoutMs)
       )
     ]);
   };
   ```

2. **Libération automatique du mutex:**
   ```javascript
   // Dans createAnchorTransaction, ajouter un timer de sécurité
   const mutexTimeout = setTimeout(() => {
     logger.error('Mutex held for too long, forcing release', { hash });
     releaseMutex();
   }, 300000); // 5 minutes max
   
   try {
     // ... opération ...
   } finally {
     clearTimeout(mutexTimeout);
     releaseMutex();
   }
   ```

3. **Déverrouillage automatique des UTXOs:**
   ```javascript
   // Script de maintenance pour déverrouiller les UTXOs verrouillés depuis plus de 10 minutes
   // À exécuter périodiquement via cron
   ```

## Modalités de déploiement

### Vérification de l'état actuel

```bash
# Vérifier que le service est actif
sudo systemctl status anchorage-api

# Vérifier que l'API répond
curl http://localhost:3010/health

# Vérifier les UTXOs verrouillés
curl http://localhost:3010/api/anchor/locked-utxos

# Vérifier les logs récents
sudo journalctl -u anchorage-api -n 50 --no-pager
```

### En cas de nouveau blocage

1. **Identifier le problème:**
   ```bash
   # Vérifier les UTXOs verrouillés
   curl http://localhost:3010/api/anchor/locked-utxos
   
   # Vérifier les logs pour identifier la requête bloquée
   sudo journalctl -u anchorage-api --since "10 minutes ago" | grep "Anchor request"
   ```

2. **Redémarrer le service:**
   ```bash
   sudo systemctl restart anchorage-api
   ```

3. **Déverrouiller les UTXOs dans la base de données:**
   ```bash
   cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
   node unlock-utxos.mjs
   ```

4. **Vérifier la récupération:**
   ```bash
   sleep 3
   curl http://localhost:3010/health
   curl http://localhost:3010/api/anchor/locked-utxos
   # Le count doit être 0
   ```

## Modalités d'analyse

### Logs à surveiller

1. **Erreurs de timeout de mutex:**
   ```bash
   sudo journalctl -u anchorage-api | grep "Mutex acquisition timeout"
   ```

2. **Requêtes d'ancrage:**
   ```bash
   sudo journalctl -u anchorage-api | grep "Anchor request received"
   ```

3. **UTXOs verrouillés:**
   ```bash
   curl http://localhost:3010/api/anchor/locked-utxos | jq '.count'
   ```

### Métriques à surveiller

- **Nombre d'UTXOs verrouillés:** Doit être 0 en temps normal
- **Durée des opérations d'ancrage:** Ne devrait pas dépasser 30 secondes
- **Erreurs de timeout:** Ne devrait pas se produire en fonctionnement normal

### Alertes recommandées

- **UTXOs verrouillés > 5:** Alerte warning
- **UTXOs verrouillés > 10:** Alerte critique
- **Timeout de mutex:** Alerte critique immédiate

## Pages affectées

- `api-anchorage/src/bitcoin-rpc.js` : Gestion du mutex et des timeouts
- `api-anchorage/src/routes/anchor.js` : Gestion des erreurs
- `fixKnowledge/api-anchorage-mutex-timeout-blocked.md` : Documentation (nouveau)