@theia/plugin-ext-headless 1.46.0-next.106

package/src/hosted/node/headless-hosted-plugin.ts

@@ -0,0 +1,199 @@
+// *****************************************************************************
+// Copyright (C) 2024 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
+// *****************************************************************************
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+// some code copied and modified from https://github.com/microsoft/vscode/blob/da5fb7d5b865aa522abc7e82c10b746834b98639/src/vs/workbench/api/node/extHostExtensionService.ts
+
+import { generateUuid } from '@theia/core/lib/common/uuid';
+import { injectable, inject, named } from '@theia/core/shared/inversify';
+import { getPluginId, DeployedPlugin, HostedPluginServer, PluginDeployer } from '@theia/plugin-ext/lib/common/plugin-protocol';
+import { setUpPluginApi } from '../../main/node/main-context';
+import { RPCProtocol, RPCProtocolImpl } from '@theia/plugin-ext/lib/common/rpc-protocol';
+import { ContributionProvider, Disposable, DisposableCollection, nls } from '@theia/core';
+import { environment } from '@theia/core/shared/@theia/application-package/lib/environment';
+import { IPCChannel } from '@theia/core/lib/node';
+import { BackendApplicationConfigProvider } from '@theia/core/lib/node/backend-application-config-provider';
+import { HostedPluginProcess } from '@theia/plugin-ext/lib/hosted/node/hosted-plugin-process';
+import { IShellTerminalServer } from '@theia/terminal/lib/common/shell-terminal-protocol';
+import { HeadlessPluginManagerExt, HEADLESSMAIN_RPC_CONTEXT } from '../../common/headless-plugin-rpc';
+import { AbstractHostedPluginSupport, PluginContributions } from '@theia/plugin-ext/lib/hosted/common/hosted-plugin';
+import { TheiaHeadlessPluginScanner } from './scanners/scanner-theia-headless';
+import { SupportedHeadlessActivationEvents } from '../../common/headless-plugin-protocol';
+import { PluginDeployerImpl } from '@theia/plugin-ext/lib/main/node/plugin-deployer-impl';
+
+import URI from '@theia/core/lib/common/uri';
+import * as fs from 'fs';
+import * as asyncFs from 'fs/promises';
+
+export type HeadlessPluginHost = string;
+
+export function isHeadlessPlugin(plugin: DeployedPlugin): boolean {
+    return !!plugin.metadata.model.entryPoint.headless;
+}
+
+@injectable()
+export class HeadlessHostedPluginSupport extends AbstractHostedPluginSupport<HeadlessPluginManagerExt, HostedPluginServer> {
+
+    @inject(HostedPluginProcess)
+    protected readonly pluginProcess: HostedPluginProcess;
+
+    @inject(IShellTerminalServer)
+    protected readonly shellTerminalServer: IShellTerminalServer;
+
+    @inject(TheiaHeadlessPluginScanner)
+    protected readonly scanner: TheiaHeadlessPluginScanner;
+
+    @inject(PluginDeployer)
+    protected readonly pluginDeployer: PluginDeployerImpl;
+
+    @inject(ContributionProvider)
+    @named(SupportedHeadlessActivationEvents)
+    protected readonly supportedActivationEventsContributions: ContributionProvider<string[]>;
+
+    constructor() {
+        super(generateUuid());
+    }
+
+    shutDown(): void {
+        this.pluginProcess.terminatePluginServer();
+    }
+
+    protected createTheiaReadyPromise(): Promise<unknown> {
+        return Promise.all([this.envServer.getVariables()]);
+    }
+
+    // Only load headless plugins
+    protected acceptPlugin(plugin: DeployedPlugin): boolean | DeployedPlugin {
+        if (!isHeadlessPlugin(plugin)) {
+            return false;
+        }
+
+        if (plugin.metadata.model.engine.type === this.scanner.apiType) {
+            // Easy case: take it as it is
+            return true;
+        }
+
+        // Adapt it for headless
+        return this.scanner.adaptForHeadless(plugin);
+    }
+
+    protected handleContributions(_plugin: DeployedPlugin): Disposable {
+        // We have no contribution points, yet, for headless plugins
+        return Disposable.NULL;
+    }
+
+    protected override async beforeSyncPlugins(toDisconnect: DisposableCollection): Promise<void> {
+        await super.beforeSyncPlugins(toDisconnect);
+
+        // Plugin deployment is asynchronous, so wait until that's finished.
+        return new Promise<void>((resolve, reject) => {
+            this.pluginDeployer.onDidDeploy(resolve);
+            toDisconnect.push(Disposable.create(reject));
+        });
+    }
+
+    protected async obtainManager(host: string, hostContributions: PluginContributions[], toDisconnect: DisposableCollection): Promise<HeadlessPluginManagerExt | undefined> {
+        let manager = this.managers.get(host);
+        if (!manager) {
+            const pluginId = getPluginId(hostContributions[0].plugin.metadata.model);
+            const rpc = this.initRpc(host, pluginId);
+            toDisconnect.push(rpc);
+
+            manager = rpc.getProxy(HEADLESSMAIN_RPC_CONTEXT.HOSTED_PLUGIN_MANAGER_EXT);
+            this.managers.set(host, manager);
+            toDisconnect.push(Disposable.create(() => this.managers.delete(host)));
+
+            const [extApi, globalState] = await Promise.all([
+                this.server.getExtPluginAPI(),
+                this.pluginServer.getAllStorageValues(undefined)
+            ]);
+            if (toDisconnect.disposed) {
+                return undefined;
+            }
+
+            const activationEvents = this.supportedActivationEventsContributions.getContributions().flatMap(array => array);
+            const shell = await this.shellTerminalServer.getDefaultShell();
+            const isElectron = environment.electron.is();
+
+            await manager.$init({
+                activationEvents,
+                globalState,
+                env: {
+                    language: nls.locale || nls.defaultLocale,
+                    shell,
+                    appName: BackendApplicationConfigProvider.get().applicationName,
+                    appHost: isElectron ? 'desktop' : 'web' // TODO: 'web' could be the embedder's name, e.g. 'github.dev'
+                },
+                extApi
+            });
+            if (toDisconnect.disposed) {
+                return undefined;
+            }
+        }
+        return manager;
+    }
+
+    protected initRpc(host: HeadlessPluginHost, pluginId: string): RPCProtocol {
+        const rpc = this.createServerRpc(host);
+        this.container.bind(RPCProtocol).toConstantValue(rpc);
+        setUpPluginApi(rpc, this.container);
+        this.mainPluginApiProviders.getContributions().forEach(p => p.initialize(rpc, this.container));
+        return rpc;
+    }
+
+    protected createServerRpc(pluginHostId: string): RPCProtocol {
+        const channel = new IPCChannel(this.pluginProcess['childProcess']);
+
+        return new RPCProtocolImpl(channel);
+    }
+
+    protected async getStoragePath(): Promise<string | undefined> {
+        // Headless plugins are associated with the main Node process, so
+        // their storage is the global storage.
+        return this.getHostGlobalStoragePath();
+    }
+
+    protected async getHostGlobalStoragePath(): Promise<string> {
+        const configDirUri = await this.envServer.getConfigDirUri();
+        const globalStorageFolderUri = new URI(configDirUri).resolve('globalStorage');
+        const globalStorageFolderUrl = new URL(globalStorageFolderUri.toString());
+
+        let stat: fs.Stats | undefined;
+
+        try {
+            stat = await asyncFs.stat(globalStorageFolderUrl);
+        } catch (_) {
+            // OK, no such directory
+        }
+
+        if (stat && !stat.isDirectory()) {
+            throw new Error(`Global storage folder is not a directory: ${globalStorageFolderUri}`);
+        }
+
+        // Make sure that folder by the path exists
+        if (!stat) {
+            await asyncFs.mkdir(globalStorageFolderUrl, { recursive: true });
+        }
+
+        const globalStorageFolderFsPath = await asyncFs.realpath(globalStorageFolderUrl);
+        if (!globalStorageFolderFsPath) {
+            throw new Error(`Could not resolve the FS path for URI: ${globalStorageFolderUri}`);
+        }
+        return globalStorageFolderFsPath;
+    }
+}

package/src/hosted/node/plugin-ext-headless-hosted-module.ts

@@ -0,0 +1,75 @@
+// *****************************************************************************
+// Copyright (C) 2024 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 * as path from 'path';
+import { bindContributionProvider } from '@theia/core/lib/common/contribution-provider';
+import { BackendApplicationContribution } from '@theia/core/lib/node';
+import { ContainerModule, interfaces } from '@theia/core/shared/inversify';
+import { ExtPluginApiProvider, HostedPluginServer, PluginHostEnvironmentVariable, PluginScanner } from '@theia/plugin-ext';
+import { HostedPluginSupport } from '@theia/plugin-ext/lib/hosted/node/hosted-plugin';
+import { HostedPluginProcess, HostedPluginProcessConfiguration } from '@theia/plugin-ext/lib/hosted/node/hosted-plugin-process';
+import { BackendPluginHostableFilter, HostedPluginServerImpl } from '@theia/plugin-ext/lib/hosted/node/plugin-service';
+import { MaybePromise } from '@theia/core';
+import { HeadlessPluginContainerModule } from '../../common/headless-plugin-container';
+import { HeadlessHostedPluginSupport, isHeadlessPlugin } from './headless-hosted-plugin';
+import { TheiaHeadlessPluginScanner } from './scanners/scanner-theia-headless';
+import { SupportedHeadlessActivationEvents } from '../../common/headless-plugin-protocol';
+
+export function bindCommonHostedBackend(bind: interfaces.Bind): void {
+    bind(HostedPluginProcess).toSelf().inSingletonScope();
+    bind(HostedPluginSupport).toSelf().inSingletonScope();
+
+    bindContributionProvider(bind, Symbol.for(ExtPluginApiProvider));
+    bindContributionProvider(bind, PluginHostEnvironmentVariable);
+    bindContributionProvider(bind, SupportedHeadlessActivationEvents);
+
+    bind(HostedPluginServerImpl).toSelf().inSingletonScope();
+    bind(HostedPluginServer).toService(HostedPluginServerImpl);
+    bind(HeadlessHostedPluginSupport).toSelf().inSingletonScope();
+    bind(BackendPluginHostableFilter).toConstantValue(isHeadlessPlugin);
+
+    bind(HostedPluginProcessConfiguration).toConstantValue({
+        path: path.join(__dirname, 'plugin-host-headless'),
+    });
+}
+
+export function bindHeadlessHosted(bind: interfaces.Bind): void {
+    bind(TheiaHeadlessPluginScanner).toSelf().inSingletonScope();
+    bind(PluginScanner).toService(TheiaHeadlessPluginScanner);
+    bind(SupportedHeadlessActivationEvents).toConstantValue(['*', 'onStartupFinished']);
+
+    bind(BackendApplicationContribution).toDynamicValue(({container}) => {
+        let hostedPluginSupport: HeadlessHostedPluginSupport | undefined;
+
+        return {
+            onStart(): MaybePromise<void> {
+                // Create a child container to isolate the Headless Plugin hosting stack
+                // from all connection-scoped frontend/backend plugin hosts and
+                // also to avoid leaking it into the global container scope
+                const headlessPluginsContainer = container.createChild();
+                const modules = container.getAll<ContainerModule>(HeadlessPluginContainerModule);
+                headlessPluginsContainer.load(...modules);
+
+                hostedPluginSupport = headlessPluginsContainer.get(HeadlessHostedPluginSupport);
+                hostedPluginSupport.onStart(headlessPluginsContainer);
+            },
+
+            onStop(): void {
+                hostedPluginSupport?.shutDown();
+            }
+        };
+    });
+}

package/src/hosted/node/plugin-host-headless-module.ts

@@ -0,0 +1,76 @@
+// *****************************************************************************
+// Copyright (C) 2024 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 '@theia/core/shared/reflect-metadata';
+import { ContainerModule } from '@theia/core/shared/inversify';
+import { RPCProtocol, RPCProtocolImpl } from '@theia/plugin-ext/lib/common/rpc-protocol';
+import { AbstractPluginHostRPC, PluginContainerModuleLoader } from '@theia/plugin-ext/lib/hosted/node/plugin-host-rpc';
+import { AbstractPluginManagerExtImpl, MinimalTerminalServiceExt } from '@theia/plugin-ext/lib/plugin/plugin-manager';
+import { HeadlessPluginHostRPC } from './plugin-host-headless-rpc';
+import { HeadlessPluginManagerExtImpl } from '../../plugin/headless-plugin-manager';
+import { IPCChannel } from '@theia/core/lib/node';
+import { InternalPluginContainerModule } from '@theia/plugin-ext/lib/plugin/node/plugin-container-module';
+
+import { EnvExtImpl } from '@theia/plugin-ext/lib/plugin/env';
+import { EnvNodeExtImpl } from '@theia/plugin-ext/lib/plugin/node/env-node-ext';
+import { LocalizationExt } from '@theia/plugin-ext';
+import { LocalizationExtImpl } from '@theia/plugin-ext/lib/plugin/localization-ext';
+import { InternalStorageExt } from '@theia/plugin-ext/lib/plugin/plugin-storage';
+import { InternalSecretsExt } from '@theia/plugin-ext/lib/plugin/secrets-ext';
+import { EnvironmentVariableCollectionImpl } from '@theia/plugin-ext/lib/plugin/terminal-ext';
+import { Disposable } from '@theia/core';
+
+export default new ContainerModule(bind => {
+    const channel = new IPCChannel();
+    bind(RPCProtocol).toConstantValue(new RPCProtocolImpl(channel));
+
+    bind(PluginContainerModuleLoader).toDynamicValue(({ container }) =>
+        (module: ContainerModule) => {
+            container.load(module);
+            const internalModule = module as InternalPluginContainerModule;
+            const pluginApiCache = internalModule.initializeApi?.(container);
+            return pluginApiCache;
+        }).inSingletonScope();
+
+    bind(AbstractPluginHostRPC).toService(HeadlessPluginHostRPC);
+    bind(HeadlessPluginHostRPC).toSelf().inSingletonScope();
+    bind(AbstractPluginManagerExtImpl).toService(HeadlessPluginManagerExtImpl);
+    bind(HeadlessPluginManagerExtImpl).toSelf().inSingletonScope();
+    bind(EnvExtImpl).to(EnvNodeExtImpl).inSingletonScope();
+    bind(LocalizationExt).to(LocalizationExtImpl).inSingletonScope();
+
+    const dummySecrets: InternalSecretsExt = {
+        get: () => Promise.resolve(undefined),
+        store: () => Promise.resolve(undefined),
+        delete: () => Promise.resolve(undefined),
+        $onDidChangePassword: () => Promise.resolve(),
+        onDidChangePassword: () => Disposable.NULL,
+    };
+    const dummyStorage: InternalStorageExt = {
+        init: () => undefined,
+        setPerPluginData: () => Promise.resolve(false),
+        getPerPluginData: () => ({}),
+        storageDataChangedEvent: () => Disposable.NULL,
+        $updatePluginsWorkspaceData: () => undefined
+    };
+    const dummyTerminalService: MinimalTerminalServiceExt = {
+        $initEnvironmentVariableCollections: () => undefined,
+        $setShell: () => undefined,
+        getEnvironmentVariableCollection: () => new EnvironmentVariableCollectionImpl(false),
+    };
+    bind(InternalSecretsExt).toConstantValue(dummySecrets);
+    bind(InternalStorageExt).toConstantValue(dummyStorage);
+    bind(MinimalTerminalServiceExt).toConstantValue(dummyTerminalService);
+});

package/src/hosted/node/plugin-host-headless-rpc.ts

@@ -0,0 +1,80 @@
+// *****************************************************************************
+// Copyright (C) 2024 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 { dynamicRequire } from '@theia/core/lib/node/dynamic-require';
+import { ContainerModule, injectable, inject } from '@theia/core/shared/inversify';
+import { EnvExtImpl } from '@theia/plugin-ext/lib/plugin/env';
+import { LocalizationExt } from '@theia/plugin-ext';
+import { LocalizationExtImpl } from '@theia/plugin-ext/lib/plugin/localization-ext';
+import { HEADLESSMAIN_RPC_CONTEXT } from '../../common/headless-plugin-rpc';
+import { HeadlessPluginManagerExtImpl } from '../../plugin/headless-plugin-manager';
+import { AbstractPluginHostRPC, ExtInterfaces } from '@theia/plugin-ext/lib/hosted/node/plugin-host-rpc';
+import { PluginModel } from '@theia/plugin-ext/lib/common/plugin-protocol';
+import { ExtPluginApi, ExtPluginApiHeadlessInitializationFn } from '../../common/plugin-ext-headless-api-contribution';
+
+type HeadlessExtInterfaces = Pick<ExtInterfaces, 'envExt'|'localizationExt'>;
+
+/**
+ * The RPC handler for headless plugins.
+ */
+@injectable()
+export class HeadlessPluginHostRPC extends AbstractPluginHostRPC<HeadlessPluginManagerExtImpl, null, HeadlessExtInterfaces> {
+    @inject(EnvExtImpl)
+    protected readonly envExt: EnvExtImpl;
+
+    @inject(LocalizationExt)
+    protected readonly localizationExt: LocalizationExtImpl;
+
+    constructor() {
+        super('HEADLESS_PLUGIN_HOST', undefined,
+            {
+                $pluginManager: HEADLESSMAIN_RPC_CONTEXT.HOSTED_PLUGIN_MANAGER_EXT,
+            }
+        );
+    }
+
+    protected createExtInterfaces(): HeadlessExtInterfaces {
+        return {
+            envExt: this.envExt,
+            localizationExt: this.localizationExt
+        };
+    }
+
+    protected createAPIFactory(_extInterfaces: HeadlessExtInterfaces): null {
+        // As yet there is no default API namespace for backend plugins to access the Theia framework
+        return null;
+    }
+
+    protected override getBackendPluginPath(pluginModel: PluginModel): string | undefined {
+        return pluginModel.entryPoint.headless;
+    }
+
+    protected initExtApi(extApi: ExtPluginApi): void {
+        interface PluginExports {
+            containerModule?: ContainerModule;
+            provideApi?: ExtPluginApiHeadlessInitializationFn;
+        }
+        if (extApi.headlessInitPath) {
+            const { containerModule, provideApi } = dynamicRequire<PluginExports>(extApi.headlessInitPath);
+            if (containerModule) {
+                this.loadContainerModule(containerModule);
+            }
+            if (provideApi) {
+                provideApi(this.rpc, this.pluginManager);
+            }
+        }
+    }
+}

package/src/hosted/node/plugin-host-headless.ts

@@ -0,0 +1,111 @@
+// *****************************************************************************
+// Copyright (C) 2018 Red Hat, Inc. 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 '@theia/core/shared/reflect-metadata';
+import { Container } from '@theia/core/shared/inversify';
+import { ConnectionClosedError, RPCProtocol } from '@theia/plugin-ext/lib/common/rpc-protocol';
+import { ProcessTerminatedMessage, ProcessTerminateMessage } from '@theia/plugin-ext/lib/hosted/node/hosted-plugin-protocol';
+import { HeadlessPluginHostRPC } from './plugin-host-headless-rpc';
+import pluginHostModule from './plugin-host-headless-module';
+
+const banner = `HEADLESS_PLUGIN_HOST(${process.pid}):`;
+console.log(banner, 'Starting instance');
+
+// override exit() function, to do not allow plugin kill this node
+process.exit = function (code?: number): void {
+    const err = new Error('A plugin called process.exit() but it was blocked.');
+    console.warn(banner, err.stack);
+} as (code?: number) => never;
+
+// same for 'crash'(works only in electron)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const proc = process as any;
+if (proc.crash) {
+    proc.crash = function (): void {
+        const err = new Error('A plugin called process.crash() but it was blocked.');
+        console.warn(banner, err.stack);
+    };
+}
+
+process.on('uncaughtException', (err: Error) => {
+    console.error(banner, err);
+});
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const unhandledPromises: Promise<any>[] = [];
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+process.on('unhandledRejection', (reason: any, promise: Promise<any>) => {
+    unhandledPromises.push(promise);
+    setTimeout(() => {
+        const index = unhandledPromises.indexOf(promise);
+        if (index >= 0) {
+            promise.catch(err => {
+                unhandledPromises.splice(index, 1);
+                if (terminating && (ConnectionClosedError.is(err) || ConnectionClosedError.is(reason))) {
+                    // during termination it is expected that pending rpc request are rejected
+                    return;
+                }
+                console.error(banner, `Promise rejection not handled in one second: ${err} , reason: ${reason}`);
+                if (err && err.stack) {
+                    console.error(banner, `With stack trace: ${err.stack}`);
+                }
+            });
+        }
+    }, 1000);
+});
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+process.on('rejectionHandled', (promise: Promise<any>) => {
+    const index = unhandledPromises.indexOf(promise);
+    if (index >= 0) {
+        unhandledPromises.splice(index, 1);
+    }
+});
+
+let terminating = false;
+
+const container = new Container();
+container.load(pluginHostModule);
+
+const rpc: RPCProtocol = container.get(RPCProtocol);
+const pluginHostRPC = container.get(HeadlessPluginHostRPC);
+
+process.on('message', async (message: string) => {
+    if (terminating) {
+        return;
+    }
+    try {
+        const msg = JSON.parse(message);
+        if (ProcessTerminateMessage.is(msg)) {
+            terminating = true;
+            if (msg.stopTimeout) {
+                await Promise.race([
+                    pluginHostRPC.terminate(),
+                    new Promise(resolve => setTimeout(resolve, msg.stopTimeout))
+                ]);
+            } else {
+                await pluginHostRPC.terminate();
+            }
+            rpc.dispose();
+            if (process.send) {
+                process.send(JSON.stringify({ type: ProcessTerminatedMessage.TYPE }));
+            }
+
+        }
+    } catch (e) {
+        console.error(banner, e);
+    }
+});

package/src/hosted/node/scanners/scanner-theia-headless.ts

@@ -0,0 +1,85 @@
+// *****************************************************************************
+// Copyright (C) 2024 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
+// *****************************************************************************
+
+/* eslint-disable @theia/localization-check */
+
+import { injectable } from '@theia/core/shared/inversify';
+import { DeployedPlugin, PluginPackage, PluginEntryPoint } from '@theia/plugin-ext';
+import { AbstractPluginScanner } from '@theia/plugin-ext/lib/hosted/node/scanners/scanner-theia';
+import { deepClone } from '@theia/core/lib/common/objects';
+
+@injectable()
+export class TheiaHeadlessPluginScanner extends AbstractPluginScanner {
+
+    constructor() {
+        super('theiaHeadlessPlugin');
+    }
+
+    protected getEntryPoint(plugin: PluginPackage): PluginEntryPoint {
+        if (plugin?.theiaPlugin?.headless) {
+            return {
+                headless: plugin.theiaPlugin.headless
+            };
+        };
+
+        return {
+            headless: plugin.main
+        };
+    }
+
+    /**
+     * Adapt the given `plugin`'s metadata for headless deployment, where it does not
+     * already natively specify its headless deployment, such as is the case for plugins
+     * declaring the `"vscode"` or `"theiaPlugin"` engine. This consists of cloning the
+     * relevant properties of its deployment metadata and modifying them as required,
+     * including but not limited to:
+     *
+     * - renaming the `lifecycle` start and stop functions as 'activate' and 'deactivate'
+     *   following the VS Code naming convention (in case the `plugin` is a Theia-style
+     *   plugin that uses 'start' and 'stop')
+     * - deleting inapplicable information such as frontend and backend init script paths
+     * - filtering/rewriting contributions and/or activation events
+     *
+     * The cloning is necessary to retain the original information for the non-headless
+     * deployments that the plugin also supports.
+     */
+    adaptForHeadless(plugin: DeployedPlugin): DeployedPlugin {
+        return {
+            type: plugin.type,
+            metadata: this.adaptMetadataForHeadless(plugin),
+            contributes: this.adaptContributesForHeadless(plugin)
+        };
+    }
+
+    protected adaptMetadataForHeadless(plugin: DeployedPlugin): DeployedPlugin['metadata'] {
+        const result = deepClone(plugin.metadata);
+
+        const lifecycle = result.lifecycle;
+        delete lifecycle.frontendInitPath;
+        delete lifecycle.backendInitPath;
+
+        // Same as in VS Code
+        lifecycle.startMethod = 'activate';
+        lifecycle.stopMethod = 'deactivate';
+
+        return result;
+    }
+
+    protected adaptContributesForHeadless(plugin: DeployedPlugin): DeployedPlugin['contributes'] {
+        // We don't yet support and contribution points in headless plugins
+        return undefined;
+    }
+}

package/src/hosted/node-electron/plugin-ext-headless-hosted-electron-module.ts

@@ -0,0 +1,22 @@
+// *****************************************************************************
+// Copyright (C) 2024 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 { interfaces } from '@theia/core/shared/inversify';
+import { bindCommonHostedBackend } from '../node/plugin-ext-headless-hosted-module';
+
+export function bindElectronBackend(bind: interfaces.Bind): void {
+    bindCommonHostedBackend(bind);
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// *****************************************************************************
+// Copyright (C) 2024 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
+// *****************************************************************************
+
+export * from './common';