Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import * as path from 'path';
import { WorkerThreadChannel } from './worker-thread-channel';
import { PluginWorkerHost } from './plugin-worker-host';
// Repo root, from src/core/plugins/sandbox.
const ROOT = path.resolve(__dirname, '../../../..');
const BOOTSTRAP = path.resolve(__dirname, 'worker-bootstrap.ts');
const FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/echo-plugin.cjs');
const CAP_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/cap-echo-plugin.cjs');
const HOOK_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/hook-plugin.cjs');
const HOOK_HANG_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/hook-hang-plugin.cjs');
const BUSY_HOOK_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/busy-hook-plugin.cjs');
const RUNAWAY_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/runaway-plugin.cjs');
const CTX_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/ctx-aware-plugin.cjs');
const HOOK_CONFIG_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/hook-config-plugin.cjs');
const HOOK_ERROR_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/hook-error-plugin.cjs');
const CTX_LIFECYCLE_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/ctx-lifecycle-plugin.cjs');
const SEARCH_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/search-plugin.cjs');
const UNLOAD_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/unload-plugin.cjs');
const UNCLONEABLE_LOG_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/uncloneable-log-plugin.cjs');
const CONFIG_THROW_FIXTURE = path.resolve(ROOT, 'test/fixtures/sandbox/config-throw-plugin.cjs');
const flushAsync = (): Promise<void> => new Promise(resolve => setImmediate(resolve));
// Run the TS bootstrap inside the worker via ts-node. The base tsconfig is nodenext; we pin the
// worker's transpile to CommonJS (same override the jest/ts-jest config uses) so `require()` works.
// Production loads the compiled `worker-bootstrap.js` directly and needs none of this.
const TS_NODE_OPTS = JSON.stringify({
module: 'commonjs',
moduleResolution: 'node',
resolvePackageJsonExports: false,
// Same bridge as the jest/ts-jest override: TypeScript 6 rejects the legacy resolution pair
// outright unless the deprecation is acknowledged. Revisit before TypeScript 7.
ignoreDeprecations: '6.0',
});
const makeChannel = (): WorkerThreadChannel =>
new WorkerThreadChannel({
workerEntry: BOOTSTRAP,
execArgv: ['-r', 'ts-node/register/transpile-only'],
env: { ...process.env, TS_NODE_COMPILER_OPTIONS: TS_NODE_OPTS },
});
const makeHost = (capDispatcher?: (verb: string, args: unknown[]) => Promise<unknown>): PluginWorkerHost =>
new PluginWorkerHost(makeChannel(), capDispatcher);
describe('plugin worker — real worker_threads round-trip (B1)', () => {
jest.setTimeout(30000);
it('loads a plugin and runs its lifecycle in a real worker thread', async () => {
const host = makeHost();
await host.load(FIXTURE);
await host.runLifecycle('onEnable');
await host.runLifecycle('onDisable');
await host.terminate();
});
it('dispatches onUnload to the plugin inside the worker (the hook the loader fires on uninstall)', async () => {
const host = makeHost();
await host.load(UNLOAD_FIXTURE);
await host.runLifecycle('onEnable');
await expect(host.healthCheck(3000)).resolves.toMatchObject({ message: 'loaded' });
await host.runLifecycle('onUnload');
// The worker-side instance observed its onUnload — before this hook was dispatched on the
// unload path, a sandboxed plugin's cleanup (timers, connections) never ran.
await expect(host.healthCheck(3000)).resolves.toMatchObject({ message: 'unloaded' });
await host.terminate();
});
it('rejects load() when the plugin module cannot be required', async () => {
const host = makeHost();
await expect(host.load(path.resolve(ROOT, 'test/fixtures/sandbox/missing.cjs'))).rejects.toThrow();
await host.terminate();
});
it('round-trips a capability call: the worker plugin invokes ctx.messages.sendText and gets the result', async () => {
const dispatcher = jest.fn().mockResolvedValue({ messageId: 'wamid' });
const host = makeHost(dispatcher);
await host.load(CAP_FIXTURE);
// onEnable awaits ctx.messages.sendText and throws unless it gets { messageId: 'wamid' } back,
// so this resolving proves the full worker -> host -> worker round-trip.
await host.runLifecycle('onEnable');
expect(dispatcher).toHaveBeenCalledWith('messages.sendText', ['s', 'c', 'hi']);
await host.terminate();
});
it('round-trips a hook: the worker registers a handler, the host dispatches and gets continue/data', async () => {
const subscribed: string[] = [];
const host = new PluginWorkerHost(makeChannel(), undefined, event => subscribed.push(event));
await host.load(HOOK_FIXTURE);
await host.runLifecycle('onEnable'); // the plugin registers its hook here
await flushAsync(); // let the hook-subscribe message land
expect(subscribed).toContain('message:received');
const result = await host.dispatchHook({
event: 'message:received',
data: { body: 'hi' },
source: 'Engine',
timeoutMs: 5000,
});
expect(result).toEqual({ continue: false, data: { body: 'hi', seen: true } });
await host.terminate();
});
it('a wedged worker hook handler times out so the host chain proceeds', async () => {
const host = new PluginWorkerHost(makeChannel(), undefined, () => undefined);
await host.load(HOOK_HANG_FIXTURE);
await host.runLifecycle('onEnable');
await flushAsync();
const onTimeout = jest.fn();
const result = await host.dispatchHook({
event: 'message:received',
data: {},
source: 'Engine',
timeoutMs: 200,
onTimeout,
});
expect(result).toEqual({ continue: true });
expect(onTimeout).toHaveBeenCalled();
await host.terminate();
});
it('force-terminates a runaway (infinite-loop) plugin', async () => {
const host = makeHost();
await host.load(RUNAWAY_FIXTURE);
// onEnable spins forever and blocks the worker event loop — it can never reply, so cooperative
// shutdown is impossible. terminate() must still reclaim the thread.
const wedged = host.runLifecycle('onEnable');
wedged.catch(() => undefined); // terminate() rejects this pending call; swallow it
// Poll until the loop is genuinely blocked rather than sleeping a fixed 150ms: the health-check
// message is queued behind the onEnable call (FIFO on one channel), so it can only time out once
// the infinite loop has actually started. Firing terminate() earlier would reclaim an idle worker
// and prove nothing.
const wedgeDeadline = Date.now() + 10_000;
for (;;) {
const health = await host.healthCheck(150);
if (!health.healthy) break;
if (Date.now() > wedgeDeadline) throw new Error('runaway plugin never blocked the worker event loop');
}
await expect(host.terminate()).resolves.toBeUndefined();
});
const probingHost = (onUnresponsive: () => void): PluginWorkerHost =>
new PluginWorkerHost(
makeChannel(),
undefined,
() => undefined,
undefined,
undefined,
undefined,
undefined,
undefined,
undefined,
undefined,
300,
onUnresponsive,
);
it('a slow async hook handler answers the liveness probe, so it is not reported', async () => {
const onUnresponsive = jest.fn();
const host = probingHost(onUnresponsive);
try {
await host.load(HOOK_HANG_FIXTURE);
await host.runLifecycle('onEnable');
await flushAsync();
await host.dispatchHook({ event: 'message:received', data: {}, source: 'Engine', timeoutMs: 200 });
await new Promise(resolve => setTimeout(resolve, 900));
expect(onUnresponsive).not.toHaveBeenCalled();
} finally {
await host.terminate();
}
});
it('a worker working through a burst of short synchronous handlers is not reported', async () => {
const onUnresponsive = jest.fn();
const host = probingHost(onUnresponsive);
try {
await host.load(BUSY_HOOK_FIXTURE);
await host.runLifecycle('onEnable');
await flushAsync();
// ~1 s of queued work against a 300 ms hook budget and a 300 ms probe: most dispatches time out
// and the ping waits behind the backlog, but results keep arriving the whole time.
const burst = Array.from({ length: 100 }, () =>
host.dispatchHook({ event: 'message:received', data: {}, source: 'Engine', timeoutMs: 300 }),
);
await Promise.all(burst);
await expect(host.healthCheck(5000)).resolves.toMatchObject({ healthy: true });
expect(onUnresponsive).not.toHaveBeenCalled();
} finally {
await host.terminate();
}
});
it('reports a worker whose event loop is blocked, and terminate() reclaims it', async () => {
let reported!: () => void;
const unresponsive = new Promise<void>(resolve => (reported = resolve));
const host = probingHost(() => reported());
try {
await host.load(RUNAWAY_FIXTURE);
const wedged = host.runLifecycle('onEnable');
wedged.catch(() => undefined); // terminate() rejects this pending call
// The dispatch queues behind the spinning onEnable and times out; the ping behind it is never read.
await host.dispatchHook({ event: 'message:received', data: {}, source: 'Engine', timeoutMs: 200 });
await unresponsive;
} finally {
await expect(host.terminate()).resolves.toBeUndefined();
}
});
it('a throwing worker hook handler is reported back on the hook-result (not silently swallowed)', async () => {
const host = new PluginWorkerHost(makeChannel(), undefined, () => undefined);
await host.load(HOOK_ERROR_FIXTURE);
await host.runLifecycle('onEnable');
await flushAsync();
// The chain still fails open (continue:true) — but the worker's error crosses the wire so the
// host can log it and record it for the plugin's health surface. `data` round-trips untouched.
const result = await host.dispatchHook({
event: 'message:received',
data: {},
source: 'Engine',
timeoutMs: 5000,
});
expect(result).toEqual({ continue: true, data: {}, error: 'intentional hook failure' });
await host.terminate();
});
it('preserves a structured-clone-safe hook payload across the worker boundary', async () => {
const host = new PluginWorkerHost(makeChannel(), undefined, () => undefined);
await host.load(HOOK_FIXTURE); // its handler returns { ...data, seen: true }
await host.runLifecycle('onEnable');
await flushAsync();
const payload = {
body: 'hi',
mentions: ['[email protected]', '[email protected]'],
meta: { ts: new Date('2026-06-22T00:00:00.000Z'), nested: { n: 1 } },
};
const result = await host.dispatchHook({
event: 'message:received',
data: payload,
source: 'Engine',
timeoutMs: 5000,
});
const data = result.data as typeof payload & { seen: boolean };
expect(data.mentions).toEqual(['[email protected]', '[email protected]']);
expect(data.meta.nested).toEqual({ n: 1 });
expect(data.meta.ts.getTime()).toBe(new Date('2026-06-22T00:00:00.000Z').getTime());
expect(data.seen).toBe(true);
await host.terminate();
});
it('exposes the host-resolved per-session config slice as ctx.config during a hook', async () => {
const host = new PluginWorkerHost(makeChannel(), undefined, () => undefined);
await host.load(HOOK_CONFIG_FIXTURE, { pluginId: 'hc', config: { greeting: 'base', lang: 'en' } });
await host.runLifecycle('onEnable');
await flushAsync();
// A dispatch carrying the resolved slice → the handler sees exactly that as ctx.config.
const overridden = await host.dispatchHook({
event: 'message:received',
data: {},
source: 'Engine',
timeoutMs: 5000,
config: { greeting: 'hello-A', lang: 'en', extra: 1 },
});
expect((overridden.data as { config: unknown }).config).toEqual({ greeting: 'hello-A', lang: 'en', extra: 1 });
// No resolved slice → ctx.config falls back to the base config.
const base = await host.dispatchHook({ event: 'message:received', data: {}, source: 'Engine', timeoutMs: 5000 });
expect((base.data as { config: unknown }).config).toEqual({ greeting: 'base', lang: 'en' });
await host.terminate();
});
it('keeps ctx.config correct when hooks for different sessions interleave across an await', async () => {
const host = new PluginWorkerHost(makeChannel(), undefined, () => undefined);
await host.load(HOOK_CONFIG_FIXTURE, { pluginId: 'hc', config: { who: 'base' } });
await host.runLifecycle('onEnable');
await flushAsync();
// Dispatch A (slow: reads ctx.config AFTER an await) and B (fast) concurrently. Without an
// AsyncLocalStorage scope, B's config would clobber a shared ctx.config and A would read B's.
const [a, b] = await Promise.all([
host.dispatchHook({
event: 'message:received',
data: { delay: 80 },
source: 'Engine',
timeoutMs: 5000,
config: { who: 'session-A' },
}),
host.dispatchHook({
event: 'message:received',
data: { delay: 0 },
source: 'Engine',
timeoutMs: 5000,
config: { who: 'session-B' },
}),
]);
expect((a.data as { config: { who: string } }).config.who).toBe('session-A');
expect((b.data as { config: { who: string } }).config.who).toBe('session-B');
await host.terminate();
});
it('bridges ctx.logger and ctx.config into a sandboxed plugin', async () => {
const logs: Array<{ level: string; message: string; meta?: Record<string, unknown> }> = [];
const host = new PluginWorkerHost(makeChannel(), undefined, undefined, undefined, (level, message, meta) =>
logs.push({ level, message, meta }),
);
await host.load(CTX_FIXTURE, { pluginId: 'ctx-demo', config: { greeting: 'hi' } });
await host.runLifecycle('onEnable');
await flushAsync();
// The plugin read ctx.pluginId + ctx.config and logged via ctx.logger; all of it crossed the bridge.
expect(logs).toContainEqual({ level: 'log', message: 'hello from ctx-demo', meta: { greeting: 'hi' } });
await host.terminate();
});
it('keeps the worker alive when a timer logs a meta the structured clone cannot copy', async () => {
const logs: Array<{ level: string; message: string; meta?: Record<string, unknown> }> = [];
const host = new PluginWorkerHost(makeChannel(), undefined, undefined, undefined, (level, message, meta) =>
logs.push({ level, message, meta }),
);
try {
await host.load(UNCLONEABLE_LOG_FIXTURE, { pluginId: 'uncloneable-log', config: {} });
await host.runLifecycle('onEnable');
// A DataCloneError thrown from the timer used to be uncaught in the worker, so the worker exited.
await expect(host.healthCheck(3000)).resolves.toEqual({ healthy: true, message: 'alive' });
expect(logs).toContainEqual({ level: 'warn', message: 'timer log', meta: undefined });
// The error reason is a string, so it still crosses when the rest of the meta cannot.
expect(logs).toContainEqual({ level: 'error', message: 'timer error', meta: { error: 'upstream down' } });
} finally {
await host.terminate();
}
});
it('keeps the worker alive when a synchronous onConfigChange throws, and logs why', async () => {
const logs: Array<{ level: string; message: string; meta?: Record<string, unknown> }> = [];
const onExit = jest.fn();
const host = new PluginWorkerHost(
makeChannel(),
undefined,
undefined,
undefined,
(level, message, meta) => logs.push({ level, message, meta }),
undefined,
undefined,
undefined,
onExit,
);
try {
await host.load(CONFIG_THROW_FIXTURE, { pluginId: 'config-throw', config: { mode: 'ok' } });
await host.runLifecycle('onEnable');
host.sendConfigChange({ mode: 'bad' });
await expect(host.healthCheck(3000)).resolves.toEqual({ healthy: true, message: 'alive' });
expect(logs).toContainEqual({
level: 'error',
message: 'onConfigChange threw',
meta: { error: 'unsupported mode: bad' },
});
expect(onExit).not.toHaveBeenCalled();
} finally {
await host.terminate();
}
});
it('delivers healthCheck and onConfigChange to a sandboxed plugin (and refreshes ctx.config)', async () => {
const host = new PluginWorkerHost(makeChannel());
await host.load(CTX_LIFECYCLE_FIXTURE, { pluginId: 'ctx-lc', config: { a: 1 } });
await host.runLifecycle('onEnable');
// healthCheck reaches the worker plugin and returns ITS result (here it reports its current config).
await expect(host.healthCheck(3000)).resolves.toEqual({ healthy: true, message: JSON.stringify({ a: 1 }) });
// A config change refreshes ctx.config in the worker (and would invoke onConfigChange).
host.sendConfigChange({ a: 2 });
await flushAsync();
await expect(host.healthCheck(3000)).resolves.toEqual({ healthy: true, message: JSON.stringify({ a: 2 }) });
await host.terminate();
});
it('round-trips a search: the worker registers a provider and the host dispatches a query', async () => {
let registered = false;
const host = new PluginWorkerHost(
makeChannel(),
undefined,
undefined,
undefined,
undefined,
undefined,
undefined,
() => {
registered = true;
},
);
await host.load(SEARCH_FIXTURE, { pluginId: 'search-fixture', config: {} });
await host.runLifecycle('onEnable'); // the plugin calls ctx.registerSearchProvider here
await flushAsync(); // let search-provider-register land
expect(registered).toBe(true);
const reply = await host.dispatchSearch({ query: { q: 'hello' }, timeoutMs: 5000 });
expect(reply.ok).toBe(true);
if (reply.ok) {
expect(reply.results.provider).toBe('plugin:search-fixture');
expect(reply.results.hits).toHaveLength(1);
expect(reply.results.hits[0].body).toBe('match for hello');
expect(reply.results.hits[0].snippet).toBe('<mark>hello</mark>');
}
// Empty query → empty hits (structured-clone-safe SearchResults round-trip).
const empty = await host.dispatchSearch({ query: { q: '' }, timeoutMs: 5000 });
expect(empty.ok).toBe(true);
if (empty.ok) expect(empty.results.hits).toEqual([]);
await host.terminate();
});
});