Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(queue): add QUEUE_PREFIX

Yudhi Armyndharis3c899178c7b9
diff --git a/.env.example b/.env.example
index 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
# =============================================================================
# STORAGE
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 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.yml
index 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.md
index 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 ENGINE
diff --git a/src/config/env-precedence.ts b/src/config/env-precedence.ts
index 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.ts
index 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.ts
index 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 public
diff --git a/src/modules/queue/queue.module.ts b/src/modules/queue/queue.module.ts
index 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.ts
index 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.ts
index 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 after
diff --git a/test/queue-on.e2e-spec.ts b/test/queue-on.e2e-spec.ts
index 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();
+ }
+ });
});