@theia/core 1.72.0-next.36 → 1.72.0-next.45

package/src/node/backend-application.spec.ts

@@ -0,0 +1,310 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { Container, ContainerModule, injectable, preDestroy } from 'inversify';
+import { bindContributionProvider, ILogger, Stopwatch } from '../common';
+import { Deferred } from '../common/promise-util';
+import { MockLogger } from '../common/test/mock-logger';
+import { NodeStopwatch } from './performance/node-stopwatch';
+import { ProcessUtils } from './process-utils';
+import {
+    BackendApplication,
+    BackendApplicationCliContribution,
+    BackendApplicationContribution,
+    RootContainer
+} from './backend-application';
+import { CliContribution } from './cli';
+
+/**
+ * Test subclass that exposes the protected `gracefulShutdown` for direct testing.
+ */
+@injectable()
+class TestBackendApplication extends BackendApplication {
+    public invokeGracefulShutdown(): Promise<void> {
+        return this.gracefulShutdown();
+    }
+}
+
+// All process events on which `BackendApplication` installs listeners in its
+// constructor. We snapshot and restore them around each test to avoid leaking
+// listeners across tests (and triggering `MaxListenersExceededWarning`).
+const PROCESS_EVENTS = ['SIGINT', 'SIGTERM', 'SIGPIPE', 'exit', 'uncaughtException'] as const;
+type ProcessEventName = typeof PROCESS_EVENTS[number];
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyListener = (...args: any[]) => void;
+
+describe('BackendApplication', () => {
+    let sandbox: sinon.SinonSandbox;
+    let exitStub: sinon.SinonStub;
+    let savedListeners: Partial<Record<ProcessEventName, AnyListener[]>>;
+
+    beforeEach(() => {
+        sandbox = sinon.createSandbox();
+
+        // Snapshot any existing listeners so we can restore after each test
+        // (BackendApplication installs its own as part of construction).
+        savedListeners = {};
+        for (const evt of PROCESS_EVENTS) {
+            savedListeners[evt] = [...process.listeners(evt as NodeJS.Signals)] as AnyListener[];
+            process.removeAllListeners(evt);
+        }
+
+        exitStub = sandbox.stub(process, 'exit');
+    });
+
+    afterEach(() => {
+        for (const evt of PROCESS_EVENTS) {
+            process.removeAllListeners(evt);
+            for (const listener of savedListeners[evt] ?? []) {
+                process.on(evt, listener);
+            }
+        }
+
+        sandbox.restore();
+    });
+
+    function createTestContainer(): Container {
+        const container = new Container();
+
+        container.bind(RootContainer).toConstantValue(container);
+
+        container.bind(ILogger).to(MockLogger).inSingletonScope();
+        container.bind(Stopwatch).to(NodeStopwatch).inSingletonScope();
+        container.bind(ProcessUtils).toSelf().inSingletonScope();
+        container.bind(BackendApplicationCliContribution).toSelf().inSingletonScope();
+        container.bind(CliContribution).toService(BackendApplicationCliContribution);
+        bindContributionProvider(container, BackendApplicationContribution);
+
+        container.bind(TestBackendApplication).toSelf().inSingletonScope();
+        container.bind(BackendApplication).toService(TestBackendApplication);
+
+        return container;
+    }
+
+    describe('graceful shutdown', () => {
+
+        it('runs @preDestroy on root-scoped singletons before exiting with code 1', async () => {
+            let canaryDisposed = false;
+
+            @injectable()
+            class Canary {
+                @preDestroy()
+                protected onPreDestroy(): void {
+                    canaryDisposed = true;
+                }
+            }
+
+            const container = createTestContainer();
+            const canaryModule = new ContainerModule(bind => {
+                bind(Canary).toSelf().inSingletonScope();
+            });
+            container.load(canaryModule);
+            container.get(Canary);
+
+            const app = container.get(TestBackendApplication);
+
+            await app.invokeGracefulShutdown();
+
+            expect(canaryDisposed, '@preDestroy was not invoked on root-scoped singleton').to.be.true;
+            expect(exitStub.calledOnceWith(1), 'process.exit(1) was not called exactly once').to.be.true;
+        });
+
+        it('is idempotent: a second invocation does not unbind the container twice', async () => {
+            const container = createTestContainer();
+            const unbindSpy = sandbox.spy(container, 'unbindAllAsync');
+
+            const app = container.get(TestBackendApplication);
+
+            await app.invokeGracefulShutdown();
+            await app.invokeGracefulShutdown();
+
+            expect(unbindSpy.callCount, 'unbindAllAsync should be called only once').to.equal(1);
+            expect(exitStub.callCount, 'process.exit should be called only once').to.equal(1);
+        });
+
+        it('still exits if container cleanup rejects', async () => {
+            const container = createTestContainer();
+            const cleanupError = new Error('cleanup boom');
+            sandbox.stub(container, 'unbindAllAsync').rejects(cleanupError);
+            const warnStub = sandbox.stub(console, 'warn');
+
+            const app = container.get(TestBackendApplication);
+
+            await app.invokeGracefulShutdown();
+
+            expect(exitStub.calledOnceWith(1), 'process.exit(1) was not called').to.be.true;
+            expect(warnStub.calledOnce, 'a warning should be logged when cleanup rejects').to.be.true;
+            expect(warnStub.firstCall.args[0]).to.match(/cleanup boom/);
+        });
+
+        it('exits even when container cleanup hangs past the timeout', async () => {
+            const clock = sandbox.useFakeTimers();
+            const container = createTestContainer();
+            sandbox.stub(container, 'unbindAllAsync').returns(new Promise<void>(() => { /* never */ }));
+            const warnStub = sandbox.stub(console, 'warn');
+
+            const app = container.get(TestBackendApplication);
+
+            const shutdownPromise = app.invokeGracefulShutdown();
+
+            await clock.tickAsync(5001);
+            await shutdownPromise;
+
+            expect(exitStub.calledOnceWith(1), 'process.exit(1) was not called after timeout').to.be.true;
+            expect(warnStub.calledOnce, 'a warning should be logged on timeout').to.be.true;
+            expect(warnStub.firstCall.args[0]).to.match(/timed out/);
+        });
+
+        it('awaits async onStop contributions before unbinding the container', async () => {
+            const container = createTestContainer();
+            const onStopDeferred = new Deferred<void>();
+            container.bind(BackendApplicationContribution).toConstantValue({
+                onStop: () => onStopDeferred.promise
+            });
+            const unbindSpy = sandbox.spy(container, 'unbindAllAsync');
+
+            const app = container.get(TestBackendApplication);
+            const shutdownPromise = app.invokeGracefulShutdown();
+
+            expect(unbindSpy.called, 'unbindAllAsync should not run before onStop resolves').to.be.false;
+
+            onStopDeferred.resolve();
+            await shutdownPromise;
+
+            expect(unbindSpy.calledOnce, 'unbindAllAsync should run once onStop completes').to.be.true;
+            expect(exitStub.calledOnceWith(1)).to.be.true;
+        });
+
+        it('invokes onStop hooks while injected services are still resolvable', async () => {
+            @injectable()
+            class Helper {
+                readonly value = 'still-bound';
+            }
+
+            const container = createTestContainer();
+            container.bind(Helper).toSelf().inSingletonScope();
+
+            let observed: string | undefined;
+            container.bind(BackendApplicationContribution).toConstantValue({
+                onStop: () => {
+                    observed = container.get(Helper).value;
+                }
+            });
+
+            const app = container.get(TestBackendApplication);
+            await app.invokeGracefulShutdown();
+
+            expect(observed, 'onStop should observe injected services that are still bound').to.equal('still-bound');
+        });
+
+        it('proceeds with shutdown when onStop hooks exceed the timeout', async () => {
+            const clock = sandbox.useFakeTimers();
+            const container = createTestContainer();
+            container.bind(BackendApplicationContribution).toConstantValue({
+                onStop: () => new Promise<void>(() => { /* never */ })
+            });
+            const unbindSpy = sandbox.spy(container, 'unbindAllAsync');
+            const warnStub = sandbox.stub(console, 'warn');
+
+            const app = container.get(TestBackendApplication);
+            const shutdownPromise = app.invokeGracefulShutdown();
+
+            await clock.tickAsync(5001);
+            await shutdownPromise;
+
+            expect(warnStub.calledOnce, 'a warning should be logged on onStop timeout').to.be.true;
+            expect(warnStub.firstCall.args[0]).to.match(/Stopping backend contributions/);
+            expect(unbindSpy.calledOnce, 'unbind should still run after onStop times out').to.be.true;
+            expect(exitStub.calledOnceWith(1)).to.be.true;
+        });
+
+        it('runs all contributions even when one onStop rejects', async () => {
+            const container = createTestContainer();
+            let secondRan = false;
+            container.bind(BackendApplicationContribution).toConstantValue({
+                onStop: async () => { throw new Error('boom'); }
+            });
+            container.bind(BackendApplicationContribution).toConstantValue({
+                onStop: () => { secondRan = true; }
+            });
+            const errorStub = sandbox.stub(console, 'error');
+
+            const app = container.get(TestBackendApplication);
+            await app.invokeGracefulShutdown();
+
+            expect(secondRan, 'second contribution should still be stopped after first rejects').to.be.true;
+            expect(errorStub.calledWithMatch('Could not stop contribution')).to.be.true;
+        });
+
+        it('is idempotent when a contribution re-enters graceful shutdown', async () => {
+            const container = createTestContainer();
+            // Indirected through a holder so the contribution closure can refer to the
+            // application instance that is constructed after the binding is recorded.
+            const appHolder: { current?: TestBackendApplication } = {};
+            container.bind(BackendApplicationContribution).toConstantValue({
+                onStop: () => appHolder.current!.invokeGracefulShutdown()
+            });
+            const unbindSpy = sandbox.spy(container, 'unbindAllAsync');
+
+            appHolder.current = container.get(TestBackendApplication);
+            await appHolder.current.invokeGracefulShutdown();
+
+            expect(unbindSpy.callCount, 'unbindAllAsync should be called only once').to.equal(1);
+            expect(exitStub.callCount, 'process.exit should be called only once').to.equal(1);
+        });
+
+    });
+
+    describe('process exit handler', () => {
+
+        it('does not re-invoke contributions after graceful shutdown ran them', async () => {
+            const container = createTestContainer();
+            const onStopSpy = sandbox.spy();
+            container.bind(BackendApplicationContribution).toConstantValue({ onStop: onStopSpy });
+            const terminateStub = sandbox.stub(ProcessUtils.prototype, 'terminateProcessTree');
+
+            const app = container.get(TestBackendApplication);
+            const exitListener = process.listeners('exit')[0] as () => void;
+
+            await app.invokeGracefulShutdown();
+            expect(onStopSpy.callCount, 'contribution onStop should fire from gracefulShutdown').to.equal(1);
+
+            exitListener();
+
+            expect(onStopSpy.callCount, 'contribution onStop should not be invoked a second time').to.equal(1);
+            expect(terminateStub.called, 'terminateProcessTree should be invoked by the exit handler').to.be.true;
+        });
+
+        it('invokes contributions synchronously when graceful shutdown was bypassed', () => {
+            const container = createTestContainer();
+            const onStopSpy = sandbox.spy();
+            container.bind(BackendApplicationContribution).toConstantValue({ onStop: onStopSpy });
+            const terminateStub = sandbox.stub(ProcessUtils.prototype, 'terminateProcessTree');
+
+            container.get(TestBackendApplication);
+            const exitListener = process.listeners('exit')[0] as () => void;
+
+            exitListener();
+
+            expect(onStopSpy.calledOnce, 'sync exit path should still invoke contributions').to.be.true;
+            expect(terminateStub.called, 'terminateProcessTree should be invoked').to.be.true;
+        });
+
+    });
+
+});

package/src/node/backend-application.ts

@@ -21,10 +21,10 @@ import * as https from 'https';
 import * as express from 'express';
 import * as yargs from 'yargs';
 import * as fs from 'fs-extra';
-import { inject, named, injectable, postConstruct } from 'inversify';
+import { inject, named, injectable, type interfaces, postConstruct } from 'inversify';
 import { ContributionProvider, LogLevel, MaybePromise, MeasurementContext, Stopwatch } from '../common';
 import { CliContribution } from './cli';
-import { Deferred } from '../common/promise-util';
+import { Deferred, timeoutReject } from '../common/promise-util';
 import { environment } from '../common/index';
 import { AddressInfo } from 'net';
 import { ProcessUtils } from './process-utils';
@@ -35,12 +35,19 @@ import { ProcessUtils } from './process-utils';
  */
 export const BackendApplicationPath = process.env.THEIA_APP_PROJECT_PATH || process.cwd();
 
+/**
+ * Private injection token for the backend's root Inversify {@link Container}.
+ */
+export const RootContainer = Symbol('RootContainer');
+
 export type DnsResultOrder = 'ipv4first' | 'verbatim' | 'nodeDefault';
 
 const APP_PROJECT_PATH = 'app-project-path';
 
 const TIMER_WARNING_THRESHOLD = 50;
 
+const SHUTDOWN_TIMEOUT_MS = 5000;
+
 const DEFAULT_PORT = environment.electron.is() ? 0 : 3000;
 const DEFAULT_HOST = 'localhost';
 const DEFAULT_SSL = false;
@@ -103,12 +110,23 @@ export interface BackendApplicationContribution {
     onStart?(server: http.Server | https.Server): MaybePromise<void>;
 
     /**
-     * Called when the backend application shuts down. Contributions must perform only synchronous operations.
-     * Any kind of additional asynchronous work queued in the event loop will be ignored and abandoned.
+     * Called when the backend application shuts down.
+     *
+     * When shutdown is initiated via `SIGINT`/`SIGTERM`, contributions are dispatched
+     * in parallel and any returned promise is awaited up to `SHUTDOWN_TIMEOUT_MS`
+     * milliseconds while injected services from the root container are still
+     * resolvable.
+     *
+     * On synchronous-exit fallback paths (uncaught exceptions, server bind failures,
+     * or normal process exit), the hook is invoked synchronously and any returned
+     * promise is discarded. Implementations should be resilient to either path.
+     *
+     * Contributions must be independent of one another during stop because they are
+     * dispatched in parallel.
      *
      * @param app the express application.
      */
-    onStop?(app?: express.Application): void;
+    onStop?(app?: express.Application): MaybePromise<void>;
 }
 
 @injectable()
@@ -162,8 +180,14 @@ export class BackendApplication {
     @inject(Stopwatch)
     protected readonly stopwatch: Stopwatch;
 
+    @inject(RootContainer)
+    protected readonly rootContainer: interfaces.Container;
+
     private _configured: Promise<void>;
 
+    private stoppedContributions = false;
+    private shuttingDown = false;
+
     private settlementContext?: MeasurementContext<BackendApplicationContribution>;
 
     constructor(
@@ -179,18 +203,15 @@ export class BackendApplication {
         process.on('SIGPIPE', () => {
             console.error(new Error('Unexpected SIGPIPE'));
         });
-        /**
-         * Kill the current process tree on exit.
-         */
-        function signalHandler(signal: NodeJS.Signals): never {
-            process.exit(1);
-        }
+
         // Handles normal process termination.
         process.on('exit', () => this.onStop());
-        // Handles `Ctrl+C`.
-        process.on('SIGINT', signalHandler);
-        // Handles `kill pid`.
-        process.on('SIGTERM', signalHandler);
+
+        // Handles `Ctrl+C` and `kill pid`. Delegates to gracefulShutdown so that
+        // root-scoped singletons get their @preDestroy hooks invoked before exit.
+        const onSignal = () => { this.gracefulShutdown().catch(err => console.error(err)); };
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
     }
 
     protected async initialize(): Promise<void> {
@@ -332,18 +353,82 @@ export class BackendApplication {
             : `${scheme}://${address}:${port}`;
     }
 
-    protected onStop(): void {
+    /**
+     * Performs an asynchronous shutdown of the backend in two phases:
+     *
+     * 1. Contributions' {@link BackendApplicationContribution.onStop onStop} hooks are
+     *    dispatched in parallel and awaited so that they can still resolve services
+     *    from the root Inversify container while it is bound.
+     * 2. All services in the root container are unbound, running their `@preDestroy`
+     *    hooks.
+     *
+     * Each phase has its own {@link SHUTDOWN_TIMEOUT_MS} budget to avoid hanging on a
+     * misbehaving hook. Late-resolving promises from a timed-out phase may still
+     * settle in the background and could log noisily or interact with a partly
+     * unbound container; this is accepted because the process is exiting.
+     *
+     * Idempotent: a second invocation is a no-op. Exits the process with code 1 so
+     * that the `process.on('exit')` handler runs for fallback cleanup such as
+     * {@link ProcessUtils.terminateProcessTree}; the exit handler does not re-invoke
+     * contribution `onStop()` hooks that this method already dispatched.
+     */
+    protected async gracefulShutdown(): Promise<void> {
+        if (this.shuttingDown) {
+            return;
+        }
+        this.shuttingDown = true;
+
+        try {
+            await Promise.race([
+                this.stopContributions(),
+                timeoutReject<void>(SHUTDOWN_TIMEOUT_MS, `Stopping backend contributions timed out after ${SHUTDOWN_TIMEOUT_MS}ms`)
+            ]);
+        } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`Backend contributions cleanup failed: ${message}`);
+        }
+
+        try {
+            await Promise.race([
+                this.rootContainer.unbindAllAsync(),
+                timeoutReject<void>(SHUTDOWN_TIMEOUT_MS, `Container unbind timed out after ${SHUTDOWN_TIMEOUT_MS}ms`)
+            ]);
+        } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`Backend root container cleanup failed: ${message}`);
+        }
+
+        process.exit(1);
+    }
+
+    protected async stopContributions(): Promise<void> {
+        if (this.stoppedContributions) {
+            return;
+        }
+        this.stoppedContributions = true;
         console.info('>>> Stopping backend contributions...');
-        for (const contrib of this.contributionsProvider.getContributions()) {
+        // The `async` wrapper converts a synchronous throw inside a non-async
+        // contribution's `onStop` into a rejected promise so the per-contribution
+        // try/catch can handle it; otherwise `Promise.all` would abort.
+        await Promise.all(this.contributionsProvider.getContributions().map(async contrib => {
             if (contrib.onStop) {
                 try {
-                    contrib.onStop(this.app);
+                    await contrib.onStop(this.app);
                 } catch (error) {
                     console.error('Could not stop contribution', error);
                 }
             }
-        }
+        }));
         console.info('<<< All backend contributions have been stopped.');
+    }
+
+    protected onStop(): void {
+        // Deliberate fire-and-forget of an async `stopContributions`()` call.
+        // It invokes each contribution's `onStop` synchronously up to its
+        // first `await`, so any synchronous cleanup runs before
+        // `terminateProcessTree`. Any returned promises are abandoned because
+        // the `'exit'` event does not yield back to the event loop.
+        this.stopContributions();
         this.processUtils.terminateProcessTree(process.pid);
     }
 

package/src/node/logger-cli-contribution.spec.ts

@@ -67,7 +67,7 @@ describe('log-level-cli-contribution', () => {
     });
 
     it('should use --log-level flag', async () => {
-        const args: yargs.Arguments = yargs.parse(['--log-level=debug']);
+        const args: yargs.Arguments = await yargs.parse(['--log-level=debug']);
         await cli.setArguments(args);
 
         expect(cli.defaultLogLevel).eq(LogLevel.DEBUG);
@@ -85,7 +85,7 @@ describe('log-level-cli-contribution', () => {
         fs.fsyncSync(file.fd);
         fs.closeSync(file.fd);
 
-        const args: yargs.Arguments = yargs.parse(['--log-config', file.path]);
+        const args: yargs.Arguments = await yargs.parse(['--log-config', file.path]);
         await cli.setArguments(args);
 
         expect(cli.defaultLogLevel).eq(LogLevel.INFO);
@@ -96,7 +96,7 @@ describe('log-level-cli-contribution', () => {
     });
 
     it('should use info as default log level', async () => {
-        const args: yargs.Arguments = yargs.parse([]);
+        const args: yargs.Arguments = await yargs.parse([]);
         await cli.setArguments(args);
 
         expect(cli.defaultLogLevel).eq(LogLevel.INFO);
@@ -113,7 +113,7 @@ describe('log-level-cli-contribution', () => {
             }
         }));
 
-        const args: yargs.Arguments = yargs.parse(['--log-config', file.path]);
+        const args: yargs.Arguments = await yargs.parse(['--log-config', file.path]);
         await cli.setArguments(args);
         sinon.assert.calledWithMatch(consoleErrorSpy, 'Unknown default log level in');
     });
@@ -128,13 +128,13 @@ describe('log-level-cli-contribution', () => {
             }
         }));
 
-        const args: yargs.Arguments = yargs.parse(['--log-config', file.path]);
+        const args: yargs.Arguments = await yargs.parse(['--log-config', file.path]);
         await cli.setArguments(args);
         sinon.assert.calledWithMatch(consoleErrorSpy, 'Unknown log level for logger hello in');
     });
 
     it('should reject nonexistent config files', async () => {
-        const args: yargs.Arguments = yargs.parse(['--log-config', '/tmp/cacaca']);
+        const args: yargs.Arguments = await yargs.parse(['--log-config', '/tmp/cacaca']);
         await cli.setArguments(args);
         sinon.assert.calledWithMatch(consoleErrorSpy, 'no such file or directory');
     });
@@ -150,7 +150,7 @@ describe('log-level-cli-contribution', () => {
         });
         fs.writeFileSync(file.fd, '{' + text);
 
-        const args: yargs.Arguments = yargs.parse(['--log-config', file.path]);
+        const args: yargs.Arguments = await yargs.parse(['--log-config', file.path]);
         await cli.setArguments(args);
         sinon.assert.calledWithMatch(consoleErrorSpy, 'Error reading log config file');
     });
@@ -175,7 +175,7 @@ describe('log-level-cli-contribution', () => {
             fs.fsyncSync(file.fd);
             fs.closeSync(file.fd);
 
-            const args: yargs.Arguments = yargs.parse(['--log-config', file.path]);
+            const args: yargs.Arguments = await yargs.parse(['--log-config', file.path]);
             await cli.setArguments(args);
         }
 
@@ -224,7 +224,7 @@ describe('log-level-cli-contribution', () => {
         }));
         fs.fsyncSync(file.fd);
 
-        const args: yargs.Arguments = yargs.parse(['--log-config', file.path]);
+        const args: yargs.Arguments = await yargs.parse(['--log-config', file.path]);
         await cli.setArguments(args);
 
         expect(cli.defaultLogLevel).eq(LogLevel.INFO);