Toidicode.com

Toidicode.com

BASIC TO ADVANCE

Bài 29: Queue với BullMQ trong NestJS

Tiếp tục với series, ở Bài 28 mail được gửi ngay trong process của API: process sập là mail mất. Bài này mình sẽ giới thiệu với mọi người về queue với BullMQ trong NestJS và chuyển việc gửi mail vào queue.

1. Queue là gì? BullMQ và Redis.

Queue (hàng đợi) lưu các việc cần làm (job). Producer đưa job vào queue; consumer (worker) lấy job ra xử lý. Job nằm trong Redis nên process sập vẫn còn, lỗi thì được thử lại.

NestJS có @nestjs/bullmq (12.0.2) bọc BullMQ (6.7.6); Bull cũ (@nestjs/bull) chỉ còn sửa lỗi. Redis dùng lại taskflow-redis và REDIS_URL từ Bài 27:

npm install @nestjs/bullmq bullmq ioredis

2. Cấu hình BullModule và đăng ký queue.

- src/app.module.ts (đoạn trích trong imports, sau CacheModule; import BullModule từ @nestjs/bullmq)

        // Kết nối Redis dùng chung cho mọi queue
        BullModule.forRootAsync({
            inject: [databaseConfig.KEY],
            useFactory: (database: ConfigType<typeof databaseConfig>) => ({
                connection: { url: database.redisUrl },
            }),
        }),

- src/notifications/mail-jobs.ts

export const MAIL_QUEUE = 'mail';

// Job chỉ chứa id, processor đọc lại dữ liệu mới nhất từ database
export interface WelcomeJob {
    userId: number;
}

export interface TaskAssignedJob {
    taskId: number;
    assigneeId: number;
}

- src/notifications/notifications.module.ts (đoạn trích trong imports; MailModule thêm retry: false vì queue lo thử lại, providers thêm MailProcessor)

        BullModule.registerQueue({
            name: MAIL_QUEUE,
            defaultJobOptions: {
                attempts: 5, // tổng số lần chạy, kể cả lần đầu
                // Chờ 5s, 10s, 20s, 40s trước mỗi lần thử lại
                backoff: { type: 'exponential', delay: 5_000 },
                removeOnComplete: { age: 24 * 3600, count: 1000 },
                // Job thất bại giữ 7 ngày để kiểm tra (age tính bằng giây)
                removeOnFail: { age: 7 * 24 * 3600 },
            },
        }),

Trong đó:

  • attempts mặc định là 1 (không thử lại). backoff kiểu exponential chờ delay * 2^(lần thử - 1) mili giây, kiểu fixed chờ đều.
  • Mặc định job xong hay lỗi đều nằm mãi trong Redis. Ở đây job thành công giữ 1 ngày (tối đa 1000), job thất bại giữ 7 ngày để kiểm tra.

3. Producer: đưa job vào queue.

- src/notifications/notifications.service.ts (không gửi mail nữa, chỉ thêm job)

import { InjectQueue } from '@nestjs/bullmq';
import { Injectable, Logger } from '@nestjs/common';
import type { Queue } from 'bullmq';
import {
    MAIL_QUEUE,
    type TaskAssignedJob,
    type WelcomeJob,
} from './mail-jobs.js';

@Injectable()
export class NotificationsService {
    private readonly logger = new Logger(NotificationsService.name);

    constructor(@InjectQueue(MAIL_QUEUE) private readonly mailQueue: Queue) {
        // Không có listener thì BullMQ in lỗi Redis ra console.error
        mailQueue.on('error', (error) => this.logger.error('Lỗi Redis', error));
    }

    // Gọi sau khi đã ghi database: chỉ đưa job vào queue, MailProcessor gửi sau
    sendWelcome(userId: number): void {
        this.enqueue('welcome', { userId } satisfies WelcomeJob);
    }

    sendTaskAssigned(taskId: number, assigneeId: number): void {
        this.enqueue('task-assigned', {
            taskId,
            assigneeId,
        } satisfies TaskAssignedJob);
    }

    // Không await: Redis chậm hay lỗi cũng không làm hỏng request đã ghi xong
    private enqueue(name: string, data: WelcomeJob | TaskAssignedJob): void {
        this.mailQueue.add(name, data).catch((error: unknown) => {
            this.logger.error(`Không đưa được job ${name} vào queue`, error);
        });
    }
}

add(name, data, options?) lưu job vào Redis dạng JSON (options ghi đè defaultJobOptions). Ai đọc được Redis là đọc được job, nên data chỉ chứa id, không có mật khẩu, token hay email.

Không await vì dữ liệu đã ghi xong: Redis tắt thì request vẫn thành công, job chờ trong bộ nhớ rồi được thêm khi Redis chạy lại. Nhưng chỉ chờ được khoảng 4 phút (ioredis thử tối đa 20 lần, maxRetriesPerRequest): lâu hơn thì add() báo MaxRetriesPerRequestError, job mất, chỉ còn dòng log lỗi; process sập lúc đó cũng mất job. Mail bắt buộc phải tới thì ghi thêm một bảng outbox trong cùng transaction với dữ liệu, rồi một tiến trình đọc bảng đó đưa vào queue. AuthService.register() gọi sendWelcome(user.id); TasksService thay notifyAssignee() bằng sendTaskAssigned(task.id, task.assigneeId) ở create(), update() (điều kiện như cũ).

Lưu ý: Với cache ở Bài 27, Redis tắt làm request ghi bị 408 dù đã lưu. Đổi createKeyv thành createKeyvNonBlocking (cùng @keyv/redis) thì lỗi trả về ngay, get() ra undefined.

4. Consumer: xử lý job bằng processor.

- src/notifications/mail.processor.ts (đoạn trích: thiếu welcome(), viết tương tự taskAssigned(), và @OnWorkerEvent('error') ghi log lỗi worker như listener 'error' của queue)

import { OnWorkerEvent, Processor, WorkerHost } from '@nestjs/bullmq';
import { Logger } from '@nestjs/common';
import { MailError, Mailer } from '@nestjs/mail';
import { type Job, UnrecoverableError } from 'bullmq';
import { PrismaService } from '../prisma/prisma.service.js';
import {
    MAIL_QUEUE,
    type TaskAssignedJob,
    type WelcomeJob,
} from './mail-jobs.js';
import { TaskAssignedMail } from './task-assigned.mail.js';
import { WelcomeMail } from './welcome.mail.js';

// Consumer của queue 'mail', xử lý tối đa 5 job cùng lúc
@Processor(MAIL_QUEUE, { concurrency: 5 })
export class MailProcessor extends WorkerHost {
    private readonly logger = new Logger(MailProcessor.name);

    constructor(
        private readonly prisma: PrismaService,
        private readonly mailer: Mailer,
    ) {
        super();
    }

    // Giá trị trả về được lưu vào job (returnvalue)
    async process(job: Job<WelcomeJob | TaskAssignedJob>): Promise<string> {
        try {
            switch (job.name) {
                case 'welcome':
                    return await this.welcome(job.data as WelcomeJob);
                case 'task-assigned':
                    return await this.taskAssigned(job.data as TaskAssignedJob);
                default:
                    throw new UnrecoverableError(`Job lạ: ${job.name}`);
            }
        } catch (error) {
            // Lỗi vĩnh viễn (vd: địa chỉ bị từ chối): thử lại cũng vô ích
            if (error instanceof MailError && error.permanent) {
                throw new UnrecoverableError(error.message);
            }
            throw error; // lỗi tạm thời: BullMQ thử lại sau
        }
    }

    private async taskAssigned({
        taskId,
        assigneeId,
    }: TaskAssignedJob): Promise<string> {
        const task = await this.prisma.task.findUnique({
            where: { id: taskId },
            include: {
                project: { select: { name: true } },
                assignee: { select: { name: true, email: true } },
            },
        });
        // Task đã bị xoá hoặc đã giao cho người khác trong lúc chờ
        if (!task?.assignee || task.assigneeId !== assigneeId) {
            return 'skipped';
        }
        await this.mailer.send(TaskAssignedMail, {
            to: { name: task.assignee.name, address: task.assignee.email },
            data: {
                name: task.assignee.name,
                title: task.title,
                projectName: task.project.name,
                dueDate: task.dueDate,
            },
        });
        return 'sent';
    }

    @OnWorkerEvent('failed') // sau mỗi lần thử thất bại
    onFailed(job: Job | undefined, error: Error): void {
        this.logger.error(
            `Job ${job?.name} #${job?.id} lỗi lần ${job?.attemptsMade}/${job?.opts.attempts}`,
            error,
        );
    }
}

Trong đó:

  • Consumer gắn @Processor(), kế thừa WorkerHost. Một queue chỉ có một process(); BullMQ không có @Process('tên') như Bull, nên phân loại bằng switch (job.name).
  • process() ném lỗi thì job được chạy lại sau backoff; UnrecoverableError thì thất bại luôn.

Reset dữ liệu như Bài 28 (flushall xoá cả queue) rồi đăng ký An: mail tới Mailpit ngay sau đó, job nằm ở key bull:mail:1 với data là {"userId":2}, returnvalue là "sent".

5. Retry, backoff và job thất bại.

Dừng Mailpit (docker stop taskflow-mailpit) rồi giao task cho An, worker thử lại theo backoff:

curl http://localhost:3000/api/v1/tasks -H "$A" -H "Content-Type: application/json" \
    -d '{"projectId":1,"title":"Viết bài Queue","assigneeId":2}'

# Log (rút gọn), cách nhau 5s, 10s, 20s:
# 11:48:54 {"level":"error",...,"message":"Job task-assigned #2 lỗi lần 1/5"}
# 11:48:59 ... lỗi lần 2/5
# 11:49:09 ... lỗi lần 3/5
# 11:49:29 ... lỗi lần 4/5

Bật lại Mailpit (docker start taskflow-mailpit) trước lần thứ 5 thì 40 giây sau mail tới. kill -9 ứng dụng lúc job đang chờ thì chạy lại là job được xử lý tiếp.

Mailpit tắt suốt 5 lần thì job vào danh sách failed:

docker exec taskflow-redis redis-cli zrange bull:mail:failed 0 -1
# 3
docker exec taskflow-redis redis-cli hmget bull:mail:3 data atm failedReason
# {"taskId":2,"assigneeId":2}
# 5
# SMTP connection to localhost:1025 failed: ECONNREFUSED

atm là số lần đã chạy. Trong code có queue.getFailed(), job.retry(). Lỗi vĩnh viễn (SMTP trả 550) thì job vào failed ngay lần đầu.

6. Bull Board.

Bull Board (@bull-board/nestjs 9.13.1) là giao diện web xem queue, dữ liệu và lỗi của từng job, bấm chạy lại hay xoá job. Đăng ký bằng BullBoardModule.forRoot({ route, adapter, middleware }) và forFeature() cho từng queue.

Chú ý: Bull Board gắn như middleware nên guard JWT toàn cục không bảo vệ nó: phải thêm xác thực qua option middleware (vd: basic auth) hoặc chỉ mở trong mạng nội bộ.

7. Lời kết.

Như vậy mình đã giới thiệu xong về queue với BullMQ trong NestJS: producer, processor, retry, job thất bại và Bull Board. Bài sau mình sẽ giới thiệu về Task Scheduling và Event trong NestJS để làm tính năng nhắc việc hằng ngày.

Đăng ký nhận tin.

Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!

Vũ Thanh Tài

About author
The best way to learn is to share
Xem tất cả bài đăng

0 Comments

Bài viết chưa có ai bình luận, hãy là người đầu tiên đi bạn!

Bình luận

Captcha