Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(plugins): name the error a sandboxed worker died of
Yudhi Armyndharisc91aeb44c548
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e5580f6ef..dbaf149c4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -126,6 +126,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Decode numeric and common named character references in a Baileys link preview's title and description, so `’` and `é` no longer reach the recipient as written.- Log an error at whatsapp-web.js start when the message-id backport is only partly applied, naming the files it did not reach.- Handle an engine disconnect again when the session row read fails, so the session reconnects instead of staying registered with no reconnect armed.+- Show the error a sandboxed plugin's worker threw before it died in the plugin's status and the log, instead of only its exit code.### Documentationdiff --git a/src/core/plugins/plugin-loader-sandbox-routing.spec.ts b/src/core/plugins/plugin-loader-sandbox-routing.spec.tsindex 57c908166..ccf5b5988 100644--- a/src/core/plugins/plugin-loader-sandbox-routing.spec.ts+++ b/src/core/plugins/plugin-loader-sandbox-routing.spec.ts@@ -20,7 +20,7 @@ class TestableLoader extends PluginLoaderService {readonly hosts: FakeHost[] = [];capturedOnHookSubscribe?: (event: string, priority?: number) => void;capturedOnLog?: (level: PluginLogLevel, message: string, meta?: Record<string, unknown>) => void;- capturedOnWorkerExit?: (code: number, intentional: boolean) => void;+ capturedOnWorkerExit?: (code: number, intentional: boolean, reason?: string) => void;capturedOnUnresponsive?: () => void;protected createSandboxHost(_capDispatcher?: (verb: string, args: unknown[]) => Promise<unknown>,@@ -29,7 +29,7 @@ class TestableLoader extends PluginLoaderService {onLog?: (level: PluginLogLevel, message: string, meta?: Record<string, unknown>) => void,_runWithHookGuard?: (inFlightEvents: string[], run: () => Promise<unknown>) => Promise<unknown>,_onSearchProviderRegister?: () => void,- onWorkerExit?: (code: number, intentional: boolean) => void,+ onWorkerExit?: (code: number, intentional: boolean, reason?: string) => void,onUnresponsive?: () => void,): PluginWorkerHost {this.capturedOnHookSubscribe = onHookSubscribe;@@ -272,6 +272,19 @@ describe('PluginLoaderService — sandbox tier routing', () => {});});+ it('shows why a sandboxed worker died when it reported a reason before exiting', async () => {+ const loader = makeLoader();+ seed(loader, { builtIn: false, instance: null });+ await loader.enablePlugin('p1');+ jest+ .spyOn((loader as unknown as { logger: { warn: jest.Mock } }).logger, 'warn')+ .mockImplementation(() => undefined);++ loader.capturedOnWorkerExit!(1, false, 'boom: relay answered 500');++ expect(pluginOf(loader).error).toBe('worker exited unexpectedly (code 1): boom: relay answered 500');+ });+it('enables a built-in plugin in-process (no sandbox worker spawned)', async () => {const loader = makeLoader();const onEnable = jest.fn().mockResolvedValue(undefined);diff --git a/src/core/plugins/plugin-loader.service.ts b/src/core/plugins/plugin-loader.service.tsindex dd00f134b..33422e104 100644--- a/src/core/plugins/plugin-loader.service.ts+++ b/src/core/plugins/plugin-loader.service.ts@@ -449,7 +449,7 @@ export class PluginLoaderService implements OnModuleInit, OnApplicationBootstraponLog?: (level: PluginLogLevel, message: string, meta?: Record<string, unknown>) => void,runWithHookGuard?: (inFlightEvents: string[], run: () => Promise<unknown>) => Promise<unknown>,onSearchProviderRegister?: () => void,- onWorkerExit?: (code: number, intentional: boolean) => void,+ onWorkerExit?: (code: number, intentional: boolean, reason?: string) => void,onUnresponsive?: () => void,): PluginWorkerHost {const workerEntry = path.join(__dirname, 'sandbox', 'worker-bootstrap.js');diff --git a/src/core/plugins/plugin-sandbox-bridge.ts b/src/core/plugins/plugin-sandbox-bridge.tsindex 7eae891ec..9700e1b3a 100644--- a/src/core/plugins/plugin-sandbox-bridge.ts+++ b/src/core/plugins/plugin-sandbox-bridge.ts@@ -65,7 +65,7 @@ type CreateSandboxHostFn = (onLog?: (level: PluginLogLevel, message: string, meta?: Record<string, unknown>) => void,runWithHookGuard?: (inFlightEvents: string[], run: () => Promise<unknown>) => Promise<unknown>,onSearchProviderRegister?: () => void,- onWorkerExit?: (code: number, intentional: boolean) => void,+ onWorkerExit?: (code: number, intentional: boolean, reason?: string) => void,onUnresponsive?: () => void,) => PluginWorkerHost;@@ -646,8 +646,8 @@ export class PluginSandboxBridge {private buildWorkerExitHandler(pluginId: string,logRelayState: SandboxLogRelayState,- ): (code: number, intentional: boolean) => void {- return (code: number, intentional: boolean): void => {+ ): (code: number, intentional: boolean, reason?: string) => void {+ return (code: number, intentional: boolean, reason?: string): void => {// Final log-relay flush: the per-window drop warn above only fires when a new line arrives in a// later window, so without this a plugin that goes quiet (or is disabled) before the rollover// silently discards its pending count. The worker is gone, so no further lines can arrive.@@ -667,8 +667,9 @@ export class PluginSandboxBridge {// unregister the hook shims (so they don't keep dispatching into the dead worker) + mark the// plugin ERROR so the dashboard reflects reality. The dispatchHook/dispatchWebhook dead-checks// fail-fast; this cleanup is the root-cause fix (it also makes the shim's !liveHost guard fire).- this.markWorkerFailed(pluginId, `worker exited unexpectedly (code ${code})`);- this.logger.warn(`Sandboxed plugin ${pluginId} worker exited unexpectedly (code ${code})`, {+ const why = reason ? `: ${reason}` : '';+ this.markWorkerFailed(pluginId, `worker exited unexpectedly (code ${code})${why}`);+ this.logger.warn(`Sandboxed plugin ${pluginId} worker exited unexpectedly (code ${code})${why}`, {pluginId,code,action: 'sandbox_worker_exit',diff --git a/src/core/plugins/sandbox/plugin-worker-host.spec.ts b/src/core/plugins/sandbox/plugin-worker-host.spec.tsindex 12d4dd20d..c84291be0 100644--- a/src/core/plugins/sandbox/plugin-worker-host.spec.ts+++ b/src/core/plugins/sandbox/plugin-worker-host.spec.ts@@ -137,6 +137,55 @@ describe('PluginWorkerHost', () => {await expect(p).rejects.toThrow(/exit/i);});+ // A worker that dies from an exception after it enabled reports the real reason as an error message+ // just before it exits: with no load() waiting, the exit used to be all the host kept.+ describe('the error a worker reports before it exits', () => {+ const hostWithExit = (ch: FakeChannel, onExit: jest.Mock): PluginWorkerHost =>+ new PluginWorkerHost(ch, undefined, undefined, undefined, undefined, undefined, undefined, undefined, onExit);++ it('is named by the rejection of a call the exit drains and by the exit callback', async () => {+ const ch = new FakeChannel();+ const onExit = jest.fn();+ const host = hostWithExit(ch, onExit);+ void host.load('/p/index.js');+ ch.reply({ kind: 'ready' });+ const p = host.runLifecycle('onEnable');++ ch.reply({ kind: 'error', error: 'boom: relay answered 500' });+ ch.crash(1);++ await expect(p).rejects.toThrow('plugin worker exited unexpectedly (code 1): boom: relay answered 500');+ expect(onExit).toHaveBeenCalledWith(1, false, 'boom: relay answered 500');+ });++ it('is cut to one bounded line, since the plugin chose it', () => {+ const ch = new FakeChannel();+ const onExit = jest.fn();+ hostWithExit(ch, onExit);++ ch.reply({ kind: 'error', error: `first\nsecond ${'x'.repeat(2000)}` });+ ch.crash(1);++ const reason = (onExit.mock.calls[0] as [number, boolean, string])[2];+ expect(reason.startsWith('first second x')).toBe(true);+ expect(reason.length).toBeLessThanOrEqual(500);+ });++ it('leaves the message and the callback as they were when the worker reported nothing', async () => {+ const ch = new FakeChannel();+ const onExit = jest.fn();+ const host = hostWithExit(ch, onExit);+ void host.load('/p/index.js');+ ch.reply({ kind: 'ready' });+ const p = host.runLifecycle('onEnable');++ ch.crash(1);++ await expect(p).rejects.toThrow(/^plugin worker exited unexpectedly \(code 1\)$/);+ expect(onExit).toHaveBeenCalledWith(1, false, undefined);+ });+ });+it('terminate() terminates the underlying channel', async () => {const ch = new FakeChannel();const host = new PluginWorkerHost(ch);diff --git a/src/core/plugins/sandbox/plugin-worker-host.ts b/src/core/plugins/sandbox/plugin-worker-host.tsindex 9626a9fdc..802506054 100644--- a/src/core/plugins/sandbox/plugin-worker-host.ts+++ b/src/core/plugins/sandbox/plugin-worker-host.ts@@ -24,6 +24,9 @@ const SEND_CAP_VERBS: ReadonlySet<string> = new Set(['messages.sendText', 'messa/** Send-verb budget as a multiple of capTimeoutMs (default 30s → 120s: the 30s media download + upload headroom). */const SEND_CAP_TIMEOUT_FACTOR = 4;+/** Longest worker-reported error kept for an exit message and the plugin's status. */+const MAX_WORKER_ERROR_CHARS = 500;+/** Worker replies that finish a host request; one arriving during a liveness probe restarts its window. */const PROGRESS_KINDS: ReadonlySet<WorkerToHostMessage['kind']> = new Set(['lifecycle-result',@@ -95,6 +98,9 @@ export class PluginWorkerHost {// True once terminate() is called, so onExit can tell a deliberate kill (disable/enable-failure) from an// unexpected worker crash — only the latter is logged as a warning.private terminated = false;+ // The last error the worker reported (an uncaught exception arrives as one just before the exit), kept for+ // the exit: once the worker is ready no load() waits for it. Plugin-chosen text, so one bounded line.+ private lastWorkerError?: string;// The liveness probe in flight, if any, and whether onUnresponsive has already fired (it fires once).private probe?: { id: number; timer: ReturnType<typeof setTimeout> };private unresponsiveReported = false;@@ -127,7 +133,8 @@ export class PluginWorkerHost {private readonly onSearchProviderRegister?: () => void,// Called once after the worker exits (crash or terminate), after in-flight calls are drained, so the// loader can release plugin-owned host resources (e.g. unregister a search provider the worker declared).- private readonly onExit?: (code: number, intentional: boolean) => void,+ // `reason` is the last error the worker reported before it exited, when it reported one.+ private readonly onExit?: (code: number, intentional: boolean, reason?: string) => void,// Host-side budget for ONE capability call. A worker whose calls hang would otherwise hold its// in-flight slots forever (self-DoS once maxInFlightCaps are all wedged). On timeout the worker gets// an error cap-result and the slot frees; the underlying host-side work is NOT cancelled (see@@ -424,6 +431,7 @@ export class PluginWorkerHost {});break;case 'error': {+ this.lastWorkerError = String(message.error).replace(/\s+/g, ' ').slice(0, MAX_WORKER_ERROR_CHARS);const error = new Error(message.error);this.drain(this.readyWaiters, w => {if (w.timer) clearTimeout(w.timer);@@ -605,7 +613,9 @@ export class PluginWorkerHost {clearTimeout(this.probe.timer);this.probe = undefined;}- const error = new Error(`plugin worker exited unexpectedly (code ${code})`);+ const error = new Error(+ `plugin worker exited unexpectedly (code ${code})${this.lastWorkerError ? `: ${this.lastWorkerError}` : ''}`,+ );this.drain(this.readyWaiters, w => {if (w.timer) clearTimeout(w.timer);w.reject(error);@@ -643,7 +653,7 @@ export class PluginWorkerHost {resolve({ ok: false, error: 'plugin worker exited' });});this.searchPending.clear();- this.onExit?.(code, this.terminated);+ this.onExit?.(code, this.terminated, this.lastWorkerError);}private drain<T>(waiters: T[], fn: (w: T) => void): void {