refactor: project restructuring

crates/libtortillas/src/ARCHITECTURE.md

@@ -0,0 +1,11 @@
+# libtortillas Architecture
+
+The library is organized around a small actor hierarchy:
+
+- `EngineActor` owns global listeners, the shared UDP tracker socket, and the torrent registry.
+- `TorrentActor` owns per-torrent state and coordinates peers, trackers, piece progress, and exports.
+- `PeerActor` owns one peer connection and peer-local protocol state.
+- `TrackerActor` owns one tracker announce loop and forwards discovered peers to its torrent supervisor.
+
+Module facades should export stable public types while keeping actor internals private to the crate.
+Domain types such as torrent state, storage strategy, exported snapshots, tracker model types, and tracker stats live outside actor files so actors can focus on orchestration.

crates/libtortillas/src/engine/messages.rs

@@ -5,6 +5,7 @@ use kameo::{
    mailbox,
    prelude::{ActorRef, Context, Message},
 };
+use tokio::time::{Duration, timeout};
 use tracing::{error, warn};
 
 use super::{EngineActor, EngineExport};
@@ -22,6 +23,8 @@ use crate::{
    },
 };
 
+const INCOMING_PEER_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(10);
+
 pub(crate) enum EngineMessage {
    /// Handles an incoming peer connection. The peer has been neither handshaked
    /// nor verified at this point.
@@ -49,32 +52,56 @@ impl Message<EngineMessage> for EngineActor {
    ) -> Self::Reply {
       match msg {
          EngineMessage::IncomingPeer(mut stream) => {
-            let msg = stream.recv().await.expect("Can't read from peer stream");
-            let peer_addr = stream.remote_addr().expect("Can't get remote address");
+            let msg = match timeout(INCOMING_PEER_HANDSHAKE_TIMEOUT, stream.recv()).await {
+               Ok(Ok(msg)) => msg,
+               Ok(Err(err)) => {
+                  warn!(error = %err, %stream, "Failed to read incoming peer handshake");
+                  return;
+               }
+               Err(_) => {
+                  warn!(%stream, timeout = ?INCOMING_PEER_HANDSHAKE_TIMEOUT, "Timed out reading incoming peer handshake");
+                  return;
+               }
+            };
+            let peer_addr = match stream.remote_addr() {
+               Ok(addr) => addr,
+               Err(err) => {
+                  warn!(error = %err, %stream, "Failed to get incoming peer remote address");
+                  return;
+               }
+            };
 
             if let PeerMessages::Handshake(handshake) = msg {
                let info_hash = *handshake.info_hash;
-               let peer = Peer::from_socket_addr(peer_addr);
+               let mut peer = Peer::from_socket_addr(peer_addr);
+
+               // Populate peer fields from parsed handshake
+               peer.id = Some(handshake.peer_id);
+               peer.reserved = handshake.reserved;
 
                if let Some(torrent) = self.torrents.get(&info_hash) {
-                  torrent
+                  if let Err(err) = torrent
                      .tell(TorrentMessage::IncomingPeer(peer, stream))
                      .await
-                     .expect("Failed to tell torrent about incoming peer");
+                  {
+                     warn!(error = %err, %info_hash, "Failed to route incoming peer to torrent");
+                  }
                } else {
                   error!(%stream, "Received incoming peer for unknown torrent, killing connection");
                   drop(stream);
                }
             } else {
-               error!("Received unexpected message from peer");
+               error!(message = %msg, "Received unexpected message from peer");
             }
          }
          EngineMessage::StartAll => {
             for torrent in self.torrents.iter() {
-               torrent
+               if let Err(err) = torrent
                   .tell(TorrentMessage::SetState(TorrentState::Downloading))
                   .await
-                  .expect("Failed to start torrent");
+               {
+                  warn!(error = %err, "Failed to start torrent");
+               }
             }
          }
       };
@@ -88,12 +115,10 @@ impl Message<EngineRequest> for EngineActor {
    ) -> Self::Reply {
       match msg {
          EngineRequest::Torrent(metainfo) => {
-            let info_hash = metainfo
-               .info_hash()
-               .map_err(|e| {
-                  error!(error = %e, "Failed to unwrap info hash");
-               })
-               .expect("Failed to unwrap info hash");
+            let info_hash = metainfo.info_hash().map_err(|e| {
+               error!(error = %e, "Failed to unwrap info hash");
+               EngineError::Other(e)
+            })?;
 
             if self.torrents.contains_key(&info_hash) {
                error!(

crates/libtortillas/src/engine/mod.rs

@@ -65,17 +65,19 @@ use crate::{
 ///
 /// # Example
 /// ```no_run
+/// use std::net::SocketAddr;
+///
 /// use libtortillas::prelude::*;
 /// // Create an engine with no explicit addresses
 /// let engine = Engine::builder()
 ///    // Optionally provide addresses for our sockets to listen on
-///    .tcp_addr("127.0.0.1:6881".parse().unwrap())
-///    .utp_addr("127.0.0.1:6882".parse().unwrap())
-///    .udp_addr("127.0.0.1:6883".parse().unwrap())
+///    .tcp_addr("127.0.0.1:6881".parse::<SocketAddr>().unwrap())
+///    .utp_addr("127.0.0.1:6882".parse::<SocketAddr>().unwrap())
+///    .udp_addr("127.0.0.1:6883".parse::<SocketAddr>().unwrap())
 ///    .build();
 /// ```
 /// Or with all default settings
-/// ```
+/// ```no_run
 /// use libtortillas::prelude::*;
 /// let engine = Engine::default();
 /// ```
@@ -239,14 +241,15 @@ impl Engine {
          })?
       };
 
-      let info_hash = metainfo.info_hash().expect("Failed to fetch info hash");
+      let info_hash = metainfo.info_hash()?;
 
-      let torrent_ref = match self
+      let response = self
          .actor()
          .ask(EngineRequest::Torrent(Box::new(metainfo)))
          .await
-         .expect("Failed to add torrent")
-      {
+         .map_err(|e| EngineError::Other(anyhow::anyhow!(e.to_string())))?;
+
+      let torrent_ref = match response {
          EngineResponse::Torrent(torrent_ref) => torrent_ref,
          #[allow(unreachable_patterns)]
          _ => unreachable!(),
@@ -258,24 +261,26 @@ impl Engine {
    }
    /// Starts all torrents managed by the engine.
    /// See [`Torrent::start`] for more information.
-   pub async fn start_all(&self) {
+   pub async fn start_all(&self) -> Result<(), EngineError> {
       self
          .actor()
          .tell(EngineMessage::StartAll)
          .await
-         .expect("Failed to start all torrents");
+         .map_err(|e| EngineError::Other(anyhow::anyhow!(e.to_string())))?;
+      Ok(())
    }
 
    /// Exports the current state of the engine.
    /// See [`Torrent::export`] for more information.
-   pub async fn export(&self) -> EngineExport {
-      match self
+   pub async fn export(&self) -> Result<EngineExport, EngineError> {
+      let response = self
          .actor()
          .ask(EngineRequest::Export)
          .await
-         .expect("Failed to get torrents")
-      {
-         EngineResponse::Export(export) => export,
+         .map_err(|e| EngineError::Other(anyhow::anyhow!(e.to_string())))?;
+
+      match response {
+         EngineResponse::Export(export) => Ok(export),
          _ => unreachable!(),
       }
    }

crates/libtortillas/src/lib.rs

@@ -3,16 +3,18 @@ pub mod errors;
 pub mod hashes;
 pub mod metainfo;
 pub mod peer;
+pub mod pieces;
 pub mod protocol;
 pub mod torrent;
 pub mod tracker;
 pub(crate) mod util;
 
 #[cfg(test)]
 pub(crate) mod testing {
-   use std::{net::SocketAddr, path::PathBuf, str::FromStr};
+   use std::{env, net::SocketAddr, path::PathBuf, process, str::FromStr};
 
    use rand::random_range;
+   use tokio::fs::read_to_string;
 
    use crate::{
       metainfo::{MagnetUri, MetaInfo, TorrentFile},
@@ -47,7 +49,7 @@ pub(crate) mod testing {
    }
 
    pub(crate) async fn read_magnet_fixture(file_name: &str) -> MetaInfo {
-      let contents = tokio::fs::read_to_string(magnet_fixture_path(file_name))
+      let contents = read_to_string(magnet_fixture_path(file_name))
          .await
          .unwrap();
       MagnetUri::parse(contents).unwrap()
@@ -70,9 +72,9 @@ pub(crate) mod testing {
    }
 
    pub(crate) fn torrent_temp_path() -> PathBuf {
-      std::env::temp_dir().join(format!(
+      env::temp_dir().join(format!(
          "tortillas-{}-{}",
-         std::process::id(),
+         process::id(),
          rand::random::<u64>()
       ))
    }