@evelandhq/sandbox-bwrap 0.1.2 → 0.2.0

package/dist/cache.js

@@ -0,0 +1,283 @@
+import { randomUUID } from "node:crypto";
+import { constants, existsSync } from "node:fs";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+const activeCachePaths = new Map();
+export function registerActiveCachePath(path) {
+    const resolved = resolve(path);
+    activeCachePaths.set(resolved, (activeCachePaths.get(resolved) ?? 0) + 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const remaining = (activeCachePaths.get(resolved) ?? 1) - 1;
+        if (remaining <= 0)
+            activeCachePaths.delete(resolved);
+        else
+            activeCachePaths.set(resolved, remaining);
+    };
+}
+function resolveCacheRoot(input) {
+    return resolve(input.cacheDir ?? join(input.appRoot, ".eve", "sandbox-cache", "bwrap"));
+}
+function leaseDirectory(cacheRoot) {
+    return join(cacheRoot, "metadata", "active", "sessions");
+}
+export async function createBwrapCacheLease(input) {
+    const generationId = randomUUID();
+    const directory = leaseDirectory(input.cacheRoot);
+    const path = join(directory, `${input.sessionId}.${generationId}.json`);
+    const lease = {
+        sessionId: input.sessionId,
+        generationId,
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        path,
+    };
+    await mkdir(directory, { recursive: true });
+    await writeFile(path, `${JSON.stringify(lease, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    let released = false;
+    return {
+        lease,
+        async release() {
+            if (released)
+                return;
+            await rm(path, { force: true });
+            released = true;
+        },
+    };
+}
+export async function listBwrapCacheLeases(input) {
+    const cacheRoot = resolveCacheRoot(input);
+    const directory = leaseDirectory(cacheRoot);
+    const names = await readdir(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const leases = await Promise.all(names
+        .filter((name) => name.endsWith(".json"))
+        .map(async (name) => {
+        const path = join(directory, name);
+        try {
+            const value = JSON.parse(await readFile(path, "utf8"));
+            if (typeof value.sessionId !== "string" ||
+                !validEntryId("session", value.sessionId) ||
+                typeof value.generationId !== "string" ||
+                typeof value.pid !== "number" ||
+                typeof value.createdAt !== "string") {
+                return null;
+            }
+            return { ...value, path };
+        }
+        catch {
+            return null;
+        }
+    }));
+    return leases
+        .filter((lease) => lease !== null)
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
+function validEntryId(kind, id) {
+    return kind === "session" ? /^[0-9a-f]{32}$/.test(id) : /^[0-9a-f]{32}-[0-9a-f]{16}$/.test(id);
+}
+async function directorySize(path) {
+    const info = await lstat(path);
+    if (!info.isDirectory())
+        return info.size;
+    const children = await readdir(path);
+    const sizes = await Promise.all(children.map(async (child) => await directorySize(join(path, child))));
+    return sizes.reduce((total, size) => total + size, 0);
+}
+async function listKind(cacheRoot, kind, leasedSessionIds) {
+    const directory = join(cacheRoot, `${kind}s`);
+    const children = await readdir(directory, { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const entries = await Promise.all(children
+        .filter((child) => child.isDirectory() && validEntryId(kind, child.name))
+        .map(async (child) => {
+        const entryPath = join(directory, child.name);
+        const info = await lstat(entryPath);
+        const stored = await readMetadata(metadataPath(cacheRoot, kind, child.name));
+        const metadata = stored?.kind === kind && stored.id === child.name
+            ? stored
+            : {
+                schemaVersion: 1,
+                kind,
+                id: child.name,
+                createdAt: info.birthtime.toISOString(),
+                lastUsedAt: info.mtime.toISOString(),
+            };
+        return {
+            ...metadata,
+            path: entryPath,
+            sizeBytes: await directorySize(entryPath),
+            active: activeCachePaths.has(entryPath) || leasedSessionIds.has(child.name),
+            metadataPresent: stored !== null && stored.kind === kind && stored.id === child.name,
+        };
+    }));
+    return entries.sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function listBwrapCache(input) {
+    const cacheRoot = resolveCacheRoot(input);
+    const leases = await listBwrapCacheLeases(input);
+    const leasedSessionIds = new Set(leases.map((lease) => lease.sessionId));
+    const [sessions, templates] = await Promise.all([
+        listKind(cacheRoot, "session", leasedSessionIds),
+        listKind(cacheRoot, "template", leasedSessionIds),
+    ]);
+    return [...sessions, ...templates];
+}
+function validatePolicy(kind, policy) {
+    if (policy.maxAgeMs !== undefined &&
+        (!Number.isSafeInteger(policy.maxAgeMs) || policy.maxAgeMs < 0)) {
+        throw new Error(`bwrap sandbox: ${kind} maxAgeMs must be a non-negative safe integer`);
+    }
+    if (policy.maxEntries !== undefined &&
+        (!Number.isSafeInteger(policy.maxEntries) || policy.maxEntries < 0)) {
+        throw new Error(`bwrap sandbox: ${kind} maxEntries must be a non-negative safe integer`);
+    }
+    if (policy.maxAgeMs === undefined && policy.maxEntries === undefined) {
+        throw new Error(`bwrap sandbox: ${kind} prune policy must set maxAgeMs or maxEntries`);
+    }
+}
+function selectCandidates(entries, policy, nowMs) {
+    const selected = new Set();
+    if (policy.maxAgeMs !== undefined) {
+        for (const entry of entries) {
+            if (nowMs - Date.parse(entry.lastUsedAt) > policy.maxAgeMs)
+                selected.add(entry);
+        }
+    }
+    if (policy.maxEntries !== undefined && entries.length > policy.maxEntries) {
+        const oldestFirst = [...entries].sort((a, b) => Date.parse(a.lastUsedAt) - Date.parse(b.lastUsedAt) || a.id.localeCompare(b.id));
+        for (const entry of oldestFirst.slice(0, entries.length - policy.maxEntries)) {
+            selected.add(entry);
+        }
+    }
+    return selected;
+}
+export async function pruneBwrapCache(input) {
+    if (!input.sessions && !input.templates) {
+        throw new Error("bwrap sandbox: cache prune requires a sessions or templates policy");
+    }
+    if (input.sessions)
+        validatePolicy("session", input.sessions);
+    if (input.templates)
+        validatePolicy("template", input.templates);
+    const entries = await listBwrapCache(input);
+    const nowMs = (input.now ?? new Date()).getTime();
+    const selected = new Set();
+    for (const [kind, policy] of [
+        ["session", input.sessions],
+        ["template", input.templates],
+    ]) {
+        if (!policy)
+            continue;
+        const matches = entries.filter((entry) => entry.kind === kind);
+        for (const entry of selectCandidates(matches, policy, nowMs))
+            selected.add(entry);
+    }
+    const candidates = [...selected].sort((a, b) => a.path.localeCompare(b.path));
+    const skippedActive = candidates.filter((entry) => entry.active || activeCachePaths.has(entry.path));
+    const removable = candidates.filter((entry) => !skippedActive.includes(entry));
+    const removed = [];
+    if (input.dryRun === false) {
+        const cacheRoot = resolveCacheRoot(input);
+        for (const entry of removable) {
+            const leased = (await listBwrapCacheLeases(input)).some((lease) => lease.sessionId === entry.id);
+            if (activeCachePaths.has(entry.path) || leased) {
+                skippedActive.push(entry);
+                continue;
+            }
+            await rm(entry.path, { force: true, recursive: true });
+            await rm(metadataPath(cacheRoot, entry.kind, entry.id), { force: true });
+            removed.push(entry);
+        }
+    }
+    return {
+        dryRun: input.dryRun !== false,
+        candidates,
+        removed,
+        skippedActive,
+        retained: entries.filter((entry) => !removed.includes(entry) && (!selected.has(entry) || skippedActive.includes(entry))),
+    };
+}
+const reflinkFallbackCodes = new Set(["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EXDEV"]);
+export async function cloneDirectoryAtomically(input) {
+    const copyDirectory = input.copyDirectory ?? (async (source, target, options) => await cp(source, target, options));
+    const temporary = `${input.targetPath}.${randomUUID()}.tmp`;
+    await mkdir(dirname(input.targetPath), { recursive: true });
+    try {
+        let strategy = "reflink";
+        try {
+            await copyDirectory(input.sourcePath, temporary, {
+                recursive: true,
+                mode: constants.COPYFILE_FICLONE_FORCE,
+            });
+        }
+        catch (error) {
+            if (!reflinkFallbackCodes.has(error.code ?? ""))
+                throw error;
+            strategy = "copy";
+            await rm(temporary, { force: true, recursive: true });
+            await copyDirectory(input.sourcePath, temporary, { recursive: true });
+        }
+        await rename(temporary, input.targetPath);
+        return strategy;
+    }
+    catch (error) {
+        await rm(temporary, { force: true, recursive: true }).catch(() => { });
+        if (existsSync(input.targetPath))
+            return "existing";
+        throw error;
+    }
+}
+function metadataPath(cacheRoot, kind, id) {
+    return join(cacheRoot, "metadata", `${kind}s`, `${id}.json`);
+}
+async function readMetadata(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        return value.schemaVersion === 1 ? value : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function touchCacheMetadata(input) {
+    const target = metadataPath(input.cacheRoot, input.kind, input.id);
+    const existing = await readMetadata(target);
+    const now = (input.now ?? new Date()).toISOString();
+    const tags = input.tags ?? existing?.tags;
+    const cloneStrategy = input.cloneStrategy === "existing"
+        ? (existing?.cloneStrategy ?? "existing")
+        : (input.cloneStrategy ?? existing?.cloneStrategy);
+    const templateRevision = input.templateRevision ?? existing?.templateRevision;
+    const metadata = {
+        schemaVersion: 1,
+        kind: input.kind,
+        id: input.id,
+        createdAt: existing?.createdAt ?? now,
+        lastUsedAt: now,
+        ...(tags && Object.keys(tags).length > 0 ? { tags } : {}),
+        ...(cloneStrategy ? { cloneStrategy } : {}),
+        ...(templateRevision ? { templateRevision } : {}),
+    };
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    await mkdir(dirname(target), { recursive: true });
+    try {
+        await writeFile(temporary, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+    return metadata;
+}

package/dist/events.d.ts

@@ -0,0 +1,44 @@
+export type BwrapCommandFinishReason = "exit" | "abort" | "timeout" | "output-limit" | "killed" | "cleanup";
+interface BwrapEventBase {
+    readonly timestamp: string;
+    readonly sessionId: string;
+    readonly generationId: string;
+    readonly tags: Readonly<Record<string, string>>;
+}
+export type BwrapSandboxEvent = (BwrapEventBase & {
+    readonly type: "generation.started";
+}) | (BwrapEventBase & {
+    readonly type: "command.started";
+    readonly commandId: string;
+    readonly pid?: number;
+    readonly pgid?: number;
+    readonly liveProcesses: number;
+}) | (BwrapEventBase & {
+    readonly type: "command.finished";
+    readonly commandId: string;
+    readonly pid?: number;
+    readonly reason: BwrapCommandFinishReason;
+    readonly exitCode?: number;
+    readonly durationMs: number;
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+    readonly liveProcesses: number;
+    readonly error?: string;
+}) | (BwrapEventBase & {
+    readonly type: "cleanup.started";
+    readonly requestedProcesses: number;
+}) | (BwrapEventBase & {
+    readonly type: "cleanup.completed";
+    readonly requestedProcesses: number;
+    readonly remainingProcesses: number;
+    readonly durationMs: number;
+}) | (BwrapEventBase & {
+    readonly type: "cleanup.failed";
+    readonly requestedProcesses: number;
+    readonly remainingProcesses: number;
+    readonly durationMs: number;
+    readonly errors: readonly string[];
+});
+export type BwrapSandboxEventPayload = BwrapSandboxEvent extends infer Event ? Event extends BwrapSandboxEvent ? Omit<Event, "timestamp" | "sessionId" | "generationId" | "tags"> : never : never;
+export type BwrapSandboxEventSink = (event: BwrapSandboxEvent) => unknown;
+export {};

package/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 import type { SandboxBackend } from "eve/sandbox";
-import type { BwrapSandboxCreateOptions } from "./options.js";
+import type { BwrapSandboxCreateOptions, BwrapSandboxUseOptions } from "./options.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, type CreateBwrapSandboxBackendInput, } from "./backend.js";
-export type { BwrapNetworkPolicy, BwrapSandboxCreateOptions } from "./options.js";
-export { DEFAULT_RUN_TIMEOUT_MS } from "./options.js";
+export type { BwrapNetworkPolicy, BwrapSandboxCreateOptions, BwrapSandboxUseOptions, } from "./options.js";
+export type { BwrapCommandFinishReason, BwrapSandboxEvent, BwrapSandboxEventSink, } from "./events.js";
+export { listBwrapCache, listBwrapCacheLeases, pruneBwrapCache } from "./cache.js";
+export type { BwrapCacheEntry, BwrapCacheEntryKind, BwrapCacheLocation, BwrapCacheLease, BwrapCacheMetadata, BwrapCachePruneInput, BwrapCachePrunePolicy, BwrapCachePruneResult, BwrapCloneStrategy, } from "./cache.js";
+export { DEFAULT_MAX_CONCURRENT_PROCESSES, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_RUN_TIMEOUT_MS, } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 export type { ProcessRunner, SpawnedProcess } from "./process.js";
 /**
@@ -18,4 +21,4 @@ export type { ProcessRunner, SpawnedProcess } from "./process.js";
  * });
  * ```
  */
-export declare function bwrap(options?: BwrapSandboxCreateOptions): SandboxBackend;
+export declare function bwrap(options?: BwrapSandboxCreateOptions): SandboxBackend<BwrapSandboxUseOptions, BwrapSandboxUseOptions>;

package/dist/index.js

@@ -1,6 +1,7 @@
 import { createBwrapSandboxBackend } from "./backend.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, } from "./backend.js";
-export { DEFAULT_RUN_TIMEOUT_MS } from "./options.js";
+export { listBwrapCache, listBwrapCacheLeases, pruneBwrapCache } from "./cache.js";
+export { DEFAULT_MAX_CONCURRENT_PROCESSES, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_RUN_TIMEOUT_MS, } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 /**
  * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`.

package/dist/options.d.ts

@@ -1,7 +1,17 @@
+import type { BwrapSandboxEventSink } from "./events.js";
 /** Coarse egress control, matching what eve's Docker backend supports. */
 export type BwrapNetworkPolicy = "allow-all" | "deny-all";
+/** Options lifecycle hooks can apply when they open a template or live Session. */
+export interface BwrapSandboxUseOptions {
+    /** Network policy used by subsequent commands in this lifecycle callback. */
+    readonly networkPolicy?: BwrapNetworkPolicy;
+}
 /** Commands executed through `run()` are bounded by default; use `spawn()` for daemons. */
 export declare const DEFAULT_RUN_TIMEOUT_MS = 600000;
+/** Per-generation admission ceiling for transient bwrap commands. */
+export declare const DEFAULT_MAX_CONCURRENT_PROCESSES = 64;
+/** Combined stdout + stderr retained by one `run()` call. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
 /** Options accepted by `bwrap(opts)`. */
 export interface BwrapSandboxCreateOptions {
     /** Environment variables set for every command the backend runs. */
@@ -31,6 +41,12 @@ export interface BwrapSandboxCreateOptions {
      * long-running `spawn()` API.
      */
     readonly runTimeoutMs?: number | null;
+    /** Maximum live `run()`/`spawn()` processes in one compute generation. */
+    readonly maxConcurrentProcesses?: number | null;
+    /** Maximum combined stdout/stderr bytes retained by one `run()` call. */
+    readonly maxOutputBytes?: number | null;
+    /** Best-effort structured lifecycle events. Sink errors never affect commands. */
+    readonly onEvent?: BwrapSandboxEventSink;
 }
 /** Fully-defaulted options consumed by the backend implementation. */
 export interface ResolvedBwrapSandboxOptions {
@@ -41,6 +57,9 @@ export interface ResolvedBwrapSandboxOptions {
     readonly cacheDir: string | null;
     readonly templateRevision: string | null;
     readonly runTimeoutMs: number | null;
+    readonly maxConcurrentProcesses: number | null;
+    readonly maxOutputBytes: number | null;
+    readonly onEvent?: BwrapSandboxEventSink;
 }
 export declare function resolveBwrapSandboxOptions(options?: BwrapSandboxCreateOptions): ResolvedBwrapSandboxOptions;
 /**

package/dist/options.js

@@ -1,6 +1,10 @@
 import { createHash } from "node:crypto";
 /** Commands executed through `run()` are bounded by default; use `spawn()` for daemons. */
 export const DEFAULT_RUN_TIMEOUT_MS = 600_000;
+/** Per-generation admission ceiling for transient bwrap commands. */
+export const DEFAULT_MAX_CONCURRENT_PROCESSES = 64;
+/** Combined stdout + stderr retained by one `run()` call. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
 function resolveRunTimeoutMs(value) {
     if (value === null)
         return null;
@@ -10,6 +14,15 @@ function resolveRunTimeoutMs(value) {
     }
     return resolved;
 }
+function resolvePositiveLimit(name, value, fallback) {
+    if (value === null)
+        return null;
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new Error(`bwrap sandbox: ${name} must be a positive safe integer or null`);
+    }
+    return resolved;
+}
 export function resolveBwrapSandboxOptions(options = {}) {
     return {
         env: options.env ?? {},
@@ -19,6 +32,9 @@ export function resolveBwrapSandboxOptions(options = {}) {
         cacheDir: options.cacheDir ?? null,
         templateRevision: options.templateRevision ?? null,
         runTimeoutMs: resolveRunTimeoutMs(options.runTimeoutMs),
+        maxConcurrentProcesses: resolvePositiveLimit("maxConcurrentProcesses", options.maxConcurrentProcesses, DEFAULT_MAX_CONCURRENT_PROCESSES),
+        maxOutputBytes: resolvePositiveLimit("maxOutputBytes", options.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES),
+        ...(options.onEvent ? { onEvent: options.onEvent } : {}),
     };
 }
 /**
@@ -32,6 +48,8 @@ export function createBwrapOptionsHash(options) {
         cacheDir: options.cacheDir,
         env: Object.fromEntries(Object.entries(options.env).sort(([a], [b]) => (a < b ? -1 : 1))),
         hidePaths: [...options.hidePaths],
+        maxConcurrentProcesses: options.maxConcurrentProcesses,
+        maxOutputBytes: options.maxOutputBytes,
         networkPolicy: options.networkPolicy,
         runTimeoutMs: options.runTimeoutMs,
         templateRevision: options.templateRevision,

package/dist/process.js

@@ -39,44 +39,68 @@ export function createNodeProcessRunner() {
             });
             exit.catch(() => { });
             const killTree = () => {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return undefined;
                 if (child.pid !== undefined) {
                     try {
                         process.kill(-child.pid, "SIGKILL");
-                        return;
+                        return undefined;
                     }
-                    catch {
-                        // fall through: group already gone or not yet set up
+                    catch (error) {
+                        // ESRCH can mean the process group was not established yet; kill
+                        // the direct child. Other failures (notably EPERM) are cleanup
+                        // failures even if the direct-child fallback succeeds, because
+                        // descendants may have escaped the signal.
+                        child.kill("SIGKILL");
+                        if (error.code !== "ESRCH")
+                            return error;
+                        return undefined;
                     }
                 }
                 child.kill("SIGKILL");
+                return undefined;
             };
             let aborted = false;
             let abortReason;
+            let abortKillError;
             const signal = options?.abortSignal;
+            let onAbort;
             if (signal) {
-                const onAbort = () => {
+                onAbort = () => {
                     aborted = true;
                     abortReason = signal.reason;
-                    killTree();
+                    abortKillError = killTree();
                 };
                 if (signal.aborted)
                     onAbort();
                 else
                     signal.addEventListener("abort", onAbort, { once: true });
             }
+            const removeAbortListener = () => {
+                if (signal && onAbort)
+                    signal.removeEventListener("abort", onAbort);
+            };
+            void exit.then(removeAbortListener, removeAbortListener);
             return {
                 pid: child.pid,
                 stdout: Readable.toWeb(child.stdout),
                 stderr: Readable.toWeb(child.stderr),
                 async wait() {
                     const result = await exit;
+                    if (abortKillError !== undefined) {
+                        const cleanupMessage = abortKillError instanceof Error ? abortKillError.message : String(abortKillError);
+                        const abortMessage = abortReason instanceof Error ? abortReason.message : String(abortReason);
+                        throw new AggregateError([abortKillError, abortReason], `bwrap process abort cleanup failed: ${cleanupMessage}; abort reason: ${abortMessage}`);
+                    }
                     if (aborted)
                         throw abortReason;
                     return result;
                 },
                 async kill() {
-                    killTree();
+                    const killError = killTree();
                     await exit.catch(() => { });
+                    if (killError !== undefined)
+                        throw killError;
                 },
             };
         },

package/dist/session.d.ts

@@ -7,6 +7,9 @@ export interface CreateBwrapSessionInput {
     readonly appRoot: string;
     readonly runner: ProcessRunner;
     readonly options: ResolvedBwrapSandboxOptions;
+    readonly generationId?: string;
+    readonly tags?: Readonly<Record<string, string>>;
+    readonly onStopped?: () => void | Promise<void>;
 }
 /**
  * A sandbox session plus the lifecycle hook the backend handle needs.
@@ -16,5 +19,7 @@ export interface CreateBwrapSessionInput {
 export type BwrapSession = SandboxSession & {
     /** Kills every process this session spawned that has not yet exited. Idempotent. */
     killAll(): Promise<void>;
+    /** Internal compute-generation state used to coordinate repeated handles. */
+    lifecycleState(): "running" | "stopping" | "stopped";
 };
 export declare function createBwrapSession(input: CreateBwrapSessionInput): BwrapSession;