Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(queue): add QUEUE_PREFIX
Yudhi Armyndharis3c899178c7b9
diff --git a/.env.example b/.env.exampleindex bce621078..dead67c00 100644--- a/.env.example+++ b/.env.example@@ -408,6 +408,13 @@ DATABASE_SYNCHRONIZE=false # WARNING: Set false in production! (data DB# REDIS_TLS=false# Redis logical database for the cache (the queue uses the default database).# REDIS_CACHE_DB=1+# Redis key prefix of the BullMQ queues (default bull). Deployments that share one Redis must each set+# their own, or one's workers take the other's webhook jobs and complete them without delivering.+# Replicas of one deployment share a value. Changing it on a live deployment leaves the jobs queued+# under the old prefix unprocessed. Up to 64 letters, digits, dots, underscores or hyphens. It covers the+# queues only: with REDIS_ENABLED=true the rate-limit counters and the WebSocket fan-out are shared too,+# and events reach the clients of every deployment on that Redis, so such deployments need a Redis each.+# QUEUE_PREFIX=bull# =============================================================================# STORAGEdiff --git a/docker-compose.dev.yml b/docker-compose.dev.ymlindex b39e7c901..c3b516ad6 100644--- a/docker-compose.dev.yml+++ b/docker-compose.dev.yml@@ -195,6 +195,7 @@ services:- REDIS_CONNECT_TIMEOUT_MS=${REDIS_CONNECT_TIMEOUT_MS:-}- REDIS_TLS=${REDIS_TLS:-}- REDIS_CACHE_DB=${REDIS_CACHE_DB:-}+ - QUEUE_PREFIX=${QUEUE_PREFIX:-}# Fetch statuses on ready (off unless the exact string 'true', matching docker-compose.yml).- STATUS_SEED_ON_READY=${STATUS_SEED_ON_READY:-false}- AUTOMATION_MAX_PER_SESSION=${AUTOMATION_MAX_PER_SESSION:-}diff --git a/docker-compose.yml b/docker-compose.ymlindex 5a913dbce..7e4bb94f7 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -348,6 +348,7 @@ services:- REDIS_CONNECT_TIMEOUT_MS=${REDIS_CONNECT_TIMEOUT_MS:-}- REDIS_TLS=${REDIS_TLS:-}- REDIS_CACHE_DB=${REDIS_CACHE_DB:-}+ - QUEUE_PREFIX=${QUEUE_PREFIX:-}# Engine / session tuning.- MAX_CONCURRENT_SESSIONS=${MAX_CONCURRENT_SESSIONS:-}- BAILEYS_AUTH_DIR=${BAILEYS_AUTH_DIR:-}diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex 384ffdb14..fd850c93d 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -444,6 +444,14 @@ LOG_FORMAT=json# for the queue alone therefore also enables the cache.# CACHE_ENABLED=true# QUEUE_ENABLED=true # process webhooks/ingress through the BullMQ queue+# Deployments that use the queue on one shared Redis need a distinct QUEUE_PREFIX each (default bull; up+# to 64 letters, digits, dots, underscores or hyphens). A queue is named only by its prefix and name, so+# two deployments on the same prefix take each other's webhook jobs and complete them without delivering.+# Replicas of one deployment share a value; changing it on a live deployment leaves the jobs queued under+# the old prefix unprocessed. The prefix covers the queues only: with REDIS_ENABLED=true the rate-limit+# counters and the WebSocket fan-out channel are shared as well, and events reach the clients of every+# deployment on that Redis, so give each such deployment a Redis of its own.+# QUEUE_PREFIX=bull# ===========================================# WHATSAPP ENGINEdiff --git a/src/config/env-precedence.ts b/src/config/env-precedence.tsindex 16090d262..6974a7254 100644--- a/src/config/env-precedence.ts+++ b/src/config/env-precedence.ts@@ -206,6 +206,7 @@ export const BLANK_SHADOWED_ENV_KEYS: string[] = ['REDIS_CONNECT_TIMEOUT_MS','REDIS_TLS','REDIS_CACHE_DB',+ 'QUEUE_PREFIX','MAX_CONCURRENT_SESSIONS','BAILEYS_AUTH_DIR','BAILEYS_BROWSER_NAME',diff --git a/src/config/env.validation.spec.ts b/src/config/env.validation.spec.tsindex ecd8d61ac..ca86a6594 100644--- a/src/config/env.validation.spec.ts+++ b/src/config/env.validation.spec.ts@@ -641,6 +641,17 @@ describe('validateEnv', () => {},);+ // The prefix is joined to the queue name with a colon in every Redis key.+ it('accepts a plain QUEUE_PREFIX, or none, and rejects one that would build ambiguous keys', () => {+ for (const ok of ['bull', 'openwa-staging', 'prod_2.eu', '', ' ']) {+ expect(() => validateEnv({ QUEUE_PREFIX: ok })).not.toThrow();+ }+ for (const bad of ['a:b', 'has space', '-lead', '.lead', 'a/b', 'x'.repeat(65)]) {+ expect(() => validateEnv({ QUEUE_PREFIX: bad })).toThrow(/QUEUE_PREFIX must be 1 to 64/);+ }+ expect(() => validateEnv({ QUEUE_PREFIX: 'x'.repeat(64) })).not.toThrow();+ });+// Read as an exact 'true'/'false' override; anything else falls back to the NODE_ENV default, so// CSP_UPGRADE_INSECURE_REQUESTS=False kept the blank-dashboard trap on in production.it.each([diff --git a/src/config/env.validation.ts b/src/config/env.validation.tsindex c8ba71018..0a08f7e19 100644--- a/src/config/env.validation.ts+++ b/src/config/env.validation.ts@@ -116,6 +116,14 @@ export function validateEnv(config: EnvConfig): EnvConfig {`S3_KEY_PREFIX must be a relative key prefix such as "staging/" with no empty, "." or ".." segment (got ${JSON.stringify(s3KeyPrefix)})`,);}+ // The BullMQ key prefix is joined to the queue name with a colon in every Redis key, so a colon or+ // whitespace in it builds keys that tooling cannot split back apart.+ const queuePrefix = str('QUEUE_PREFIX');+ if (queuePrefix !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(queuePrefix)) {+ errors.push(+ `QUEUE_PREFIX must be 1 to 64 letters, digits, dots, underscores or hyphens, starting with a letter or digit (got ${JSON.stringify(queuePrefix)})`,+ );+ }// Every production hardening in the repo gates on the exact string 'production', so an// unrecognised value silently selects the permissive branch of each one — CORS, Swagger, DTO// error detail, the default-secret guard and the ALLOW_DEV_API_KEY rejection that stops the publicdiff --git a/src/modules/queue/queue.module.ts b/src/modules/queue/queue.module.tsindex e0730d6a9..88e7074ff 100644--- a/src/modules/queue/queue.module.ts+++ b/src/modules/queue/queue.module.ts@@ -7,7 +7,7 @@ import { TypeOrmModule } from '@nestjs/typeorm';import { WebhookProcessor } from './processors/webhook.processor';import { IngressProcessor } from './processors/ingress.processor';import { QUEUE_NAMES } from './queue-names';-import { queueConnectionOptions } from './redis-connection';+import { queueRootOptions } from './redis-connection';import { ShutdownSafeQueue } from './shutdown-safe-queue';import { Webhook } from '../webhook/entities/webhook.entity';import { WebhookOutboxModule } from '../webhook/webhook-outbox.module';@@ -45,7 +45,7 @@ BullModule.queueClass = ShutdownSafeQueue;// explicitly for clarity, matching HooksModule above).PluginsModule,BullModule.forRootAsync({- useFactory: () => ({ connection: queueConnectionOptions() }),+ useFactory: queueRootOptions,}),BullModule.registerQueue({name: QUEUE_NAMES.WEBHOOK,diff --git a/src/modules/queue/redis-connection.spec.ts b/src/modules/queue/redis-connection.spec.tsindex 70a9e0671..63e8f80a6 100644--- a/src/modules/queue/redis-connection.spec.ts+++ b/src/modules/queue/redis-connection.spec.ts@@ -5,6 +5,8 @@ import {producerConnectWaitMs,producerReady,queueConnectionOptions,+ queuePrefix,+ queueRootOptions,workerConnectionOptions,webhookWorkerConcurrency,} from './redis-connection';@@ -173,6 +175,29 @@ describe('webhookWorkerConcurrency', () => {});});+describe('queue key prefix', () => {+ const ORIGINAL_ENV = process.env;+ afterEach(() => {+ process.env = ORIGINAL_ENV;+ });++ it('leaves the prefix out when unset or blank, so BullMQ keeps its own and queued jobs survive an upgrade', () => {+ for (const value of [undefined, '', ' ']) {+ process.env = { ...ORIGINAL_ENV };+ if (value === undefined) delete process.env.QUEUE_PREFIX;+ else process.env.QUEUE_PREFIX = value;+ expect(queuePrefix()).toBeUndefined();+ expect(queueRootOptions()).not.toHaveProperty('prefix');+ }+ });++ it('hands the configured prefix, trimmed, to the root options next to the producer connection', () => {+ process.env = { ...ORIGINAL_ENV, QUEUE_PREFIX: ' staging ' };+ expect(queuePrefix()).toBe('staging');+ expect(queueRootOptions()).toEqual({ connection: queueConnectionOptions(), prefix: 'staging' });+ });+});+describe('producerReady', () => {const ORIGINAL_ENV = process.env;diff --git a/src/modules/queue/redis-connection.ts b/src/modules/queue/redis-connection.tsindex 5842ae940..ba66fb60c 100644--- a/src/modules/queue/redis-connection.ts+++ b/src/modules/queue/redis-connection.ts@@ -28,6 +28,23 @@ export function queueConnectionOptions(): RedisConnectionOptions & {return { ...redisConnectionOptions(), enableOfflineQueue: false, commandTimeout: QUEUE_COMMAND_TIMEOUT_MS };}+/**+ * Redis key prefix of the BullMQ queues, handed to every Queue and Worker through the shared module+ * options. Unset keeps BullMQ's own `bull`, so jobs queued by an earlier version are still found after+ * an upgrade. A queue is named only by this prefix and its name, so two deployments on one Redis must+ * each set their own: otherwise one's workers take the other's webhook jobs, find no such webhook in+ * their own database and complete them without delivering. Replicas of one deployment share a value.+ */+export function queuePrefix(): string | undefined {+ return process.env.QUEUE_PREFIX?.trim() || undefined;+}++/** `BullModule.forRootAsync` options: the producer connection, plus the prefix when one is set. */+export function queueRootOptions(): { connection: ReturnType<typeof queueConnectionOptions>; prefix?: string } {+ const prefix = queuePrefix();+ return { connection: queueConnectionOptions(), ...(prefix ? { prefix } : {}) };+}+/*** How long producerReady waits for a producer queue's first connect: REDIS_CONNECT_TIMEOUT_MS, or the* default when it is 0 (see producerReady), capped at MAX_TIMER_MS. Above that a Node timer fires afterdiff --git a/test/queue-on.e2e-spec.ts b/test/queue-on.e2e-spec.tsindex def9d82c7..debbecf3d 100644--- a/test/queue-on.e2e-spec.ts+++ b/test/queue-on.e2e-spec.ts@@ -7,6 +7,9 @@ import { spawnSync } from 'node:child_process';// opts back in — the integration-instance suite uses the same env-before-import pattern for its flags.process.env.QUEUE_ENABLED = 'true';process.env.REDIS_ENABLED = 'true';+// A non-default key prefix for the whole suite: a Worker that built its queue under a different prefix+// than the producer would never see a job, and the dispatch tests below would time out.+process.env.QUEUE_PREFIX = 'openwa-e2e';// QUEUE_TEST_REDIS_* overrides the standard REDIS_* for this suite only, so a dev box whose Redis is// not on localhost:6379 can still run it; CI sets REDIS_HOST/REDIS_PORT at the service container.const REDIS_HOST = process.env.QUEUE_TEST_REDIS_HOST || process.env.REDIS_HOST || 'localhost';@@ -50,6 +53,7 @@ import { getRepositoryToken } from '@nestjs/typeorm';import { getQueueToken } from '@nestjs/bullmq';import { Repository } from 'typeorm';import { Queue } from 'bullmq';+import IORedis from 'ioredis';import request from 'supertest';import { App } from 'supertest/types';import { json, urlencoded, Request } from 'express';@@ -292,4 +296,18 @@ describeQueueOn('Queued dispatch paths (e2e, QUEUE_ENABLED=true)', () => {await waitFor(async () => (await outboxRepo.findOneBy({ idempotencyKey }))?.state === 'dispatched');expect(await outboxRepo.findOneByOrFail({ idempotencyKey })).toMatchObject({ state: 'dispatched', payload: null });}, 30000);++ it('keeps both queues under QUEUE_PREFIX', async () => {+ expect(ingressQueue.opts.prefix).toBe('openwa-e2e');+ expect(webhookQueue.opts.prefix).toBe('openwa-e2e');++ const redis = new IORedis({ host: REDIS_HOST, port: REDIS_PORT });+ try {+ for (const name of [QUEUE_NAMES.INGRESS, QUEUE_NAMES.WEBHOOK]) {+ expect((await redis.keys(`openwa-e2e:${name}:*`)).length).toBeGreaterThan(0);+ }+ } finally {+ redis.disconnect();+ }+ });});