smartvm/ts/interfaces/config.ts

import type { TFirecrackerArch, TCacheType, TSnapshotType, TLogLevel } from './common.js';

/**
 * Top-level options for the SmartVM orchestrator.
 */
export interface ISmartVMOptions {
  /** Directory for storing binaries, kernels, rootfs images, and sockets. Defaults to /tmp/.smartvm */
  dataDir?: string;
  /** Firecracker version to use. Defaults to latest. */
  firecrackerVersion?: string;
  /** Target architecture. Defaults to x86_64. */
  arch?: TFirecrackerArch;
  /** Custom path to firecracker binary (overrides version-based lookup). */
  firecrackerBinaryPath?: string;
  /** Network bridge name. Defaults to 'svbr0'. */
  bridgeName?: string;
  /** Network subnet in CIDR notation. Defaults to '172.30.0.0/24'. */
  subnet?: string;
}

/**
 * Firecracker boot source configuration.
 */
export interface IBootSource {
  /** Path to the kernel image on the host. */
  kernelImagePath: string;
  /** Kernel boot arguments. */
  bootArgs?: string;
  /** Path to initrd image (optional). */
  initrdPath?: string;
}

/**
 * Machine hardware configuration.
 */
export interface IMachineConfig {
  /** Number of vCPUs (1-32). */
  vcpuCount: number;
  /** Memory size in MiB. */
  memSizeMib: number;
  /** Enable SMT (simultaneous multi-threading). Defaults to false. */
  smt?: boolean;
  /** Enable CPU template for security (C3, T2, T2S, T2CL, T2A, V1N1, None). */
  cpuTemplate?: string;
  /** Whether to track dirty pages for incremental snapshots. */
  trackDirtyPages?: boolean;
}

/**
 * Rate limiter configuration for drives and network interfaces.
 */
export interface IRateLimiter {
  /** Bandwidth limit. */
  bandwidth?: {
    size: number;
    oneTimeBurst?: number;
    refillTime: number;
  };
  /** Operations per second limit. */
  ops?: {
    size: number;
    oneTimeBurst?: number;
    refillTime: number;
  };
}

/**
 * Block device (drive) configuration.
 */
export interface IDriveConfig {
  /** Unique drive identifier. */
  driveId: string;
  /** Path to the disk image on the host. */
  pathOnHost: string;
  /** Whether this is the root device. */
  isRootDevice: boolean;
  /** Whether the drive is read-only. */
  isReadOnly?: boolean;
  /** Partition UUID (optional). */
  partUuid?: string;
  /** Cache type (Unsafe or Writeback). */
  cacheType?: TCacheType;
  /** Rate limiter for the drive. */
  rateLimiter?: IRateLimiter;
  /** Path to a file that backs the device for I/O. */
  ioEngine?: string;
}

/**
 * Network interface configuration.
 */
export interface INetworkInterfaceConfig {
  /** Unique interface identifier (e.g., 'eth0'). */
  ifaceId: string;
  /** TAP device name on the host. Automatically set by NetworkManager if not provided. */
  hostDevName?: string;
  /** Guest MAC address. Automatically generated if not provided. */
  guestMac?: string;
  /** Rate limiter for RX traffic. */
  rxRateLimiter?: IRateLimiter;
  /** Rate limiter for TX traffic. */
  txRateLimiter?: IRateLimiter;
}

/**
 * Vsock device configuration.
 */
export interface IVsockConfig {
  /** Guest CID (Context Identifier). Must be >= 3. */
  guestCid: number;
  /** Path to the Unix domain socket on the host. */
  udsPath: string;
}

/**
 * Balloon device configuration for dynamic memory management.
 */
export interface IBalloonConfig {
  /** Target balloon size in MiB. */
  amountMib: number;
  /** Whether to deflate on OOM. */
  deflateOnOom: boolean;
  /** Polling interval for balloon stats in seconds. */
  statsPollingIntervalS?: number;
}

/**
 * MMDS (Microvm Metadata Service) configuration.
 */
export interface IMmdsConfig {
  /** MMDS version (V1 or V2). */
  version?: 'V1' | 'V2';
  /** Network interfaces that MMDS traffic is allowed on. */
  networkInterfaces: string[];
}

/**
 * Logger configuration for Firecracker.
 */
export interface ILoggerConfig {
  /** Path to the log file. */
  logPath: string;
  /** Log level. */
  level?: TLogLevel;
  /** Whether to show log origin (file, line). */
  showLevel?: boolean;
  /** Whether to show log level. */
  showLogOrigin?: boolean;
}

/**
 * Metrics configuration for Firecracker.
 */
export interface IMetricsConfig {
  /** Path to the metrics file (FIFO). */
  metricsPath: string;
}

/**
 * Snapshot creation parameters.
 */
export interface ISnapshotCreateParams {
  /** Path to save the snapshot file. */
  snapshotPath: string;
  /** Path to save the memory file. */
  memFilePath: string;
  /** Snapshot type (Full or Diff). */
  snapshotType?: TSnapshotType;
}

/**
 * Snapshot loading parameters.
 */
export interface ISnapshotLoadParams {
  /** Path to the snapshot file. */
  snapshotPath: string;
  /** Path to the memory file. */
  memFilePath: string;
  /** Whether to enable diff snapshots after loading. */
  enableDiffSnapshots?: boolean;
  /** Whether to resume the VM after loading. */
  resumeVm?: boolean;
}

/**
 * Complete MicroVM configuration combining all sub-configs.
 */
export interface IMicroVMConfig {
  /** Unique VM identifier. Auto-generated if not provided. */
  id?: string;
  /** Boot source configuration (required). */
  bootSource: IBootSource;
  /** Machine hardware configuration (required). */
  machineConfig: IMachineConfig;
  /** Block devices. */
  drives?: IDriveConfig[];
  /** Network interfaces. */
  networkInterfaces?: INetworkInterfaceConfig[];
  /** Vsock device. */
  vsock?: IVsockConfig;
  /** Balloon device. */
  balloon?: IBalloonConfig;
  /** MMDS configuration. */
  mmds?: IMmdsConfig;
  /** Logger configuration. */
  logger?: ILoggerConfig;
  /** Metrics configuration. */
  metrics?: IMetricsConfig;
}

/**
 * Options for the NetworkManager.
 */
export interface INetworkManagerOptions {
  /** Bridge device name. Defaults to 'svbr0'. */
  bridgeName?: string;
  /** Subnet in CIDR notation. Defaults to '172.30.0.0/24'. */
  subnet?: string;
}

/**
 * Represents a TAP device created by the NetworkManager.
 */
export interface ITapDevice {
  /** TAP device name on the host. */
  tapName: string;
  /** IP address assigned to the guest. */
  guestIp: string;
  /** Gateway IP (bridge IP). */
  gatewayIp: string;
  /** Subnet mask. */
  subnetMask: string;
  /** MAC address for the guest. */
  mac: string;
}