compiler-explorer/lib/temp.ts

// Copyright (c) 2025, Compiler Explorer Authors
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
//     * Redistributions of source code must retain the above copyright notice,
//       this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright
//       notice, this list of conditions and the following disclaimer in the
//       documentation and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';

import {logger} from './logger.js';
import * as utils from './utils.js';

const pendingRemoval: string[] = [];
export type Stats = {
    numCreated: number;
    numActive: number;
    numRemoved: number;
    numAlreadyGone: number;
};

const stats = {
    numCreated: 0,
    numRemoved: 0,
    numAlreadyGone: 0,
};

/**
 * Get the current stats for temporary directories.
 */
export function getStats(): Stats {
    return {
        ...stats,
        numActive: pendingRemoval.length,
    };
}

// Reset stats, for tests only.
export function resetStats() {
    stats.numCreated = 0;
    stats.numRemoved = 0;
    stats.numAlreadyGone = 0;
}

/**
 * The directory under which this module creates temporary directories (unless callers pass
 * an absolute prefix). The --tmp-dir command line option is not read directly: at startup
 * setupTempDir() exports it as $TMPDIR/$TMP/$TEMP, which os.tmpdir() consults.
 * See lib/app/temp-dir.ts.
 */
export function getTempRoot(): string {
    return os.tmpdir();
}

/**
 * Create a temporary directory. If the prefix is an absolute path, use it directly;
 * otherwise create the directory in the operating system's temporary directory.
 * @param prefix a prefix for the directory name, or an absolute path prefix
 */
export async function mkdir(prefix: string) {
    const baseDir = path.isAbsolute(prefix) ? prefix : path.join(getTempRoot(), prefix);
    const result = await fs.promises.mkdtemp(baseDir);
    ++stats.numCreated;
    pendingRemoval.push(result);
    return result;
}

/**
 * Synchronously create a temporary directory. If the prefix is an absolute path, use it directly;
 * otherwise create the directory in the operating system's temporary directory.
 * @param prefix a prefix for the directory name, or an absolute path prefix
 */
export function mkdirSync(prefix: string) {
    const baseDir = path.isAbsolute(prefix) ? prefix : path.join(getTempRoot(), prefix);
    const result = fs.mkdtempSync(baseDir);
    ++stats.numCreated;
    pendingRemoval.push(result);
    return result;
}

/**
 * Remove all temporary directories created by this module.
 */
export async function cleanup() {
    // "Atomically" take a copy of the things to remove and set it to an empty array.
    const toRemove = pendingRemoval.splice(0, pendingRemoval.length);
    let numRemoved = 0;
    let numAlreadyGone = 0;
    for (const dir of toRemove) {
        if (!(await utils.dirExists(dir))) {
            ++stats.numAlreadyGone;
            ++numAlreadyGone;
            continue;
        }
        try {
            await fs.promises.rm(dir, {recursive: true, force: true});
            ++numRemoved;
            ++stats.numRemoved;
        } catch (e) {
            logger.error(`Failed to remove ${dir}: ${e}`);
        }
    }
    logger.debug(`Removed ${numRemoved} (${numAlreadyGone} already gone) of ${toRemove.length} temporary directories`);
}

/**
 * Synchronously remove all temporary directories created by this module; for use at process
 * exit, where asynchronous work never runs.
 */
export function cleanupSync() {
    const toRemove = pendingRemoval.splice(0, pendingRemoval.length);
    for (const dir of toRemove) {
        try {
            if (!fs.existsSync(dir)) {
                ++stats.numAlreadyGone;
                continue;
            }
            fs.rmSync(dir, {recursive: true, force: true});
            ++stats.numRemoved;
        } catch {
            // Best effort only: we may be partway through exiting.
        }
    }
}

process.on('exit', () => {
    cleanupSync();
});