chore: initial sanitized public snapshot

2026-07-18 14:16:57 +08:00
commit 17688c3e34
321 changed files with 76859 additions and 0 deletions
@@ -0,0 +1,92 @@
+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>,
+}