@pasko70/pibo 1.8.2 → 1.9.2

package/dist/resources/lifecycle.js

@@ -0,0 +1,353 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir, readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { applyComputeWorkerReapPlan, buildComputeWorkerReapPlan, planReapWorkers, } from "../compute/docker.js";
+import { defaultBrowserPoolRoot, defaultBrowserUseHome, getComputeResourceHealth, parseProcessList, } from "../compute/resource-health.js";
+import { loadBrowserPoolState, reapIdleBrowserPool, } from "../tools/browser-pool.js";
+const execFileAsync = promisify(execFile);
+export async function collectManagedBrowserPools(rootDir) {
+    const records = [];
+    for (const statePath of await findStateFiles(rootDir)) {
+        const raw = await readFile(statePath, "utf8").catch(() => undefined);
+        if (!raw)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const candidate = parsed;
+        if (typeof candidate.workerId !== "string" || typeof candidate.poolId !== "string")
+            continue;
+        const identity = {
+            workerId: candidate.workerId,
+            poolId: candidate.poolId,
+            maxBrowserProcesses: typeof candidate.maxBrowserProcesses === "number" ? candidate.maxBrowserProcesses : 1,
+        };
+        const state = await loadBrowserPoolState(statePath, { ...identity, onMalformed: "throw" }).catch(() => undefined);
+        if (!state)
+            continue;
+        records.push({ statePath, lockPath: join(dirname(statePath), "state.lock"), state });
+    }
+    return records;
+}
+export function listActiveResourceLeases(records) {
+    return records
+        .filter(({ state }) => Boolean(state.activeLeaseId))
+        .map(({ state }) => ({
+        leaseId: state.activeLeaseId,
+        holder: state.holder,
+        workerId: state.workerId,
+        poolId: state.poolId,
+        expiresAt: state.idleExpiresAt,
+        state: state.state,
+    }))
+        .sort((a, b) => a.leaseId.localeCompare(b.leaseId));
+}
+export async function getActiveResourceLeases(browserPoolRoot = defaultBrowserPoolRoot()) {
+    return listActiveResourceLeases(await collectManagedBrowserPools(browserPoolRoot));
+}
+export async function planResourceReap(options = {}) {
+    const now = options.now ?? new Date();
+    const resolved = resolveReapOptions(options);
+    const [records, staleFiles, compute, health] = await Promise.all([
+        collectManagedBrowserPools(resolved.browserPoolRoot),
+        planStaleCdpFiles(resolved.browserUseHome),
+        planComputeReapSafely({ includeDev: resolved.includeDev, maxAgeMinutes: resolved.maxAgeMinutes, now }),
+        getComputeResourceHealth({ now, browserPoolRoot: resolved.browserPoolRoot, browserUseHome: resolved.browserUseHome }),
+    ]);
+    const unmanagedBrowsers = buildUnmanagedBrowserPlanItems(health.browserProcesses.unassignedMainProcessDetails, resolved.unmanagedBrowserGraceMinutes, new Set(resolved.exemptBrowserPids));
+    return buildResourceReapPlan({ now, options: resolved, records, staleFiles, unmanagedBrowsers, compute });
+}
+export function buildResourceReapPlan(input) {
+    const browserItems = input.records.map((record) => buildBrowserReapPlanItem(record, input.now, input.options.idleTimeoutMinutes));
+    const unmanagedBrowsers = input.unmanagedBrowsers ?? [];
+    return {
+        createdAt: input.now.toISOString(),
+        dryRun: true,
+        options: input.options,
+        browserPools: {
+            items: browserItems,
+            selected: browserItems.filter((item) => item.action === "reap").length,
+            skipped: browserItems.filter((item) => item.action === "skip").length,
+        },
+        staleFiles: { items: input.staleFiles, selected: input.staleFiles.length },
+        unmanagedBrowsers: {
+            items: unmanagedBrowsers,
+            selected: unmanagedBrowsers.filter((item) => item.action === "terminate").length,
+            skipped: unmanagedBrowsers.filter((item) => item.action === "skip").length,
+        },
+        compute: input.compute,
+        worktreesPreserved: true,
+    };
+}
+export async function applyResourceReapPlan(plan, dependencies = {}) {
+    const replan = dependencies.plan ?? planResourceReap;
+    const confirmed = await replan({ ...plan.options, now: new Date() });
+    const reapBrowserPool = dependencies.reapBrowserPool ?? reapIdleBrowserPool;
+    const browserResults = [];
+    for (const item of confirmed.browserPools.items) {
+        if (item.action !== "reap")
+            continue;
+        browserResults.push(await reapBrowserPool({ statePath: item.statePath, lockPath: item.lockPath }, { workerId: item.workerId, poolId: item.poolId }, { idleTimeoutMs: confirmed.options.idleTimeoutMinutes * 60_000 }));
+    }
+    const terminateUnmanagedBrowser = dependencies.terminateUnmanagedBrowser ?? terminateUnmanagedBrowserProcessGroup;
+    const terminatedUnmanagedBrowsers = [];
+    for (const item of confirmed.unmanagedBrowsers.items) {
+        if (item.action !== "terminate")
+            continue;
+        if (await terminateUnmanagedBrowser(item))
+            terminatedUnmanagedBrowsers.push(item.pid);
+    }
+    const removedStaleFiles = await applyStaleCdpFilePlan(confirmed.staleFiles.items, dependencies.isPidAlive);
+    const removedComputeWorkers = await (dependencies.applyCompute ?? applyComputeWorkerReapPlan)(confirmed.compute);
+    return {
+        applied: true,
+        plan: confirmed,
+        browserResults,
+        terminatedUnmanagedBrowsers,
+        removedStaleFiles,
+        removedComputeWorkers,
+        worktreesPreserved: true,
+    };
+}
+function resolveReapOptions(options) {
+    return {
+        includeDev: options.includeDev === true,
+        maxAgeMinutes: options.maxAgeMinutes ?? 60,
+        idleTimeoutMinutes: options.idleTimeoutMinutes ?? 10,
+        unmanagedBrowserGraceMinutes: options.unmanagedBrowserGraceMinutes ?? 10,
+        browserPoolRoot: options.browserPoolRoot ?? defaultBrowserPoolRoot(),
+        browserUseHome: options.browserUseHome ?? defaultBrowserUseHome(),
+        exemptBrowserPids: options.exemptBrowserPids ?? readExemptBrowserPids(),
+    };
+}
+export function buildUnmanagedBrowserPlanItems(processes, graceMinutes, exemptPids = new Set()) {
+    const graceSeconds = graceMinutes * 60;
+    return processes.map((process) => {
+        let action = "terminate";
+        let reason = "unmanaged Chromium main process has no managed browser-pool lease";
+        if (process.pid <= 1 || process.pgid <= 1) {
+            action = "skip";
+            reason = "unsafe pid or process group";
+        }
+        else if (exemptPids.has(process.pid) || exemptPids.has(process.pgid)) {
+            action = "skip";
+            reason = "explicitly exempted pid or process group";
+        }
+        else if (process.elapsedSeconds !== undefined && process.elapsedSeconds < graceSeconds) {
+            action = "skip";
+            reason = `process age ${process.elapsedSeconds}s is within ${graceSeconds}s grace period`;
+        }
+        return {
+            pid: process.pid,
+            ppid: process.ppid,
+            processGroupId: process.pgid,
+            commandName: process.commandName,
+            userDataDir: process.userDataDir,
+            elapsedSeconds: process.elapsedSeconds,
+            action,
+            reason,
+            processGroup: true,
+        };
+    });
+}
+async function terminateUnmanagedBrowserProcessGroup(item) {
+    if (!defaultIsPidAlive(item.pid))
+        return false;
+    const [processInfo, ownProcessGroupId] = await Promise.all([inspectProcess(item.pid), readProcessGroupId(process.pid)]);
+    if (!processInfo || !processInfo.isChromium || !processInfo.isMainProcess || processInfo.pgid !== item.processGroupId)
+        return false;
+    if (ownProcessGroupId !== undefined && ownProcessGroupId === item.processGroupId)
+        return false;
+    try {
+        process.kill(-item.processGroupId, "SIGTERM");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH"))
+            throw error;
+        return false;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    if (defaultIsPidAlive(item.pid)) {
+        try {
+            process.kill(-item.processGroupId, "SIGKILL");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH"))
+                throw error;
+        }
+    }
+    return !defaultIsPidAlive(item.pid);
+}
+async function inspectProcess(pid) {
+    try {
+        const { stdout } = await execFileAsync("ps", ["-o", "pid=,ppid=,pgid=,comm=,args=", "-p", String(pid)]);
+        return parseProcessList(stdout).find((item) => item.pid === pid);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readProcessGroupId(pid) {
+    try {
+        const { stdout } = await execFileAsync("ps", ["-o", "pgid=", "-p", String(pid)]);
+        const value = Number.parseInt(stdout.trim(), 10);
+        return Number.isInteger(value) && value > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readExemptBrowserPids() {
+    return (process.env.PIBO_RESOURCE_REAPER_EXEMPT_BROWSER_PIDS ?? "")
+        .split(",")
+        .map((value) => Number.parseInt(value.trim(), 10))
+        .filter((value) => Number.isInteger(value) && value > 0);
+}
+function buildBrowserReapPlanItem(record, now, idleTimeoutMinutes) {
+    const { state } = record;
+    let action = "skip";
+    let reason = "not idle long enough";
+    if (state.activeLeaseId || (state.activeLeaseCount ?? 0) > 0 || state.state === "leased") {
+        reason = state.activeLeaseId ? `active lease ${state.activeLeaseId}` : "active leases";
+    }
+    else if (state.state === "empty" || (!state.pid && !state.cdpUrl && !state.userDataDir)) {
+        reason = "no recorded browser";
+    }
+    else if (state.state === "stale" || state.state === "dirty") {
+        action = "reap";
+        reason = `pool state is ${state.state}`;
+    }
+    else if (hasExpired(state.idleExpiresAt, now)) {
+        action = "reap";
+        reason = `idle expiry ${state.idleExpiresAt} has passed`;
+    }
+    else if (isOlderThan(state.lastUsedAt, now, idleTimeoutMinutes * 60_000)) {
+        action = "reap";
+        reason = `last used at ${state.lastUsedAt} exceeds idle timeout`;
+    }
+    return {
+        workerId: state.workerId,
+        poolId: state.poolId,
+        statePath: record.statePath,
+        lockPath: record.lockPath,
+        action,
+        reason,
+        preservesWorktree: true,
+    };
+}
+async function planComputeReapSafely(options) {
+    try {
+        return await planReapWorkers(options);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+        const plan = buildComputeWorkerReapPlan([], options);
+        plan.nextCommands = ["Docker CLI is unavailable in this runtime; browser and stale-file cleanup remain active."];
+        return plan;
+    }
+}
+async function planStaleCdpFiles(browserUseHome, isPidAlive = defaultIsPidAlive) {
+    const stateDir = join(browserUseHome, "pibo-cdp");
+    let files;
+    try {
+        files = await readdir(stateDir);
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    for (const file of files) {
+        if (file.endsWith(".pid")) {
+            const path = join(stateDir, file);
+            const pid = await readPid(path);
+            if (pid === undefined || !isPidAlive(pid))
+                items.push({ path, kind: "pid", action: "remove", reason: pid === undefined ? "invalid pid file" : `pid ${pid} is not alive` });
+        }
+        else if (file.endsWith(".port")) {
+            const pidPath = join(stateDir, `${file.slice(0, -5)}.pid`);
+            if (!existsSync(pidPath))
+                items.push({ path: join(stateDir, file), kind: "port", action: "remove", reason: "matching pid file is missing" });
+        }
+    }
+    return items;
+}
+async function applyStaleCdpFilePlan(items, isPidAlive = defaultIsPidAlive) {
+    const removed = [];
+    for (const item of items) {
+        if (item.kind === "pid") {
+            const pid = await readPid(item.path);
+            if (pid !== undefined && isPidAlive(pid))
+                continue;
+            await rm(item.path, { force: true });
+            removed.push(item.path);
+            const portPath = `${item.path.slice(0, -4)}.port`;
+            if (existsSync(portPath)) {
+                await rm(portPath, { force: true });
+                removed.push(portPath);
+            }
+            continue;
+        }
+        const pidPath = `${item.path.slice(0, -5)}.pid`;
+        if (existsSync(pidPath))
+            continue;
+        await rm(item.path, { force: true });
+        removed.push(item.path);
+    }
+    return removed;
+}
+async function findStateFiles(rootDir) {
+    const found = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.isFile() && entry.name === "state.json")
+                found.push(path);
+        }
+    }
+    await walk(rootDir);
+    return found;
+}
+async function readPid(path) {
+    const text = await readFile(path, "utf8").catch(() => "");
+    const pid = Number.parseInt(text.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+function hasExpired(value, now) {
+    if (!value)
+        return false;
+    const timestamp = Date.parse(value);
+    return !Number.isNaN(timestamp) && timestamp <= now.getTime();
+}
+function isOlderThan(value, now, ageMs) {
+    if (!value)
+        return false;
+    const timestamp = Date.parse(value);
+    return !Number.isNaN(timestamp) && timestamp + ageMs <= now.getTime();
+}
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}

package/dist/resources/reaper-state.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { piboHomePath } from "../core/pibo-home.js";
+export function defaultResourceReaperStatePath() {
+    return process.env.PIBO_RESOURCE_REAPER_STATE_PATH || piboHomePath("resource-reaper-state.json");
+}
+export async function writeResourceReaperState(path, state) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporaryPath = `${path}.${process.pid}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporaryPath, path);
+}
+export async function claimResourceReaperOwnership(lockPath, pid = process.pid, isPidAlive = defaultIsPidAlive) {
+    await mkdir(dirname(lockPath), { recursive: true });
+    try {
+        const handle = await open(lockPath, "wx", 0o600);
+        await handle.writeFile(`${pid}\n`);
+        await handle.close();
+        return true;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+            throw error;
+    }
+    const owner = Number.parseInt((await readFile(lockPath, "utf8").catch(() => "")).trim(), 10);
+    if (Number.isInteger(owner) && owner > 0 && isPidAlive(owner))
+        return false;
+    await rm(lockPath, { force: true });
+    try {
+        const handle = await open(lockPath, "wx", 0o600);
+        await handle.writeFile(`${pid}\n`);
+        await handle.close();
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+export async function releaseResourceReaperOwnership(lockPath, pid = process.pid) {
+    const owner = Number.parseInt((await readFile(lockPath, "utf8").catch(() => "")).trim(), 10);
+    if (owner === pid)
+        await rm(lockPath, { force: true });
+}
+export function readResourceReaperTimerStatus(path = defaultResourceReaperStatePath(), isPidAlive = defaultIsPidAlive) {
+    if (!existsSync(path)) {
+        return {
+            status: "missing",
+            details: "No automatic resource reaper state was found.",
+            nextCommands: ["pibo resources status --json", "pibo resources reap --dry-run --json"],
+        };
+    }
+    try {
+        const state = JSON.parse(readFileSync(path, "utf8"));
+        if (state.status !== "running" || !Number.isInteger(state.pid) || state.pid <= 0 || !isPidAlive(state.pid)) {
+            return {
+                status: "unknown",
+                details: `Resource reaper state exists but its owner is not running (${path}).`,
+                lastRunAt: state.lastRunAt,
+                nextRunAt: state.nextRunAt,
+                lastResult: state.lastResult,
+                lastError: state.lastError,
+                nextCommands: ["pibo resources status --json", "pibo resources reap --dry-run --json"],
+            };
+        }
+        return {
+            status: "configured",
+            details: `Automatic resource reaper is running every ${state.intervalMs} ms (pid ${state.pid}).`,
+            lastRunAt: state.lastRunAt,
+            nextRunAt: state.nextRunAt,
+            lastResult: state.lastResult,
+            lastError: state.lastError,
+            nextCommands: ["pibo resources status --json", "pibo resources reap --dry-run --json"],
+        };
+    }
+    catch (error) {
+        return {
+            status: "unknown",
+            details: `Resource reaper state could not be read: ${error instanceof Error ? error.message : String(error)}`,
+            nextCommands: ["pibo resources status --json", "pibo resources reap --dry-run --json"],
+        };
+    }
+}
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}

package/dist/resources/reaper.js

@@ -0,0 +1,145 @@
+import { applyResourceReapPlan, planResourceReap } from "./lifecycle.js";
+import { claimResourceReaperOwnership, defaultResourceReaperStatePath, releaseResourceReaperOwnership, writeResourceReaperState, } from "./reaper-state.js";
+export class ResourceReaperService {
+    options;
+    intervalMs;
+    initialDelayMs;
+    statePath;
+    lockPath;
+    plan;
+    apply;
+    now;
+    timer;
+    running = false;
+    stopped = true;
+    ownsTimer = false;
+    state;
+    constructor(options = {}) {
+        this.options = options;
+        this.intervalMs = Math.max(1_000, options.intervalMs ?? readPositiveInteger(process.env.PIBO_RESOURCE_REAPER_INTERVAL_MS) ?? 5 * 60_000);
+        this.initialDelayMs = Math.max(0, options.initialDelayMs ?? readNonNegativeInteger(process.env.PIBO_RESOURCE_REAPER_INITIAL_DELAY_MS) ?? 30_000);
+        this.statePath = options.statePath ?? defaultResourceReaperStatePath();
+        this.lockPath = `${this.statePath}.lock`;
+        this.plan = options.plan ?? planResourceReap;
+        this.apply = options.apply ?? applyResourceReapPlan;
+        this.now = options.clock ?? (() => new Date());
+    }
+    async start() {
+        if (!this.stopped)
+            return;
+        this.ownsTimer = await claimResourceReaperOwnership(this.lockPath);
+        if (!this.ownsTimer)
+            return;
+        this.stopped = false;
+        const now = this.now();
+        this.state = {
+            status: "running",
+            pid: process.pid,
+            startedAt: now.toISOString(),
+            intervalMs: this.intervalMs,
+            nextRunAt: new Date(now.getTime() + this.initialDelayMs).toISOString(),
+        };
+        await this.persist();
+        this.arm(this.initialDelayMs);
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        if (this.state && this.ownsTimer) {
+            this.state = { ...this.state, status: "stopped", nextRunAt: undefined };
+            await this.persist();
+        }
+        if (this.ownsTimer)
+            await releaseResourceReaperOwnership(this.lockPath);
+        this.ownsTimer = false;
+    }
+    async runNow() {
+        if (!this.ownsTimer || this.running)
+            return undefined;
+        this.running = true;
+        const runAt = this.now();
+        try {
+            const plan = await this.plan({
+                includeDev: this.options.includeDev,
+                maxAgeMinutes: this.options.maxAgeMinutes,
+                idleTimeoutMinutes: this.options.idleTimeoutMinutes,
+                unmanagedBrowserGraceMinutes: this.options.unmanagedBrowserGraceMinutes,
+                browserPoolRoot: this.options.browserPoolRoot,
+                browserUseHome: this.options.browserUseHome,
+                exemptBrowserPids: this.options.exemptBrowserPids,
+                now: runAt,
+            });
+            const result = await this.apply(plan);
+            this.state = {
+                ...(this.state ?? {
+                    status: "running",
+                    pid: process.pid,
+                    startedAt: runAt.toISOString(),
+                    intervalMs: this.intervalMs,
+                }),
+                status: "running",
+                lastRunAt: runAt.toISOString(),
+                nextRunAt: new Date(this.now().getTime() + this.intervalMs).toISOString(),
+                lastResult: {
+                    browserPools: result.browserResults.filter((item) => item.reaped).length,
+                    unmanagedBrowsers: result.terminatedUnmanagedBrowsers.length,
+                    staleFiles: result.removedStaleFiles.length,
+                    computeWorkers: result.removedComputeWorkers.length,
+                },
+                lastError: undefined,
+            };
+            console.error(JSON.stringify({ event: "resource_reaper_finished", at: runAt.toISOString(), ...this.state.lastResult }));
+            await this.persist();
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.state = {
+                ...(this.state ?? {
+                    status: "running",
+                    pid: process.pid,
+                    startedAt: runAt.toISOString(),
+                    intervalMs: this.intervalMs,
+                }),
+                status: "running",
+                lastRunAt: runAt.toISOString(),
+                nextRunAt: new Date(this.now().getTime() + this.intervalMs).toISOString(),
+                lastError: message,
+            };
+            console.error(JSON.stringify({ event: "resource_reaper_failed", at: runAt.toISOString(), error: message }));
+            await this.persist();
+            return undefined;
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    arm(delayMs) {
+        if (this.stopped)
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            void this.runNow().finally(() => this.arm(this.intervalMs));
+        }, delayMs);
+        this.timer.unref?.();
+    }
+    async persist() {
+        if (this.state)
+            await writeResourceReaperState(this.statePath, this.state);
+    }
+}
+function readPositiveInteger(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function readNonNegativeInteger(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}