<?php

namespace App\Services\Proxmox;

use App\Models\Host;

/**
 * Proxmox VE REST client, addressed per host over its wg_ip with a token.
 * A v1.0 uses it read-only (capacity + reachability); the automation token is
 * bootstrapped over SSH (pveum). Subsystem B extends it with VM lifecycle
 * methods (clone, cloud-init, guestExec …).
 */
interface ProxmoxClient
{
    /** Configure this client for a host (base URL from wg_ip, token from api_token_ref). */
    public function forHost(Host $host): static;

    /** @return array<int, array<string, mixed>> */
    public function listNodes(): array;

    /** @return array<string, mixed> */
    public function nodeStatus(string $node): array;

    /** @return array<int, array<string, mixed>> */
    public function nodeStorage(string $node): array;

    // --- VM lifecycle (Subsystem B) ---

    public function nextVmid(): int;

    /** Clone a template to a new VM; returns the task UPID. */
    public function cloneVm(string $node, int $templateVmid, int $newVmid, string $name): string;

    /** @param array<string, mixed> $params */
    public function setCloudInit(string $node, int $vmid, array $params): void;

    public function resizeDisk(string $node, int $vmid, string $disk, string $size): void;

    /** Start a VM; returns the task UPID. */
    public function startVm(string $node, int $vmid): string;

    /** @return array<string, mixed> ['status' => 'running'|'stopped', …] */
    public function vmStatus(string $node, int $vmid): array;

    /** Whether a VM with this id already exists on the node. */
    public function vmExists(string $node, int $vmid): bool;

    public function deleteVm(string $node, int $vmid): void;

    public function guestAgentPing(string $node, int $vmid): bool;

    /** @return array{exitcode: int, out-data: string} */
    public function guestExec(string $node, int $vmid, string $command): array;

    /** @return array{status: string, exitstatus?: string} */
    public function taskStatus(string $node, string $upid): array;

    /** @param array<int, array<string, mixed>> $rules */
    public function applyFirewall(string $node, int $vmid, array $rules): void;

    /**
     * Limit (or release) the VM's network interface.
     *
     * $mbytesPerSecond === null removes the limit. Proxmox expresses `rate` in
     * MB/s on the NIC definition, so the caller converts — this signature keeps
     * the unit visible instead of hiding a magic number.
     */
    public function setNetworkRate(string $node, int $vmid, ?float $mbytesPerSecond): void;

    /** Create a scheduled vzdump backup job for the VM; returns the job id. */
    public function createBackupJob(string $node, int $vmid, string $schedule): string;
}