Infinization Module

Introduction

Infinization is Infinibay's custom virtualization solution that replaces the libvirt dependency for VM management. It provides TypeScript classes for building QEMU commands and managing VM process lifecycle with a type-safe, fluent API.

Package: @infinibay/infinization Location: infinization/ (separate npm package)

Why Infinization?

Traditional VDI solutions rely on libvirt as an abstraction layer over QEMU/KVM. Infinization takes a different approach:

Note: Firewall rules are managed via nftables (see NftablesService).

Architecture

graph TD
    Backend[Backend Service] --> Infinization[Infinization Module]
    Infinization --> CommandBuilder[QemuCommandBuilder]
    Infinization --> ProcessManager[Process Manager]
    Infinization --> StorageManager[Storage Manager]

    CommandBuilder --> Args[QEMU Arguments Array]
    ProcessManager --> QEMU[QEMU Process]
    StorageManager --> QemuImg[qemu-img CLI]

    QEMU --> KVM[KVM Hypervisor]

    style Infinization fill:#22c55e,stroke:#16a34a,color:#fff
    style CommandBuilder fill:#0ea5e9,stroke:#0284c7,color:#fff
    style ProcessManager fill:#0ea5e9,stroke:#0284c7,color:#fff
    style StorageManager fill:#0ea5e9,stroke:#0284c7,color:#fff

Module Structure

infinization/
├── src/
│   ├── index.ts           # Main exports
│   ├── core/              # Core QEMU command building
│   ├── cpu/               # CPU configuration
│   ├── display/           # Graphics (SPICE/VNC) configuration
│   ├── network/           # Network interface configuration
│   ├── storage/           # Disk and qemu-img operations
│   ├── system/            # System-level configuration
│   ├── unattended/        # Unattended installation support
│   ├── config/            # Default configurations
│   ├── db/                # Database integration
│   ├── sync/              # State synchronization
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Utility functions
├── tests/                 # Jest tests
└── systemd/               # Systemd service templates

Key Features

1. Fluent API for QEMU Command Building

Type-safe builder pattern for constructing QEMU command arrays:

import { QemuCommandBuilder } from '@infinibay/infinization'

const command = new QemuCommandBuilder()
  .setMachine('pc-q35-8.2')
  .setMemory(4096)  // 4GB
  .setCpu({ cores: 2, sockets: 1, threads: 2 })
  .addDrive({
    file: '/path/to/disk.qcow2',
    format: 'qcow2',
    cache: 'writeback'
  })
  .addNetwork({
    type: 'bridge',
    bridge: 'br0',
    mac: '52:54:00:12:34:56'
  })
  .addSpiceGraphics({
    port: 5900,
    password: 'secretpassword'
  })
  .build()

// Returns: ['qemu-system-x86_64', '-machine', 'pc-q35-8.2', ...]

2. Safe Process Management

Spawn-based process execution without shell injection risks:

import { ProcessManager } from '@infinibay/infinization'

const pm = new ProcessManager()

// Start VM
const process = await pm.spawn(command)

// Monitor process
process.on('exit', (code) => {
  console.log(`VM exited with code ${code}`)
})

// Graceful shutdown
await pm.shutdown(process)  // Sends ACPI shutdown

// Force kill
await pm.kill(process)  // SIGKILL

3. Storage Management

qemu-img wrapper for disk operations:

import { StorageManager } from '@infinibay/infinization'

const storage = new StorageManager()

// Create disk
await storage.create({
  path: '/path/to/disk.qcow2',
  format: 'qcow2',
  size: '100G',
  options: {
    lazy_refcounts: true,
    extended_l2: true
  }
})

// Create snapshot
await storage.snapshot({
  disk: '/path/to/disk.qcow2',
  name: 'pre-update-snapshot'
})

// Get disk info
const info = await storage.info('/path/to/disk.qcow2')

4. OS-Specific Driver Presets

Automatic optimization for different operating systems:

import { getDriverPreset } from '@infinibay/infinization'

// Windows 10/11
const windowsPreset = getDriverPreset('windows11')
// Returns: { disk: 'virtio-blk', net: 'virtio-net', ...}

// Ubuntu
const linuxPreset = getDriverPreset('ubuntu')
// Returns: { disk: 'virtio-blk', net: 'virtio-net', ...}

// Legacy OS
const legacyPreset = getDriverPreset('windows7')
// Returns: { disk: 'ide', net: 'e1000', ...}

Integration with Backend

The backend uses Infinization through the InfinizationService:

// backend/app/services/InfinizationService.ts
import { QemuCommandBuilder, ProcessManager } from '@infinibay/infinization'

class InfinizationService {
  private pm: ProcessManager

  async createVM(machine: Machine): Promise<void> {
    const command = this.buildCommand(machine)
    const process = await this.pm.spawn(command)
    await this.updateMachineStatus(machine.id, 'running', process.pid)
  }

  async stopVM(machine: Machine): Promise<void> {
    await this.pm.shutdown(machine.pid)
    await this.updateMachineStatus(machine.id, 'stopped')
  }
}

QMP Socket Support

QEMU Machine Protocol (QMP) support for runtime VM control:

import { QmpClient } from '@infinibay/infinization'

const qmp = new QmpClient('/run/qemu/vm-123.qmp')

// Query VM status
const status = await qmp.query('query-status')

// Send commands
await qmp.execute('system_powerdown')  // ACPI shutdown
await qmp.execute('system_reset')       // Hard reset
await qmp.execute('stop')               // Pause
await qmp.execute('cont')               // Resume

Configuration

Environment Variables

Default Machine Configuration

const defaultConfig = {
  machine: 'pc-q35-8.2',
  cpu: 'host',
  accelerator: 'kvm',
  memory: 2048,
  cores: 2,
  graphics: 'spice'
}

Error Handling

Infinization provides structured errors:

import { InfinizationError, QemuError, StorageError } from '@infinibay/infinization'

try {
  await storage.create({ path: '/path/to/disk.qcow2', size: '100G' })
} catch (error) {
  if (error instanceof StorageError) {
    console.error('Storage operation failed:', error.message)
    console.error('qemu-img stderr:', error.stderr)
  }
}

Comparison with VM Operations Document

For user-facing VM operations (create, start, stop), see VM Operations. This document focuses on the internal Infinization module architecture.

Development

cd infinization

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

Future Development

• QMP full support: Complete QMP protocol implementation
• Live migration: VM migration between hosts
• Device hotplug: Dynamic device attachment
• Nested virtualization: Running VMs inside VMs