typescript-virtual-container 1.4.6 → 1.4.8

package/src/index.ts

@@ -5,6 +5,8 @@ export { default as VirtualFileSystem } from "./VirtualFileSystem/index";
 export { VirtualPackageManager } from "./VirtualPackageManager/index";
 export { VirtualShell } from "./VirtualShell/index";
 export { VirtualUserManager } from "./VirtualUserManager/index";
+export { IdleManager } from "./VirtualShell/idleManager";
+export type { IdleManagerOptions, IdleState } from "./VirtualShell/idleManager";
 
 export type {
 	AuditLogEntry,

package/src/modules/linuxRootfs.ts

@@ -15,10 +15,12 @@
  */
 
 import * as os from "node:os";
-import type VirtualFileSystem from "../VirtualFileSystem";
+import VirtualFileSystem from "../VirtualFileSystem";
+import { decodeVfs } from "../VirtualFileSystem/binaryPack";
 import type { ShellProperties } from "../VirtualShell";
 import type { VirtualActiveSession, VirtualUserManager } from "../VirtualUserManager";
 
+
 // ─── helpers ────────────────────────────────────────────────────────────────
 
 function ensureDir(vfs: VirtualFileSystem, path: string, mode = 0o755): void {
@@ -31,7 +33,8 @@ function ensureFile(
 	content: string,
 	mode = 0o644,
 ): void {
-	if (!vfs.exists(path)) vfs.writeFile(path, content, { mode });
+	// Use lazy stub — no Buffer allocated until the file is actually read or overwritten
+	vfs.writeStub(path, content, mode);
 }
 
 function write(vfs: VirtualFileSystem, path: string, content: string): void {
@@ -766,6 +769,50 @@ function bootstrapMisc(vfs: VirtualFileSystem, props: ShellProperties): void {
 	ensureDir(vfs, "/lost+found", 0o700);
 }
 
+// ── Static rootfs snapshot cache ─────────────────────────────────────────────
+// The static parts of the rootfs (dev, usr, var, bin, tmp, etc, sys, misc)
+// are identical for all shells sharing the same hostname+props.
+// We build them once, serialise to VFSB binary, and clone via decodeVfs()
+// for each new shell — avoiding ~250 JS object allocations per instance.
+
+const _staticRootfsCache = new Map<string, Buffer>();
+
+function _staticCacheKey(hostname: string, props: ShellProperties): string {
+	return `${hostname}|${props.kernel}|${props.os}|${props.arch}`;
+}
+
+/**
+ * Build or retrieve the static rootfs VFSB snapshot for the given
+ * hostname + ShellProperties combination.
+ *
+ * Subsequent calls with the same key return the cached Buffer in ~0ms.
+ */
+export function getStaticRootfsSnapshot(
+	hostname: string,
+	props: ShellProperties,
+): Buffer {
+	const key = _staticCacheKey(hostname, props);
+	const cached = _staticRootfsCache.get(key);
+	if (cached) return cached;
+
+	// Build the static subset into a temporary VFS
+	const tmp = new VirtualFileSystem({ mode: "memory" });
+	bootstrapEtc(tmp, hostname, props);
+	bootstrapSys(tmp, hostname, props);
+	bootstrapDev(tmp);
+	bootstrapUsr(tmp);
+	bootstrapVar(tmp);
+	bootstrapBin(tmp);
+	bootstrapTmp(tmp);
+	bootstrapMisc(tmp, props);
+	bootProcLog(tmp, props);
+
+	const snapshot = tmp.encodeBinary();
+	_staticRootfsCache.set(key, snapshot);
+	return snapshot;
+}
+
+
 // ─── main entry point ─────────────────────────────────────────────────────────
 
 /**
@@ -787,18 +834,15 @@ export function bootstrapLinuxRootfs(
 	shellStartTime: number,
 	sessions: VirtualActiveSession[] = [],
 ): void {
-	bootstrapEtc(vfs, hostname, props);
-	bootstrapSys(vfs, hostname, props);
-	bootstrapDev(vfs);
-	bootstrapUsr(vfs);
-	bootstrapVar(vfs);
-	bootstrapBin(vfs);
-	bootstrapTmp(vfs);
-	bootstrapRoot(vfs);
-	bootstrapMisc(vfs, props);
-	bootProcLog(vfs, props);
-	refreshProc(vfs, props, hostname, shellStartTime, sessions);
-	syncEtcPasswd(vfs, users);
+	// Fast path: clone the cached static rootfs snapshot (VFSB decode ~0.07ms)
+	// instead of rebuilding ~250 JS objects from scratch each time.
+	const snapshot = getStaticRootfsSnapshot(hostname, props);
+	vfs.importRootTree(decodeVfs(snapshot));
+
+	// Dynamic parts: per-instance data injected after the static clone
+	bootstrapRoot(vfs);           // /root home dir + .bashrc
+	refreshProc(vfs, props, hostname, shellStartTime, sessions);  // /proc live data
+	syncEtcPasswd(vfs, users);   // /etc/passwd|group|shadow
 }
 
 // ─── optional live engine ─────────────────────────────────────────────────────

package/src/self-standalone.ts

@@ -62,7 +62,7 @@ function writeLastLogin(username: string, from: string): void {
 }
 
 async function flushVfs(): Promise<void> {
-	await virtualShell.vfs.flushMirror();
+	await virtualShell.vfs.stopAutoFlush();
 }
 
 function loadHistory(authUser: string): string[] {
@@ -506,6 +506,19 @@ runReadlineShell().catch((error: unknown) => {
 	process.exit(1);
 });
 
+
+// ── Graceful shutdown (process-level) ────────────────────────────────────────
+let _shuttingDown = false;
+async function _gracefulShutdown(signal: string): Promise<void> {
+	if (_shuttingDown) return;
+	_shuttingDown = true;
+	process.stdout.write(`\n[${signal}] Saving VFS...\n`);
+	try { await virtualShell.vfs.stopAutoFlush(); } catch {}
+	process.exit(0);
+}
+process.on("SIGTERM", () => { void _gracefulShutdown("SIGTERM"); });
+process.on("beforeExit", () => { void virtualShell.vfs.stopAutoFlush(); });
+
 process.on("uncaughtException", (error) => {
 	console.error("Uncaught exception:", error);
 });

package/src/standalone.ts

@@ -31,6 +31,29 @@ new VirtualSftpServer({ port: 2223, hostname, shell: virtualShell })
 		process.exit(1);
 	});
 
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+// On SIGINT / SIGTERM: flush the WAL journal to a full checkpoint before exit.
+// A kill -9 or OOM crash is unrecoverable here, but the WAL journal on disk
+// guarantees all writes since the last checkpoint are replayed on next start.
+let isShuttingDown = false;
+async function gracefulShutdown(signal: string): Promise<void> {
+	if (isShuttingDown) return;
+	isShuttingDown = true;
+	console.log(`\n[${signal}] Flushing VFS checkpoint before exit...`);
+	try {
+		await virtualShell.vfs.stopAutoFlush();
+		console.log("[shutdown] Checkpoint written. Goodbye.");
+	} catch (err) {
+		console.error("[shutdown] Flush failed:", err);
+	}
+	process.exit(0);
+}
+
+process.on("SIGINT",  () => { void gracefulShutdown("SIGINT"); });
+process.on("SIGTERM", () => { void gracefulShutdown("SIGTERM"); });
+process.on("beforeExit", () => { void virtualShell.vfs.stopAutoFlush(); });
+
 process.on("uncaughtException", (error) => {
 	console.debug("Oh my god, something terrible happened: ", error);
 });