Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

feat(media): add an optional process-wide inbound media download cap

Yudhi Armyndharisb28dcf58b3f1
diff --git a/.env.example b/.env.example
index 230ee0067..f2d78c12b 100644
--- a/.env.example
+++ b/.env.example
@@ -503,10 +503,17 @@ WEBHOOK_SSRF_PROTECT=true
# unit string. Writing `50mb` here is refused at boot rather than read as its leading digits.
# MEDIA_DOWNLOAD_MAX_BYTES=52428800 # cap remote-URL sends, inbound media, AND outbound base64 sends (default 50 MiB; oversized inbound media is dropped, message kept; oversized base64 is rejected with 413)
# MEDIA_DOWNLOAD_TIMEOUT_MS=30000 # abort a slow media download (default 30s), in milliseconds
-# Inbound media download parallelism (how many inbound media items download at once). Each concurrent
-# download holds memory up to MEDIA_DOWNLOAD_MAX_BYTES; this bounds N. Unset takes the default; a
-# value that is not a positive integer fails the boot.
+# Inbound media download parallelism PER SESSION (how many inbound media items one session downloads
+# at once). Each concurrent download holds memory up to MEDIA_DOWNLOAD_MAX_BYTES (held as base64 on
+# whatsapp-web.js, about a third larger), so the worst case is about sessions x N x MEDIA_DOWNLOAD_MAX_BYTES
+# (x ~1.33 on whatsapp-web.js). Unset takes the default; a value that is not a positive integer fails the boot.
# INBOUND_MEDIA_CONCURRENCY=4 # default 4
+# Process-wide ceiling on inbound media downloads across all sessions, on top of the per-session one.
+# 0 (default) is off. When on, media that waits longer than MEDIA_DOWNLOAD_TIMEOUT_MS for a slot is
+# delivered without its payload (the omitted marker), as a timed-out download is. On Baileys a timed-out
+# download frees its slot at the deadline. whatsapp-web.js cannot abort one, so its slot stays taken until
+# the page answers or Puppeteer fails the call (PUPPETEER_PROTOCOL_TIMEOUT_MS, 180s by default).
+# INBOUND_MEDIA_GLOBAL_CONCURRENCY=0 # default 0 (off)
# Fetch a caller-supplied URL (a media URL passed to a send or to POST /media/convert/voice|video, and the link
# preview of a text send) through the egress proxy of the session the request names. ON by default,
# so the destination sees the same address as the rest of that session's traffic. Set to false when
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 901d372d8..9170c9032 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -140,6 +140,7 @@ services:
- MEDIA_DOWNLOAD_MAX_BYTES=${MEDIA_DOWNLOAD_MAX_BYTES:-}
- MEDIA_DOWNLOAD_TIMEOUT_MS=${MEDIA_DOWNLOAD_TIMEOUT_MS:-}
- INBOUND_MEDIA_CONCURRENCY=${INBOUND_MEDIA_CONCURRENCY:-}
+ - INBOUND_MEDIA_GLOBAL_CONCURRENCY=${INBOUND_MEDIA_GLOBAL_CONCURRENCY:-}
- SESSION_PROXY_URL_FETCH=${SESSION_PROXY_URL_FETCH:-}
- MEDIA_CONVERSION_ENABLED=${MEDIA_CONVERSION_ENABLED:-}
- FFMPEG_PATH=${FFMPEG_PATH:-}
diff --git a/docker-compose.yml b/docker-compose.yml
index 5619755b6..9b5cc22b0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -218,6 +218,7 @@ services:
- MEDIA_DOWNLOAD_MAX_BYTES=${MEDIA_DOWNLOAD_MAX_BYTES:-}
- MEDIA_DOWNLOAD_TIMEOUT_MS=${MEDIA_DOWNLOAD_TIMEOUT_MS:-}
- INBOUND_MEDIA_CONCURRENCY=${INBOUND_MEDIA_CONCURRENCY:-}
+ - INBOUND_MEDIA_GLOBAL_CONCURRENCY=${INBOUND_MEDIA_GLOBAL_CONCURRENCY:-}
- SESSION_PROXY_URL_FETCH=${SESSION_PROXY_URL_FETCH:-}
# Server-side media conversion (opt-in). The image ships ffmpeg, but without these forwards
# the feature could not be switched on from .env at all.
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index a8e4c424a..9dad484d8 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1207,10 +1207,12 @@ docker exec openwa-api curl http://host.docker.internal:8080
> - 8GB RAM: 15-20 sessions
>
> With `ENGINE_TYPE=baileys` (browser-free), RAM per session is significantly lower — you can run more sessions on the same hardware. Exact figures depend on message volume and group membership.
+>
+> A media burst adds roughly `INBOUND_MEDIA_CONCURRENCY` x `MEDIA_DOWNLOAD_MAX_BYTES` per session on top of that (4 x 50 MiB by default; about a third more on whatsapp-web.js, which holds each payload as base64). Set `INBOUND_MEDIA_GLOBAL_CONCURRENCY` to cap concurrent inbound media downloads across all sessions. On whatsapp-web.js a download that times out keeps its slot until Puppeteer fails the call (`PUPPETEER_PROTOCOL_TIMEOUT_MS`, 180 s by default), since it cannot be aborted.
**Q: Can I run 10+ sessions in one container? Will they get banned for sharing one IP?**
-> A: Yes — there is no hard session limit; the practical ceiling is RAM/CPU (see the table above). Sharing one IP across sessions is not itself a ban trigger: carrier NAT already puts hundreds of ordinary users on a single IP, so WhatsApp cannot treat a shared IP as a violation. Ten sessions on one residential IP behave like ten phones on one home WiFi. What actually matters:
+> A: Yes: there is no session limit by default (`MAX_CONCURRENT_SESSIONS` sets one); the practical ceiling is RAM/CPU (see the table above). Sharing one IP across sessions is not itself a ban trigger: carrier NAT already puts hundreds of ordinary users on a single IP, so WhatsApp cannot treat a shared IP as a violation. Ten sessions on one residential IP behave like ten phones on one home WiFi. What actually matters:
>
> - **IP reputation** — cheap datacenter IPs are flagged more aggressively than residential ones. A residential proxy (per-session, via the proxy settings) can help; it is not a license to spam.
> - **Sending behavior** — bans follow message patterns (volume, identical templates, cold reachouts), not session count. See "How to avoid getting banned?" below.
diff --git a/src/config/env-precedence.spec.ts b/src/config/env-precedence.spec.ts
index c9f4c4581..40e6412e2 100644
--- a/src/config/env-precedence.spec.ts
+++ b/src/config/env-precedence.spec.ts
@@ -365,6 +365,7 @@ describe.each(['docker-compose.yml', 'docker-compose.dev.yml'])('%s forwards the
'MEDIA_DOWNLOAD_MAX_BYTES',
'MEDIA_DOWNLOAD_TIMEOUT_MS',
'INBOUND_MEDIA_CONCURRENCY',
+ 'INBOUND_MEDIA_GLOBAL_CONCURRENCY',
])('forwards %s', key => {
expect(forwards(key)).toBe(true);
});
diff --git a/src/config/env-precedence.ts b/src/config/env-precedence.ts
index 847cddabe..abbced8b6 100644
--- a/src/config/env-precedence.ts
+++ b/src/config/env-precedence.ts
@@ -31,6 +31,7 @@ export const BLANK_SHADOWED_ENV_KEYS: string[] = [
'MEDIA_DOWNLOAD_MAX_BYTES',
'MEDIA_DOWNLOAD_TIMEOUT_MS',
'INBOUND_MEDIA_CONCURRENCY',
+ 'INBOUND_MEDIA_GLOBAL_CONCURRENCY',
// Whether a caller-supplied URL is fetched through the named session's egress proxy.
'SESSION_PROXY_URL_FETCH',
// Database selection + connection details (#488)
diff --git a/src/config/env.validation.spec.ts b/src/config/env.validation.spec.ts
index c1d25918d..fd74528dc 100644
--- a/src/config/env.validation.spec.ts
+++ b/src/config/env.validation.spec.ts
@@ -67,6 +67,13 @@ describe('validateEnv', () => {
expect(() => validateEnv({ MEDIA_DOWNLOAD_TIMEOUT_MS: '30000' })).not.toThrow();
});
+ it('accepts 0 for INBOUND_MEDIA_GLOBAL_CONCURRENCY (off) and rejects a negative or suffixed value', () => {
+ expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '0' })).not.toThrow();
+ expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '16' })).not.toThrow();
+ expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '-1' })).toThrow(/INBOUND_MEDIA_GLOBAL_CONCURRENCY/);
+ expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '4x' })).toThrow(/INBOUND_MEDIA_GLOBAL_CONCURRENCY/);
+ });
+
// Unset and empty stay the operator's way of taking the default; compose forwards a blank.
it('leaves an unset or blank media knob alone', () => {
expect(() => validateEnv({})).not.toThrow();
diff --git a/src/config/env.validation.ts b/src/config/env.validation.ts
index 300fd8de8..28003aa81 100644
--- a/src/config/env.validation.ts
+++ b/src/config/env.validation.ts
@@ -222,6 +222,7 @@ export function validateEnv(config: EnvConfig): EnvConfig {
'CHAT_MEDIA_ARCHIVE_TTL_DAYS', // 0 = keep archived chat media forever
'INGRESS_RETRY_DELAY_MS', // 0 = retry without backoff
'REDIS_CACHE_DB',
+ 'INBOUND_MEDIA_GLOBAL_CONCURRENCY', // 0 = no process-wide ceiling, only the per-session one
]) {
checkNonNegativeInt(key);
}
diff --git a/src/engine/adapters/baileys-events.ts b/src/engine/adapters/baileys-events.ts
index b7b457064..1cc4be29e 100644
--- a/src/engine/adapters/baileys-events.ts
+++ b/src/engine/adapters/baileys-events.ts
@@ -35,6 +35,7 @@ import {
inboundMediaMaxBytes,
inboundMediaTimeoutMs,
isMediaDownloadEnabled,
+ runUnderGlobalMediaGate,
withInboundDownloadTimeout,
} from './inbound-media-cap';
import type { Dispatcher } from 'undici';
@@ -1169,7 +1170,19 @@ export class BaileysEvents {
// The timeout can fire before the stream exists (an expired-media re-upload wait, a slow response):
// the abandoned download must then stop on its own instead of buffering outside the limiter.
let timedOut = false;
- const download = (async (): Promise<Buffer | { overflowBytes: number }> => {
+ // Settles the gate task at the deadline. Without it the process-wide slot is held until the body
+ // settles, and a fetch stuck before the stream exists (an expired-media re-upload the phone never
+ // answers waits with no timeout until the socket closes) would keep that slot for hours, starving
+ // every other session's media. Freeing it early is safe: nothing is buffered before the stream
+ // exists, and a stream that turns up late is destroyed by the `timedOut` check below.
+ let releaseSlot: () => void = () => undefined;
+ const deadlinePassed = new Promise<Buffer>(resolve => {
+ releaseSlot = () => resolve(Buffer.alloc(0));
+ });
+ const body = async (): Promise<Buffer | { overflowBytes: number }> => {
+ if (timedOut) {
+ return Buffer.alloc(0);
+ }
const b = await this.host.loadLib();
stream = (await b.downloadMediaMessage(
msg,
@@ -1199,7 +1212,15 @@ export class BaileysEvents {
chunks.push(chunk);
}
return Buffer.concat(chunks);
- })();
+ };
+ // The wait for the process-wide gate sits inside the deadline below, so a contended gate cannot
+ // hold this session's inbound handler longer than MEDIA_DOWNLOAD_TIMEOUT_MS.
+ const download = runUnderGlobalMediaGate(() => {
+ const run = body();
+ // The abandoned body can still reject later (the socket closing under a re-upload wait).
+ run.catch(() => undefined);
+ return Promise.race([run, deadlinePassed]);
+ });
// A slow/trickling sender never trips the byte cap, so without a deadline it pins a concurrency
// slot (and, on Baileys, the whole inbound handler) indefinitely. On timeout, destroy the stream
@@ -1207,6 +1228,7 @@ export class BaileysEvents {
return withInboundDownloadTimeout(download, inboundMediaTimeoutMs(), () => {
timedOut = true;
stream?.destroy?.();
+ releaseSlot();
});
}
diff --git a/src/engine/adapters/inbound-media-cap.spec.ts b/src/engine/adapters/inbound-media-cap.spec.ts
index c532c8e1b..864d746fb 100644
--- a/src/engine/adapters/inbound-media-cap.spec.ts
+++ b/src/engine/adapters/inbound-media-cap.spec.ts
@@ -1,4 +1,13 @@
+import type { WAMessage, WASocket } from '@whiskeysockets/baileys';
+import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
+import { createLogger } from '../../common/services/logger.service';
+import { BaileysEvents, type BaileysEventsHost } from './baileys-events';
+import { WhatsAppWebJsAdapter } from './whatsapp-web-js.adapter';
import {
+ __resetGlobalInboundMediaGate,
+ globalInboundMediaGate,
+ inboundMediaGlobalConcurrency,
+ runUnderGlobalMediaGate,
capInboundMedia,
chatHistoryMediaBudgetBytes,
inboundMediaMaxBytes,
@@ -255,3 +264,230 @@ describe('ingestMediaBudgetBytes', () => {
expect(ingestMediaBudgetBytes(Number.NaN)).toBe(chatHistoryMediaBudgetBytes());
});
});
+
+describe('process-wide inbound media gate (INBOUND_MEDIA_GLOBAL_CONCURRENCY)', () => {
+ const KEYS = [
+ 'INBOUND_MEDIA_GLOBAL_CONCURRENCY',
+ 'INBOUND_MEDIA_CONCURRENCY',
+ 'MEDIA_DOWNLOAD_TIMEOUT_MS',
+ 'MEDIA_DOWNLOAD_MAX_BYTES',
+ 'MEDIA_DOWNLOAD_ENABLED',
+ ];
+ const saved: Record<string, string | undefined> = {};
+ beforeEach(() => {
+ KEYS.forEach(k => (saved[k] = process.env[k]));
+ process.env.MEDIA_DOWNLOAD_ENABLED = 'true';
+ process.env.MEDIA_DOWNLOAD_MAX_BYTES = String(10 * 1024 * 1024);
+ __resetGlobalInboundMediaGate();
+ });
+ afterEach(() => {
+ KEYS.forEach(k => {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ });
+ __resetGlobalInboundMediaGate();
+ jest.useRealTimers();
+ });
+
+ type Deferred<T> = { promise: Promise<T>; resolve: (v: T) => void };
+ const defer = <T>(): Deferred<T> => {
+ let resolve: (v: T) => void = () => undefined;
+ const promise = new Promise<T>(res => (resolve = res));
+ return { promise, resolve };
+ };
+
+ it('is off unless set to a positive integer', () => {
+ for (const value of [undefined, '', '0', 'abc']) {
+ if (value === undefined) delete process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY;
+ else process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = value;
+ expect(inboundMediaGlobalConcurrency()).toBe(0);
+ __resetGlobalInboundMediaGate();
+ expect(globalInboundMediaGate()).toBeNull();
+ }
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '8';
+ expect(inboundMediaGlobalConcurrency()).toBe(8);
+ });
+
+ it('builds one shared gate and runs tasks directly when off', async () => {
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '3';
+ const gate = globalInboundMediaGate();
+ expect(gate).toBeInstanceOf(ConcurrencyLimiter);
+ expect(globalInboundMediaGate()).toBe(gate);
+
+ __resetGlobalInboundMediaGate();
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '0';
+ let ran = false;
+ const pending = runUnderGlobalMediaGate(() => {
+ ran = true;
+ return Promise.resolve('ok');
+ });
+ expect(ran).toBe(true); // no gate: the task starts synchronously
+ await expect(pending).resolves.toBe('ok');
+ });
+
+ describe('whatsapp-web.js', () => {
+ const newAdapter = (sessionId: string): WhatsAppWebJsAdapter =>
+ new WhatsAppWebJsAdapter({ sessionId, sessionDataPath: './data/sessions', puppeteer: {} });
+ const cap = (adapter: WhatsAppWebJsAdapter, m: unknown): Promise<{ data?: string; omitted?: boolean }> =>
+ (
+ adapter as unknown as { capInboundMediaFor: (msg: unknown) => Promise<{ data?: string; omitted?: boolean }> }
+ ).capInboundMediaFor(m);
+
+ it('caps downloads in flight across sessions while each session keeps its own cap', async () => {
+ process.env.INBOUND_MEDIA_CONCURRENCY = '4';
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '2';
+ process.env.MEDIA_DOWNLOAD_TIMEOUT_MS = '100000';
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const downloads: Deferred<{ mimetype: string; data: string }>[] = [];
+ const makeMsg = (id: string): unknown => ({
+ id: { _serialized: id },
+ _data: { size: 100, mimetype: 'image/png' },
+ downloadMedia: jest.fn(() => {
+ inFlight++;
+ maxInFlight = Math.max(maxInFlight, inFlight);
+ const d = defer<{ mimetype: string; data: string }>();
+ downloads.push(d);
+ return d.promise.finally(() => inFlight--);
+ }),
+ });
+ const a = newAdapter('gate-a');
+ const b = newAdapter('gate-b');
+
+ const results = [
+ ...['a1', 'a2', 'a3'].map(id => cap(a, makeMsg(id))),
+ ...['b1', 'b2', 'b3'].map(id => cap(b, makeMsg(id))),
+ ];
+ for (let settled = 0; settled < 6; settled++) {
+ await new Promise(resolve => setImmediate(resolve));
+ expect(inFlight).toBeLessThanOrEqual(2);
+ downloads[settled].resolve({ mimetype: 'image/png', data: Buffer.from(`m${settled}`).toString('base64') });
+ }
+
+ expect((await Promise.all(results)).every(r => typeof r.data === 'string')).toBe(true);
+ expect(maxInFlight).toBe(2);
+ });
+
+ it('never downloads a message that timed out while queued on the shared gate', async () => {
+ process.env.INBOUND_MEDIA_CONCURRENCY = '4';
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '1';
+ process.env.MEDIA_DOWNLOAD_TIMEOUT_MS = '50';
+ jest.useFakeTimers();
+ const held = defer<{ mimetype: string; data: string }>();
+ const first = {
+ id: { _serialized: 'x1' },
+ _data: { size: 100, mimetype: 'image/png' },
+ downloadMedia: jest.fn(() => held.promise),
+ };
+ const second = {
+ id: { _serialized: 'y1' },
+ _data: { size: 100, mimetype: 'image/png' },
+ downloadMedia: jest.fn(),
+ };
+
+ const r1 = cap(newAdapter('gate-x'), first);
+ const r2 = cap(newAdapter('gate-y'), second);
+ await jest.advanceTimersByTimeAsync(60);
+
+ expect(await r2).toEqual(expect.objectContaining({ omitted: true, sizeBytes: 100 }));
+ held.resolve({ mimetype: 'image/png', data: Buffer.from('late').toString('base64') });
+ await jest.advanceTimersByTimeAsync(0);
+ expect(second.downloadMedia).not.toHaveBeenCalled();
+ await r1;
+ });
+ });
+
+ describe('Baileys', () => {
+ type Stream = AsyncIterable<Buffer> & { destroy: jest.Mock };
+ const imageMessage = (id: string): WAMessage => ({
+ key: { id, remoteJid: '[email protected]', fromMe: false },
+ messageTimestamp: 1_700_000_000,
+ message: { imageMessage: { mimetype: 'image/png', fileLength: 64 } },
+ });
+ const build = (downloadMediaMessage: jest.Mock): BaileysEvents =>
+ new BaileysEvents({
+ getSocket: () => ({ updateMediaMessage: jest.fn() }) as unknown as WASocket,
+ getSocketOrNull: () => null,
+ logger: { ...createLogger('InboundMediaGateSpec'), warn: () => undefined },
+ loadLib: () => Promise.resolve({ normalizeMessageContent: (c: unknown) => c, downloadMediaMessage }),
+ getFetchDispatcher: () => undefined,
+ toNeutralJid: (jid: string) => jid,
+ normalizedSelfJid: () => '[email protected]',
+ inboundLimiter: new ConcurrencyLimiter(4),
+ } as unknown as BaileysEventsHost);
+
+ it('makes a second session wait for the gate and gives up at the deadline without downloading', async () => {
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '1';
+ process.env.MEDIA_DOWNLOAD_TIMEOUT_MS = '1000';
+ jest.useFakeTimers();
+ const release = defer<void>();
+ const slow: Stream = {
+ async *[Symbol.asyncIterator]() {
+ await release.promise;
+ yield Buffer.from('first');
+ },
+ destroy: jest.fn(),
+ };
+ const downloadA = jest.fn().mockResolvedValue(slow);
+ const downloadB = jest.fn();
+
+ // Session A takes the only slot at t=0 with a 1s deadline; session B asks at t=30 with a 50 ms
+ // one, so B's deadline (t=80) passes while A still holds the gate.
+ const pendingA = build(downloadA).mapMessage(imageMessage('A1'), 'imageMessage');
+ await jest.advanceTimersByTimeAsync(30);
+ process.env.MEDIA_DOWNLOAD_TIMEOUT_MS = '50';
+ const pendingB = build(downloadB).mapMessage(imageMessage('B1'), 'imageMessage');
+ await jest.advanceTimersByTimeAsync(60);
+
+ expect((await pendingB).media).toEqual(expect.objectContaining({ omitted: true, sizeBytes: 64 }));
+ release.resolve();
+ await jest.advanceTimersByTimeAsync(0);
+ await pendingA;
+ expect(downloadA).toHaveBeenCalledTimes(1);
+ expect(downloadB).not.toHaveBeenCalled();
+ });
+
+ it('frees the slot at the deadline when a download never produces a stream', async () => {
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '1';
+ process.env.MEDIA_DOWNLOAD_TIMEOUT_MS = '50';
+ jest.useFakeTimers();
+ // Session A's fetch never settles: an expired-media re-upload that the phone never answers.
+ const stuck = jest.fn(() => new Promise<never>(() => undefined));
+ const stream: Stream = {
+ // eslint-disable-next-line @typescript-eslint/require-await
+ async *[Symbol.asyncIterator]() {
+ yield Buffer.from('ok');
+ },
+ destroy: jest.fn(),
+ };
+ const downloadB = jest.fn().mockResolvedValue(stream);
+
+ const pendingA = build(stuck).mapMessage(imageMessage('A2'), 'imageMessage');
+ await jest.advanceTimersByTimeAsync(60);
+ expect((await pendingA).media).toEqual(expect.objectContaining({ omitted: true }));
+
+ const pendingB = build(downloadB).mapMessage(imageMessage('B2'), 'imageMessage');
+ await jest.advanceTimersByTimeAsync(60);
+
+ expect((await pendingB).media).toEqual(expect.objectContaining({ data: Buffer.from('ok').toString('base64') }));
+ expect(stuck).toHaveBeenCalledTimes(1);
+ });
+
+ it('downloads immediately when the gate is off', async () => {
+ process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY = '0';
+ process.env.MEDIA_DOWNLOAD_TIMEOUT_MS = '10000';
+ const stream: Stream = {
+ // eslint-disable-next-line @typescript-eslint/require-await
+ async *[Symbol.asyncIterator]() {
+ yield Buffer.from('ok');
+ },
+ destroy: jest.fn(),
+ };
+ const download = jest.fn().mockResolvedValue(stream);
+
+ const incoming = await build(download).mapMessage(imageMessage('C1'), 'imageMessage');
+
+ expect(incoming.media).toEqual(expect.objectContaining({ data: Buffer.from('ok').toString('base64') }));
+ });
+ });
+});
diff --git a/src/engine/adapters/inbound-media-cap.ts b/src/engine/adapters/inbound-media-cap.ts
index 351b020b6..618535c23 100644
--- a/src/engine/adapters/inbound-media-cap.ts
+++ b/src/engine/adapters/inbound-media-cap.ts
@@ -1,4 +1,5 @@
import type { IncomingMessage } from '../interfaces/whatsapp-engine.interface';
+import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
/** Default inbound media cap: 50 MiB. Shares MEDIA_DOWNLOAD_MAX_BYTES with the outbound download cap. */
const DEFAULT_INBOUND_MEDIA_MAX_BYTES = 50 * 1024 * 1024;
@@ -29,6 +30,41 @@ export function inboundMediaConcurrency(): number {
return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_INBOUND_MEDIA_CONCURRENCY;
}
+/**
+ * Process-wide ceiling on inbound media downloads, across every session (INBOUND_MEDIA_GLOBAL_CONCURRENCY).
+ * INBOUND_MEDIA_CONCURRENCY bounds one session, so without this the worst case grows with the session
+ * count. 0 (the default, and unset or empty) turns it off.
+ */
+export function inboundMediaGlobalConcurrency(): number {
+ const parsed = Number.parseInt(process.env.INBOUND_MEDIA_GLOBAL_CONCURRENCY ?? '', 10);
+ return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+}
+
+let globalGate: ConcurrencyLimiter | null | undefined;
+
+/**
+ * The gate every session's downloads share, built on first use and never closed. Null when off:
+ * ConcurrencyLimiter clamps 0 to 1, which would serialize every download in the process.
+ */
+export function globalInboundMediaGate(): ConcurrencyLimiter | null {
+ if (globalGate === undefined) {
+ const max = inboundMediaGlobalConcurrency();
+ globalGate = max > 0 ? new ConcurrencyLimiter(max) : null;
+ }
+ return globalGate;
+}
+
+/** Run one media download under the process-wide gate, or directly when it is off. */
+export function runUnderGlobalMediaGate<T>(task: () => Promise<T>): Promise<T> {
+ const gate = globalInboundMediaGate();
+ return gate ? gate.run(task) : task();
+}
+
+/** Forget the built gate so the next call reads INBOUND_MEDIA_GLOBAL_CONCURRENCY again. Tests only. */
+export function __resetGlobalInboundMediaGate(): void {
+ globalGate = undefined;
+}
+
/** Default inbound media download timeout: 30s. Shares MEDIA_DOWNLOAD_TIMEOUT_MS with the outbound download. */
const DEFAULT_INBOUND_MEDIA_TIMEOUT_MS = 30_000;
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.ts b/src/engine/adapters/whatsapp-web-js.adapter.ts
index f22543a20..a48088210 100644
--- a/src/engine/adapters/whatsapp-web-js.adapter.ts
+++ b/src/engine/adapters/whatsapp-web-js.adapter.ts
@@ -65,6 +65,7 @@ import {
inboundMediaMaxBytes,
inboundMediaTimeoutMs,
isMediaDownloadEnabled,
+ runUnderGlobalMediaGate,
withInboundDownloadTimeout,
} from './inbound-media-cap';
import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
@@ -321,7 +322,7 @@ export class WhatsAppWebJsAdapter extends EventEmitter implements IWhatsAppEngin
// base64 blob over CDP and holding the slot for it: after a burst, that backlog is what made
// later messages miss their own deadline. A download that already started is unaffected.
let abandoned = false;
- const slotHeld = this.inboundLimiter.run(() => {
+ const downloadInSlot = (): Promise<void> => {
if (abandoned) {
resolveBounded(null);
return Promise.resolve();
@@ -352,7 +353,10 @@ export class WhatsAppWebJsAdapter extends EventEmitter implements IWhatsAppEngin
() => undefined,
() => undefined,
);
- });
+ };
+ // Per-session slot first, then the process-wide one, so a session parks at most its own
+ // INBOUND_MEDIA_CONCURRENCY waiters on the shared gate. Both are held until the download settles.
+ const slotHeld = this.inboundLimiter.run(() => runUnderGlobalMediaGate(downloadInSlot));
// Defensive only, and deliberately kept. `run()` rejects on a full queue (gone — the queue is
// unbounded) or on close(), which nothing calls on this limiter; the task itself swallows both
// download outcomes. So nothing is expected here — but an unhandled rejection from a