Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(plugins): disable running plugins before waiting on in-flight enables (#1831)

Yudhi Armyndharis56f69e90b7c9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 135561f91..c74104d42 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- Disable plugins whose enable is still running at shutdown, after the running ones, and refuse new plugin enables during teardown.
- Refuse session starts with `503` once shutdown begins, including one already past its checks.
- Leave a session start that shutdown interrupts for the next boot instead of marking it failed.
- Destroy session engines at shutdown before waiting on a boot auto-start launch, and bound that wait, so a stalled launch no longer holds teardown past the kill deadline.
@@ -48,7 +49,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Keep a new dashboard template draft when an earlier template save finishes.
- Stop the dashboard Chats page from marking the open chat read on a newly selected session.
- Refuse bulk batches once shutdown begins, and answer `503` for a batch saved during shutdown instead of sending it.
-- Disable plugins whose enable is still running at shutdown, and refuse new plugin enables during teardown.
- Stop in-flight webhook replay, ingress replay and pending-message sweeps at shutdown, waiting a bounded time for a replay in hand.
- Close queue workers, waiting up to 15 s for running jobs, before plugins shut down, so no new job is taken against stopped plugins.
- Answer new HTTP requests other than health probes with `503` once teardown begins after SIGTERM, SIGINT or `POST /api/infra/restart`.
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index 47f06ad58..3a4dad197 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -579,8 +579,9 @@ double-enable, and engines must match the configured active engine):
**Disable / unload / uninstall.** `disablePlugin` runs `onDisable` (force-terminating the worker for a
sandboxed plugin, even if `onDisable` hangs or throws) and unregisters the plugin's hooks. `onModuleDestroy`
-disables every enabled plugin on graceful shutdown so stateful plugins can flush; it first waits for
-enables already in flight, and refuses new ones once teardown starts. `uninstallPlugin`
+disables every enabled plugin on graceful shutdown so stateful plugins can flush. Running plugins are
+disabled first; then it waits for enables already in flight (a sandboxed enable is three 30 s-bounded
+calls) and disables those plugins too. New enables are refused once teardown starts. `uninstallPlugin`
disables + unloads, drops the registry entry, and deletes the plugin's directory and its `ctx.storage`
data dir (built-ins are protected and cannot be uninstalled). The unload path dispatches `onUnload`:
for a sandboxed plugin it runs in the worker between `onDisable` and terminate (a plain disable does
diff --git a/src/core/plugins/plugin-loader.service.spec.ts b/src/core/plugins/plugin-loader.service.spec.ts
index c76e25dc3..1c3e45ef2 100644
--- a/src/core/plugins/plugin-loader.service.spec.ts
+++ b/src/core/plugins/plugin-loader.service.spec.ts
@@ -416,6 +416,33 @@ describe('PluginLoaderService — graceful shutdown (onModuleDestroy)', () => {
expect(loader.getPlugin('slow-plg')?.status).toBe(PluginStatus.DISABLED);
});
+ it('disables running plugins without waiting for an enable still in flight', async () => {
+ let release!: () => void;
+ const gate = new Promise<void>(resolve => (release = resolve));
+ const runningDisable = jest.fn(() => Promise.resolve());
+ const slowDisable = jest.fn(() => Promise.resolve());
+ loader.registerBuiltInPlugin(ext('running-plg'), { onDisable: runningDisable });
+ loader.registerBuiltInPlugin(ext('slow-plg'), { onEnable: () => gate, onDisable: slowDisable });
+ await loader.enablePlugin('running-plg');
+
+ const enabling = loader.enablePlugin('slow-plg');
+ const destroying = loader.onModuleDestroy();
+ await new Promise(resolve => setImmediate(resolve));
+
+ // The running plugin's onDisable runs while the other enable is still held.
+ expect(runningDisable).toHaveBeenCalledTimes(1);
+ expect(slowDisable).not.toHaveBeenCalled();
+
+ release();
+ await enabling;
+ await destroying;
+
+ expect(runningDisable).toHaveBeenCalledTimes(1);
+ expect(slowDisable).toHaveBeenCalledTimes(1);
+ expect(loader.getPlugin('running-plg')?.status).toBe(PluginStatus.DISABLED);
+ expect(loader.getPlugin('slow-plg')?.status).toBe(PluginStatus.DISABLED);
+ });
+
it('refuses an enable once teardown has begun', async () => {
const onEnable = jest.fn(() => Promise.resolve());
loader.registerBuiltInPlugin(ext('late-plg'), { onEnable });
diff --git a/src/core/plugins/plugin-loader.service.ts b/src/core/plugins/plugin-loader.service.ts
index 15c0ea838..3193ff149 100644
--- a/src/core/plugins/plugin-loader.service.ts
+++ b/src/core/plugins/plugin-loader.service.ts
@@ -283,12 +283,18 @@ export class PluginLoaderService implements OnModuleInit, OnApplicationBootstrap
* and uninstall paths, so a normal restart/deploy/scale-down skipped it and stateful plugins lost
* in-flight work. Best-effort and sequential: one plugin's failure must not block the others.
*
- * Enables already in flight are awaited first, so a plugin that finishes enabling mid-teardown is in
- * the snapshot below instead of running on with its onDisable never called; later enables are refused.
+ * Running plugins are disabled first, so a slow enable still in flight cannot hold back their onDisable.
+ * Then the in-flight enables are awaited and a second pass disables the plugins that finished enabling
+ * mid-teardown, instead of leaving them running with onDisable never called. Later enables are refused.
*/
async onModuleDestroy(): Promise<void> {
this.shuttingDown = true;
+ await this.disableEnabledPlugins();
await Promise.allSettled(this.pendingEnables);
+ await this.disableEnabledPlugins();
+ }
+
+ private async disableEnabledPlugins(): Promise<void> {
const enabled = this.getAllPlugins().filter(p => p.status === PluginStatus.ENABLED);
for (const plugin of enabled) {
try {