Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

18.2 KB
Raw Blame
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();
  });
});