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;
  /** Directory for VM sockets and ephemeral per-VM files. Defaults to /dev/shm/.smartvm/runtime on Linux when available. */
  runtimeDir?: string;
  /** Copy writable drives into the VM runtime directory before boot and delete them on cleanup. Defaults to true. */
  ephemeralWritableDrives?: boolean;
  /** 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;
  /** VM egress firewall configuration. */
  firewall?: IFirewallConfig;
  /** Host-side WireGuard egress routing configuration for VM traffic. */
  wireguard?: TWireGuardConfig;
  /** Directory for cached base images. Defaults to /tmp/.smartvm/base-images. */
  baseImageCacheDir?: string;
  /** Maximum number of cached base image bundles. Defaults to 2. */
  maxStoredBaseImages?: number;
  /** Hosted/project-owned base image manifest URL. */
  baseImageManifestUrl?: string;
  /** Local hosted/project-owned base image manifest path for development and tests. */
  baseImageManifestPath?: string;
}

/**
 * Predefined base image sources for integration testing and quick starts.
 */
export type TBaseImagePreset = 'latest' | 'lts' | 'hosted';

/**
 * Root filesystem image type used by a base image bundle.
 */
export type TBaseImageRootfsType = 'ext4' | 'squashfs';

/**
 * Options for the BaseImageManager.
 */
export interface IBaseImageManagerOptions {
  /** Architecture to resolve. Defaults to x86_64. */
  arch?: TFirecrackerArch;
  /** Directory for cached base image bundles. Defaults to /tmp/.smartvm/base-images. */
  cacheDir?: string;
  /** Maximum number of cached base image bundles. Defaults to 2. */
  maxStoredBaseImages?: number;
  /** Hosted base image manifest URL for project-owned bundles. */
  hostedManifestUrl?: string;
  /** Local hosted base image manifest path for development and tests. */
  hostedManifestPath?: string;
}

/**
 * Options when resolving or downloading a base image bundle.
 */
export interface IEnsureBaseImageOptions {
  /** Preset to use. Defaults to latest. */
  preset?: TBaseImagePreset;
  /** Architecture to resolve. Defaults to manager architecture. */
  arch?: TFirecrackerArch;
  /** Redownload even if the bundle already exists locally. */
  forceDownload?: boolean;
  /** Hosted base image manifest URL. Overrides preset resolution. */
  manifestUrl?: string;
  /** Local hosted base image manifest path. Overrides preset resolution. */
  manifestPath?: string;
}

/**
 * Single hosted base image artifact in a manifest.
 */
export interface IBaseImageArtifactManifest {
  /** Public URL for hosted artifacts. */
  url?: string;
  /** Local path for development/tests. */
  path?: string;
  /** Optional plain output filename. Defaults to basename of url/path. */
  fileName?: string;
  /** Expected SHA256 for verification. Required when url is used. */
  sha256?: string;
  /** Expected file size in bytes. */
  sizeBytes?: number;
}

/**
 * Hosted/project-owned base image manifest format.
 */
export interface IBaseImageHostedManifest {
  schemaVersion: 1;
  bundleId: string;
  name?: string;
  arch: TFirecrackerArch;
  firecrackerVersion: string;
  rootfsType: TBaseImageRootfsType;
  rootfsIsReadOnly?: boolean;
  bootArgs?: string;
  kernel: IBaseImageArtifactManifest;
  rootfs: IBaseImageArtifactManifest;
}

/**
 * Cached base image bundle metadata.
 */
export interface IBaseImageBundle {
  preset: TBaseImagePreset;
  arch: TFirecrackerArch;
  ciVersion: string;
  firecrackerVersion: string;
  bundleId: string;
  bundleDir: string;
  kernelImagePath: string;
  rootfsPath: string;
  rootfsType: TBaseImageRootfsType;
  rootfsIsReadOnly: boolean;
  bootArgs: string;
  source: {
    type?: 'firecracker-ci' | 'hosted-manifest';
    bucketUrl?: string;
    kernelKey?: string;
    rootfsKey?: string;
    manifestUrl?: string;
    manifestPath?: string;
    kernelUrl?: string;
    rootfsUrl?: string;
    kernelSourcePath?: string;
    rootfsSourcePath?: string;
  };
  checksums?: {
    kernelSha256?: string;
    rootfsSha256?: string;
  };
  sizes?: {
    kernelBytes?: number;
    rootfsBytes?: number;
  };
  createdAt: string;
  lastAccessedAt: string;
}

/**
 * Runtime behavior for a MicroVM instance.
 */
export interface IMicroVMRuntimeOptions {
  /** Directory for VM sockets and ephemeral per-VM files. */
  runtimeDir?: string;
  /** Copy writable drives into runtimeDir before boot and delete them on cleanup. Defaults to true. */
  ephemeralWritableDrives?: boolean;
}

/** Firewall action for VM egress traffic. */
export type TFirewallAction = 'allow' | 'deny';

/** Firewall protocol selector for VM egress traffic. */
export type TFirewallProtocol = 'all' | 'tcp' | 'udp' | 'icmp';

/** One ordered VM egress firewall rule. */
export interface IFirewallRule {
  /** Rule action. */
  action: TFirewallAction;
  /** Destination IPv4 address or CIDR. Omit to match all destinations. */
  to?: string;
  /** Protocol to match. Defaults to all. */
  protocol?: TFirewallProtocol;
  /** Destination port or ports for tcp/udp rules. */
  ports?: number | number[];
  /** Optional human-readable rule label. */
  comment?: string;
}

/** VM egress firewall policy. */
export interface IFirewallEgressConfig {
  /** Final action when no rule matches. Defaults to allow. */
  defaultAction?: TFirewallAction;
  /** Ordered rules; first match wins. */
  rules?: IFirewallRule[];
}

/** Firewall configuration. */
export interface IFirewallConfig {
  /** Egress firewall for traffic leaving the VM subnet. */
  egress?: IFirewallEgressConfig;
}

/** Common WireGuard routing options. */
export interface IWireGuardBaseConfig {
  /** Route all VM subnet traffic through this WireGuard interface. Defaults to true. */
  routeAllVmTraffic?: boolean;
  /** Drop VM traffic that would leave through a non-WireGuard interface. Defaults to true. */
  failClosed?: boolean;
  /** Linux routing table number for VM WireGuard egress. Defaults to 51820. */
  routeTable?: number;
}

/** Managed WireGuard interface created and removed by smartvm. */
export interface IWireGuardManagedConfig extends IWireGuardBaseConfig {
  /** wg-quick-style WireGuard config text. Hook fields are rejected. */
  config: string;
  /** Interface name to create. Defaults to svwg0. */
  interfaceName?: string;
}

/** Existing WireGuard interface owned outside smartvm. */
export interface IWireGuardExistingInterfaceConfig extends IWireGuardBaseConfig {
  /** Existing WireGuard interface to route VM traffic through. */
  existingInterface: string;
}

/** WireGuard egress configuration. */
export type TWireGuardConfig = IWireGuardManagedConfig | IWireGuardExistingInterfaceConfig;

/**
 * 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;
  /** Whether this drive should be staged into per-VM ephemeral storage. Defaults to true for writable drives. */
  ephemeral?: boolean;
}

/**
 * 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 level. */
  showLevel?: boolean;
  /** Whether to show log origin (file, line). */
  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;
  /** VM egress firewall configuration. */
  firewall?: IFirewallConfig;
  /** Host-side WireGuard egress routing configuration for VM traffic. */
  wireguard?: TWireGuardConfig;
}

/**
 * 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;
}