Un endpoint Node.js qui génère un export PDF de deux mille lignes, envoie un email de confirmation et notifie un webhook externe, tout ça de façon synchrone dans le handler HTTP, répond en huit secondes quand tout va bien et time out quand le service d'email est lent. Le symptôme visible est une API "parfois lente", mais la cause réelle est un mélange de deux responsabilités qui n'ont rien à faire dans le même cycle requête-réponse : répondre vite à l'utilisateur, et exécuter un traitement qui peut prendre du temps ou échouer pour des raisons hors du contrôle de l'API.
Pourquoi une file d'attente plutôt qu'un simple async
Lancer le traitement lourd en arrière-plan avec un setImmediate ou une promesse non attendue règle le symptôme de latence, mais crée un problème pire : si le processus Node redémarre (déploiement, crash, scaling horizontal) pendant le traitement, le job est perdu sans trace, sans retry, sans visibilité. Une file d'attente persistante résout ce problème en séparant la production du job (rapide, dans le handler HTTP) de sa consommation (dans un worker séparé, avec retry et persistance).
BullMQ s'appuie sur Redis comme backend de persistance et de coordination. Chaque job est stocké dans une structure Redis dédiée tant qu'il n'est pas traité, ce qui garantit qu'il survit à un redémarrage du worker.
// queue.js
import { Queue } from 'bullmq';
import { connection } from './redis.js';
export const exportQueue = new Queue('export-report', { connection });
// api/routes/export.js
app.post('/reports/:id/export', async (req, res) => {
const job = await exportQueue.add('generate-pdf', {
reportId: req.params.id,
userId: req.user.id,
}, {
attempts: 3,
backoff: { type: 'exponential', delay: 5000 },
});
res.status(202).json({ jobId: job.id });
});
Le handler HTTP répond en quelques millisecondes avec un 202 Accepted et un identifiant de job, pas avec le résultat final. C'est un changement de contrat d'API qui doit être assumé côté client : le front doit interroger un endpoint de statut ou écouter un WebSocket, pas attendre une réponse synchrone.
Le worker : isoler le traitement lent
// worker.js
import { Worker } from 'bullmq';
import { connection } from './redis.js';
import { generatePdf } from './services/pdf.js';
const worker = new Worker('export-report', async (job) => {
const { reportId, userId } = job.data;
const pdfBuffer = await generatePdf(reportId);
await uploadToStorage(pdfBuffer, `reports/${reportId}.pdf`);
await notifyUser(userId, reportId);
}, {
connection,
concurrency: 5,
});
worker.on('failed', (job, err) => {
console.error(`Job ${job.id} failed after ${job.attemptsMade} attempts`, err);
});
Le worker tourne dans un processus séparé du serveur HTTP, ce qui permet de le scaler indépendamment (plus de workers si la file grossit, sans toucher au nombre d'instances API) et d'éviter qu'un pic de jobs lourds ne consomme la boucle d'événements qui doit aussi répondre aux requêtes HTTP.
Le piège de la concurrence et des ressources partagées
Le paramètre concurrency contrôle combien de jobs un worker traite en parallèle. Une erreur fréquente est de le régler trop haut sans tenir compte des ressources externes limitées : une génération de PDF qui ouvre un navigateur headless (Puppeteer) consomme facilement 200 à 400 Mo de mémoire par instance. Avec concurrency: 20 sur un worker limité à 1 Go de RAM, le processus OOM-kill après quelques jobs simultanés, et BullMQ marque ces jobs comme bloqués (stalled) plutôt qu'échoués, ce qui complique le diagnostic.
Le bon réglage se mesure, pas se devine : surveiller la mémoire du worker sous charge réelle, puis fixer concurrency en fonction de la ressource la plus contrainte (mémoire, connexions à une API externe avec un rate limit, connexions à la base de données).
const worker = new Worker('export-report', processJob, {
connection,
concurrency: 5,
limiter: {
max: 10,
duration: 1000, // au plus 10 jobs démarrés par seconde
},
});
Le limiter est distinct de concurrency : il borne le débit de démarrage des jobs, utile quand le traitement appelle une API externe avec un quota (un service d'envoi d'email limité à N requêtes par seconde, par exemple), indépendamment du nombre de jobs traités en parallèle.
Idempotence et retry : le piège silencieux
BullMQ retente automatiquement un job qui lève une exception, selon la stratégie attempts/backoff configurée. Ce comportement est correct uniquement si le traitement est idempotent : si generatePdf réussit mais que notifyUser échoue au tour précédent, le retry complet régénère le PDF et peut envoyer l'email de notification en double.
async function processJob(job) {
const { reportId, userId } = job.data;
let pdfUrl = job.data.pdfUrl;
if (!pdfUrl) {
const pdfBuffer = await generatePdf(reportId);
pdfUrl = await uploadToStorage(pdfBuffer, `reports/${reportId}.pdf`);
await job.updateData({ ...job.data, pdfUrl });
}
await notifyUser(userId, reportId, pdfUrl);
}
En persistant le résultat intermédiaire (pdfUrl) dans les données du job via updateData, un retry après l'échec de notifyUser ne régénère pas le PDF : il reprend exactement où le job s'est arrêté. C'est le même principe que la reprise sur erreur d'une transaction distribuée, appliqué à l'échelle d'un seul job.
Déduplication avec jobId
Quand le producteur peut être appelé plusieurs fois pour la même opération logique (un clic double, un retry côté client), fixer un jobId déterministe empêche la duplication au niveau de la file elle-même :
await exportQueue.add('generate-pdf', { reportId }, {
jobId: `export-${reportId}`,
});
BullMQ refuse silencieusement d'ajouter un job dont l'identifiant existe déjà dans la file (tant qu'il n'est pas terminé), ce qui évite de traiter deux fois la même demande sans logique de déduplication applicative supplémentaire.
Observabilité : savoir ce qui se passe dans la file
Une file d'attente sans supervision devient une boîte noire où les jobs échouent silencieusement. BullMQ expose des événements (completed, failed, stalled) et une API pour interroger l'état de la file (getJobCounts), que Bull Board ou un dashboard maison peuvent afficher :
const counts = await exportQueue.getJobCounts('waiting', 'active', 'failed', 'delayed');
// { waiting: 3, active: 2, failed: 1, delayed: 0 }
Surveiller la taille de la file waiting dans le temps est aussi le signal le plus direct pour savoir s'il faut ajouter des workers : une file qui grossit en continu, même sans erreur, signifie que le débit de production dépasse le débit de consommation.
Quand BullMQ ne suffit plus
BullMQ convient très bien pour des volumes de l'ordre de dizaines de milliers de jobs par jour avec une latence de traitement de l'ordre de la seconde à la minute. Pour du traitement de flux à très haut débit (événements en continu, des dizaines de milliers de messages par seconde) ou des besoins de garantie de livraison exactement-une-fois à l'échelle d'un système distribué multi-services, un système de messagerie dédié (Kafka, RabbitMQ avec des accusés de réception transactionnels) devient plus adapté, parce que Redis en tant que backend de file n'offre pas les mêmes garanties de partitionnement et de rétention qu'un vrai log de messages distribué.
À retenir
Déporter un traitement lent dans une file d'attente change le contrat de l'API (réponse asynchrone avec statut interrogeable, pas résultat synchrone) et déplace la responsabilité de fiabilité du handler HTTP vers le worker. Le réglage de concurrency doit être mesuré contre la ressource la plus contrainte, pas deviné, et chaque job doit être écrit comme idempotent dès le départ, parce que le retry automatique est une garantie, pas une option.
