@theia/core 1.77.0-next.1 → 1.77.0-next.14

package/src/node/bundled-resource-provider.spec.ts

@@ -0,0 +1,196 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH 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 'reflect-metadata';
+import { expect } from 'chai';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as temp from 'temp';
+import { Container } from 'inversify';
+import { EnvVariablesServer } from '../common/env-variables';
+import { ILogger } from '../common/logger';
+import { MockLogger } from '../common/test/mock-logger';
+import { FileUri } from '../common/file-uri';
+import { BundledResourceProvider, BundledResourceProviderImpl } from './bundled-resource-provider';
+import { FileSystemLocking, FileSystemLockingImpl } from './filesystem-locking';
+
+/**
+ * The provider recognizes archives by their `.asar` path segment and reads them through `fs`, which Electron
+ * patches to transparently read from the archive. Plain directories named `*.asar` therefore behave like
+ * archives from the point of view of the provider and let us test it outside of Electron.
+ */
+describe('BundledResourceProvider', () => {
+
+    const track = temp.track();
+
+    let configDir: string;
+    let appDir: string;
+    let provider: BundledResourceProvider;
+
+    beforeEach(() => {
+        const root = track.mkdirSync();
+        configDir = path.join(root, 'config');
+        appDir = path.join(root, 'app');
+        fs.mkdirSync(configDir);
+        fs.mkdirSync(appDir);
+        provider = createProvider();
+    });
+
+    /** Each provider instance stands for one run of the application, as resolved paths are cached. */
+    function createProvider(): BundledResourceProvider {
+        const container = new Container();
+        container.bind(ILogger).toConstantValue(new MockLogger());
+        container.bind(FileSystemLocking).to(FileSystemLockingImpl).inSingletonScope();
+        container.bind(EnvVariablesServer).toConstantValue({
+            getConfigDirUri: async () => FileUri.create(configDir).toString()
+        } as unknown as EnvVariablesServer);
+        container.bind(BundledResourceProviderImpl).toSelf().inSingletonScope();
+        container.bind(BundledResourceProvider).toService(BundledResourceProviderImpl);
+        return container.get(BundledResourceProvider);
+    }
+
+    afterEach(() => track.cleanupSync());
+
+    /**
+     * Assert that the given path is nested in the given directory. The provider derives the configuration
+     * directory from a URI, which on Windows yields a lower-case drive letter, so the paths cannot simply be
+     * compared by prefix. `path.relative` ignores the case of a path on Windows.
+     */
+    function expectNestedIn(directoryPath: string, nestedPath: string): void {
+        const relativePath = path.relative(directoryPath, nestedPath);
+        expect(relativePath).to.not.be.empty;
+        expect(relativePath.split(path.sep)).to.not.contain('..');
+    }
+
+    function writeResources(rootPath: string, files: Record<string, string>): string {
+        for (const [relativePath, content] of Object.entries(files)) {
+            const filePath = path.join(rootPath, relativePath);
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, content);
+        }
+        return rootPath;
+    }
+
+    it('returns the path of a resource that is not packaged into an archive', async () => {
+        const resourcePath = path.join(writeResources(appDir, { 'scripts/greet.sh': 'echo hello' }), 'scripts');
+        expect(await provider.resolveExternalPath(resourcePath)).to.equal(resourcePath);
+    });
+
+    it('rejects for a resource that does not exist', async () => {
+        const resourcePath = path.join(appDir, 'scripts');
+        await provider.resolveExternalPath(resourcePath).then(
+            () => expect.fail('should have been rejected'),
+            error => expect(String(error)).to.contain(resourcePath)
+        );
+    });
+
+    it('extracts a packaged resource into the configuration directory', async () => {
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello', 'scripts/nested/.hidden': 'secret' });
+
+        const resolvedPath = await provider.resolveExternalPath(path.join(archivePath, 'scripts'));
+
+        expect(resolvedPath).to.not.contain('.asar');
+        expectNestedIn(configDir, resolvedPath);
+        expect(fs.readFileSync(path.join(resolvedPath, 'greet.sh'), 'utf8')).to.equal('echo hello');
+        expect(fs.readFileSync(path.join(resolvedPath, 'nested', '.hidden'), 'utf8')).to.equal('secret');
+    });
+
+    it('extracts a packaged resource that is a plain file', async () => {
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello' });
+
+        const resolvedPath = await provider.resolveExternalPath(path.join(archivePath, 'scripts', 'greet.sh'));
+
+        expectNestedIn(configDir, resolvedPath);
+        expect(fs.readFileSync(resolvedPath, 'utf8')).to.equal('echo hello');
+    });
+
+    it('extracts a packaged file as executable', async function (): Promise<void> {
+        if (process.platform === 'win32') {
+            this.skip();
+        }
+        // Electron reports the files of an asar archive with this mode, even executables.
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'native/tool': 'binary' });
+        fs.chmodSync(path.join(archivePath, 'native', 'tool'), 0o644);
+
+        const resolvedPath = await provider.resolveExternalPath(path.join(archivePath, 'native', 'tool'));
+
+        expect(fs.statSync(resolvedPath).mode & 0o700).to.equal(0o700);
+    });
+
+    it('prefers the copy that the packaging step has left outside of the archive', async () => {
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello' });
+        const unpackedPath = writeResources(`${archivePath}.unpacked`, { 'scripts/greet.sh': 'echo hello' });
+
+        const resolvedPath = await provider.resolveExternalPath(path.join(archivePath, 'scripts'));
+
+        expect(resolvedPath).to.equal(path.join(unpackedPath, 'scripts'));
+    });
+
+    it('extracts a packaged resource that was only unpacked partially', async () => {
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello', 'scripts/farewell.sh': 'echo bye' });
+        writeResources(`${archivePath}.unpacked`, { 'scripts/greet.sh': 'echo hello' });
+
+        const resolvedPath = await provider.resolveExternalPath(path.join(archivePath, 'scripts'));
+
+        expectNestedIn(configDir, resolvedPath);
+        expect(fs.readFileSync(path.join(resolvedPath, 'farewell.sh'), 'utf8')).to.equal('echo bye');
+    });
+
+    it('re-extracts a resource that was removed from the configuration directory', async () => {
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello' });
+        const resourcePath = path.join(archivePath, 'scripts');
+
+        const resolvedPath = await provider.resolveExternalPath(resourcePath);
+        fs.rmSync(resolvedPath, { recursive: true });
+
+        expect(await provider.resolveExternalPath(resourcePath)).to.equal(resolvedPath);
+        expect(fs.readFileSync(path.join(resolvedPath, 'greet.sh'), 'utf8')).to.equal('echo hello');
+    });
+
+    it('extracts into a temporary directory if the configuration directory cannot be written to', async () => {
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello' });
+        // a configuration directory that is a regular file cannot hold the extracted resources
+        configDir = path.join(appDir, 'not-a-directory');
+        fs.writeFileSync(configDir, '');
+
+        const resolvedPath = await createProvider().resolveExternalPath(path.join(archivePath, 'scripts'));
+
+        expectNestedIn(os.tmpdir(), resolvedPath);
+        expect(fs.readFileSync(path.join(resolvedPath, 'greet.sh'), 'utf8')).to.equal('echo hello');
+        fs.rmSync(resolvedPath, { recursive: true, force: true });
+    });
+
+    it('updates an extracted resource when the application has been updated', async () => {
+        const archivePath = path.join(appDir, 'app.asar');
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello' });
+        const resourcePath = path.join(archivePath, 'scripts');
+
+        await provider.resolveExternalPath(resourcePath);
+        writeResources(archivePath, { 'scripts/greet.sh': 'echo hello again' });
+        const resolvedPath = await createProvider().resolveExternalPath(resourcePath);
+
+        expect(fs.readFileSync(path.join(resolvedPath, 'greet.sh'), 'utf8')).to.equal('echo hello again');
+    });
+
+});

package/src/node/bundled-resource-provider.ts

@@ -0,0 +1,266 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH 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 crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { inject, injectable, interfaces, named } from 'inversify';
+import { EnvVariablesServer } from '../common/env-variables';
+import { FileUri } from '../common/file-uri';
+import { ILogger } from '../common/logger';
+import { FileSystemLocking } from './filesystem-locking';
+
+export const BundledResourceProvider = Symbol('BundledResourceProvider') as symbol & interfaces.Abstract<BundledResourceProvider>;
+/**
+ * Provides paths to resources that are bundled with the application, in a form that can also be used by
+ * processes which do not run inside the application, such as shells, debug adapters or other external tools.
+ *
+ * When an Electron application is packaged with `asar: true`, the resources of the application are stored in
+ * an `app.asar` archive. Paths pointing into such an archive can only be read through Electron's patched `fs`
+ * module, so handing them to an external process fails. Therefore, always resolve a bundled resource through
+ * this service before passing its path to a process outside of the application.
+ */
+export interface BundledResourceProvider {
+    /**
+     * Resolve the given path of a bundled file or directory to a path that external processes can read.
+     *
+     * If the resource is not packaged into an archive, its path is returned unchanged. Otherwise the copy that
+     * the packaging step has left outside of the archive is used, if it is complete, and the resource is
+     * extracted from the archive into the configuration directory as a last resort.
+     *
+     * Results are cached, so that a resource is extracted at most once per application version.
+     *
+     * @param resourcePath the path of the bundled resource, typically resolved against `__dirname`.
+     * @returns the path to use outside of the application.
+     * @throws if the resource does not exist or cannot be made available.
+     */
+    resolveExternalPath(resourcePath: string): Promise<string>;
+}
+
+@injectable()
+export class BundledResourceProviderImpl implements BundledResourceProvider {
+
+    @inject(ILogger) @named('core:BundledResourceProviderImpl')
+    protected readonly logger: ILogger;
+
+    @inject(EnvVariablesServer)
+    protected readonly envVariablesServer: EnvVariablesServer;
+
+    @inject(FileSystemLocking)
+    protected readonly fileSystemLocking: FileSystemLocking;
+
+    /** The folder within the configuration directory into which resources are extracted. */
+    protected readonly extractionFolder = 'bundled-resources';
+
+    /** Resources extracted for another application version are removed when they are older than this. */
+    protected readonly staleExtractionAge = 7 * 24 * 60 * 60 * 1000;
+
+    protected readonly resolved = new Map<string, Promise<string>>();
+    protected temporaryExtractionPath: Promise<string> | undefined;
+
+    async resolveExternalPath(resourcePath: string): Promise<string> {
+        const normalizedPath = path.resolve(resourcePath);
+        const pending = this.resolved.get(normalizedPath);
+        if (pending) {
+            try {
+                const resolvedPath = await pending;
+                if (await this.exists(resolvedPath)) {
+                    return resolvedPath;
+                }
+            } catch {
+                // the previous attempt failed, so try again below
+            }
+            this.resolved.delete(normalizedPath);
+        }
+        const result = this.doResolveExternalPath(normalizedPath);
+        this.resolved.set(normalizedPath, result);
+        return result;
+    }
+
+    protected async doResolveExternalPath(resourcePath: string): Promise<string> {
+        if (!await this.exists(resourcePath)) {
+            throw new Error(`Bundled resource does not exist: ${resourcePath}`);
+        }
+        const archivePath = this.findArchivePath(resourcePath);
+        if (!archivePath) {
+            // The resource is not packaged into an archive, so external processes can read it directly.
+            return resourcePath;
+        }
+        const relativePath = path.relative(archivePath, resourcePath);
+        const unpackedPath = path.join(`${archivePath}.unpacked`, relativePath);
+        if (await this.isExtracted(resourcePath, unpackedPath)) {
+            return unpackedPath;
+        }
+        const extractionPath = path.join(await this.getExtractionPath(archivePath), relativePath);
+        await this.fileSystemLocking.lockPath(archivePath, () => this.extract(resourcePath, extractionPath));
+        this.logger.info(`Extracted bundled resource '${resourcePath}' to '${extractionPath}'.`);
+        return extractionPath;
+    }
+
+    /**
+     * Find the archive that the given resource is packaged into, if any.
+     *
+     * @returns the path of the archive, i.e. the shortest prefix of the given path ending in an `.asar` segment,
+     * which is also how Electron itself determines the archive that a path refers to.
+     */
+    protected findArchivePath(resourcePath: string): string | undefined {
+        const segments = resourcePath.split(/[\\/]/);
+        const archiveIndex = segments.findIndex(segment => segment.toLowerCase().endsWith('.asar'));
+        return archiveIndex < 0 ? undefined : segments.slice(0, archiveIndex + 1).join(path.sep);
+    }
+
+    /**
+     * Whether every file of the given resource is already available at the given target path. Packaging tools
+     * only unpack the files that the application configured them to unpack, so a partial copy must be ignored.
+     */
+    protected async isExtracted(resourcePath: string, targetPath: string): Promise<boolean> {
+        for (const file of await this.collectFiles(resourcePath)) {
+            if (!await this.exists(path.join(targetPath, file))) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    protected async extract(resourcePath: string, targetPath: string): Promise<void> {
+        for (const file of await this.collectFiles(resourcePath)) {
+            await this.copyFile(path.join(resourcePath, file), path.join(targetPath, file));
+        }
+    }
+
+    /**
+     * Collect the files of the given resource as paths relative to it. The relative path of a resource that is
+     * a plain file is the empty string.
+     */
+    protected async collectFiles(resourcePath: string, relativePath: string = ''): Promise<string[]> {
+        const currentPath = path.join(resourcePath, relativePath);
+        if (!(await fs.promises.stat(currentPath)).isDirectory()) {
+            return [relativePath];
+        }
+        const files: string[] = [];
+        for (const entry of await fs.promises.readdir(currentPath)) {
+            files.push(...await this.collectFiles(resourcePath, path.join(relativePath, entry)));
+        }
+        return files;
+    }
+
+    protected async copyFile(sourcePath: string, targetPath: string): Promise<void> {
+        const sourceStat = await fs.promises.stat(sourcePath);
+        if (await this.isUpToDate(targetPath, sourceStat)) {
+            return;
+        }
+        await fs.promises.mkdir(path.dirname(targetPath), { recursive: true, mode: 0o700 });
+        // Write to a temporary file and move it into place, so that a concurrently starting application
+        // instance never reads partially written content.
+        const temporaryPath = `${targetPath}.${process.pid}.tmp`;
+        try {
+            // Electron reports the files of an asar archive as not executable, even those that the archive marks as
+            // executable, so every extracted file is made executable for the owner to keep bundled executables usable.
+            await fs.promises.writeFile(temporaryPath, await fs.promises.readFile(sourcePath), { mode: sourceStat.mode & 0o777 | 0o700 });
+            try {
+                await fs.promises.rename(temporaryPath, targetPath);
+            } catch {
+                // renaming onto an existing file is not supported on all platforms
+                await fs.promises.rm(targetPath, { force: true });
+                await fs.promises.rename(temporaryPath, targetPath);
+            }
+        } finally {
+            await fs.promises.rm(temporaryPath, { force: true });
+        }
+    }
+
+    protected async isUpToDate(targetPath: string, sourceStat: fs.Stats): Promise<boolean> {
+        try {
+            return (await fs.promises.stat(targetPath)).size === sourceStat.size;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * The directory into which resources of the given archive are extracted. It is specific to the content of
+     * the archive, so that updating the application invalidates previously extracted copies.
+     */
+    protected async getExtractionPath(archivePath: string): Promise<string> {
+        const archiveName = path.basename(archivePath, path.extname(archivePath));
+        try {
+            const extractionRoot = path.join(FileUri.fsPath(await this.envVariablesServer.getConfigDirUri()), this.extractionFolder);
+            const extractionPath = path.join(extractionRoot, `${archiveName}-${this.getArchiveStamp(archivePath)}`);
+            await fs.promises.mkdir(extractionPath, { recursive: true, mode: 0o700 });
+            this.removeStaleExtractions(extractionRoot, `${archiveName}-`, extractionPath);
+            return extractionPath;
+        } catch (error) {
+            this.logger.warn('Could not extract bundled resources into the configuration directory, using a temporary directory instead.', error);
+            return this.getTemporaryExtractionPath();
+        }
+    }
+
+    /**
+     * Fallback for applications whose configuration directory cannot be written to. The directory is unique to
+     * this run of the application, so that resources are extracted again whenever the application is started.
+     */
+    protected getTemporaryExtractionPath(): Promise<string> {
+        return this.temporaryExtractionPath ??= fs.promises.mkdtemp(path.join(os.tmpdir(), 'theia-bundled-resources-'));
+    }
+
+    /**
+     * Identify the content of the given archive. `process.noAsar` is toggled around the synchronous `stat` call
+     * to get the stats of the archive file itself rather than of the directory that it appears as.
+     */
+    protected getArchiveStamp(archivePath: string): string {
+        const asarProcess = process as NodeJS.Process & { noAsar?: boolean };
+        const noAsar = asarProcess.noAsar;
+        try {
+            asarProcess.noAsar = true;
+            const stat = fs.statSync(archivePath);
+            return crypto.createHash('sha256').update(`${archivePath}:${stat.size}:${stat.mtimeMs}`).digest('hex').substring(0, 12);
+        } finally {
+            asarProcess.noAsar = noAsar;
+        }
+    }
+
+    /**
+     * Remove resources that were extracted from an earlier version of the archive, unless they were used
+     * recently, because another application instance may still be running on that version.
+     */
+    protected removeStaleExtractions(extractionRoot: string, prefix: string, currentPath: string): void {
+        const removeStale = async () => {
+            for (const entry of await fs.promises.readdir(extractionRoot)) {
+                const entryPath = path.join(extractionRoot, entry);
+                if (!entry.startsWith(prefix) || entryPath === currentPath) {
+                    continue;
+                }
+                const stat = await fs.promises.stat(entryPath);
+                if (Date.now() - stat.mtimeMs > this.staleExtractionAge) {
+                    await fs.promises.rm(entryPath, { recursive: true, force: true });
+                    this.logger.info(`Removed stale extracted resources: ${entryPath}`);
+                }
+            }
+        };
+        removeStale().catch(error => this.logger.warn(`Could not remove stale extracted resources in '${extractionRoot}'.`, error));
+    }
+
+    protected async exists(targetPath: string): Promise<boolean> {
+        try {
+            await fs.promises.stat(targetPath);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+}

package/src/node/index.ts

@@ -22,5 +22,6 @@ export * from './messaging';
 export * from './cli';
 export * from './setting-service';
 export { FileSystemLocking } from './filesystem-locking';
+export { BundledResourceProvider } from './bundled-resource-provider';
 export { BackendRequestAllowedContribution } from './request/backend-request-facade';
 export { HttpConnectionValidator } from './hosting/browser-connection-token';