typescript-virtual-container 1.2.7 → 1.2.8

package/src/VirtualFileSystem/binaryPack.ts

@@ -0,0 +1,219 @@
+/**
+ * Binary serialisation format for VirtualFileSystem snapshots.
+ *
+ * Replaces the JSON+base64 approach. No external dependencies.
+ *
+ * Wire format (little-endian throughout):
+ *
+ *   File header:
+ *     [4]  magic  = 0x56 0x46 0x53 0x21  ("VFS!")
+ *     [1]  version = 0x01
+ *
+ *   Node (recursive):
+ *     [1]  type    = 0x01 (file) | 0x02 (directory)
+ *     [2]  name length (uint16)
+ *     [N]  name bytes (utf8)
+ *     [4]  mode (uint32)
+ *     [8]  createdAt ms (float64)
+ *     [8]  updatedAt ms (float64)
+ *
+ *   File node extra:
+ *     [1]  compressed flag (0x00 | 0x01)
+ *     [4]  content length (uint32)
+ *     [N]  content bytes (raw — no base64)
+ *
+ *   Directory node extra:
+ *     [4]  children count (uint32)
+ *     [N]  children nodes (recursive)
+ *
+ * Total overhead vs JSON+base64 for 1 MB of file data:
+ *   JSON+base64 :  ~1.37 MB (base64 33% bloat) + JSON string wrapping
+ *   Binary pack :  ~1.00 MB + ~40 bytes/node header  → ~27% smaller, no string parsing
+ */
+
+import type { InternalDirectoryNode, InternalFileNode, InternalNode } from "./internalTypes";
+
+const MAGIC = Buffer.from([0x56, 0x46, 0x53, 0x21]); // "VFS!"
+const VERSION = 0x01;
+const TYPE_FILE = 0x01;
+const TYPE_DIR  = 0x02;
+
+// ── Encoder ───────────────────────────────────────────────────────────────────
+
+class Encoder {
+	private chunks: Buffer[] = [];
+
+	write(buf: Buffer): void { this.chunks.push(buf); }
+
+	writeUint8(n: number): void {
+		const b = Buffer.allocUnsafe(1);
+		b.writeUInt8(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeUint16(n: number): void {
+		const b = Buffer.allocUnsafe(2);
+		b.writeUInt16LE(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeUint32(n: number): void {
+		const b = Buffer.allocUnsafe(4);
+		b.writeUInt32LE(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeFloat64(n: number): void {
+		const b = Buffer.allocUnsafe(8);
+		b.writeDoubleBE(n, 0);
+		this.chunks.push(b);
+	}
+
+	writeString(s: string): void {
+		const encoded = Buffer.from(s, "utf8");
+		this.writeUint16(encoded.length);
+		this.chunks.push(encoded);
+	}
+
+	writeBytes(bytes: Buffer): void {
+		this.writeUint32(bytes.length);
+		this.chunks.push(bytes);
+	}
+
+	toBuffer(): Buffer { return Buffer.concat(this.chunks); }
+}
+
+function encodeNode(enc: Encoder, node: InternalNode): void {
+	if (node.type === "file") {
+		const f = node as InternalFileNode;
+		enc.writeUint8(TYPE_FILE);
+		enc.writeString(f.name);
+		enc.writeUint32(f.mode);
+		enc.writeFloat64(f.createdAt.getTime());
+		enc.writeFloat64(f.updatedAt.getTime());
+		enc.writeUint8(f.compressed ? 0x01 : 0x00);
+		enc.writeBytes(f.content);
+	} else {
+		const d = node as InternalDirectoryNode;
+		enc.writeUint8(TYPE_DIR);
+		enc.writeString(d.name);
+		enc.writeUint32(d.mode);
+		enc.writeFloat64(d.createdAt.getTime());
+		enc.writeFloat64(d.updatedAt.getTime());
+		const children = Array.from(d.children.values());
+		enc.writeUint32(children.length);
+		for (const child of children) encodeNode(enc, child);
+	}
+}
+
+/**
+ * Serialise an in-memory VFS root to a compact binary Buffer.
+ * No base64, no JSON. ~27% smaller than the JSON+base64 format for typical VFS trees.
+ */
+export function encodeVfs(root: InternalDirectoryNode): Buffer {
+	const enc = new Encoder();
+	enc.write(MAGIC);
+	enc.writeUint8(VERSION);
+	encodeNode(enc, root);
+	return enc.toBuffer();
+}
+
+// ── Decoder ───────────────────────────────────────────────────────────────────
+
+class Decoder {
+	private pos = 0;
+	constructor(private readonly buf: Buffer) {}
+
+	readUint8(): number { return this.buf.readUInt8(this.pos++); }
+
+	readUint16(): number {
+		const v = this.buf.readUInt16LE(this.pos);
+		this.pos += 2;
+		return v;
+	}
+
+	readUint32(): number {
+		const v = this.buf.readUInt32LE(this.pos);
+		this.pos += 4;
+		return v;
+	}
+
+	readFloat64(): number {
+		const v = this.buf.readDoubleBE(this.pos);
+		this.pos += 8;
+		return v;
+	}
+
+	readString(): string {
+		const len = this.readUint16();
+		const s = this.buf.toString("utf8", this.pos, this.pos + len);
+		this.pos += len;
+		return s;
+	}
+
+	readBytes(): Buffer {
+		const len = this.readUint32();
+		const b = this.buf.slice(this.pos, this.pos + len);
+		this.pos += len;
+		return b;
+	}
+
+	remaining(): number { return this.buf.length - this.pos; }
+}
+
+function decodeNode(dec: Decoder): InternalNode {
+	const type = dec.readUint8();
+	const name = dec.readString();
+	const mode = dec.readUint32();
+	const createdAt = new Date(dec.readFloat64());
+	const updatedAt = new Date(dec.readFloat64());
+
+	if (type === TYPE_FILE) {
+		const compressed = dec.readUint8() === 0x01;
+		const content = dec.readBytes();
+		return { type: "file", name, mode, createdAt, updatedAt, compressed, content } satisfies InternalFileNode;
+	}
+
+	if (type === TYPE_DIR) {
+		const count = dec.readUint32();
+		const children = new Map<string, InternalNode>();
+		for (let i = 0; i < count; i++) {
+			const child = decodeNode(dec);
+			children.set(child.name, child);
+		}
+		return { type: "directory", name, mode, createdAt, updatedAt, children } satisfies InternalDirectoryNode;
+	}
+
+	throw new Error(`[VFS binary] Unknown node type: 0x${type.toString(16)}`);
+}
+
+/**
+ * Deserialise a binary Buffer produced by {@link encodeVfs} back into an
+ * InternalDirectoryNode tree. Throws on magic/version mismatch or truncation.
+ */
+export function decodeVfs(buf: Buffer): InternalDirectoryNode {
+	if (buf.length < 5) throw new Error("[VFS binary] Buffer too short");
+
+	const magic = buf.slice(0, 4);
+	if (!magic.equals(MAGIC)) {
+		throw new Error("[VFS binary] Invalid magic — not a VFS binary snapshot");
+	}
+
+	const dec = new Decoder(buf);
+	// skip magic (4) + version (1)
+	for (let i = 0; i < 5; i++) dec.readUint8();
+
+	const root = decodeNode(dec);
+	if (root.type !== "directory") {
+		throw new Error("[VFS binary] Root node must be a directory");
+	}
+	return root as InternalDirectoryNode;
+}
+
+/**
+ * Returns true if `buf` looks like a VFS binary snapshot (starts with magic bytes).
+ * Used to auto-detect format when loading from disk.
+ */
+export function isBinarySnapshot(buf: Buffer): boolean {
+	return buf.length >= 4 && buf.slice(0, 4).equals(MAGIC);
+}

package/src/VirtualFileSystem/index.ts

@@ -7,6 +7,7 @@ import type {
 	InternalFileNode,
 	InternalNode,
 } from "./internalTypes";
+import { decodeVfs, encodeVfs, isBinarySnapshot } from "./binaryPack";
 import { getNode, getParentDirectory, normalizePath } from "./path";
 import type {
 	RemoveOptions,
@@ -24,8 +25,8 @@ import type {
  * "memory" — pure in-memory, no disk I/O (default).
  *
  * "fs"     — mirrors the VFS tree to a directory on the host filesystem.
- *             `snapshotPath` must be set to the directory where the JSON
- *             snapshot file will be read/written.
+ *             `snapshotPath` must be set to the directory where the binary
+ *             snapshot file will be read/written (`vfs-snapshot.vfsb`).
  */
 export type VfsPersistenceMode = "memory" | "fs";
 
@@ -53,7 +54,7 @@ export interface VfsOptions {
  * **Memory mode** (default) — all state lives in a fast recursive tree.
  * Use `toSnapshot()` / `fromSnapshot()` / `importSnapshot()` for serialisation.
  *
- * **FS mode** — same in-memory tree, but `restoreMirror()` loads a JSON
+ * **FS mode** — same in-memory tree, but `restoreMirror()` loads a binary
  * snapshot from disk and `flushMirror()` writes it back.  This gives you
  * persistent VFS state across process restarts without any real POSIX filesystem
  * semantics leaking through.
@@ -86,7 +87,7 @@ class VirtualFileSystem extends EventEmitter {
 			}
 			this.snapshotFile = path.resolve(
 				options.snapshotPath,
-				"vfs-snapshot.json",
+				"vfs-snapshot.vfsb",
 			);
 		} else {
 			this.snapshotFile = null;
@@ -151,7 +152,8 @@ class VirtualFileSystem extends EventEmitter {
 	// ── Persistence ───────────────────────────────────────────────────────────
 
 	/**
-	 * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+	 * In `"fs"` mode: reads the binary snapshot (`vfs-snapshot.vfsb`) from disk.
+	 * Automatically falls back to legacy JSON format for backward compatibility.
 	 * Silently succeeds when the snapshot file does not exist yet.
 	 *
 	 * In `"memory"` mode: no-op (kept for API compatibility).
@@ -162,9 +164,16 @@ class VirtualFileSystem extends EventEmitter {
 		if (!fsSync.existsSync(this.snapshotFile)) return;
 
 		try {
-			const raw = fsSync.readFileSync(this.snapshotFile, "utf8");
-			const snapshot: VfsSnapshot = JSON.parse(raw);
-			this.root = this.deserializeDir(snapshot.root, "");
+			const raw = fsSync.readFileSync(this.snapshotFile);
+			if (isBinarySnapshot(raw)) {
+				// Fast binary format (current)
+				this.root = decodeVfs(raw);
+			} else {
+				// Legacy JSON fallback — auto-migrates on next flushMirror()
+				const snapshot: VfsSnapshot = JSON.parse(raw.toString("utf8"));
+				this.root = this.deserializeDir(snapshot.root, "");
+				console.info("[VirtualFileSystem] Migrating legacy JSON snapshot to binary format.");
+			}
 			this.emit("snapshot:restore", { path: this.snapshotFile });
 		} catch (err) {
 			// Corrupt or unreadable snapshot — start fresh and warn
@@ -176,7 +185,8 @@ class VirtualFileSystem extends EventEmitter {
 	}
 
 	/**
-	 * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+	 * In `"fs"` mode: serialises the in-memory tree to a binary snapshot on disk
+	 * (`vfs-snapshot.vfsb`). ~27% smaller and significantly faster than JSON+base64.
 	 * The directory is created if it does not exist.
 	 *
 	 * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).
@@ -189,8 +199,8 @@ class VirtualFileSystem extends EventEmitter {
 
 		const dir = path.dirname(this.snapshotFile);
 		fsSync.mkdirSync(dir, { recursive: true });
-		const snapshot = this.toSnapshot();
-		fsSync.writeFileSync(this.snapshotFile, JSON.stringify(snapshot), "utf8");
+		const binary = encodeVfs(this.root);
+		fsSync.writeFileSync(this.snapshotFile, binary);
 		this.emit("mirror:flush", { path: this.snapshotFile });
 	}
 

package/src/standalone.ts

@@ -1,7 +1,10 @@
 import { VirtualSftpServer, VirtualShell, VirtualSshServer } from ".";
 
 const hostname = process.env.SSH_MIMIC_HOSTNAME ?? "typescript-vm";
-const virtualShell = new VirtualShell(hostname);
+const virtualShell = new VirtualShell(hostname, undefined, {
+	mode: "fs",
+	snapshotPath: ".vfs",
+});
 
 virtualShell.addCommand("demo", [], () => {
 	return {