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,94 @@
+use crate::model::{Piece, PieceIndex};
+
+/// Represents a checksum value together with its algorithm family.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum Checksum {
+    /// SHA-1 checksum encoded as lowercase hexadecimal text.
+    Sha1(String),
+    /// SHA-256 checksum encoded as lowercase hexadecimal text.
+    Sha256(String),
+    /// MD5 checksum encoded as lowercase hexadecimal text.
+    Md5(String),
+    /// Adler-32 checksum encoded as lowercase hexadecimal text.
+    Adler32(String),
+    /// CRC-32 checksum encoded as lowercase hexadecimal text.
+    Crc32(String),
+}
+
+/// Identifies a supported hashing algorithm.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum HashAlgorithm {
+    /// SHA-1.
+    Sha1,
+    /// SHA-256.
+    Sha256,
+    /// MD5.
+    Md5,
+    /// Adler-32.
+    Adler32,
+    /// CRC-32.
+    Crc32,
+}
+
+/// Stores a finalized digest value.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct HashDigest {
+    /// Digest algorithm.
+    pub algorithm: HashAlgorithm,
+    /// Digest bytes rendered as hexadecimal text.
+    pub value_hex: String,
+}
+
+/// Reports the result of comparing actual and expected digests.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum VerificationResult {
+    /// The calculated digest matched the expected value.
+    Match,
+    /// The calculated digest differed from the expected value.
+    Mismatch {
+        /// Digest that was expected by the caller.
+        expected: HashDigest,
+        /// Digest that was actually calculated from the payload.
+        actual: HashDigest,
+    },
+    /// The requested algorithm is unsupported by the verifier.
+    Unsupported(HashAlgorithm),
+}
+
+/// Builds algorithm-specific checksum verifiers.
+pub trait HasherFactory {
+    /// Concrete verifier type produced by the factory.
+    type Hasher: ChecksumVerifier;
+
+    /// Creates a verifier for the requested algorithm when supported.
+    fn create(&self, algorithm: HashAlgorithm) -> Option<Self::Hasher>;
+}
+
+/// Incrementally computes a digest for a byte stream.
+pub trait ChecksumVerifier {
+    /// Returns the digest algorithm used by this verifier.
+    fn algorithm(&self) -> HashAlgorithm;
+    /// Feeds another payload chunk into the verifier.
+    fn update(&mut self, chunk: &[u8]);
+    /// Finalizes and returns the calculated digest.
+    fn finish(&mut self) -> HashDigest;
+}
+
+/// Verifies piece payloads against expected digests.
+pub trait PieceHashVerifier {
+    /// Verifies the supplied piece payload against an expected digest.
+    fn verify_piece(
+        &self,
+        piece: &Piece,
+        payload: &[u8],
+        expected: &HashDigest,
+    ) -> VerificationResult;
+
+    /// Verifies a piece payload when only the piece index is available.
+    fn verify_by_index(
+        &self,
+        index: PieceIndex,
+        payload: &[u8],
+        expected: &HashDigest,
+    ) -> VerificationResult;
+}