Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import type { InboundTicket, 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;
/**
* Resolved inbound media byte cap.
*
* The fallback below only covers unset and empty: boot validation rejects anything else, including
* the unit-suffixed form its neighbours accept. `parseInt` would read `50mb` as 50 and this helper
* would take it, since 50 is a positive integer, capping every download at 50 bytes.
*/
export function inboundMediaMaxBytes(): number {
const parsed = Number.parseInt(process.env.MEDIA_DOWNLOAD_MAX_BYTES ?? '', 10);
return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_INBOUND_MEDIA_MAX_BYTES;
}
/** Default number of inbound media downloads processed at once. */
const DEFAULT_INBOUND_MEDIA_CONCURRENCY = 4;
/**
* Max inbound media downloads processed concurrently. Each download materialises a full decrypted
* buffer in heap, so an unbounded fire-and-forget loop lets a sender flood the gateway with N parallel
* multi-MB allocations; this bounds N. Override via INBOUND_MEDIA_CONCURRENCY; boot validation
* rejects a malformed value, so the fallback below only covers unset and empty.
*/
export function inboundMediaConcurrency(): number {
const parsed = Number.parseInt(process.env.INBOUND_MEDIA_CONCURRENCY ?? '', 10);
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;
/**
* Resolved per-download wall-clock timeout. Boot validation rejects a malformed override, so the
* fallback only covers unset and empty: `parseInt` would read `30s` as 30 and this helper would take
* it, timing out every download after 30 ms.
*/
export function inboundMediaTimeoutMs(): number {
const parsed = Number.parseInt(process.env.MEDIA_DOWNLOAD_TIMEOUT_MS ?? '', 10);
return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_INBOUND_MEDIA_TIMEOUT_MS;
}
/**
* Bound an inbound media download by a wall-clock deadline. The byte cap and concurrency limiter don't
* bound TIME: a remote sender can trickle bytes slowly (never tripping the cap) and hold a concurrency
* slot indefinitely — a slow-loris on the inbound pipeline. On timeout `onTimeout` runs — a best-effort
* hook to abort the source where it's abortable (e.g. destroy a Baileys stream) — and the result resolves
* `null`, the "no usable media" sentinel. A non-abortable source (the wwjs page download,
* `downloadCappedMedia()`) can't be stopped, so that caller must instead hold its concurrency slot until the
* real download settles. A late rejection from the abandoned download is swallowed so it can't surface as an
* unhandled rejection after the race has already settled.
*/
export function withInboundDownloadTimeout<T>(
promise: Promise<T>,
timeoutMs: number,
onTimeout?: () => void,
): Promise<T | null> {
let timer: NodeJS.Timeout | undefined;
const timeout = new Promise<null>(resolve => {
timer = setTimeout(() => {
onTimeout?.();
resolve(null);
}, timeoutMs);
timer.unref?.();
});
// Defuse a post-settle rejection from the download we may stop awaiting.
promise.catch(() => undefined);
return Promise.race([promise, timeout]).finally(() => {
if (timer) clearTimeout(timer);
});
}
/**
* Whether inbound media download is enabled. When false, the engine skips downloading media from
* incoming messages entirely — no decryption, no memory allocation, no storage. Override via
* MEDIA_DOWNLOAD_ENABLED; accepts 'false', '0', or 'no' (case-insensitive, whitespace-tolerant) to disable.
*/
export function isMediaDownloadEnabled(): boolean {
const val = (process.env.MEDIA_DOWNLOAD_ENABLED ?? '').trim().toLowerCase();
return val !== 'false' && val !== '0' && val !== 'no';
}
/**
* Default aggregate base64 budget for one getChatHistory(includeMedia=true) call: 25 MiB of inlined
* payload. The per-message cap (MEDIA_DOWNLOAD_MAX_BYTES) bounds ONE blob, but a 100-message history
* could otherwise stack ~100 × 50 MiB of base64 into a single response (and its JSON serialisation).
*/
const DEFAULT_CHAT_HISTORY_MEDIA_BUDGET_BYTES = 25 * 1024 * 1024;
/**
* Aggregate budget (counted in base64 characters, the actual response/heap payload) for media inlined
* by one getChatHistory pass. Once the running total crosses it, remaining media messages carry the
* usual `omitted` marker instead of a download. Boot validation rejects a malformed override, so the
* fallback covers unset and empty only.
*/
export function chatHistoryMediaBudgetBytes(): number {
const parsed = Number.parseInt(process.env.CHAT_HISTORY_MEDIA_BUDGET_BYTES ?? '', 10);
return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_CHAT_HISTORY_MEDIA_BUDGET_BYTES;
}
/**
* How many per-item caps an ingest pass (a caller that supplies its own `mediaMaxBytes`, i.e. the
* status seed) may accumulate before later items fall back to the omitted marker.
*
* The response budget above is sized for ONE HTTP response and is too tight here: two ~10 MiB videos
* are ~28 MiB of base64 and would strip every later status. But "exempt" must not mean unbounded —
* a 50-item seed at a 10 MiB per-item cap would be ~650 MiB of base64 on the heap at connect time.
* Four full-size items is roomy enough for a realistic story feed while keeping the bound.
*/
const INGEST_MEDIA_BUDGET_ITEMS = 4;
/**
* Aggregate budget for a pass whose caller supplies its own per-item cap. Derived from that cap so
* the two always move together; falls back to the response budget when the cap is absent/unusable.
*/
export function ingestMediaBudgetBytes(perItemMaxBytes: number): number {
if (!Number.isFinite(perItemMaxBytes) || perItemMaxBytes <= 0) return chatHistoryMediaBudgetBytes();
return Math.max(chatHistoryMediaBudgetBytes(), Math.ceil(perItemMaxBytes * INGEST_MEDIA_BUDGET_ITEMS * 1.37));
}
/**
* Coerce a sender-declared media size (a protobuf `fileLength`, which may be a number, a Long-like
* `{ toNumber() }`, a numeric string, or absent) to a finite byte count. Unknown/garbage → 0, i.e.
* "don't pre-gate" (the streaming abort is the backstop), never NaN.
*/
export function coerceDeclaredSize(value: unknown): number {
if (typeof value === 'number') return Number.isFinite(value) ? value : 0;
if (value && typeof (value as { toNumber?: () => number }).toNumber === 'function') {
const n = (value as { toNumber: () => number }).toNumber();
return Number.isFinite(n) ? n : 0;
}
const n = Number(value);
return Number.isFinite(n) ? n : 0;
}
type InboundMedia = NonNullable<IncomingMessage['media']>;
/**
* SECONDARY guard on inbound media from an untrusted sender. Within the limit, keep it (base64 via
* `toBase64`). Over the limit, drop the blob and return a marker `{ mimetype, filename?, omitted,
* sizeBytes }` so the `media` field stays present (n8n/dashboard contract) while the multi-MB base64
* is never encoded, persisted, webhooked, or broadcast — the durable amplification.
*
* `toBase64` is a lazy callback so an over-cap payload is never base64-encoded (the +33% copy). NOTE:
* this runs AFTER the bytes are in heap, so it does NOT bound the decrypted-download allocation — the
* caller must do that with the pre-download declared-size gate + the streaming abort + the concurrency
* limiter. This is the last line, not the OOM guard for the download itself.
*/
export function capInboundMedia(args: {
mimetype: string;
filename?: string;
sizeBytes: number;
toBase64: () => string;
maxBytes?: number;
}): InboundMedia {
const max = args.maxBytes ?? inboundMediaMaxBytes();
if (args.sizeBytes > max) {
return { mimetype: args.mimetype, filename: args.filename, omitted: true, sizeBytes: args.sizeBytes };
}
return { mimetype: args.mimetype, filename: args.filename, data: args.toBase64() };
}
const NO_ROOM: InboundTicket = {
reserve: () => false,
holdUntil: () => undefined,
drop: () => undefined,
revoked: false,
};
/**
* Admit a live message (EngineEventCallbacks.admitInbound) without letting a throw escape the event
* handler. A message whose admission failed still goes out, but holds no room, so its media takes the
* omitted marker instead of a download nothing bounds.
*/
export function admitInboundSafely(
admit: () => InboundTicket | undefined,
onError: (error: unknown) => void,
): InboundTicket | undefined {
try {
return admit();
} catch (error) {
onError(error);
return NO_ROOM;
}
}