Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(plugins): name the error a sandboxed worker died of

Yudhi Armyndharisc91aeb44c548
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.
### Documentation
diff --git a/src/core/plugins/plugin-loader-sandbox-routing.spec.ts b/src/core/plugins/plugin-loader-sandbox-routing.spec.ts
index 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.ts
index 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, OnApplicationBootstrap
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 {
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.ts
index 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.ts
index 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.ts
index 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 {