Implémenter une file de travaux asynchrones avec BullMQ et Redis

Une application Node.js ne devrait pas bloquer une requête HTTP pendant l’envoi d’un e-mail, la génération d’un rapport, le redimensionnement d’une image ou l’appel à une API externe. Ces opérations peuvent être confiées à une file de travaux afin que le serveur réponde rapidement, tandis qu’un processus indépendant les exécute en arrière-plan.

BullMQ fournit une abstraction moderne pour créer cette architecture avec Redis. La bibliothèque gère la mise en attente, les tentatives, les délais, la concurrence et le suivi des traitements. Redis joue le rôle de stockage rapide et partagé entre les producteurs de tâches et les workers.

Comprendre l’architecture de traitement

Une file de travaux repose généralement sur trois composants. Le producteur ajoute un job à une queue, le worker récupère les jobs disponibles et exécute la logique métier, tandis que Redis conserve les états nécessaires : en attente, actif, terminé ou échoué. Plusieurs workers peuvent utiliser la même queue et répartir la charge.

Cette séparation découple le cycle de vie de la requête et celui du traitement. Une API peut ainsi retourner immédiatement un identifiant de suivi, même si le travail prend plusieurs minutes. Pour les systèmes déployés dans le cloud, cette approche s’intègre facilement à une architecture cloud composée de conteneurs, de services indépendants et d’une mise à l’échelle horizontale.

BullMQ fonctionne avec Redis ou une solution compatible. Il est préférable de réserver une instance Redis correctement dimensionnée pour les files de production, avec authentification, chiffrement réseau lorsque c’est nécessaire et politique de persistance adaptée à la criticité des jobs.

Installer BullMQ et configurer Redis

Dans un projet TypeScript, l’installation peut se faire avec les paquets suivants :

npm install bullmq ioredis
npm install -D typescript tsx @types/node

Créez ensuite une configuration Redis partagée par la queue et les workers. Le paramètre maxRetriesPerRequest: null est recommandé pour les workers BullMQ, car ils doivent conserver leur connexion lors de certaines opérations longues.

// src/redis.ts
import IORedis from "ioredis";

export const connection = new IORedis({
  host: process.env.REDIS_HOST ?? "127.0.0.1",
  port: Number(process.env.REDIS_PORT ?? 6379),
  password: process.env.REDIS_PASSWORD,
  maxRetriesPerRequest: null,
});

La queue représente le point d’entrée des tâches. Le nom du job permet ensuite au worker de distinguer plusieurs types de traitements, tandis que les données transportent uniquement les informations utiles, comme un identifiant de fichier ou de commande.

// src/queues/image.queue.ts
import { Queue } from "bullmq";
import { connection } from "../redis";

export const imageQueue = new Queue("image-processing", {
  connection,
  defaultJobOptions: {
    attempts: 3,
    backoff: {
      type: "exponential",
      delay: 1000,
    },
    removeOnComplete: 1000,
    removeOnFail: 5000,
  },
});

Ajouter des travaux de manière fiable

Une route Express peut publier un job après avoir validé la requête. Il est conseillé de transmettre un identifiant métier plutôt que des données volumineuses. Le worker pourra récupérer le fichier ou l’enregistrement concerné dans une base de données.

import { imageQueue } from "./queues/image.queue";

const job = await imageQueue.add(
  "resize",
  {
    imageId: "img_842",
    width: 1200,
    height: 800,
  },
  {
    jobId: "resize-img_842-1200x800",
  }
);

console.log(`Travail créé : ${job.id}`);

Le jobId personnalisé aide à éviter les doublons lorsqu’un client répète une requête après un délai d’attente. Cette protection doit être complétée par une logique idempotente dans le worker : relancer le même traitement ne doit pas créer un état incohérent. Une transaction, une clé d’unicité ou une vérification de statut peut être nécessaire selon le domaine.

BullMQ permet aussi de planifier l’exécution avec delay, de créer des travaux récurrents et de définir des priorités. Ces options doivent être utilisées avec discernement : une accumulation massive de jobs différés ou prioritaires peut consommer rapidement la mémoire Redis.

Exécuter les jobs avec un worker

Le worker écoute la queue et reçoit chaque job disponible. La fonction de traitement doit lever une erreur en cas d’échec réel. BullMQ pourra alors appliquer le nombre de tentatives et le délai configurés.

// src/workers/image.worker.ts
import { Worker } from "bullmq";
import { connection } from "../redis";

const worker = new Worker(
  "image-processing",
  async (job) => {
    console.log(`Traitement du job ${job.id}`);

    const { imageId, width, height } = job.data;

    await resizeImage(imageId, width, height);

    await job.updateProgress(100);
    return { imageId, status: "processed" };
  },
  {
    connection,
    concurrency: 5,
  }
);

worker.on("completed", (job) => {
  console.log(`Job terminé : ${job.id}`);
});

worker.on("failed", (job, error) => {
  console.error(`Échec du job ${job?.id} : ${error.message}`);
});

La valeur concurrency autorise plusieurs traitements simultanés dans un même processus. Elle doit correspondre aux ressources disponibles. Une opération principalement liée aux entrées-sorties peut supporter une concurrence élevée, alors qu’un calcul lourd en CPU risque de saturer le processus Node.js. Pour ces calculs, des workers séparés ou des processus enfants sont souvent plus adaptés. Certaines méthodes algorithmiques, comme la recherche par dichotomie, peuvent réduire le coût d’un traitement avant même son placement dans la file.

Gérer les erreurs, les délais et les résultats

Les tentatives automatiques conviennent aux erreurs temporaires : interruption d’un service tiers, dépassement de délai réseau ou indisponibilité momentanée d’une base. Elles ne corrigent pas une erreur de validation ou un fichier définitivement absent. Le code du worker doit donc différencier les erreurs récupérables des erreurs permanentes.

Le backoff exponentiel espace progressivement les nouvelles tentatives. Pour une intégration externe, ajoutez aussi un délai maximal, un mécanisme de limitation de débit et une stratégie de mise en quarantaine. Les jobs définitivement échoués peuvent être conservés pour analyse, puis supprimés après une période définie afin d’éviter une croissance illimitée de Redis.

Les événements BullMQ permettent de suivre l’état des traitements avec QueueEvents. Une interface d’administration peut afficher la progression, le nombre de jobs en attente et les dernières erreurs. Dans une architecture de recherche ou d’intelligence artificielle, une zone dédiée à l’IA peut également bénéficier de files séparées pour les inférences longues, les embeddings et les tâches de préparation de données.

Superviser et sécuriser la file

Une file de travaux doit être observable comme n’importe quel composant critique. Mesurez la profondeur de la queue, l’âge du job le plus ancien, le taux d’échec, la durée moyenne et le nombre de tentatives. Des alertes peuvent signaler une file qui grandit continuellement ou un worker qui ne consomme plus de tâches.

Redis étant au centre du système, sa capacité mémoire et sa politique d’éviction doivent être surveillées. Une comparaison des solutions de cache distribué aide à distinguer les usages de cache, de coordination et de file persistante. Pour BullMQ, évitez de considérer Redis comme un simple cache jetable lorsque les jobs représentent des opérations métier importantes.

Les données placées dans un job peuvent contenir des informations sensibles. Ne stockez pas de secret, de jeton d’accès ou de document complet dans Redis. Utilisez des identifiants, chiffrez les connexions, limitez les permissions et appliquez une durée de conservation cohérente. Pensez aussi à fermer proprement les workers lors du déploiement afin que les jobs actifs puissent terminer ou être repris sans interruption brutale.

const stop = async () => {
  await worker.close();
  process.exit(0);
};

process.on("SIGTERM", stop);
process.on("SIGINT", stop);

Déployer plusieurs workers sans doublons

En production, le producteur et les workers peuvent être déployés séparément. Il est possible d’augmenter le nombre de réplicas du worker lorsque la longueur de la file augmente, sans redimensionner l’API. Chaque instance écoute la même queue et BullMQ distribue les jobs disponibles.

Cette élasticité ne dispense pas d’une conception robuste. Un job peut être exécuté à nouveau après une panne ou une perte de connexion. Les écritures externes doivent donc être idempotentes, les transactions doivent être courtes et les appels non répétables doivent disposer d’une clé de déduplication. Les traitements CPU intensifs peuvent être isolés dans une queue spécifique afin de ne pas retarder les tâches urgentes.

Pour tester l’ensemble, simulez des erreurs Redis, des timeouts, des arrêts de worker et des jobs mal formés. Vérifiez que les retries restent limités, que les échecs sont visibles et que le redémarrage reprend correctement les travaux actifs. Cette validation transforme une simple file technique en véritable infrastructure de traitement asynchrone.

Commencez par une queue spécialisée, un worker observable et quelques règles d’idempotence. Ajoutez ensuite les retries, la planification et la montée en charge selon les besoins réels de votre application Node.js.