PH Mailer

// BullMQ worker with configurable concurrency and rate limiting.
// Workers scale independently from the API server.
const emailQueue = new Queue("email-delivery", {
    connection: redisConfig,
    defaultJobOptions: {
        attempts: 5,
        backoff: { type: "exponential", delay: 1000 },
        removeOnComplete: { count: 1000 },
        removeOnFail: { count: 5000 },
    },
})

const worker = new Worker("email-delivery", processEmailJob, {
    connection: redisConfig,
    concurrency: 10,
    limiter: { max: 100, duration: 1000 },
})

worker.on("failed", (job, err) => {
    logger.error("Email delivery failed", {
        jobId: job.id,
        attempt: job.attemptsMade,
        error: err.message,
    })
})

// Exponential backoff with jitter: prevents thundering herd on recovery.
async function retryWithBackoff<T>(
    fn: () => Promise<T>,
    opts: { maxAttempts: number; baseDelay: number; maxDelay: number },
): Promise<T> {
    for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
        try {
            return await fn()
        } catch (err) {
            if (attempt === opts.maxAttempts - 1) throw err
            const delay = Math.min(
                opts.baseDelay * Math.pow(2, attempt) + Math.random() * 1000,
                opts.maxDelay,
            )
            logger.warn("retry after failure", {
                attempt,
                delay,
                error: (err as Error).message,
            })
            await new Promise(r => setTimeout(r, delay))
        }
    }
    throw new Error("unreachable")
}