Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import {
BadRequestException,
HttpException,
PayloadTooLargeException,
ServiceUnavailableException,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Repository } from 'typeorm';
import { MediaConversionService } from './media-conversion.service';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { Session } from '../session/entities/session.entity';
import * as ffmpeg from './ffmpeg';
import * as loadRemoteMedia from '../../common/media/load-remote-media';
/**
* The behaviours worth pinning here are the ones a caller can reach: that a host without ffmpeg says
* so instead of failing at spawn time, that the caller's bytes are size-checked on the way in, and —
* most of all — that a remote URL is fetched through the SSRF guard and never handed to ffmpeg,
* which would resolve it itself.
*/
describe('MediaConversionService', () => {
const config = (overrides: Record<string, unknown> = {}): ConfigService => {
const values: Record<string, unknown> = {
'mediaConversion.enabled': true,
'mediaConversion.ffmpegPath': 'ffmpeg',
'mediaConversion.timeoutMs': 60_000,
'mediaConversion.maxOutputBytes': 50 * 1024 * 1024,
...overrides,
};
return { get: (key: string, fallback?: unknown) => values[key] ?? fallback } as unknown as ConfigService;
};
/** Route param of every call below: conversion is session-scoped even though it needs no engine. */
const SESSION = '11111111-1111-4111-8111-111111111111';
/** The session-row read, so a case can assert whether the row was consulted at all. */
const findOne = jest.fn();
/**
* The service with a real (empty) engine registry and no session row, which is what every case
* except the egress-proxy ones needs.
*/
const makeService = (
configService: ConfigService = config(),
opts: { registry?: EngineRegistry; row?: Pick<Session, 'proxyUrl'> | null } = {},
): MediaConversionService => {
findOne.mockResolvedValue(opts.row ?? null);
return new MediaConversionService(configService, opts.registry ?? new EngineRegistry(), {
findOne,
} as unknown as Repository<Session>);
};
/** A registry holding a live engine for SESSION, started with the given proxy. */
const registryWith = (proxyUrl?: string): EngineRegistry => {
const registry = new EngineRegistry();
registry.set(SESSION, {} as never, proxyUrl);
return registry;
};
/** runFfmpeg(input, inputExtension, outputExtension, ...) — the third argument fixes the format. */
const outputExtensionOf = (spy: jest.SpyInstance): unknown => (spy.mock.calls[0] as unknown[])[2];
let runFfmpeg: jest.SpyInstance;
let probeFfmpeg: jest.SpyInstance;
beforeEach(() => {
findOne.mockReset();
runFfmpeg = jest.spyOn(ffmpeg, 'runFfmpeg').mockResolvedValue(Buffer.from('converted-bytes'));
probeFfmpeg = jest.spyOn(ffmpeg, 'probeFfmpeg').mockResolvedValue(true);
});
afterEach(() => jest.restoreAllMocks());
describe('input load', () => {
// A download resolved before the gate was a 50 MiB buffer for every request that had not reached a
// slot, held until the gate answered 503: peak memory was the number of requests, not the cap.
it('downloads at most as many inputs at once as it converts', async () => {
let downloading = 0;
let peak = 0;
jest.spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer').mockImplementation(async () => {
downloading++;
peak = Math.max(peak, downloading);
await new Promise(resolve => setTimeout(resolve, 15));
downloading--;
return { data: Buffer.from('input'), mimetype: 'audio/mpeg' };
});
runFfmpeg.mockImplementation(async () => {
await new Promise(resolve => setTimeout(resolve, 15));
return Buffer.from('converted-bytes');
});
const service = makeService(config({ 'mediaConversion.concurrency': 2 }));
const outcomes = await Promise.allSettled(
Array.from({ length: 30 }, () => service.convertToVoice(SESSION, { url: 'https://media.example/a.mp3' })),
);
expect(peak).toBeLessThanOrEqual(2);
expect(outcomes.filter(o => o.status === 'fulfilled')).toHaveLength(10);
const refused = outcomes.filter((o): o is PromiseRejectedResult => o.status === 'rejected');
expect(refused).toHaveLength(20);
expect(refused.every(o => o.reason instanceof ServiceUnavailableException)).toBe(true);
});
});
describe('availability', () => {
it('refuses with 503 when conversion is switched off, without probing for the binary', async () => {
const service = makeService(config({ 'mediaConversion.enabled': false }));
await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(
ServiceUnavailableException,
);
expect(probeFfmpeg).not.toHaveBeenCalled();
expect(runFfmpeg).not.toHaveBeenCalled();
});
// Enabling the flag on a host with no ffmpeg must be a clear answer, not a spawn error.
it('refuses with 503 when the binary cannot be run', async () => {
probeFfmpeg.mockResolvedValue(false);
const service = makeService(config());
await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toThrow(
/ffmpeg binary could not be run/,
);
expect(runFfmpeg).not.toHaveBeenCalled();
});
it('reports availability without converting anything', async () => {
await expect(makeService(config()).isAvailable()).resolves.toBe(true);
await expect(makeService(config({ 'mediaConversion.enabled': false })).isAvailable()).resolves.toBe(false);
});
// Concurrent first requests must not each spawn their own probe.
it('probes the binary once per process, even under concurrent first calls', async () => {
const service = makeService(config());
await Promise.all([
service.isAvailable(),
service.isAvailable(),
service.convertToVoice(SESSION, { base64: 'AAAA' }),
]);
expect(probeFfmpeg).toHaveBeenCalledTimes(1);
});
// A probe that timed out on a loaded host, or hit EAGAIN, says nothing lasting about the binary.
it('probes again after a failed probe instead of reporting unavailable until restart', async () => {
probeFfmpeg.mockResolvedValueOnce(false).mockResolvedValueOnce(true);
const service = makeService(config());
await expect(service.isAvailable()).resolves.toBe(false);
await expect(service.isAvailable()).resolves.toBe(true);
await expect(service.isAvailable()).resolves.toBe(true);
expect(probeFfmpeg).toHaveBeenCalledTimes(2);
});
});
describe('resolving the caller’s media', () => {
// The point of the whole endpoint shape: ffmpeg is handed BYTES, never a URL. Given a URL it
// would fetch the address itself, outside the guard that vets and pins the destination.
it('fetches a URL through the SSRF guard and gives ffmpeg the bytes, not the URL', async () => {
const load = jest
.spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer')
.mockResolvedValue({ data: Buffer.from('remote-audio'), mimetype: 'audio/mpeg' });
const service = makeService(config());
await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });
expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', undefined);
const [input] = runFfmpeg.mock.calls[0] as [Buffer];
expect(input).toEqual(Buffer.from('remote-audio'));
// Nothing resembling the URL may appear anywhere in the ffmpeg call.
expect(JSON.stringify(runFfmpeg.mock.calls[0])).not.toContain('example.com');
});
/**
* A conversion is a fetch the gateway makes on a session's behalf, so it has to leave from that
* session's address rather than the gateway's own (#1626). The live engine's proxy is the
* authority: PATCH /proxy does not restart the engine, so the row can already say something the
* running session does not use.
*/
describe('the egress proxy of the named session', () => {
const loadSpy = (): jest.SpyInstance =>
jest
.spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer')
.mockResolvedValue({ data: Buffer.from('remote-audio'), mimetype: 'audio/mpeg' });
it('uses the proxy the running engine was started with, not the stored row', async () => {
const load = loadSpy();
const service = makeService(config(), {
registry: registryWith('socks5://live.invalid:1080'),
row: { proxyUrl: 'http://edited-since.invalid:8080' },
});
await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });
expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', 'socks5://live.invalid:1080');
});
it('fetches direct for a running session that has no proxy, whatever the row says', async () => {
const load = loadSpy();
const service = makeService(config(), {
registry: registryWith(undefined),
row: { proxyUrl: 'http://not-in-use.invalid:8080' },
});
await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });
expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', undefined);
});
it('falls back to the stored proxy when the session has no live engine', async () => {
const load = loadSpy();
const service = makeService(config(), { row: { proxyUrl: 'socks4://stored.invalid:1080' } });
await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });
expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', 'socks4://stored.invalid:1080');
});
it('uses the saved proxy for an imported safe-string session id', async () => {
const load = loadSpy();
const service = makeService(config(), { row: { proxyUrl: 'socks5://stored.invalid:1080' } });
await service.convertToVoice('legacy-session', { url: 'https://example.com/note.m4a' });
expect(findOne).toHaveBeenCalledWith({ where: { id: 'legacy-session' }, select: { proxyUrl: true } });
expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', 'socks5://stored.invalid:1080');
});
it('keeps direct fetch behavior for an unknown safe-string id', async () => {
const load = loadSpy();
const service = makeService();
await service.convertToVoice('missing-session', { url: 'https://example.com/note.m4a' });
expect(findOne).toHaveBeenCalledTimes(1);
expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', undefined);
});
it('does not query a NUL-bearing session id', async () => {
const load = loadSpy();
const service = makeService();
await service.convertToVoice('session\0name', { url: 'https://example.com/note.m4a' });
expect(findOne).not.toHaveBeenCalled();
expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', undefined);
});
// The row read is server-side I/O, not part of the caller's input. Mapped as a bad URL it
// would answer 400 with the driver's own message, telling a client to stop retrying a
// failover or a locked SQLite file.
it('does not report a failed row read as a bad URL', async () => {
const load = loadSpy();
const service = makeService();
findOne.mockRejectedValue(new Error('SQLITE_BUSY: database is locked'));
const failure: unknown = await service
.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' })
.catch((error: unknown) => error);
expect(failure).not.toBeInstanceOf(HttpException);
expect(failure).toMatchObject({ message: 'SQLITE_BUSY: database is locked' });
expect(load).not.toHaveBeenCalled();
});
});
// A fault in the fetch that is not about the caller's URL is the server's, and its message can
// name the session proxy; it must not come back to the client as a 400.
it('does not report a server-side fetch fault as a bad URL', async () => {
const fault = new Error('Unsupported proxy protocol: gopher://user:[email protected]');
jest.spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer').mockRejectedValue(fault);
const service = makeService(config());
const failure: unknown = await service
.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' })
.catch((error: unknown) => error);
expect(failure).toBe(fault);
});
it('decodes base64, stripping a data: prefix', async () => {
const service = makeService(config());
await service.convertToVoice(SESSION, {
base64: `data:audio/mpeg;base64,${Buffer.from('inline').toString('base64')}`,
});
expect((runFfmpeg.mock.calls[0] as [Buffer])[0]).toEqual(Buffer.from('inline'));
});
it.each(['convertToVoice', 'convertToVideo'] as const)(
'%s uses the URL when a data URI carries no base64 bytes',
async method => {
const load = jest
.spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer')
.mockResolvedValue({ data: Buffer.from('remote-media'), mimetype: 'audio/mpeg' });
const service = makeService(config(), { registry: registryWith('socks5://live.invalid:1080') });
await service[method](SESSION, {
base64: 'data:audio/mpeg;base64,',
url: 'https://example.com/media',
});
expect((runFfmpeg.mock.calls[0] as [Buffer])[0]).toEqual(Buffer.from('remote-media'));
expect(load).toHaveBeenCalledWith('https://example.com/media', 'socks5://live.invalid:1080');
},
);
it('keeps nonempty base64 ahead of a stale URL', async () => {
const load = jest.spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer');
await makeService().convertToVoice(SESSION, {
base64: 'data:audio/mpeg;base64,aW5saW5l',
url: 'https://example.com/ignored',
});
expect((runFfmpeg.mock.calls[0] as [Buffer])[0]).toEqual(Buffer.from('inline'));
expect(load).not.toHaveBeenCalled();
});
it('rejects base64 above the media cap with 413, before any conversion', async () => {
const service = makeService(config());
const oversized = Buffer.alloc(51 * 1024 * 1024).toString('base64');
await expect(service.convertToVoice(SESSION, { base64: oversized })).rejects.toBeInstanceOf(
PayloadTooLargeException,
);
expect(runFfmpeg).not.toHaveBeenCalled();
});
it('rejects a request carrying neither url nor base64', async () => {
await expect(makeService(config()).convertToVoice(SESSION, {})).rejects.toThrow(
/Either url or base64 must be provided/,
);
});
it('rejects base64 that decodes to nothing', async () => {
await expect(makeService(config()).convertToVoice(SESSION, { base64: '!!!' })).rejects.toThrow(/did not decode/);
});
});
describe('conversion', () => {
it('returns Ogg/Opus for voice, which is what makes a playable mic bubble', async () => {
const service = makeService(config());
const result = await service.convertToVoice(SESSION, { base64: 'AAAA' });
expect(result).toEqual({
base64: Buffer.from('converted-bytes').toString('base64'),
mimetype: 'audio/ogg; codecs=opus',
bytes: 15,
});
expect(outputExtensionOf(runFfmpeg)).toBe('ogg');
});
it('returns MP4 for video', async () => {
const service = makeService(config());
const result = await service.convertToVideo(SESSION, { base64: 'AAAA' });
expect(result.mimetype).toBe('video/mp4');
expect(outputExtensionOf(runFfmpeg)).toBe('mp4');
});
// ffmpeg's complaint is about the caller's own bytes, so surfacing it is what makes a 400 useful.
it('turns an ffmpeg refusal into a 400 carrying its reason', async () => {
runFfmpeg.mockRejectedValue(new ffmpeg.FfmpegConversionError('ffmpeg exited with code 1', 'Invalid data found'));
const service = makeService(config());
await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(BadRequestException);
await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toThrow(/Invalid data found/);
});
// A spawn that fails (EAGAIN, EMFILE, a binary removed by an upgrade) is the host's fault, not the
// caller's, so it answers the documented 503 and the binary is probed again on the next call.
it('answers 503, not 400, when ffmpeg cannot be started, and probes again', async () => {
runFfmpeg.mockRejectedValue(new ffmpeg.FfmpegSpawnError('Could not run ffmpeg: spawn ffmpeg EAGAIN'));
const service = makeService(config());
await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(
ServiceUnavailableException,
);
await service.isAvailable();
expect(probeFfmpeg).toHaveBeenCalledTimes(2);
});
// A programming error must not be relabelled as the caller's fault.
it('lets an unexpected error through rather than reporting it as a bad request', async () => {
runFfmpeg.mockRejectedValue(new TypeError('boom'));
const service = makeService(config());
await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(TypeError);
});
});
describe('concurrency gate', () => {
// The rate limiter caps admission per second, not how many long-running ffmpeg processes stack
// up while each runs toward its timeout — that bound lives here.
it('bounds concurrent ffmpeg runs and answers 503 past the queue instead of stacking processes', async () => {
// concurrency 1 → queue depth 4: five simultaneous requests fill the gate, the sixth is refused.
const service = makeService(config({ 'mediaConversion.concurrency': 1 }));
let release!: () => void;
runFfmpeg.mockImplementation(
() =>
new Promise<Buffer>(resolve => {
release = () => resolve(Buffer.from('x'));
}),
);
const inflight = Array.from({ length: 5 }, () => service.convertToVoice(SESSION, { base64: 'AAAA' }));
await new Promise(resolve => setImmediate(resolve));
expect(runFfmpeg).toHaveBeenCalledTimes(1);
await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(
ServiceUnavailableException,
);
// Drain: release each run in turn so every parked task completes and nothing leaks.
for (let i = 0; i < 5; i++) {
release();
await new Promise(resolve => setImmediate(resolve));
}
await Promise.all(inflight);
expect(runFfmpeg).toHaveBeenCalledTimes(5);
});
});
describe('shutdown', () => {
// Nest's own signal handler re-raises the signal after its hooks run, so the process dies from it
// and never emits `exit`. The shutdown hook is what still reaches the detached ffmpeg groups then.
it('kills the running ffmpeg groups when the application shuts down', () => {
const kill = jest.spyOn(ffmpeg, 'killRunningConversions').mockImplementation(() => undefined);
makeService().onApplicationShutdown();
expect(kill).toHaveBeenCalledTimes(1);
});
});
});