<?php

namespace App\Services\Wireguard;

/**
 * The CluPilot VM's WireGuard hub. Onboarding allocates a management IP and
 * registers the new host as a peer so its Proxmox API is reachable over the tunnel.
 */
interface WireguardHub
{
    /** Allocate a free management IP from the hub subnet. */
    /**
     * Die nächste freie Adresse ab `$from` (Zähler im Subnetz, nicht Oktett).
     *
     * Personen und Hosts kommen aus demselben Subnetz, sollen aber nicht
     * ineinander wachsen: fortlaufend vergeben landete der erste Host zwischen
     * zwei Notebooks, und wer eine Adresse in einem Protokoll sieht, konnte
     * nicht sagen, ob dahinter ein Mensch oder eine Maschine steht.
     */
    public function allocateIp(int $from = 1): string;

    public function addPeer(string $publicKey, string $ip): void;

    public function removePeer(string $publicKey): void;

    /** Public endpoint (host:port) peers dial to reach the hub. */
    public function endpoint(): string;

    /** The hub's WireGuard public key. */
    public function publicKey(): string;

    /**
     * What the interface currently reports, keyed by public key. Live state —
     * traffic counters and handshakes only exist here, never in the database
     * until SyncVpnPeers copies them over.
     *
     * @return array<string, PeerSnapshot>
     */
    public function peers(): array;
}