vmm-node-manager 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+# VmmNodeManagerConfig – Bun loads .env natively. Copy to .env and set paths.
+# For custom file: bun --env-file=.env.custom run src/index.ts
+
+VMM_KERNEL_IMAGE_PATH=./build/vmlinux
+VMM_ROOTFS_PATH=./build/alpine-rootfs.img
+VMM_MASTER_OVERLAY_PATH=./build/alpine-overlay.ext4
+VMM_OVERLAY_OUTPUT_DIR=./build/overlays

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "vmm-node-manager",
+  "version": "0.1.0",
+  "description": "VMM Manager standalone application",
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "DEBUG=continuum:* bun run --watch src/index.ts",
+    "type-check": "tsc --noEmit",
+    "generate:firecracker-client": "bun run scripts/generate-firecracker-client.ts"
+  },
+  "dependencies": {
+    "@mindignited/continuum-client": "3.0.0-beta.2",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.90.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.5.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}

package/scripts/generate-firecracker-client.ts

@@ -0,0 +1,12 @@
+import { createClient } from '@hey-api/openapi-ts';
+
+const FIRECRACKER_OPENAPI_URL = 'https://raw.githubusercontent.com/firecracker-microvm/firecracker/main/src/firecracker/swagger/firecracker.yaml';
+const OUTPUT_DIR = 'src/internal/api/firecracker/generated';
+
+await createClient({
+	input: FIRECRACKER_OPENAPI_URL,
+	output: OUTPUT_DIR,
+	plugins: ['@hey-api/client-fetch'],
+});
+
+console.log(`Firecracker API client generated successfully in ${OUTPUT_DIR}`);

package/src/api/config/VmmNodeManagerConfig.ts

@@ -0,0 +1,54 @@
+import { z, type ZodIssue } from 'zod'
+
+/**
+ * Global config for the vmm-node-manager. Loaded once at process start from environment via Bun's native .env.
+ * Extensible for other vmm-node-manager settings later.
+ *
+ * Env vars: VMM_CONTINUUM_HOST, VMM_KERNEL_IMAGE_PATH, VMM_ROOTFS_PATH, VMM_MASTER_OVERLAY_PATH, VMM_OVERLAY_OUTPUT_DIR
+ * Bun loads .env, .env.local, .env.{NODE_ENV} automatically. For custom: bun --env-file=.env.custom run ...
+ */
+
+const VmmNodeManagerConfigSchema = z.object({
+	continuumHost: z
+		.string({ required_error: 'VMM_CONTINUUM_HOST must be set' })
+		.min(1, 'VMM_CONTINUUM_HOST must be non-empty'),
+	kernelImagePath: z
+		.string({ required_error: 'VMM_KERNEL_IMAGE_PATH must be set' })
+		.min(1, 'VMM_KERNEL_IMAGE_PATH must be non-empty'),
+	rootfsPath: z
+		.string({ required_error: 'VMM_ROOTFS_PATH must be set' })
+		.min(1, 'VMM_ROOTFS_PATH must be non-empty'),
+	masterOverlayPath: z
+		.string({ required_error: 'VMM_MASTER_OVERLAY_PATH must be set' })
+		.min(1, 'VMM_MASTER_OVERLAY_PATH must be non-empty'),
+	overlayOutputDir: z
+		.string({ required_error: 'VMM_OVERLAY_OUTPUT_DIR must be set' })
+		.min(1, 'VMM_OVERLAY_OUTPUT_DIR must be non-empty'),
+})
+
+export type VmmNodeManagerConfig = z.infer<typeof VmmNodeManagerConfigSchema>
+
+function loadVmmNodeManagerConfig(): VmmNodeManagerConfig {
+	const env = typeof Bun !== 'undefined' ? Bun.env : process.env
+	const raw = {
+		continuumHost: env.VMM_CONTINUUM_HOST,
+		kernelImagePath: env.VMM_KERNEL_IMAGE_PATH,
+		rootfsPath: env.VMM_ROOTFS_PATH,
+		masterOverlayPath: env.VMM_MASTER_OVERLAY_PATH,
+		overlayOutputDir: env.VMM_OVERLAY_OUTPUT_DIR,
+	}
+
+	const result = VmmNodeManagerConfigSchema.safeParse(raw)
+	if (!result.success) {
+		const msg = result.error.issues
+			.map((i: ZodIssue) => `  - ${i.path.join('.')}: ${i.message}`)
+			.join('\n')
+		throw new Error(
+			`VmmNodeManagerConfig: validation failed:\n${msg}\nSet them in .env or the environment. See .env.example.`,
+		)
+	}
+	return result.data
+}
+
+/** Loaded once when this module is first imported. Throws if required env vars are missing. */
+export const vmmNodeManagerConfig: VmmNodeManagerConfig = loadVmmNodeManagerConfig()

package/src/api/domain/DriveConfig.ts

@@ -0,0 +1,6 @@
+export class DriveConfig {
+	public driveId!: string;
+	public pathOnHost!: string;
+	public isRootDevice!: boolean;
+	public isReadOnly!: boolean;
+}

package/src/api/domain/KinoticMicrovmLaunchResult.ts

@@ -0,0 +1,7 @@
+export interface KinoticMicrovmLaunchResult {
+	vmIndex: number;
+	tapIp: string;
+	guestIp: string;
+	overlayPath: string;
+	tapName: string;
+}

package/src/api/domain/MachineConfig.ts

@@ -0,0 +1,4 @@
+export class MachineConfig {
+	public vcpuCount!: number;
+	public memSizeMib!: number;
+}

package/src/api/domain/MmdsConfig.ts

@@ -0,0 +1,6 @@
+export class MmdsConfig {
+	public networkInterfaces!: string[];
+	public data!: Record<string, unknown>;
+	public ipv4Address?: string;
+	public imdsCompat?: boolean;
+}

package/src/api/domain/NetworkInterfaceConfig.ts

@@ -0,0 +1,5 @@
+export class NetworkInterfaceConfig {
+	public ifaceId!: string;
+	public guestMac?: string;
+	public hostDevName!: string;
+}

package/src/api/domain/VmmConfig.ts

@@ -0,0 +1,19 @@
+import type {VmmType} from './VmmType.js'
+import type {DriveConfig} from './DriveConfig.js'
+import type {NetworkInterfaceConfig} from './NetworkInterfaceConfig.js'
+import type {MachineConfig} from './MachineConfig.js'
+import type {MmdsConfig} from './MmdsConfig.js'
+
+export class VmmConfig {
+
+	/** Used to derive the API socket path: /tmp/firecracker-{id}.socket */
+	public id!: string | number;
+	public vmmType!: VmmType;
+	public kernelImagePath!: string;
+	public bootArgs?: string;
+	public drives!: DriveConfig[];
+	public networkInterfaces!: NetworkInterfaceConfig[];
+	public machineConfig!: MachineConfig;
+	public mmdsConfig?: MmdsConfig;
+
+}

package/src/api/domain/VmmType.ts

@@ -0,0 +1,4 @@
+export enum VmmType{
+	FIRECRACKER = 'FIRECRACKER',
+	CLOUD_HYPERVISOR = 'CLOUD_HYPERVISOR',
+}

package/src/api/services/KinoticMicrovmLauncherService.ts

@@ -0,0 +1,118 @@
+import {copyFileSync, mkdirSync} from 'node:fs'
+import {join} from 'node:path'
+import {vmmNodeManagerConfig} from '../config/VmmNodeManagerConfig.js'
+import type {KinoticMicrovmLaunchResult} from '../domain/KinoticMicrovmLaunchResult.js'
+import {VmmType} from '../domain/VmmType.js'
+import type {VmmConfig} from '../domain/VmmConfig.js'
+import type {VmmManagerService} from './VmmManagerService.js'
+import {Publish} from '@mindignited/continuum-client'
+
+const NETWORK_BASE = '172.16'
+const SUBNET_SIZE = 4
+const NETMASK = '255.255.255.252'
+const CIDR = 30
+
+@Publish('kinotic.vmm-node-manager')
+export class KinoticMicrovmLauncherService {
+	private readonly paths = vmmNodeManagerConfig
+
+	constructor(private readonly vmmManager: VmmManagerService) {}
+
+	async launch(vmIndex: number): Promise<KinoticMicrovmLaunchResult> {
+		const tapName = `tap${vmIndex}`
+		const {tapIp, guestIp} = this.computeIps(SUBNET_SIZE, vmIndex)
+
+		// 1. Create tap
+		await this.execIpCommand(['tuntap', 'add', tapName, 'mode', 'tap'])
+		await this.execIpCommand(['addr', 'add', `${tapIp}/${CIDR}`, 'dev', tapName])
+		await this.execIpCommand(['link', 'set', tapName, 'up'])
+
+		// 2. Copy overlay
+		mkdirSync(this.paths.overlayOutputDir, {recursive: true})
+		const overlayPath = join(this.paths.overlayOutputDir, `overlay-${vmIndex}.ext4`)
+		const masterFile = Bun.file(this.paths.masterOverlayPath)
+		if (!(await masterFile.exists())) {
+			throw new Error(`Master overlay not found at: ${this.paths.masterOverlayPath}`)
+		}
+		copyFileSync(this.paths.masterOverlayPath, overlayPath)
+
+		// 3. Build bootArgs
+		const bootArgs = `console=ttyS0 reboot=k panic=1 pci=off overlay_root=vdb init=/sbin/overlay-init.sh ip=${guestIp}::${tapIp}:${NETMASK}::eth0:off loglevel=7 earlyprintk=serial`
+
+		// 4. Build VmmConfig
+		const vmmConfig: VmmConfig = {
+			id: vmIndex,
+			vmmType: VmmType.FIRECRACKER,
+			kernelImagePath: this.paths.kernelImagePath,
+			bootArgs,
+			drives: [
+				{
+					driveId: 'rootfs',
+					pathOnHost: this.paths.rootfsPath,
+					isRootDevice: true,
+					isReadOnly: true,
+				},
+				{
+					driveId: 'overlayfs',
+					pathOnHost: overlayPath,
+					isRootDevice: false,
+					isReadOnly: false,
+				},
+			],
+			networkInterfaces: [{ifaceId: 'eth0', hostDevName: tapName}],
+			machineConfig: {vcpuCount: 1, memSizeMib: 128},
+		}
+
+		// 5. Launch via VmmManagerService
+		await this.vmmManager.launchVmm(vmmConfig)
+
+		return {
+			vmIndex,
+			tapIp,
+			guestIp,
+			overlayPath,
+			tapName,
+		}
+	}
+
+	/**
+	 * Stops the VM (sends SendCtrlAltDel to request shutdown) and removes the tap device.
+	 * Does not delete the overlay file.
+	 */
+	async stop(vmIndex: number): Promise<void> {
+		await this.vmmManager.stopVmm(vmIndex)
+		await this.execIpCommand(['link', 'delete', `tap${vmIndex}`])
+	}
+
+	/**
+	 * Sequential subnet allocation for tap and guest IPs. Each VM gets a /30 (4 addresses):
+	 * network, tap (host), guest (VM), broadcast. For VM index O (0-based) and A = subnetSize
+	 * (e.g. 4 for /30), we place this VM's /30 at offset (A*O) in the 172.16.0.0/16 range.
+	 * Tap = 2nd address (offset A*O+1), guest = 3rd (offset A*O+2). The offset is encoded as
+	 * 3rd octet = floor(offset/256), 4th = offset%256. Example: O=0 → tap 172.16.0.1, guest 172.16.0.2;
+	 * O=999 → tap 172.16.15.157, guest 172.16.15.158.
+	 */
+	private computeIps(subnetSize: number, vmIndex: number): {tapIp: string; guestIp: string} {
+		const tapThird = Math.floor((subnetSize * vmIndex + 1) / 256)
+		const tapFourth = (subnetSize * vmIndex + 1) % 256
+		const guestThird = Math.floor((subnetSize * vmIndex + 2) / 256)
+		const guestFourth = (subnetSize * vmIndex + 2) % 256
+		return {
+			tapIp: `${NETWORK_BASE}.${tapThird}.${tapFourth}`,
+			guestIp: `${NETWORK_BASE}.${guestThird}.${guestFourth}`,
+		}
+	}
+
+	private async execIpCommand(args: string[]): Promise<void> {
+		const proc = Bun.spawn({
+			cmd: ['ip', ...args],
+			stdout: 'pipe',
+			stderr: 'pipe',
+		})
+		const exitCode = await proc.exited
+		if (exitCode !== 0) {
+			const stderr = await new Response(proc.stderr).text()
+			throw new Error(`ip ${args.join(' ')} failed (exit ${exitCode}): ${stderr}`)
+		}
+	}
+}

package/src/api/services/VmmManagerService.ts

@@ -0,0 +1,205 @@
+import {Publish} from '@mindignited/continuum-client'
+import type {VmmConfig} from '../domain/VmmConfig.js'
+import {VmmType} from '../domain/VmmType.js'
+import {createClient} from '@/internal/api/firecracker/generated/client/index.js'
+import {
+	putGuestBootSource,
+	putGuestDriveById,
+	putGuestNetworkInterfaceById,
+	putMachineConfiguration,
+	putMmdsConfig,
+	putMmds,
+	createSyncAction,
+} from '@/internal/api/firecracker/generated/sdk.gen.js'
+
+const FIRECRACKER_BIN = 'firecracker'
+
+@Publish('kinotic.vmm-node-manager')
+export class VmmManagerService {
+
+	public constructor() {
+		console.log('VmmManagerService constructed')
+	}
+
+	public async launchVmm(vmmConfig: VmmConfig): Promise<void> {
+		// Validate VMM type
+		if (vmmConfig.vmmType !== VmmType.FIRECRACKER) {
+			throw new Error(`Unsupported VMM type: ${vmmConfig.vmmType}. Only ${VmmType.FIRECRACKER} is supported.`);
+		}
+
+		// Validate required fields
+		if (vmmConfig.id === undefined || vmmConfig.id === null || vmmConfig.id === '') {
+			throw new Error('id is required');
+		}
+		if (!vmmConfig.kernelImagePath) {
+			throw new Error('kernelImagePath is required');
+		}
+		if (!vmmConfig.drives || vmmConfig.drives.length === 0) {
+			throw new Error('At least one drive is required');
+		}
+		if (!vmmConfig.networkInterfaces || vmmConfig.networkInterfaces.length === 0) {
+			throw new Error('At least one network interface is required');
+		}
+		if (!vmmConfig.machineConfig) {
+			throw new Error('machineConfig is required');
+		}
+
+		// Validate file paths exist
+		const kernelFile = Bun.file(vmmConfig.kernelImagePath);
+		if (!(await kernelFile.exists())) {
+			throw new Error(`Kernel image not found at: ${vmmConfig.kernelImagePath}`);
+		}
+
+		for (const drive of vmmConfig.drives) {
+			const driveFile = Bun.file(drive.pathOnHost);
+			if (!(await driveFile.exists())) {
+				throw new Error(`Drive file not found at: ${drive.pathOnHost}`);
+			}
+		}
+
+		const socketPath = this.socketPathFor(vmmConfig.id);
+
+		// Spawn Firecracker as a detached background process; it stays running after vmm-node-manager exits.
+		Bun.spawn({
+			cmd: [FIRECRACKER_BIN],
+			env: { ...process.env, API_SOCKET: socketPath },
+			detached: true,
+			stdio: ['ignore', 'ignore', 'ignore'],
+		});
+
+		// Wait for the API socket to appear before configuring the VM.
+		const socketDeadline = Date.now() + 5000;
+		while (!(await Bun.file(socketPath).exists())) {
+			if (Date.now() > socketDeadline) {
+				throw new Error(`Firecracker socket did not appear at ${socketPath} within 5s`);
+			}
+			await new Promise((r) => setTimeout(r, 50));
+		}
+
+		// Use a dedicated client for this VM's socket to avoid contention with concurrent launch/stop.
+		const fc = createClient({ baseUrl: `http://unix:${socketPath}:` });
+
+		try {
+			// 1. Configure boot source
+			await putGuestBootSource({
+				client: fc,
+				body: {
+					kernel_image_path: vmmConfig.kernelImagePath,
+					boot_args: vmmConfig.bootArgs,
+				},
+			});
+
+			// 2. Configure drives
+			for (const drive of vmmConfig.drives) {
+				await putGuestDriveById({
+					client: fc,
+					path: {
+						drive_id: drive.driveId,
+					},
+					body: {
+						drive_id: drive.driveId,
+						path_on_host: drive.pathOnHost,
+						is_root_device: drive.isRootDevice,
+						is_read_only: drive.isReadOnly,
+					},
+				});
+			}
+
+			// 3. Configure network interfaces
+			for (const iface of vmmConfig.networkInterfaces) {
+				await putGuestNetworkInterfaceById({
+					client: fc,
+					path: {
+						iface_id: iface.ifaceId,
+					},
+					body: {
+						iface_id: iface.ifaceId,
+						guest_mac: iface.guestMac,
+						host_dev_name: iface.hostDevName,
+					},
+				});
+			}
+
+			// 4. Configure machine config
+			await putMachineConfiguration({
+				client: fc,
+				body: {
+					vcpu_count: vmmConfig.machineConfig.vcpuCount,
+					mem_size_mib: vmmConfig.machineConfig.memSizeMib,
+				},
+			});
+
+			// 5. Configure MMDS if provided
+			if (vmmConfig.mmdsConfig) {
+				await putMmdsConfig({
+					client: fc,
+					body: {
+						version: 'V2', // Always use V2, V1 is deprecated
+						network_interfaces: vmmConfig.mmdsConfig.networkInterfaces,
+						ipv4_address: vmmConfig.mmdsConfig.ipv4Address,
+						imds_compat: vmmConfig.mmdsConfig.imdsCompat,
+					},
+				});
+
+				// Set MMDS data
+				await putMmds({
+					client: fc,
+					body: vmmConfig.mmdsConfig.data,
+				});
+			}
+
+			// 6. Start VM
+			await createSyncAction({
+				client: fc,
+				body: {
+					action_type: 'InstanceStart',
+				},
+			});
+		} catch (error) {
+			// Provide more context about which step failed
+			let stepContext = '';
+			if (error instanceof Error) {
+				const message = error.message.toLowerCase();
+				if (message.includes('boot') || message.includes('kernel')) {
+					stepContext = ' (boot source configuration)';
+				} else if (message.includes('drive')) {
+					stepContext = ' (drive configuration)';
+				} else if (message.includes('network') || message.includes('interface')) {
+					stepContext = ' (network interface configuration)';
+				} else if (message.includes('machine') || message.includes('config')) {
+					stepContext = ' (machine configuration)';
+				} else if (message.includes('mmds')) {
+					stepContext = ' (MMDS configuration)';
+				} else if (message.includes('action') || message.includes('start')) {
+					stepContext = ' (VM start)';
+				}
+			}
+
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			throw new Error(`Failed to launch Firecracker VM${stepContext}: ${errorMessage}`);
+		}
+	}
+
+	/**
+	 * Sends SendCtrlAltDel to the VM to request a graceful shutdown.
+	 * The socket path is derived from the id: /tmp/firecracker-{id}.socket.
+	 */
+	public async stopVmm(id: string | number): Promise<void> {
+		const sp = this.socketPathFor(id);
+		if (!(await Bun.file(sp).exists())) {
+			throw new Error(`Firecracker socket not found at ${sp}. Is the VM running?`);
+		}
+		const fc = createClient({ baseUrl: `http://unix:${sp}:` });
+		await createSyncAction({
+			client: fc,
+			body: {
+				action_type: 'SendCtrlAltDel',
+			},
+		});
+	}
+
+	private socketPathFor(id: string | number): string {
+		return `/tmp/firecracker-${id}.socket`
+	}
+
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+import 'reflect-metadata'
+import {BootstrapService} from './internal/api/services/BootstrapService.js'
+
+export {vmmNodeManagerConfig, type VmmNodeManagerConfig} from './api/config/VmmNodeManagerConfig.js'
+export type {KinoticMicrovmLaunchResult} from './api/domain/KinoticMicrovmLaunchResult.js'
+export {KinoticMicrovmLauncherService} from './api/services/KinoticMicrovmLauncherService.js'
+
+const bootstrapService = new BootstrapService()
+
+console.log('Starting VMM Node Manager bootstrap process...')
+
+await bootstrapService.bootstrap()
+
+console.log('VMM Node Manager bootstrap process completed.')