use super::DownloadStatus;

/// One coordinator-visible BitTorrent action that the dispatcher can execute in a loop.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum BtRuntimeCoordinatorAction {
    /// Advance share/seeding timers using the supplied wall clock.
    AdvanceClock,
    /// Refresh peers and tracker metadata from the primary tracker.
    TrackerAnnounce,
    /// Query DHT for peers against the current info hash.
    DhtGetPeers,
    /// Expand the DHT node frontier when peers are still unavailable.
    DhtFindNode,
    /// Announce the local presence back into DHT once a token is cached.
    DhtAnnouncePeer,
    /// Perform one peer-wire request/response exchange against the best current peer.
    PeerWireExchange,
}

/// Outcome classification for one coordinator-visible BitTorrent action.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum BtRuntimeCoordinatorStepStatus {
    /// The dispatcher executed the action successfully.
    Executed,
    /// The dispatcher intentionally skipped the action because a prerequisite was absent.
    Skipped,
    /// The dispatcher attempted the action and it failed.
    Failed,
}

/// Detailed result for one BitTorrent coordinator action.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct BtRuntimeCoordinatorStepReport {
    /// Action that was evaluated.
    pub action: BtRuntimeCoordinatorAction,
    /// Final status for the action in this loop iteration.
    pub status: BtRuntimeCoordinatorStepStatus,
    /// Optional human-readable detail for skips and failures.
    pub detail: Option<String>,
}

/// Snapshot of dispatcher-visible BitTorrent runtime state for loop orchestration.
#[derive(Clone, Debug, Eq, PartialEq)]
#[expect(
    clippy::struct_excessive_bools,
    reason = "aria2-compatible BT status snapshots intentionally surface several independent boolean facets"
)]
pub struct BtRuntimeCoordinatorSnapshot {
    /// Download GID in aria2 hex form.
    pub gid: String,
    /// Current aria2/core download state.
    pub status: DownloadStatus,
    /// Whether the BT runtime currently considers the local side seeding.
    pub seeding: bool,
    /// Aggregate number of bytes marked complete in the request group.
    pub completed_length: u64,
    /// Aggregate total length known to the runtime.
    pub total_length: u64,
    /// Live connection count currently exposed through aria2 status surfaces.
    pub connections: u32,
    /// Number of configured tracker entries in BT runtime state.
    pub tracker_count: usize,
    /// Total DHT node entries currently cached, including malformed ones.
    pub dht_node_count: usize,
    /// Number of DHT node entries that can actually be converted into transport targets.
    pub addressable_dht_node_count: usize,
    /// Total peer rows currently cached in BT runtime state.
    pub peer_count: usize,
    /// Number of peers that are currently usable for peer-wire transport.
    pub connectable_peer_count: usize,
    /// Whether a DHT announce token is already cached from a prior get_peers response.
    pub has_dht_token: bool,
    /// Whether the BT runtime is still metadata-only.
    pub metadata_only: bool,
    /// Whether this looks like a magnet-backed partial path that still lacks metadata exchange support.
    pub metadata_exchange_pending: bool,
    /// Number of locally requestable pieces remaining under the current piece state.
    pub requestable_piece_count: usize,
    /// Dispatcher-level action suggestions derived from the current snapshot.
    pub recommended_actions: Vec<BtRuntimeCoordinatorAction>,
}

/// Full report for one dispatcher-driven BitTorrent loop iteration.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct BtRuntimeCoordinatorReport {
    /// Snapshot captured before any coordinator actions were attempted.
    pub initial_snapshot: BtRuntimeCoordinatorSnapshot,
    /// Snapshot captured after the last attempted coordinator action.
    pub final_snapshot: BtRuntimeCoordinatorSnapshot,
    /// Ordered per-action results for this iteration.
    pub steps: Vec<BtRuntimeCoordinatorStepReport>,
}