Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(session): answer 503 when shutdown overtakes a start (#1847)

Yudhi Armyndharis781fc3801718
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ba99bea86..49198ace8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- 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.
- Stop taking ingress queue jobs once shutdown begins after SIGTERM, SIGINT or an admin restart, instead of running them against stopped sessions.
- Run the daily ingress retention hand-off after a reconcile sweep in progress instead of skipping it.
@@ -50,7 +52,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- 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`.
-- Refuse session starts with `503` once shutdown begins, and leave a start that shutdown interrupts for the next boot instead of marking it failed.
- Stop dashboard multi-page loads and a pending chat mark-as-read from sending requests after logout.
- Keep a new dashboard login signed in when a request sent with the previous API key fails afterwards.
- Enforce the plugin package size limit before reading `manifest.json`, and reject archive entries whose path starts with `/`.
diff --git a/src/modules/session/session-engine-controls.ts b/src/modules/session/session-engine-controls.ts
index 7b16d6bda..88aac9036 100644
--- a/src/modules/session/session-engine-controls.ts
+++ b/src/modules/session/session-engine-controls.ts
@@ -290,12 +290,30 @@ export class SessionEngineControls {
// it, and any other start yields to it with the mark put back. A stop from here on sets the
// mark again and retires this start after its init. A launch that fails after the clear still
// counts as the start the operator asked for.
- if ((await this.requireSession(id)).desiredState === 'stopped') {
- if (!explicit || session.desiredState !== 'stopped') {
- this.stoppingSessions.add(id);
- throw new SessionStoppedException(`Session ${id} was stopped`);
- }
+ const { desiredState } = await this.requireSession(id);
+ if (desiredState === 'stopped' && (!explicit || session.desiredState !== 'stopped')) {
+ this.stoppingSessions.add(id);
+ throw new SessionStoppedException(`Session ${id} was stopped`);
+ }
+ // Shutdown may have begun during the reads above, past SessionService's own checks. A start the
+ // exiting process will not keep must not clear the stop or run the hook. A start that yielded to
+ // a stop answers as the stop, never as a retryable 503: one already on the row is refused above,
+ // and the mark (cleared above, so set by a stop or delete that began since) covers one whose row
+ // write has not landed yet.
+ const closedRefusal = (): Error =>
+ this.stoppingSessions.has(id)
+ ? new SessionStoppedException(`Session ${id} was stopped`)
+ : new ServerShuttingDownException();
+ if (this.host.isClosed()) {
+ throw closedRefusal();
+ }
+ if (desiredState === 'stopped') {
await this.sessionRepository.update({ id, desiredState: 'stopped' }, { desiredState: null });
+ // The clear stands (this start was the operator's), but the hook must not fire for a start
+ // shutdown overtook during the write.
+ if (this.host.isClosed()) {
+ throw closedRefusal();
+ }
}
// Execute hook before starting
@@ -328,6 +346,7 @@ export class SessionEngineControls {
const init = this.host.initializeEngine(id, session);
const registered = this.engines.get(id);
const mine = registered !== before ? registered : undefined;
+ let failedWritten = false;
try {
await init;
} catch (err) {
@@ -352,6 +371,7 @@ export class SessionEngineControls {
// shutdown too: an init that rejects then usually does so because shutdown destroyed its
// engine, and the INITIALIZING row is reset by the next boot, where FAILED would not be.
if (this.host.ownsSession(id) && !this.host.isClosed()) {
+ failedWritten = true;
await this.host.updateStatus(id, SessionStatus.FAILED).catch(() => undefined);
}
}
@@ -362,7 +382,14 @@ export class SessionEngineControls {
if (!this.engines.has(id)) {
this.host.cancelReconnect(id);
}
- throw err;
+ // Shutdown's destroy is the usual cause of an init rejecting now; the adapter's error would
+ // read as a fault (or, if transient, buy a retry shutdown refuses anyway). A start a stop
+ // retired keeps the adapter's error, as it would without shutdown. So does one whose FAILED
+ // went out before shutdown began: a transient error then reaches the retry, whose refusal
+ // hands the row back as DISCONNECTED for the next boot.
+ throw this.host.isClosed() && !failedWritten && !this.stoppingSessions.has(id)
+ ? new ServerShuttingDownException()
+ : err;
}
// A stop()/delete() may have landed while we awaited engine.initialize() — if so, tear down the
@@ -379,6 +406,11 @@ export class SessionEngineControls {
// A delete() that raced this start purged the on-disk auth dirs BEFORE this init re-created
// them — purge again so the window leaves no credential residue behind (no-op for a stop()).
await this.host.purgeAuthDirsIfDeleted(id);
+ } else if (this.host.isClosed()) {
+ // Shutdown destroys every engine it finds, this one included, and skips initialize() for an
+ // engine it caught mid-start. Either way the session is not kept, so this is no success. A
+ // start retired above answers as the stop or delete that retired it instead.
+ throw new ServerShuttingDownException();
}
return this.requireSession(id);
} finally {
diff --git a/src/modules/session/session-engine-lifecycle.service.ts b/src/modules/session/session-engine-lifecycle.service.ts
index d7851813f..7e46f8119 100644
--- a/src/modules/session/session-engine-lifecycle.service.ts
+++ b/src/modules/session/session-engine-lifecycle.service.ts
@@ -640,17 +640,18 @@ export class SessionEngineLifecycle {
}
private async initializeEngine(id: string, session: Session): Promise<void> {
+ // A stop that landed before this engine exists had nothing to tear down and already wrote its
+ // DISCONNECTED; registering now would overwrite it with INITIALIZING and then retire. start()
+ // clears its own mark and executeReconnect checks it on entry, so a mark seen here always came
+ // from a later stop, force-kill, logout or delete. Checked before `closed`: start() answers a
+ // retired start as the stop or delete, never as a 503 a client would replay after the restart.
+ if (this.stoppingSessions.has(id)) return;
// shutdown() destroys only the engines registered when it starts. A start or a transient retry
// still on its way here would register one nothing tears down, so it fails instead; its caller
// releases the claim. A 503 is not a transient launch failure, so it is not retried.
if (this.closed) {
throw new ServerShuttingDownException();
}
- // A stop that landed before this engine exists had nothing to tear down and already wrote its
- // DISCONNECTED; registering now would overwrite it with INITIALIZING and then retire. start()
- // clears its own mark and executeReconnect checks it on entry, so a mark seen here always came
- // from a later stop, force-kill, logout or delete.
- if (this.stoppingSessions.has(id)) return;
this.logger.log(`Initializing engine for session: ${session.name}`, {
sessionId: id,
action: 'engine_init',
@@ -713,7 +714,8 @@ export class SessionEngineLifecycle {
// lookup, so nothing can swap the engine between them (a second, identical check used to sit
// after the stop mark and could never disagree with this one). `closed` covers an engine that
// shutdown() is already destroying: it stays registered until every destroy settles. Returned,
- // not thrown: start()'s failure path would force-destroy the engine shutdown is destroying.
+ // not thrown: start()'s failure path would force-destroy the engine shutdown is destroying. start()
+ // answers 503 past that path instead.
if (this.closed || !this.isLiveEngine(id, engine)) {
return;
}
diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.ts
index 99f2e8909..2b4724b21 100644
--- a/src/modules/session/session.service.spec.ts
+++ b/src/modules/session/session.service.spec.ts
@@ -2302,6 +2302,33 @@ describe('SessionService', () => {
expect(await nodeIdOf(row.id)).toBeNull();
});
+ it('for a start whose FAILED write was pending when shutdown began', async () => {
+ const row = await arrange();
+ let reachedFailed: () => void = () => undefined;
+ const failedHeld = new Promise<void>(resolve => (reachedFailed = resolve));
+ let releaseFailed: () => void = () => undefined;
+ const gate = new Promise<void>(resolve => (releaseFailed = resolve));
+ (repository.update as jest.Mock).mockImplementation(
+ async (...args: Parameters<Repository<Session>['update']>) => {
+ if ((args[1] as { status?: SessionStatus }).status === SessionStatus.FAILED) {
+ reachedFailed();
+ await gate;
+ }
+ return sessions.update(...args);
+ },
+ );
+
+ const outcome = service.start(row.id, { explicit: true }).catch((error: unknown) => error);
+ await failedHeld;
+ const shutdown = service.onModuleDestroy();
+ releaseFailed();
+ await shutdown;
+
+ expect(await outcome).toBeInstanceOf(ServerShuttingDownException);
+ expect(mockEngine.initialize).toHaveBeenCalledTimes(1);
+ expect(await statusOf(row.id)).toBe(SessionStatus.DISCONNECTED);
+ });
+
it('but not on a row a peer adopted since, whose FAILED is its own', async () => {
const row = await arrange();
@@ -8750,7 +8777,7 @@ describe('SessionService', () => {
let releaseDestroy: () => void = () => undefined;
mockEngine.destroy.mockImplementationOnce(() => new Promise<void>(resolve => (releaseDestroy = resolve)));
- const start = service.start('sess-uuid-1');
+ const start = service.start('sess-uuid-1').catch((error: unknown) => error);
await flush();
expect(engineFactory.create).toHaveBeenCalledTimes(1);
const shutdown = service.onModuleDestroy();
@@ -8760,10 +8787,249 @@ describe('SessionService', () => {
await flush();
releaseDestroy();
await shutdown;
- await start;
+ expect(await start).toBeInstanceOf(ServerShuttingDownException);
expect(mockEngine.initialize).not.toHaveBeenCalled();
expect(service.isActive('sess-uuid-1')).toBe(false);
+ // Left INITIALIZING for the next boot's reset, never FAILED.
+ expect((repository.update as jest.Mock).mock.calls).not.toContainEqual([
+ expect.anything(),
+ expect.objectContaining({ status: SessionStatus.FAILED }),
+ ]);
+ });
+
+ it('answers 503 for a start whose engine finished initializing as shutdown began', async () => {
+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession());
+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });
+ let releaseInit: () => void = () => undefined;
+ const initHeld = new Promise<void>(resolve => {
+ mockEngine.initialize.mockImplementationOnce(
+ () =>
+ new Promise<void>(done => {
+ releaseInit = done;
+ resolve();
+ }),
+ );
+ });
+ // The init settles inside shutdown's destroy, as an adapter does when teardown cuts it short.
+ mockEngine.destroy.mockImplementationOnce(() => {
+ releaseInit();
+ return Promise.resolve();
+ });
+
+ const start = service.start('sess-uuid-1').catch((error: unknown) => error);
+ await initHeld;
+ await service.onModuleDestroy();
+
+ expect(await start).toBeInstanceOf(ServerShuttingDownException);
+ expect(mockEngine.forceDestroy).not.toHaveBeenCalled();
+ });
+
+ it('refuses a start that shutdown overtakes during its reads before it clears a stop or runs the hook', async () => {
+ const stopped = createMockSession({ desiredState: 'stopped' });
+ let releaseRead: () => void = () => undefined;
+ const readHeld = new Promise<void>(resolve => {
+ (repository.findOne as jest.Mock).mockImplementationOnce(
+ () =>
+ new Promise(done => {
+ releaseRead = () => done(stopped);
+ resolve();
+ }),
+ );
+ });
+ (repository.findOne as jest.Mock).mockResolvedValue(stopped);
+
+ const start = service.start('sess-uuid-1', { explicit: true }).catch((error: unknown) => error);
+ await readHeld;
+ await service.onModuleDestroy();
+ releaseRead();
+
+ expect(await start).toBeInstanceOf(ServerShuttingDownException);
+ expect(hookManager.execute).not.toHaveBeenCalled();
+ expect((repository.update as jest.Mock).mock.calls).not.toContainEqual([
+ { id: 'sess-uuid-1', desiredState: 'stopped' },
+ { desiredState: null },
+ ]);
+ expect(engineFactory.create).not.toHaveBeenCalled();
+ });
+
+ it('does not run the hook for a start that shutdown overtakes while it clears a stop', async () => {
+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession({ desiredState: 'stopped' }));
+ let releaseClear: () => void = () => undefined;
+ const clearHeld = new Promise<void>(resolve => {
+ (repository.update as jest.Mock).mockImplementationOnce(
+ () =>
+ new Promise(done => {
+ releaseClear = () => done({ affected: 1 });
+ resolve();
+ }),
+ );
+ });
+
+ const start = service.start('sess-uuid-1', { explicit: true }).catch((error: unknown) => error);
+ await clearHeld;
+ await service.onModuleDestroy();
+ releaseClear();
+
+ expect(await start).toBeInstanceOf(ServerShuttingDownException);
+ expect(repository.update).toHaveBeenCalledWith(
+ { id: 'sess-uuid-1', desiredState: 'stopped' },
+ { desiredState: null },
+ );
+ expect(hookManager.execute).not.toHaveBeenCalled();
+ expect(engineFactory.create).not.toHaveBeenCalled();
+ });
+
+ it('answers a start as the stop that landed during its reads even when shutdown began too', async () => {
+ (repository.findOne as jest.Mock).mockResolvedValueOnce(createMockSession());
+ let releaseRead: () => void = () => undefined;
+ const readHeld = new Promise<void>(resolve => {
+ (repository.findOne as jest.Mock).mockImplementationOnce(
+ () =>
+ new Promise(done => {
+ releaseRead = () => done(createMockSession({ desiredState: 'stopped' }));
+ resolve();
+ }),
+ );
+ });
+
+ const start = service.start('sess-uuid-1', { explicit: true }).catch((error: unknown) => error);
+ await readHeld;
+ await service.onModuleDestroy();
+ releaseRead();
+
+ expect(await start).toBeInstanceOf(SessionStoppedException);
+ expect(hookManager.execute).not.toHaveBeenCalled();
+ expect((repository.update as jest.Mock).mock.calls).not.toContainEqual([
+ { id: 'sess-uuid-1', desiredState: 'stopped' },
+ { desiredState: null },
+ ]);
+ });
+
+ it('answers a start as a stop marked during its last read, not 503, when shutdown began too', async () => {
+ const marks = (lifecycle as unknown as { stoppingSessions: Set<string> }).stoppingSessions;
+ (repository.findOne as jest.Mock).mockResolvedValueOnce(createMockSession());
+ let releaseRead: () => void = () => undefined;
+ const readHeld = new Promise<void>(resolve => {
+ (repository.findOne as jest.Mock).mockImplementationOnce(
+ () =>
+ new Promise(done => {
+ releaseRead = () => done(createMockSession());
+ resolve();
+ }),
+ );
+ });
+
+ const start = service.start('sess-uuid-1').catch((error: unknown) => error);
+ await readHeld;
+ // The stop has set its mark but not yet written the row.
+ marks.add('sess-uuid-1');
+ await service.onModuleDestroy();
+ releaseRead();
+
+ expect(await start).toBeInstanceOf(SessionStoppedException);
+ expect(hookManager.execute).not.toHaveBeenCalled();
+ expect(engineFactory.create).not.toHaveBeenCalled();
+ });
+
+ it('answers a start as a stop marked while it clears a stop, not 503, when shutdown began too', async () => {
+ const marks = (lifecycle as unknown as { stoppingSessions: Set<string> }).stoppingSessions;
+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession({ desiredState: 'stopped' }));
+ let releaseClear: () => void = () => undefined;
+ const clearHeld = new Promise<void>(resolve => {
+ (repository.update as jest.Mock).mockImplementationOnce(
+ () =>
+ new Promise(done => {
+ releaseClear = () => done({ affected: 1 });
+ resolve();
+ }),
+ );
+ });
+
+ const start = service.start('sess-uuid-1', { explicit: true }).catch((error: unknown) => error);
+ await clearHeld;
+ marks.add('sess-uuid-1');
+ await service.onModuleDestroy();
+ releaseClear();
+
+ expect(await start).toBeInstanceOf(SessionStoppedException);
+ expect(hookManager.execute).not.toHaveBeenCalled();
+ expect(engineFactory.create).not.toHaveBeenCalled();
+ });
+
+ it('answers a start retired by a stop during init as the stop, not 503, when shutdown began too', async () => {
+ const marks = (lifecycle as unknown as { stoppingSessions: Set<string> }).stoppingSessions;
+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession());
+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });
+ let releaseInit: () => void = () => undefined;
+ const initHeld = new Promise<void>(resolve => {
+ mockEngine.initialize.mockImplementationOnce(
+ () =>
+ new Promise<void>(done => {
+ marks.add('sess-uuid-1');
+ releaseInit = done;
+ resolve();
+ }),
+ );
+ });
+ mockEngine.destroy.mockImplementationOnce(() => {
+ releaseInit();
+ return Promise.resolve();
+ });
+
+ const start = service.start('sess-uuid-1').catch((error: unknown) => error);
+ await initHeld;
+ await service.onModuleDestroy();
+
+ expect(await start).toMatchObject({ id: 'sess-uuid-1' });
+ });
+
+ it('answers a start retired by a stop during its hook as the stop, not 503, when shutdown began too', async () => {
+ const marks = (lifecycle as unknown as { stoppingSessions: Set<string> }).stoppingSessions;
+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession());
+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });
+ let shutdown: Promise<void> = Promise.resolve();
+ (hookManager.execute as jest.Mock).mockImplementationOnce((_e: string, data: unknown) => {
+ marks.add('sess-uuid-1');
+ shutdown = service.onModuleDestroy();
+ return Promise.resolve({ continue: true, data });
+ });
+
+ const start = service.start('sess-uuid-1').catch((error: unknown) => error);
+ const outcome = await start;
+ await shutdown;
+
+ expect(outcome).toMatchObject({ id: 'sess-uuid-1' });
+ expect(engineFactory.create).not.toHaveBeenCalled();
+ });
+
+ it('keeps the adapter error of a start a stop retired during a failed init, not 503, when shutdown began too', async () => {
+ const marks = (lifecycle as unknown as { stoppingSessions: Set<string> }).stoppingSessions;
+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession());
+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });
+ let rejectInit: (error: Error) => void = () => undefined;
+ const initHeld = new Promise<void>(resolve => {
+ mockEngine.initialize.mockImplementationOnce(
+ () =>
+ new Promise<void>((_done, reject) => {
+ marks.add('sess-uuid-1');
+ rejectInit = reject;
+ resolve();
+ }),
+ );
+ });
+ mockEngine.destroy.mockImplementationOnce(() => {
+ rejectInit(new Error('Target closed'));
+ return Promise.resolve();
+ });
+
+ const start = service.start('sess-uuid-1').catch((error: unknown) => error);
+ await initHeld;
+ await service.onModuleDestroy();
+
+ const outcome = await start;
+ expect(outcome).not.toBeInstanceOf(ServerShuttingDownException);
+ expect(outcome).toMatchObject({ message: 'Target closed' });
});
it('does not initialize a reconnect engine whose first status write settles while shutdown destroys it', async () => {
@@ -8821,7 +9087,8 @@ describe('SessionService', () => {
expect(mockEngine.initialize).toHaveBeenCalledTimes(1);
await service.onModuleDestroy();
- expect(await start).toMatchObject({ message: 'Target closed' });
+ // Answered as the shutdown it is, not as the adapter fault its destroy caused.
+ expect(await start).toBeInstanceOf(ServerShuttingDownException);
expect(updateStatus).not.toHaveBeenCalledWith('sess-uuid-1', SessionStatus.FAILED);
expect(service.isActive('sess-uuid-1')).toBe(false);
});
@@ -9598,6 +9865,44 @@ describe('SessionService', () => {
expect(logInfo).not.toHaveBeenCalledWith(`Auto-started session: ${session.name}`, expect.anything());
});
+ it('logs a launch whose engine shutdown destroyed during its last row read as abandoned', async () => {
+ process.env.AUTO_START_SESSIONS = 'true';
+ const session = createMockSession();
+ (repository.find as jest.Mock).mockResolvedValue([session]);
+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });
+ withAutoStartOwnership();
+ let releaseRead: () => void = () => undefined;
+ let readHeld = false;
+ let readsAfterInit = 0;
+ // After initialize() the start reads the row twice: the retired check, then the row it answers
+ // with. The second is held, past every shutdown check of the start.
+ (repository.findOne as jest.Mock).mockImplementation(() => {
+ if (mockEngine.initialize.mock.calls.length === 0 || ++readsAfterInit < 2) return Promise.resolve(session);
+ readHeld = true;
+ return new Promise(resolve => (releaseRead = () => resolve(session)));
+ });
+ const logInfo = jest.spyOn((service as unknown as { logger: { log: jest.Mock } }).logger, 'log');
+ const flush = async (until: () => boolean): Promise<void> => {
+ for (let i = 0; i < 50 && !until(); i++) await new Promise(resolve => setImmediate(resolve));
+ };
+
+ service.onApplicationBootstrap();
+ await flush(() => readHeld);
+ expect(readHeld).toBe(true);
+ const shutdown = service.onModuleDestroy();
+ await flush(() => mockEngine.destroy.mock.calls.length > 0);
+ expect(mockEngine.destroy).toHaveBeenCalledTimes(1);
+ releaseRead();
+ await shutdown;
+
+ expect(service.isActive(session.id)).toBe(false);
+ expect(logInfo).toHaveBeenCalledWith(
+ `Auto-start abandoned for session ${session.name}: shutting down`,
+ expect.objectContaining({ action: 'auto_start_aborted' }),
+ );
+ expect(logInfo).not.toHaveBeenCalledWith(`Auto-started session: ${session.name}`, expect.anything());
+ });
+
// A whatsapp-web.js launch still starting Chromium has no browser for the destroy to close, so
// its init runs until whatsapp-web.js settles it, at worst to the init deadline (>= 60s);
// shutdown must not wait that out, and must not hand away the claim that browser may still use.
diff --git a/src/modules/session/session.service.ts b/src/modules/session/session.service.ts
index 1c1c3824f..6fd96c39e 100644
--- a/src/modules/session/session.service.ts
+++ b/src/modules/session/session.service.ts
@@ -296,8 +296,10 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicat
const session = sessions[i];
try {
await this.start(session.id);
- // A launch the shutdown tore down mid-init resolves too (the adapter settles a torn-down
- // init quietly), but nothing was started.
+ // A launch shutdown tore down mid-init is refused with ServerShuttingDownException (caught
+ // below). One already past the engine's post-init checks resolves, but shutdown can still
+ // destroy its engine during the start's last row read or its claim bookkeeping, so
+ // nothing is left running.
if (this.shuttingDown && !this.isActive(session.id)) {
this.logger.log(`Auto-start abandoned for session ${session.name}: shutting down`, {
sessionId: session.id,
diff --git a/src/modules/takeover/session-takeover.service.spec.ts b/src/modules/takeover/session-takeover.service.spec.ts
index 04129d2a0..7e4ba1b24 100644
--- a/src/modules/takeover/session-takeover.service.spec.ts
+++ b/src/modules/takeover/session-takeover.service.spec.ts
@@ -1,6 +1,6 @@
import { ConflictException } from '@nestjs/common';
import { SessionTakeoverService } from './session-takeover.service';
-import { SessionStoppedException } from '../session/session-engine-controls';
+import { ServerShuttingDownException, SessionStoppedException } from '../session/session-engine-controls';
import { Session, SessionStatus } from '../session/entities/session.entity';
import type { SessionService } from '../session/session.service';
import type { SessionOwnershipService } from '../session/session-ownership.service';
@@ -178,6 +178,22 @@ describe('SessionTakeoverService', () => {
]);
});
+ it('a start refused by shutdown ends the sweep quietly instead of logging a failed takeover', async () => {
+ const start = jest.fn().mockRejectedValueOnce(new ServerShuttingDownException()).mockResolvedValue({});
+ const { svc } = build([lapsed({ name: 'late' }), lapsed({ name: 'next' })], { startImpl: start });
+ const logger = (svc as unknown as { logger: { warn: jest.Mock; debug: jest.Mock } }).logger;
+ const warn = jest.spyOn(logger, 'warn');
+ const debug = jest.spyOn(logger, 'debug');
+
+ await svc.sweep();
+
+ expect(start).toHaveBeenCalledTimes(1);
+ expect(warn).not.toHaveBeenCalled();
+ expect(debug.mock.calls.map(([message]) => message as string)).toEqual([
+ 'Takeover of session late abandoned: shutting down',
+ ]);
+ });
+
it('a non-conflict start failure is logged and does not abort the rest of the sweep', async () => {
jest.useFakeTimers();
const start = jest.fn().mockRejectedValueOnce(new Error('chromium died')).mockResolvedValueOnce({});
diff --git a/src/modules/takeover/session-takeover.service.ts b/src/modules/takeover/session-takeover.service.ts
index 6fae84e3b..4e9dc9583 100644
--- a/src/modules/takeover/session-takeover.service.ts
+++ b/src/modules/takeover/session-takeover.service.ts
@@ -6,7 +6,7 @@ import { Session, SessionStatus } from '../session/entities/session.entity';
import { SessionOwnershipService } from '../session/session-ownership.service';
import { ShutdownService } from '../../common/services/shutdown.service';
import { SessionService } from '../session/session.service';
-import { SessionStoppedException } from '../session/session-engine-controls';
+import { ServerShuttingDownException, SessionStoppedException } from '../session/session-engine-controls';
import { resolveMaxConcurrentSessions } from '../session/session-engine-lifecycle.service';
/**
@@ -179,6 +179,10 @@ export class SessionTakeoverService implements OnApplicationBootstrap, OnModuleD
if (error instanceof SessionStoppedException) {
// Stopped between the sweep's read and this start; the start refused it, as it should.
this.logger.debug(`Session ${session.name} skipped: stopped by an operator`, { sessionId: session.id });
+ } else if (error instanceof ServerShuttingDownException) {
+ // Shutdown began while this start was in flight; the session is left for a peer or the next boot.
+ this.logger.debug(`Takeover of session ${session.name} abandoned: shutting down`, { sessionId: session.id });
+ return;
} else if (error instanceof ConflictException) {
// A peer won the race — exactly the claim doing its job.
this.logger.debug(`Session ${session.name} was adopted by another node first`, { sessionId: session.id });