@harperfast/integration-testing 0.1.0

package/dist/harperLifecycle.js

@@ -0,0 +1,315 @@
+import { spawn, ChildProcess } from 'node:child_process';
+import { createWriteStream, existsSync, rmSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+import { mkdtemp, mkdir, rm, cp } from 'node:fs/promises';
+import {} from 'node:test';
+import { getNextAvailableLoopbackAddress, releaseLoopbackAddress } from "./loopbackAddressPool.js";
+import { ok, equal } from 'node:assert';
+import { createRequire } from 'node:module';
+/**
+ * Creates a plain object satisfying HarperTestContext, for use outside node:test
+ * (e.g. as a Playwright worker fixture).
+ *
+ * @param name Optional name for log directory naming (e.g. Playwright worker index).
+ */
+export function createHarperContext(name) {
+    return { name };
+}
+// Constants
+const HTTP_PORT = 9926;
+const HTTPS_PORT = 9927;
+export const OPERATIONS_API_PORT = 9925;
+export const DEFAULT_ADMIN_USERNAME = 'admin';
+export const DEFAULT_ADMIN_PASSWORD = 'Abc1234!';
+export const DEFAULT_STARTUP_TIMEOUT_MS = process.env.HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS
+    ? parseInt(process.env.HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS, 10)
+    : 30000;
+const LOG_DIR = process.env.HARPER_INTEGRATION_TEST_LOG_DIR;
+/**
+ * Gets the path to the Harper CLI script.
+ *
+ * Resolution order:
+ * 1. `harperBinPath` argument
+ * 2. `HARPER_INTEGRATION_TEST_INSTALL_SCRIPT` environment variable
+ * 3. Auto-resolved from 'harper' package in node_modules
+ *
+ * @returns The absolute path to the Harper CLI entry script
+ * @throws {AssertionError} If the script cannot be found
+ */
+function getHarperScript(harperBinPath) {
+    // 1. Explicit option
+    if (harperBinPath) {
+        ok(existsSync(harperBinPath), `Harper script not found at provided harperBinPath: ${harperBinPath}`);
+        return harperBinPath;
+    }
+    // 2. Environment variable
+    const envPath = process.env.HARPER_INTEGRATION_TEST_INSTALL_SCRIPT;
+    if (envPath) {
+        ok(existsSync(envPath), `Harper script not found at HARPER_INTEGRATION_TEST_INSTALL_SCRIPT path: ${envPath}`);
+        return envPath;
+    }
+    // 3. Auto-resolve from node_modules
+    try {
+        const require = createRequire(import.meta.url);
+        const resolved = require.resolve('harper/dist/bin/harper.js');
+        if (existsSync(resolved)) {
+            return resolved;
+        }
+    }
+    catch {
+        // harper package not found in node_modules
+    }
+    throw new Error(`Harper CLI script not found. Provide the path via:\n` +
+        `  - harperBinPath option: startHarper(ctx, { harperBinPath: '/path/to/dist/bin/harper.js' })\n` +
+        `  - HARPER_INTEGRATION_TEST_INSTALL_SCRIPT environment variable\n` +
+        `  - Install 'harper' as a dependency in your project`);
+}
+/**
+ * Sanitizes a string for use as a filesystem directory name.
+ */
+function sanitizeForFilesystem(name) {
+    return name
+        .replace(/[^a-zA-Z0-9_-]/g, '_')
+        .replace(/_+/g, '_')
+        .substring(0, 100);
+}
+/**
+ * Runs a Harper CLI command and captures output.
+ *
+ * When `logDir` is provided, stdout and stderr are also written to files
+ * (`stdout.log` and `stderr.log`) in that directory.
+ *
+ * @throws {AssertionError} If the command exits with a non-zero status code
+ */
+function runHarperCommand({ args, env, completionMessage, logDir, harperBinPath, }) {
+    const harperScript = getHarperScript(harperBinPath);
+    const proc = spawn('node', ['--trace-warnings', '--force-node-api-uncaught-exceptions-policy=true', harperScript, ...args], {
+        env: { ...process.env, ...env },
+    });
+    let stdoutStream;
+    let stderrStream;
+    if (logDir) {
+        stdoutStream = createWriteStream(join(logDir, 'stdout.log'));
+        stderrStream = createWriteStream(join(logDir, 'stderr.log'));
+    }
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        let timer = setTimeout(() => {
+            let errorMessage = `Harper process timed out after ${DEFAULT_STARTUP_TIMEOUT_MS}ms`;
+            if (stdout) {
+                errorMessage += `\n\nstdout:\n${stdout}`;
+            }
+            if (stderr) {
+                errorMessage += `\n\nstderr:\n${stderr}`;
+            }
+            reject(errorMessage);
+            proc.kill();
+        }, DEFAULT_STARTUP_TIMEOUT_MS);
+        proc.stdout?.on('data', (data) => {
+            const dataString = data.toString();
+            stdoutStream?.write(data);
+            if (completionMessage && dataString.includes(completionMessage)) {
+                clearTimeout(timer);
+                resolve(proc);
+            }
+            stdout += dataString;
+        });
+        proc.stderr?.on('data', (data) => {
+            stderrStream?.write(data);
+            stderr += data.toString();
+        });
+        proc.on('error', (error) => {
+            reject(error);
+        });
+        proc.on('exit', (statusCode, signal) => {
+            clearTimeout(timer);
+            if (statusCode === 0) {
+                resolve(proc);
+            }
+            else {
+                let errorMessage = `Harper process failed with exit code/signal ${statusCode ?? signal}`;
+                stderrStream?.write(errorMessage);
+                if (stderr) {
+                    errorMessage += `\n\nstderr:\n${stderr}`;
+                }
+                reject(errorMessage);
+            }
+            stdoutStream?.end();
+            stderrStream?.end();
+        });
+    });
+}
+/**
+ * Sets up a Harper instance with a component pre-installed from a local directory.
+ *
+ * Copies `fixturePath` into `{dataRootDir}/components/{name}` before Harper starts,
+ * so the component is available on the first request without a post-startup deploy.
+ * Use this when tests need a known route available at startup (e.g. mTLS cert tests).
+ *
+ * @param ctx - The test context to populate with Harper instance details
+ * @param fixturePath - Absolute path to the component directory to pre-install
+ * @param options - Optional configuration for the setup process
+ */
+export async function setupHarperWithFixture(ctx, fixturePath, options) {
+    const dataRootDirPrefix = join(process.env.HARPER_INTEGRATION_TEST_INSTALL_PARENT_DIR || tmpdir(), 'harper-integration-test-');
+    const dataRootDir = await mkdtemp(dataRootDirPrefix);
+    await cp(fixturePath, join(dataRootDir, 'components', basename(fixturePath)), { recursive: true });
+    ctx.harper = { dataRootDir };
+    return startHarper(ctx, options);
+}
+/**
+ * Sets up and starts a Harper instance for testing.
+ *
+ * @param ctx - The test context to populate with Harper instance details
+ * @param options - Optional configuration for the setup process
+ * @returns The context with the `harper` property populated
+ *
+ * @example
+ * ```ts
+ * suite('My tests', (ctx: ContextWithHarper) => {
+ *   before(async () => {
+ *     await startHarper(ctx);
+ *   });
+ *
+ *   after(async () => {
+ *     await teardownHarper(ctx);
+ *   });
+ *
+ *   test('can connect', async () => {
+ *     const response = await fetch(ctx.harper.httpURL);
+ *     // ...
+ *   });
+ * });
+ * ```
+ */
+export async function startHarper(ctx, options) {
+    const dataRootDirPrefix = join(process.env.HARPER_INTEGRATION_TEST_INSTALL_PARENT_DIR || tmpdir(), `harper-integration-test-`);
+    const dataRootDir = ctx.harper?.dataRootDir ?? (await mkdtemp(dataRootDirPrefix));
+    const loopbackAddress = ctx.harper?.hostname ?? (await getNextAvailableLoopbackAddress());
+    // Set up per-suite log directory when HARPER_INTEGRATION_TEST_LOG_DIR is configured
+    let logDir;
+    if (LOG_DIR) {
+        const suiteName = sanitizeForFilesystem(ctx.name || 'unknown');
+        logDir = join(LOG_DIR, `${suiteName}-${sanitizeForFilesystem(loopbackAddress)}`);
+        await mkdir(logDir, { recursive: true });
+    }
+    // Point Harper's log directory to the suite log dir so hdb.log is preserved for upload
+    const config = { ...options?.config };
+    if (logDir) {
+        config.logging = { ...config.logging, root: logDir };
+        // Clean up log directory on successful exit — only keep logs when tests fail
+        process.on('exit', (code) => {
+            if (code === 0) {
+                try {
+                    rmSync(logDir, { recursive: true, force: true });
+                }
+                catch { }
+            }
+        });
+    }
+    const args = [
+        `--ROOTPATH=${dataRootDir}`,
+        '--DEFAULTS_MODE=dev',
+        `--HDB_ADMIN_USERNAME=${DEFAULT_ADMIN_USERNAME}`,
+        `--HDB_ADMIN_PASSWORD=${DEFAULT_ADMIN_PASSWORD}`,
+        '--THREADS_COUNT=1',
+        '--THREADS_DEBUG=false',
+        `--NODE_HOSTNAME=${loopbackAddress}`,
+        `--HTTP_PORT=${loopbackAddress}:${HTTP_PORT}`,
+        `--OPERATIONSAPI_NETWORK_PORT=${loopbackAddress}:${OPERATIONS_API_PORT}`,
+        '--LOGGING_LEVEL=debug',
+        '--LOGGING_STDSTREAMS=false',
+    ];
+    // Bind secure port if HTTPS is needed (mTLS or other TLS config present)
+    if (options?.config?.http?.mtls !== undefined || options?.config?.tls !== undefined) {
+        args.push(`--HTTP_SECUREPORT=${loopbackAddress}:${HTTPS_PORT}`);
+    }
+    // HARPER_SET_CONFIG must be passed as an environment variable, not a CLI arg,
+    // because applyRuntimeEnvVarConfig reads from process.env.HARPER_SET_CONFIG
+    const harperEnv = {
+        HARPER_SET_CONFIG: JSON.stringify(config),
+        ...options?.env,
+    };
+    const harperProcess = await runHarperCommand({
+        args,
+        env: harperEnv,
+        completionMessage: 'successfully started',
+        logDir,
+        harperBinPath: options?.harperBinPath,
+    });
+    ctx.harper = {
+        dataRootDir,
+        admin: {
+            username: DEFAULT_ADMIN_USERNAME,
+            password: DEFAULT_ADMIN_PASSWORD,
+        },
+        httpURL: `http://${loopbackAddress}:${HTTP_PORT}`,
+        operationsAPIURL: `http://${loopbackAddress}:${OPERATIONS_API_PORT}`,
+        hostname: loopbackAddress,
+        process: harperProcess,
+        logDir,
+    };
+    return ctx;
+}
+/**
+ * Kill harper process (can be used for teardown, or killing it before a restart)
+ * @param ctx
+ */
+export async function killHarper(ctx) {
+    await new Promise((resolve) => {
+        let timer;
+        ctx.harper.process.on('exit', () => {
+            resolve();
+            clearTimeout(timer);
+        });
+        ctx.harper.process.kill();
+        timer = setTimeout(() => {
+            try {
+                ctx.harper.process.kill('SIGKILL');
+            }
+            catch {
+                // possible that the process terminated but the exit event hasn't fired yet
+            }
+            resolve();
+        }, 200);
+    });
+}
+/**
+ * Tears down a Harper instance and cleans up all resources.
+ *
+ * This function stops the Harper instance, releases the loopback address,
+ * and removes the installation directory.
+ * @param ctx - The test context with Harper instance details
+ *
+ * @example
+ * ```ts
+ * suite('My tests', (ctx: ContextWithHarper) => {
+ *   before(async () => {
+ *     await startHarper(ctx);
+ *   });
+ *
+ *   after(async () => {
+ *     await teardownHarper(ctx);
+ *   });
+ * });
+ * ```
+ */
+export async function teardownHarper(ctx) {
+    await killHarper(ctx);
+    await releaseLoopbackAddress(ctx.harper.hostname);
+    // a few retries are typically necessary, might take a sec for a process to finish, especially since rocksdb may be flushing
+    await rm(ctx.harper.dataRootDir, { recursive: true, force: true, maxRetries: 4 });
+}
+export async function sendOperation(context, operation) {
+    const response = await fetch(context.operationsAPIURL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(operation),
+    });
+    const responseData = await response.json();
+    equal(response.status, 200, JSON.stringify(responseData));
+    return responseData;
+}
+//# sourceMappingURL=harperLifecycle.js.map

package/dist/harperLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harperLifecycle.js","sourceRoot":"","sources":["../src/harperLifecycle.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { startHarper, setupHarperWithFixture, killHarper, teardownHarper, sendOperation, createHarperContext, OPERATIONS_API_PORT, DEFAULT_ADMIN_USERNAME, DEFAULT_ADMIN_PASSWORD, DEFAULT_STARTUP_TIMEOUT_MS, } from "./harperLifecycle.js";
+export { validateLoopbackAddressPool, getNextAvailableLoopbackAddress, releaseLoopbackAddress, releaseAllLoopbackAddressesForCurrentProcess, } from "./loopbackAddressPool.js";
+export { targz } from "./targz.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,GAM1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACN,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,EACtB,4CAA4C,GAC5C,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/loopbackAddressPool.js

@@ -0,0 +1,337 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { open, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
+// Configuration constants
+const HARPER_LOOPBACK_POOL_COUNT = process.env.HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT
+    ? parseInt(process.env.HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT, 10)
+    : 32;
+if (HARPER_LOOPBACK_POOL_COUNT < 1 || HARPER_LOOPBACK_POOL_COUNT > 255) {
+    throw new Error('HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT must be between 1 and 255');
+}
+const HARPER_LOOPBACK_POOL_PATH = join(tmpdir(), 'harper-integration-test-loopback-pool.json');
+const HARPER_LOOPBACK_POOL_LOCK_PATH = join(tmpdir(), 'harper-integration-test-loopback-pool.lock');
+// Constants for timeouts and retries
+const LOCK_STALE_TIMEOUT_MS = 10000;
+const RETRY_DELAY_MS = 1000;
+// Custom error classes
+class LoopbackAddressValidationError extends Error {
+    constructor(address, cause) {
+        super(`Failed to validate loopback address ${address}. This likely means your system does not have the required loopback addresses configured/enabled. Refer to the Harper Integration Test documentation (integrationTests/README.md) for more information.`);
+        this.name = 'LoopbackAddressValidationError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+class InvalidLoopbackAddressError extends Error {
+    constructor(address) {
+        super(`Invalid loopback address format: ${address}. Expected format: 127.0.0.X where X is between 1 and ${HARPER_LOOPBACK_POOL_COUNT}`);
+        this.name = 'InvalidLoopbackAddressError';
+    }
+}
+/**
+ * Acquires a file-based lock by creating the lock file. This enables safe concurrent
+ * access to the loopback pool across multiple test processes.
+ *
+ * Uses the 'wx' file flag which atomically fails if the file already exists, providing
+ * a simple but effective cross-process mutex. Handles stale locks by removing lock files
+ * older than LOCK_STALE_TIMEOUT_MS (10 seconds).
+ *
+ * @returns A promise that resolves when the lock is acquired
+ */
+async function acquireLock() {
+    while (true) {
+        try {
+            // The 'wx' flag causes the open to fail if the file already exists
+            const lockFileHandle = await open(HARPER_LOOPBACK_POOL_LOCK_PATH, 'wx');
+            // We have the lock - close the handle as we don't intend to write to it
+            await lockFileHandle.close();
+            return;
+        }
+        catch (error) {
+            // If the lock file already exists, it's either stale or we wait for it to be released
+            if (error.code === 'EEXIST') {
+                try {
+                    const lockFileStat = await stat(HARPER_LOOPBACK_POOL_LOCK_PATH);
+                    // If the lock file is older than the timeout, consider it stale and remove it
+                    if (Date.now() - lockFileStat.mtimeMs > LOCK_STALE_TIMEOUT_MS) {
+                        await unlink(HARPER_LOOPBACK_POOL_LOCK_PATH);
+                    }
+                }
+                catch {
+                    // Lock file may have been removed by another process, continue
+                }
+                await sleep(RETRY_DELAY_MS);
+                continue;
+            }
+            // Rethrow other errors
+            throw error;
+        }
+    }
+}
+/**
+ * Releases the file-based lock by deleting the lock file.
+ */
+async function releaseLock() {
+    try {
+        await unlink(HARPER_LOOPBACK_POOL_LOCK_PATH);
+    }
+    catch {
+        // Ignore errors if lock file is already gone
+    }
+}
+/**
+ * Executes a callback function while holding the lock. Automatically acquires
+ * and releases the lock, ensuring the lock is always released even if the callback
+ * throws an error.
+ *
+ * @param callback The async function to execute while holding the lock
+ * @returns The result of the callback function
+ */
+async function withLock(callback) {
+    await acquireLock();
+    try {
+        return await callback();
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * Reads the loopback pool from the pool file. The pool is a JSON array where each
+ * index represents a loopback address (127.0.0.1, 127.0.0.2, etc.) and the value
+ * is either null (available) or a process PID (in use).
+ *
+ * If the file doesn't exist, creates and returns a new empty pool with all addresses
+ * marked as available (null).
+ *
+ * @returns The loopback pool array
+ */
+async function readPoolFile() {
+    try {
+        const content = await readFile(HARPER_LOOPBACK_POOL_PATH, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            // If the pool file doesn't exist yet, create it with null entries
+            return Array(HARPER_LOOPBACK_POOL_COUNT).fill(null);
+        }
+        throw error;
+    }
+}
+/**
+ * Writes the loopback pool to the pool file as JSON.
+ *
+ * @param pool The loopback pool array to persist
+ */
+async function writePoolFile(pool) {
+    await writeFile(HARPER_LOOPBACK_POOL_PATH, JSON.stringify(pool));
+}
+/**
+ * Finds the first available (null) index in the pool. This implements a simple
+ * first-available allocation strategy.
+ *
+ * @param pool The loopback pool array
+ * @returns The first available index, or null if the pool is full
+ */
+function findAvailableIndex(pool) {
+    for (let i = 0; i < pool.length; i++) {
+        if (pool[i] === null) {
+            return i;
+        }
+    }
+    return null;
+}
+/**
+ * Validates the format of a loopback address and extracts the pool index.
+ *
+ * Expects addresses in the format "127.0.0.X" where X is between 1 and the pool count.
+ * The returned index is 0-based (e.g., "127.0.0.1" returns index 0).
+ *
+ * @param address The loopback address to parse (e.g., "127.0.0.2")
+ * @returns The 0-based pool index for this address
+ * @throws {InvalidLoopbackAddressError} If the address format is invalid or out of range
+ */
+function parseLoopbackAddress(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4 || parts[0] !== '127' || parts[1] !== '0' || parts[2] !== '0') {
+        throw new InvalidLoopbackAddressError(address);
+    }
+    const index = parseInt(parts[3], 10) - 1;
+    if (isNaN(index) || index < 0 || index >= HARPER_LOOPBACK_POOL_COUNT) {
+        throw new InvalidLoopbackAddressError(address);
+    }
+    return index;
+}
+/**
+ * Validates that a given loopback address can be bound to by creating a temporary
+ * TCP server on that address. This ensures the loopback address is actually configured
+ * and available on the system before allocating it to a test process.
+ *
+ * The server is bound to port 0 (random port) just to verify the address exists,
+ * then immediately closed.
+ *
+ * @param loopbackAddress The loopback IP address to validate (e.g., "127.0.0.2")
+ * @returns A promise that resolves with the address if valid
+ * @throws An error with the loopbackAddress property if binding fails
+ */
+function validateLoopbackAddress(loopbackAddress) {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', (error) => {
+            const enhancedError = error;
+            enhancedError.loopbackAddress = loopbackAddress;
+            reject(enhancedError);
+        });
+        server.listen(0, loopbackAddress, () => {
+            server.close(() => {
+                resolve(loopbackAddress);
+            });
+        });
+    });
+}
+/**
+ * This method attempts to validate all loopback addresses in the pool by trying to
+ * bind to each one. It returns an object containing arrays of successfully bound
+ * loopback addresses and those that failed along with their errors.
+ *
+ * It will check all loopback addresses from 127.0.0.1 to 127.0.0.32 (by default).
+ *
+ * Use the HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT environment variable to
+ * adjust the number of loopback addresses to validate (up to 255).
+ */
+export async function validateLoopbackAddressPool() {
+    return Promise.allSettled(Array.from({ length: HARPER_LOOPBACK_POOL_COUNT }, (_, i) => validateLoopbackAddress(`127.0.0.${i + 1}`))).then((results) => results.reduce((acc, result) => {
+        if (result.status === 'fulfilled') {
+            acc.successful.push(result.value);
+        }
+        else {
+            const error = result.reason;
+            acc.failed.push({ loopbackAddress: error.loopbackAddress, error });
+        }
+        return acc;
+    }, { successful: [], failed: [] }));
+}
+/**
+ * Retrieves the next available loopback address from the pool using a file-based
+ * locking mechanism to safely allocate addresses across concurrent test processes.
+ *
+ * **How it works:**
+ * 1. Acquires a file-based lock to prevent race conditions with other processes
+ * 2. Reads the pool state (a JSON array of process IDs, with null for available slots)
+ * 3. Finds the first available (null) slot and assigns the current process PID to it
+ * 4. Writes the updated pool back to disk and releases the lock
+ * 5. Validates that the allocated address can actually be bound to
+ * 6. Returns the loopback address (e.g., "127.0.0.2")
+ *
+ * If no addresses are available, waits and retries until one becomes available.
+ *
+ * **Pool file location:** `${tmpdir()}/harper-integration-test-loopback-pool.json`
+ * **Lock file location:** `${tmpdir()}/harper-integration-test-loopback-pool.lock`
+ *
+ * @returns A promise that resolves with an allocated loopback address
+ * @throws {LoopbackAddressValidationError} If the allocated address cannot be bound to
+ */
+export async function getNextAvailableLoopbackAddress() {
+    // Each index+1 is a different loopback address that a test process will be assigned to
+    // So if the first test process number is 42, it would be assigned to index 0 associated with address 127.0.0.1
+    // [42, null, null, ...];
+    // Then the next process (call is 43) gets the next available, so index 1 -> 127.0.0.2
+    // [42, 43, null, ...];
+    // And so on...
+    // As processes exit and release their loopback addresses, those addresses become available for new processes to use
+    // [42, null, 44, ...];
+    // Next process (45) gets index 1 again ->
+    // [42, 45, 44, ...];
+    // This continues until all loopback addresses are used, at which point new processes will wait until an address becomes available
+    // Since multiple processes may be trying to get a loopback address at the same time, we need to implement a simple file-based locking mechanism to prevent race conditions
+    while (true) {
+        const assignedIndex = await withLock(async () => {
+            // Read the pool file
+            const loopbackPool = await readPoolFile();
+            // Find the first available index
+            const index = findAvailableIndex(loopbackPool);
+            if (index === null) {
+                // No available addresses - remove any dead processes from the pool and wait for one to become available
+                removeDeadProcessesFromPool(loopbackPool);
+            }
+            else {
+                // Assign the process PID to that index to mark it as used
+                loopbackPool[index] = process.pid;
+            }
+            // Write the updated pool back to the file
+            await writePoolFile(loopbackPool);
+            return index;
+        });
+        // If we got an index, validate and return the address
+        if (assignedIndex !== null) {
+            const loopbackAddress = `127.0.0.${assignedIndex + 1}`;
+            try {
+                await validateLoopbackAddress(loopbackAddress);
+                return loopbackAddress;
+            }
+            catch (error) {
+                // Validation failed - throw a proper error instead of breaking
+                throw new LoopbackAddressValidationError(loopbackAddress, error);
+            }
+        }
+        // No available addresses; wait and retry
+        await sleep(RETRY_DELAY_MS);
+    }
+}
+/**
+ * Removes any dead processes from the loopback pool.
+ * @param loopbackPool
+ */
+function removeDeadProcessesFromPool(loopbackPool) {
+    loopbackPool.forEach((pid, index) => {
+        if (pid === null)
+            return;
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            loopbackPool[index] = null;
+        }
+    });
+}
+/**
+ * Releases a loopback address back to the pool, making it available for other processes.
+ *
+ * @param address The loopback address to release (e.g., "127.0.0.1")
+ * @throws InvalidLoopbackAddressError if the address format is invalid
+ */
+export async function releaseLoopbackAddress(address) {
+    // Validate and parse the address
+    const index = parseLoopbackAddress(address);
+    await withLock(async () => {
+        // Read the pool file
+        const loopbackPool = await readPoolFile();
+        // Release the address by setting it to null
+        loopbackPool[index] = null;
+        // Write the updated pool back to the file
+        await writePoolFile(loopbackPool);
+    });
+}
+/**
+ * Releases all loopback addresses assigned to the current process.
+ * Useful for cleanup during graceful shutdown.
+ */
+export async function releaseAllLoopbackAddressesForCurrentProcess() {
+    await withLock(async () => {
+        // Read the pool file
+        const loopbackPool = await readPoolFile();
+        // Find and release all addresses assigned to this process
+        for (let i = 0; i < loopbackPool.length; i++) {
+            if (loopbackPool[i] === process.pid) {
+                loopbackPool[i] = null;
+            }
+        }
+        // Write the updated pool back to the file
+        await writePoolFile(loopbackPool);
+    });
+}
+//# sourceMappingURL=loopbackAddressPool.js.map