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

   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 :

   cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
   node unlock-utxos.mjs
   

   Ou directement avec 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:

   // 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:

   // 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:

   // 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

# 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:

   # 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:

   sudo systemctl restart anchorage-api
   

3. Déverrouiller les UTXOs dans la base de données:

   cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
   node unlock-utxos.mjs
   

4. Vérifier la récupération:

   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:

   sudo journalctl -u anchorage-api | grep "Mutex acquisition timeout"
   

2. Requêtes d'ancrage:

   sudo journalctl -u anchorage-api | grep "Anchor request received"
   

3. UTXOs verrouillés:

   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)