Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(plugins): restore the previous version when an update meets shutdown (#1832)

Yudhi Armyndharisde362161a0d8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c74104d42..6b1c0fb7c 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
+- Answer `503` and keep the previous version when shutdown begins before an update of a plugin the operator switched on has applied.
- 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.
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 271f47aae..41e89b0bf 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -6342,7 +6342,7 @@ Set which sessions a session-scoped plugin is activated for. This is a **full re
#### POST /api/plugins/:id/update
-Update an installed plugin in place from a URL, preserving config + enabled state. The new package is written to a staging sibling and validated BEFORE the running plugin is stopped, then swapped in with two renames (live → backup, staging → live); a failure before or during the swap restores the previous version, and a process crash mid-swap is reconciled at boot (the backup is restored when the live directory is missing), so an interrupted update can never make the plugin silently vanish. The URL follows the same transport and pin rules as `install-url`: plain http only with a `#sha256=` digest pin, and https needs the pin too under `NODE_ENV=production` unless `PLUGIN_INSTALL_REQUIRE_PIN=false` (fail-closed on mismatch).
+Update an installed plugin in place from a URL, preserving config + enabled state. The new package is written to a staging sibling and validated BEFORE the running plugin is stopped, then swapped in with two renames (live → backup, staging → live); a failure before or during the swap restores the previous version, and a process crash mid-swap is reconciled at boot (the backup is restored when the live directory is missing), so an interrupted update can never make the plugin silently vanish. An update of a plugin the operator switched on (not one in `error`) that is still applying once shutdown has begun is refused, or rolled back if the swap already happened, and answered with `503`, since the new version cannot be started to prove it works. The URL follows the same transport and pin rules as `install-url`: plain http only with a `#sha256=` digest pin, and https needs the pin too under `NODE_ENV=production` unless `PLUGIN_INSTALL_REQUIRE_PIN=false` (fail-closed on mismatch).
**Auth:** API key (ADMIN)
@@ -6366,7 +6366,7 @@ Update an installed plugin in place from a URL, preserving config + enabled stat
**Response** `201` — the updated `PluginDto`.
-**Errors:** `400` download/package invalid, manifest id mismatch, or built-in plugin · `401` · `403` · `404` unknown id
+**Errors:** `400` download/package invalid, manifest id mismatch, or built-in plugin · `401` · `403` · `404` unknown id · `503` shutdown began before the update of a plugin the operator switched on finished applying (the previous version is kept)
---
diff --git a/openapi.json b/openapi.json
index 4e19cfd17..05b32b9be 100644
--- a/openapi.json
+++ b/openapi.json
@@ -16665,6 +16665,16 @@
}
}
}
+ },
+ "503": {
+ "description": "Gateway shutting down; the previous version was kept",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
}
},
"summary": "Update an installed plugin in place from a URL (preserves config + enabled state)",
diff --git a/src/modules/plugins/plugins.controller.ts b/src/modules/plugins/plugins.controller.ts
index ef908522a..8032c7ee9 100644
--- a/src/modules/plugins/plugins.controller.ts
+++ b/src/modules/plugins/plugins.controller.ts
@@ -202,6 +202,10 @@ export class PluginsController {
@ApiResponse({ status: 201, description: 'Plugin updated', type: PluginDto })
@ApiResponse({ status: 400, description: 'Invalid URL/package, id mismatch, or built-in' })
@ApiResponse({ status: 404, description: 'Plugin not found' })
+ @ApiResponse({
+ status: 503,
+ description: 'Gateway shutting down; the previous version was kept',
+ })
async update(@Param('id') id: string, @Body() dto: InstallFromUrlDto): Promise<PluginDto> {
return await this.pluginsService.updateFromUrl(id, dto.url);
}
diff --git a/src/modules/plugins/plugins.service.spec.ts b/src/modules/plugins/plugins.service.spec.ts
index 99f808152..2db3af63f 100644
--- a/src/modules/plugins/plugins.service.spec.ts
+++ b/src/modules/plugins/plugins.service.spec.ts
@@ -14,7 +14,7 @@ import * as os from 'os';
import * as path from 'path';
import { createHash } from 'crypto';
import AdmZip from 'adm-zip';
-import { BadRequestException, ConflictException, NotFoundException } from '@nestjs/common';
+import { BadRequestException, ConflictException, NotFoundException, ServiceUnavailableException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { ModuleRef } from '@nestjs/core';
import { PluginsService, isIngressCapable } from './plugins.service';
@@ -165,12 +165,79 @@ describe('PluginsService — install / uninstall (real loader + disk)', () => {
enableSpy.mockRestore();
});
- it('keeps the new version when an update finishes during shutdown instead of rolling back', async () => {
+ it('restores the previous version when shutdown begins while an update stops the running plugin', async () => {
+ service.install({ buffer: pkg({ version: '1.0.0' }) });
+ pluginStorage.setPluginEnabledByOperator('svc-plg', true);
+ loader.getPlugin('svc-plg')!.status = PluginStatus.ENABLED;
+ // Hold the update inside unloadPlugin so teardown can begin while the old version is being stopped.
+ let entered!: () => void;
+ const unloading = new Promise<void>(resolve => (entered = resolve));
+ let release!: () => void;
+ const gate = new Promise<void>(resolve => (release = resolve));
+ const realUnload = loader.unloadPlugin.bind(loader);
+ jest.spyOn(loader, 'unloadPlugin').mockImplementationOnce(async (pluginId: string) => {
+ entered();
+ await gate;
+ return realUnload(pluginId);
+ });
+ const enableSpy = jest.spyOn(loader, 'enablePlugin');
+
+ const updating = service.updatePackage('svc-plg', pkg({ version: '2.0.0' }));
+ await unloading;
+ const destroying = loader.onModuleDestroy();
+ release();
+
+ await expect(updating).rejects.toBeInstanceOf(ServiceUnavailableException);
+ await destroying;
+
+ // The new version was never enabled, so it is not kept: the previous one is back, loaded and on disk.
+ expect(loader.getPlugin('svc-plg')?.manifest.version).toBe('1.0.0');
+ const onDisk = JSON.parse(fs.readFileSync(path.join(pluginsDir, 'svc-plg', 'manifest.json'), 'utf8')) as {
+ version: string;
+ };
+ expect(onDisk.version).toBe('1.0.0');
+ expect(fs.existsSync(path.join(pluginsDir, '.svc-plg.bak'))).toBe(false);
+ expect(fs.existsSync(path.join(pluginsDir, '.svc-plg.new'))).toBe(false);
+ // Only the rollback's best-effort re-enable reached enablePlugin, and shutdown refused it.
+ expect(enableSpy).toHaveBeenCalledTimes(1);
+ await expect(enableSpy.mock.results[0].value).rejects.toThrow(/shutting down/);
+ expect(loader.getPlugin('svc-plg')?.status).not.toBe(PluginStatus.ENABLED);
+ // The operator decision survives, so the next boot brings the previous version back up.
+ expect(pluginStorage.getPluginEntry('svc-plg')?.enabledByOperator).toBe(true);
+ });
+
+ it('restores the previous version when an update applies after shutdown already disabled the plugin', async () => {
service.install({ buffer: pkg({ version: '1.0.0' }) });
pluginStorage.setPluginEnabledByOperator('svc-plg', true);
- // Teardown has begun (nothing was enabled yet), then the update of a running plugin reaches its re-enable.
- await loader.onModuleDestroy();
loader.getPlugin('svc-plg')!.status = PluginStatus.ENABLED;
+ // A slow download or a queued operation lets teardown disable the plugin before the update applies.
+ await loader.onModuleDestroy();
+ expect(loader.getPlugin('svc-plg')?.status).not.toBe(PluginStatus.ENABLED);
+ const unloadSpy = jest.spyOn(loader, 'unloadPlugin');
+
+ await expect(service.updatePackage('svc-plg', pkg({ version: '2.0.0' }))).rejects.toBeInstanceOf(
+ ServiceUnavailableException,
+ );
+
+ // Refused before the swap: the previous version was never stopped and no plugin code ran.
+ expect(unloadSpy).not.toHaveBeenCalled();
+ expect(loader.getPlugin('svc-plg')?.manifest.version).toBe('1.0.0');
+ const onDisk = JSON.parse(fs.readFileSync(path.join(pluginsDir, 'svc-plg', 'manifest.json'), 'utf8')) as {
+ version: string;
+ };
+ expect(onDisk.version).toBe('1.0.0');
+ expect(fs.existsSync(path.join(pluginsDir, '.svc-plg.bak'))).toBe(false);
+ expect(fs.existsSync(path.join(pluginsDir, '.svc-plg.new'))).toBe(false);
+ // The next boot enables the previous version, not an untested new one.
+ expect(pluginStorage.getPluginEntry('svc-plg')?.enabledByOperator).toBe(true);
+ });
+
+ it('still applies an update of a plugin in ERROR once shutdown has begun', async () => {
+ service.install({ buffer: pkg({ version: '1.0.0' }) });
+ pluginStorage.setPluginEnabledByOperator('svc-plg', true);
+ // For example its restore on boot failed: it is not running, and the update is likely the fix.
+ loader.getPlugin('svc-plg')!.status = PluginStatus.ERROR;
+ await loader.onModuleDestroy();
const dto = await service.updatePackage('svc-plg', pkg({ version: '2.0.0' }));
@@ -180,10 +247,25 @@ describe('PluginsService — install / uninstall (real loader + disk)', () => {
};
expect(onDisk.version).toBe('2.0.0');
expect(fs.existsSync(path.join(pluginsDir, '.svc-plg.bak'))).toBe(false);
- // The operator decision survives, so the next boot restores the new version.
expect(pluginStorage.getPluginEntry('svc-plg')?.enabledByOperator).toBe(true);
});
+ it('still applies an update of a plugin the operator switched off once shutdown has begun', async () => {
+ service.install({ buffer: pkg({ version: '1.0.0' }) });
+ await loader.onModuleDestroy();
+
+ const dto = await service.updatePackage('svc-plg', pkg({ version: '2.0.0' }));
+
+ // Nothing will ever enable it, so there is nothing to prove and no reason to refuse the update.
+ expect(dto.version).toBe('2.0.0');
+ const onDisk = JSON.parse(fs.readFileSync(path.join(pluginsDir, 'svc-plg', 'manifest.json'), 'utf8')) as {
+ version: string;
+ };
+ expect(onDisk.version).toBe('2.0.0');
+ expect(fs.existsSync(path.join(pluginsDir, '.svc-plg.bak'))).toBe(false);
+ expect(pluginStorage.getPluginEntry('svc-plg')?.enabledByOperator).toBeFalsy();
+ });
+
it('cleans up the staging + backup dirs after a successful update (swap happened)', async () => {
service.install({ buffer: pkg({ version: '1.0.0' }) });
diff --git a/src/modules/plugins/plugins.service.ts b/src/modules/plugins/plugins.service.ts
index 0953f884e..43b249dea 100644
--- a/src/modules/plugins/plugins.service.ts
+++ b/src/modules/plugins/plugins.service.ts
@@ -1,4 +1,11 @@
-import { Injectable, NotFoundException, BadRequestException, ConflictException, HttpException } from '@nestjs/common';
+import {
+ Injectable,
+ NotFoundException,
+ BadRequestException,
+ ConflictException,
+ HttpException,
+ ServiceUnavailableException,
+} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import * as fs from 'fs';
import * as path from 'path';
@@ -483,7 +490,9 @@ export class PluginsService {
* reconciled at boot by the loader's interrupted-update recovery, which restores the backup when
* the live dir is missing — an interrupted update can no longer make the plugin silently vanish.
* If loading/enabling the new version fails, the backup is restored and reloaded, so a bad update
- * never leaves the plugin broken.
+ * never leaves the plugin broken. An update of a plugin the operator switched on that is still
+ * applying once shutdown has begun is refused or rolled back the same way (with a 503), since the
+ * new version cannot be enabled to prove it works.
*/
updatePackage(id: string, buffer: Buffer): Promise<PluginDto> {
return this.serialize(id, () => this.updatePackageInner(id, buffer));
@@ -505,6 +514,23 @@ export class PluginsService {
}
const wasEnabled = plugin.status === PluginStatus.ENABLED;
+ // Shutdown refuses new enables, so an update of a plugin meant to run cannot prove the new version
+ // starts. It is refused with a 503 and the previous version stays, so the next boot restores that
+ // one from the persisted operator decision. wasEnabled alone is not enough: once teardown has
+ // disabled the plugin, it reads false while enabledByOperator stays true. A plugin the operator
+ // switched off, or one in ERROR (which is not running either way), is never enabled after an
+ // update, so its update still applies.
+ const meantToRun =
+ wasEnabled ||
+ (plugin.status !== PluginStatus.ERROR && this.pluginLoader.getRegistryEntry(id)?.enabledByOperator === true);
+ const refuseDuringShutdown = (): void => {
+ if (meantToRun && this.pluginLoader.isShuttingDown()) {
+ throw new ServiceUnavailableException(`Plugin ${id} was not updated: the gateway is shutting down`);
+ }
+ };
+ // Already shutting down (a slow download or a queued operation): refuse before touching disk or
+ // running any plugin code.
+ refuseDuringShutdown();
// The tree the package was loaded from, which is the legacy plugins directory for a host that
// has not migrated. Updating in the configured root instead renames a directory that is not
// there, after unloadPlugin has already dropped the plugin from the runtime.
@@ -598,16 +624,10 @@ export class PluginsService {
fs.chmodSync(stateFile, 0o600);
}
this.pluginLoader.loadPlugin(dir);
- if (wasEnabled && this.pluginLoader.isShuttingDown()) {
- // Shutdown refuses new enables. That is not a failed update: keep the new version and let the
- // next boot restore it from the persisted operator decision instead of rolling back.
- logger.warn(`Plugin ${id} updated during shutdown; it will be enabled on the next start`, {
- pluginId: id,
- action: 'plugin_update_enable_deferred',
- });
- } else if (wasEnabled) {
- await this.pluginLoader.enablePlugin(id);
- }
+ // Shutdown may have begun while the old version was being stopped: roll back below rather than
+ // keep the new version untested with its backup deleted.
+ refuseDuringShutdown();
+ if (wasEnabled) await this.pluginLoader.enablePlugin(id);
fs.rmSync(backup, { recursive: true, force: true });
logger.log(`Plugin updated: ${id} → v${manifest.version}`, {
pluginId: id,