@elaraai/e3-core 0.0.2-beta.5 → 0.0.2-beta.50

package/dist/src/workspaceLock.js

@@ -1,217 +0,0 @@
-/**
- * Copyright (c) 2025 Elara AI Pty Ltd
- * Licensed under BSL 1.1. See LICENSE for details.
- */
-/**
- * Workspace locking for safe concurrent access.
- *
- * Provides exclusive locks on workspaces to prevent concurrent dataflow
- * executions or writes that could corrupt workspace state. Uses Linux
- * flock() for automatic lock release on process death.
- *
- * Lock mechanism:
- * - Uses flock(LOCK_EX | LOCK_NB) via the `flock` command for kernel-managed locking
- * - Lock is automatically released when the process dies (kernel handles this)
- * - Metadata (PID, bootId, startTime) written to lock file for diagnostics
- * - Stale lock detection via bootId comparison (handles system restarts)
- */
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { spawn } from 'child_process';
-import { WorkspaceLockError } from './errors.js';
-import { getBootId, getPidStartTime, isProcessAlive } from './executions.js';
-/**
- * Get the lock file path for a workspace.
- */
-export function workspaceLockPath(repoPath, workspace) {
-    return path.join(repoPath, 'workspaces', `${workspace}.lock`);
-}
-/**
- * Read lock metadata from a lock file.
- * Returns null if file doesn't exist or is invalid.
- */
-async function readLockMetadata(lockPath) {
-    try {
-        const data = await fs.readFile(lockPath, 'utf-8');
-        return JSON.parse(data);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Convert internal metadata to public LockHolder interface.
- */
-function metadataToHolder(metadata) {
-    return {
-        pid: metadata.pid,
-        acquiredAt: metadata.acquiredAt,
-        bootId: metadata.bootId,
-        startTime: metadata.startTime,
-        command: metadata.command,
-    };
-}
-// =============================================================================
-// Lock Acquisition
-// =============================================================================
-/**
- * Acquire an exclusive lock on a workspace.
- *
- * Uses Linux flock() for kernel-managed locking. The lock is automatically
- * released when the process exits (even on crash/kill).
- *
- * @param repoPath - Path to .e3 repository
- * @param workspace - Workspace name to lock
- * @param options - Lock acquisition options
- * @returns Lock handle - call release() when done
- * @throws {WorkspaceLockError} If workspace is locked by another process
- *
- * @example
- * ```typescript
- * const lock = await acquireWorkspaceLock(repoPath, 'production');
- * try {
- *   await dataflowExecute(repoPath, 'production', { lock });
- * } finally {
- *   await lock.release();
- * }
- * ```
- */
-export async function acquireWorkspaceLock(repoPath, workspace, options = {}) {
-    const lockPath = workspaceLockPath(repoPath, workspace);
-    // Ensure workspaces directory exists
-    await fs.mkdir(path.dirname(lockPath), { recursive: true });
-    // Gather our process identification
-    const pid = process.pid;
-    const bootId = await getBootId();
-    const startTime = await getPidStartTime(pid);
-    const command = process.argv.join(' ');
-    const acquiredAt = new Date().toISOString();
-    const metadata = { pid, bootId, startTime, acquiredAt, command };
-    // Try to acquire flock via subprocess
-    // The subprocess holds the lock and we communicate with it via stdin/signals
-    const flockProcess = await tryAcquireFlock(lockPath, metadata, options);
-    if (!flockProcess) {
-        // Failed to acquire - read metadata to report who has it
-        const existingMetadata = await readLockMetadata(lockPath);
-        const holder = existingMetadata ? metadataToHolder(existingMetadata) : undefined;
-        throw new WorkspaceLockError(workspace, holder);
-    }
-    // Lock acquired! Create handle
-    let released = false;
-    const handle = {
-        workspace,
-        lockPath,
-        async release() {
-            if (released)
-                return;
-            released = true;
-            // Kill the flock subprocess to release the lock
-            flockProcess.kill('SIGTERM');
-            // Clean up lock file (best effort)
-            try {
-                await fs.unlink(lockPath);
-            }
-            catch {
-                // Ignore - file might already be gone
-            }
-        },
-    };
-    return handle;
-}
-/**
- * Try to acquire flock using a subprocess.
- *
- * We spawn `flock --nonblock <lockfile> cat` which:
- * 1. Tries to acquire exclusive lock (non-blocking)
- * 2. If successful, runs `cat` which blocks reading stdin forever
- * 3. We keep the subprocess alive to hold the lock
- * 4. When we kill the subprocess, the lock is released
- *
- * Returns the subprocess if lock acquired, null if lock is held by another.
- */
-async function tryAcquireFlock(lockPath, metadata, options) {
-    // First, check if there's a stale lock we can clean up
-    await checkAndCleanStaleLock(lockPath);
-    const args = options.wait
-        ? ['--timeout', String((options.timeout ?? 30000) / 1000), lockPath, 'cat']
-        : ['--nonblock', lockPath, 'cat'];
-    const child = spawn('flock', args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        detached: false,
-    });
-    return new Promise((resolve) => {
-        let resolved = false;
-        // If flock fails to acquire, it exits with code 1
-        child.on('error', () => {
-            if (!resolved) {
-                resolved = true;
-                resolve(null);
-            }
-        });
-        child.on('exit', () => {
-            if (!resolved) {
-                resolved = true;
-                // Exit code 1 means lock is held by another
-                resolve(null);
-            }
-        });
-        // Give flock a moment to either acquire or fail
-        // If it's still running after 100ms, we have the lock
-        setTimeout(() => {
-            if (!resolved && !child.killed && child.exitCode === null) {
-                resolved = true;
-                // Write metadata to lock file now that we have the lock
-                // Use void to explicitly ignore the promise (metadata is informational only)
-                void fs.writeFile(lockPath, JSON.stringify(metadata, null, 2)).catch(() => { });
-                resolve(child);
-            }
-        }, 100);
-    });
-}
-/**
- * Check if a lock file exists with stale metadata and clean it up.
- * A lock is stale if the holder process no longer exists.
- */
-async function checkAndCleanStaleLock(lockPath) {
-    const metadata = await readLockMetadata(lockPath);
-    if (!metadata)
-        return;
-    // Check if the process that created this lock is still alive
-    const alive = await isProcessAlive(metadata.pid, metadata.startTime, metadata.bootId);
-    if (!alive) {
-        // Stale lock - try to remove it
-        try {
-            await fs.unlink(lockPath);
-        }
-        catch {
-            // Ignore - another process might have cleaned it up
-        }
-    }
-}
-/**
- * Check if a workspace is currently locked.
- *
- * @param repoPath - Path to .e3 repository
- * @param workspace - Workspace name to check
- * @returns Lock holder info if locked, null if not locked
- */
-export async function getWorkspaceLockHolder(repoPath, workspace) {
-    const lockPath = workspaceLockPath(repoPath, workspace);
-    const metadata = await readLockMetadata(lockPath);
-    if (!metadata)
-        return null;
-    // Check if the holder is still alive
-    const alive = await isProcessAlive(metadata.pid, metadata.startTime, metadata.bootId);
-    if (!alive) {
-        // Stale lock - clean it up and report as not locked
-        try {
-            await fs.unlink(lockPath);
-        }
-        catch {
-            // Ignore
-        }
-        return null;
-    }
-    return metadataToHolder(metadata);
-}
-//# sourceMappingURL=workspaceLock.js.map

package/dist/src/workspaceLock.js.map

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