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,107 @@
+use std::fmt::{Display, Formatter};
+
+use crate::piece::PieceId;
+
+/// Stable identifier for a download group.
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct DownloadId(u64);
+
+impl DownloadId {
+    /// Wraps the raw numeric identifier used internally and on the RPC surface.
+    #[must_use]
+    pub const fn new(raw: u64) -> Self {
+        Self(raw)
+    }
+
+    /// Returns the raw numeric identifier.
+    #[must_use]
+    pub const fn as_u64(self) -> u64 {
+        self.0
+    }
+
+    /// Parses the hexadecimal GID representation used by aria2 RPC clients.
+    #[must_use]
+    pub fn parse_hex(raw: &str) -> Option<Self> {
+        u64::from_str_radix(raw, 16).ok().map(Self)
+    }
+}
+
+impl Display for DownloadId {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{:016x}", self.0)
+    }
+}
+
+/// User-visible lifecycle state for a download group.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum DownloadStatus {
+    /// The group is actively transferring data.
+    Active,
+    /// The group is queued and waiting to start.
+    Waiting,
+    /// The group is paused by user or scheduler action.
+    Paused,
+    /// The group stopped because the last attempt failed.
+    Error,
+    /// The group finished successfully.
+    Complete,
+    /// The group was removed from runtime state.
+    Removed,
+}
+
+impl DownloadStatus {
+    /// Returns the lowercase RPC status token expected by aria2-compatible clients.
+    #[must_use]
+    pub const fn as_rpc_status(&self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Waiting => "waiting",
+            Self::Paused => "paused",
+            Self::Error => "error",
+            Self::Complete => "complete",
+            Self::Removed => "removed",
+        }
+    }
+}
+
+/// Captures one retry decision for a request or segment.
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct RetryAttempt {
+    /// Retry attempt ordinal, starting at one for the first retry.
+    pub attempt: u32,
+    /// Byte offset at which the retry resumes.
+    pub offset: u64,
+    /// Optional retry length when the retry only covers one segment.
+    pub length: Option<u64>,
+    /// Human-readable error that triggered the retry.
+    pub error: Option<String>,
+    /// Whether the error is considered recoverable by the scheduler.
+    pub recoverable: bool,
+}
+
+impl RetryAttempt {
+    /// Builds a recoverable retry record for the provided attempt number and offset.
+    #[must_use]
+    pub const fn new(attempt: u32, offset: u64) -> Self {
+        Self {
+            attempt,
+            offset,
+            length: None,
+            error: None,
+            recoverable: true,
+        }
+    }
+}
+
+/// Resume metadata recovered from persisted session state.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct ResumeState {
+    /// Whether this resume snapshot came from persisted storage.
+    pub persisted: bool,
+    /// Byte offset from which the resumed transfer should continue.
+    pub resume_offset: u64,
+    /// Verified payload length recovered from prior state, if known.
+    pub validated_length: Option<u64>,
+    /// Optional piece cursor used to continue segmented scheduling.
+    pub segment_cursor: Option<PieceId>,
+}