Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
feat(media): add an optional process-wide inbound media download cap
Yudhi Armyndharisb28dcf58b3f1
diff --git a/.env.example b/.env.exampleindex 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 whendiff --git a/docker-compose.dev.yml b/docker-compose.dev.ymlindex 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.ymlindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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