Files et workers

Le backend sort de la requête HTTP les traitements lents ou à risque : envoi des emails, actions on-chain différées (frappe des POAP, versement de la cagnotte, remboursements) et lecture continue de la blockchain. Les deux premiers passent par des files BullMQ dans Redis ; la lecture de la chaîne et le keeper sont des boucles à intervalle fixe. Tous ces traitements peuvent tourner dans le process de l'API ou dans un process worker séparé. Le principe du repli sans Redis est justifié dans l'ADR 0002.

#Vue d'ensemble

backend/src/workers/index.ts regroupe les trois workers BullMQ (startWorkers, closeWorkers). L'indexeur et le keeper sont démarrés par startChainServices, seulement en mode onchain.

#Options communes des jobs

backend/src/queues/queue.options.ts définit les options appliquées par défaut aux trois files :

Un job qui lève UnrecoverableError n'est pas retenté. Chaque fin de job incrémente queue_jobs_total{queue, status} avec completed ou failed.

Les files utilisent le client ioredis partagé de backend/src/config/redis.config.ts, avec le préfixe de clés par défaut de BullMQ : les clés sont bull:emails-queue:*, bull:ledger-queue:* et bull:chain-actions:*, sans REDIS_KEY_PREFIX. Deux environnements qui partagent la même base Redis partagent donc leurs files.

#File emails-queue

await enqueueEmail({
  to: user.email,
  subject: 'Votre code de connexion - BlockLucky',
  templateName: 'otp-code',
  variables: { CODE: code, EXPIRES_MINUTES: '10' },
});

Le producteur ajoute un job send-email et renvoie { queued: true, jobId }. Si la file n'existe pas ou si l'ajout échoue, l'email est envoyé immédiatement dans la requête et la fonction renvoie { queued: false }. Le worker vérifie que to et templateName sont présents (sinon UnrecoverableError) puis appelle emailService.sendTemplateEmail.

Le job accepte un champ facultatif replyTo, transmis à Nodemailer comme adresse de réponse. Seul le message au support (POST /user/support) le renseigne, avec l'email du citoyen.

#File ledger-queue

enqueueLedgerTransaction({ userId, amount, actionType, description, operation }) met en file un crédit ou un débit d'EtherPoints, exécuté un par un par le worker (concurrence 1) pour sérialiser les écritures. Une AppError de statut inférieur à 500 (solde insuffisant, compte introuvable) devient une UnrecoverableError.

#File chain-actions

Les actions on-chain qui découlent d'un événement du contrat sont mises en file par l'indexeur, pour ne pas bloquer l'indexation et pour bénéficier des nouvelles tentatives. Le détail fonctionnel est sur la page File d'actions on-chain.

Comme le jobId est conservé 14 jours après un échec définitif, il faut supprimer le job échoué pour pouvoir remettre la même action en file. Voir Runbooks blockchain.

#Indexeur et keeper

L'indexeur fait un premier passage dès le démarrage. Un passage en cours bloque le suivant dans le même process. Le keeper prend le verrou Redis chain:keeper-lock (durée de KEEPER_INTERVAL_MS, 5 secondes au moins) et le relâche à la fin de chaque passage : deux process ne demandent pas le tirage en même temps. Le fonctionnement détaillé est dans Indexeur d'événements et Keeper du tirage.

#Où tournent les workers

Le process worker ignore RUN_WORKERS : il démarre toujours ses workers et, en mode onchain, l'indexeur et le keeper. Les événements temps réel qu'il produit sont relayés vers l'API par Redis (voir Relais depuis le worker).

#Sondes du process worker

Le worker ouvre un serveur HTTP minimal sur PORT + 1 (2054 avec la configuration par défaut) :

Le service Docker worker utilise /health/live sur le port 2054 comme sonde de santé ; ce port n'est pas publié sur l'hôte. Si startWorkers ne crée aucun worker, le process journalise Aucun worker démarré : Redis est requis pour le process worker et s'arrête avec le code 1.

#Fonctionnement sans Redis

Le client ioredis abandonne la reconnexion après trois tentatives espacées de 200 à 600 ms (retryStrategy renvoie null à la quatrième). Une fois abandonnée, ioredis ne rétablit plus la connexion de lui-même : si Redis redevient disponible, le process reste en repli mémoire jusqu'à son redémarrage, et /health/deep signale redis: down. Après un incident Redis, redémarrez l'API et le worker.

#Arrêt

À l'arrêt, closeWorkers attend la fin des jobs en cours de chaque worker (worker.close()), puis les files sont fermées avec les autres ressources (voir Arrêt propre). Un job interrompu par l'arrêt forcé est repris par BullMQ au redémarrage suivant, comme un job bloqué.