Struct SessionHandle 

pub struct SessionHandle { /* private fields */ }

Cloneable handle for interacting with a running session.

Implementations

impl SessionHandle

pub async fn start(settings: Settings) -> Result<Self>

Start a new session with the given settings and no plugins.

pub async fn start_with_backend( settings: Settings, backend: Arc<dyn DiskIoBackend>, ) -> Result<Self>

Start a new session with a custom disk I/O backend and no plugins.

pub async fn start_with_plugins( settings: Settings, plugins: Arc<Vec<Box<dyn ExtensionPlugin>>>, ) -> Result<Self>

Start a new session with the given settings and extension plugins.

pub async fn start_with_plugins_and_backend( settings: Settings, plugins: Arc<Vec<Box<dyn ExtensionPlugin>>>, backend: Arc<dyn DiskIoBackend>, ) -> Result<Self>

Start a new session with the given settings, extension plugins, and a custom disk I/O backend.

pub async fn start_with_transport( settings: Settings, factory: Arc<NetworkFactory>, ) -> Result<Self>

Start a new session with the given settings and a custom transport factory.

Uses default plugins (none) and default disk backend.

pub async fn start_full( settings: Settings, plugins: Arc<Vec<Box<dyn ExtensionPlugin>>>, backend: Arc<dyn DiskIoBackend>, factory: Arc<NetworkFactory>, ) -> Result<Self>

Start a new session with all customizable parameters.

This is the most general constructor — all other start_* variants delegate to this method. The factory parameter controls how TCP listeners and connections are created: use crate::transport::NetworkFactory::tokio() for real networking or a custom factory for simulation.

pub async fn add_torrent( &self, meta: TorrentMeta, storage: Option<Arc<dyn TorrentStorage>>, ) -> Result<Id20>

Add a torrent from parsed .torrent metadata (v1, v2, or hybrid).

pub async fn add_torrent_with_dir( &self, meta: TorrentMeta, storage: Option<Arc<dyn TorrentStorage>>, download_dir: Option<PathBuf>, ) -> Result<Id20>

Add a torrent with an optional per-torrent download directory override.

pub async fn add_magnet(&self, magnet: Magnet) -> Result<Id20>

Add a torrent from a magnet link (metadata fetched via BEP 9).

pub async fn add_magnet_with_dir( &self, magnet: Magnet, download_dir: Option<PathBuf>, ) -> Result<Id20>

Add a magnet link with an optional per-torrent download directory override.

pub async fn remove_torrent(&self, info_hash: Id20) -> Result<()>

Remove a torrent from the session.

pub async fn pause_torrent(&self, info_hash: Id20) -> Result<()>

Pause a torrent.

pub async fn resume_torrent(&self, info_hash: Id20) -> Result<()>

Resume a paused torrent.

pub async fn torrent_stats(&self, info_hash: Id20) -> Result<TorrentStats>

Get statistics for a specific torrent.

pub async fn torrent_info(&self, info_hash: Id20) -> Result<TorrentInfo>

Get metadata info for a specific torrent.

pub async fn list_torrents(&self) -> Result<Vec<Id20>>

List all active torrent info hashes.

pub async fn session_stats(&self) -> Result<SessionStats>

Get aggregate session statistics.

pub fn subscribe(&self) -> Receiver<Alert>

Subscribe to all alerts passing the session-level mask.

pub fn subscribe_filtered(&self, filter: AlertCategory) -> AlertStream

Subscribe with per-subscriber category filtering.

pub async fn post_session_stats(&self) -> Result<()>

Trigger an immediate session stats snapshot and alert.

pub fn counters(&self) -> &Arc<SessionCounters>

Access the shared atomic counters (read-only handle).

pub fn set_alert_mask(&self, mask: AlertCategory)

Atomically update the session-level alert mask.

pub fn alert_mask(&self) -> AlertCategory

Read the current session-level alert mask.

pub async fn add_peers( &self, info_hash: Id20, peers: Vec<SocketAddr>, source: PeerSource, ) -> Result<()>

Add peers to a specific torrent by info hash.

pub async fn shutdown(&self) -> Result<()>

Gracefully shut down the session and all torrents.

pub async fn save_torrent_resume_data( &self, info_hash: Id20, ) -> Result<FastResumeData>

Save resume data for a specific torrent.

pub async fn save_session_state(&self) -> Result<SessionState>

Save full session state (all torrent resume data + DHT node cache).

pub async fn load_resume_state(&self) -> Result<ResumeLoadResult>

Load and restore torrents from per-torrent resume files on disk.

Scans the resume directory for .resume files, deserializes each one, reconstructs the torrent metadata, and re-adds it to the session. For resolved torrents (with stored info dict), the piece bitmap is restored. Unresolved magnets are re-added as magnet links.

Errors

Returns crate::Error::Shutdown if the session has been shut down.

pub async fn save_resume_state(&self) -> Result<usize>

Save per-torrent resume files for all dirty torrents.

Iterates every torrent in the session, checks the need_save_resume dirty flag, serializes resume data to disk, and clears the flag. Returns the number of files written.

Errors

Returns [Error::Shutdown] if the session actor has stopped.

pub async fn queue_position(&self, info_hash: Id20) -> Result<i32>

Get the queue position of a torrent. Returns -1 if not auto-managed.

pub async fn set_queue_position(&self, info_hash: Id20, pos: i32) -> Result<()>

Set the absolute queue position of a torrent. Shifts other torrents.

pub async fn queue_position_up(&self, info_hash: Id20) -> Result<()>

Move a torrent one position up (lower number = higher priority).

pub async fn queue_position_down(&self, info_hash: Id20) -> Result<()>

Move a torrent one position down.

pub async fn queue_position_top(&self, info_hash: Id20) -> Result<()>

Move a torrent to position 0 (highest priority).

pub async fn queue_position_bottom(&self, info_hash: Id20) -> Result<()>

Move a torrent to the last position (lowest priority).

pub async fn ban_peer(&self, ip: IpAddr) -> Result<()>

Ban a peer IP session-wide. All torrents will disconnect and refuse this IP.

pub async fn unban_peer(&self, ip: IpAddr) -> Result<bool>

Remove a ban and clear strikes for an IP. Returns true if the IP was banned.

pub async fn set_ip_filter(&self, filter: IpFilter) -> Result<()>

Replace the session-wide IP filter. Connected peers that are now blocked will be refused on subsequent connection attempts.

pub async fn ip_filter(&self) -> Result<IpFilter>

Get a clone of the current IP filter.

pub async fn settings(&self) -> Result<Settings>

Get a clone of the current session settings.

pub async fn apply_settings(&self, settings: Settings) -> Result<()>

Apply new settings at runtime.

Validates the settings, updates rate limiters immediately, and stores the new settings. Sub-actor reconfiguration (disk, DHT, NAT) takes effect on next session restart.

pub async fn banned_peers(&self) -> Result<Vec<IpAddr>>

Get the list of currently banned peer IPs.

pub async fn move_torrent_storage( &self, info_hash: Id20, new_path: PathBuf, ) -> Result<()>

Move a torrent’s data files to a new download directory.

pub async fn open_file( &self, info_hash: Id20, file_index: usize, ) -> Result<FileStream>

Opens a file stream for sequential reading (AsyncRead + AsyncSeek).

The returned FileStream reads data from a specific file within a torrent, blocking on pieces that haven’t been downloaded yet.

pub async fn force_reannounce(&self, info_hash: Id20) -> Result<()>

Force all trackers for a torrent to re-announce immediately.

pub async fn tracker_list(&self, info_hash: Id20) -> Result<Vec<TrackerInfo>>

Get the list of all configured trackers with their status for a torrent.

pub async fn scrape( &self, info_hash: Id20, ) -> Result<Option<(String, ScrapeInfo)>>

Scrape trackers for seeder/leecher counts for a torrent.

pub async fn set_file_priority( &self, info_hash: Id20, index: usize, priority: FilePriority, ) -> Result<()>

Set the download priority of a specific file within a torrent.

pub async fn file_priorities( &self, info_hash: Id20, ) -> Result<Vec<FilePriority>>

Get the current per-file priorities for a torrent.

pub async fn set_download_limit( &self, info_hash: Id20, bytes_per_sec: u64, ) -> Result<()>

Set the per-torrent download rate limit in bytes/sec (0 = unlimited).

pub async fn set_upload_limit( &self, info_hash: Id20, bytes_per_sec: u64, ) -> Result<()>

Set the per-torrent upload rate limit in bytes/sec (0 = unlimited).

pub async fn download_limit(&self, info_hash: Id20) -> Result<u64>

Get the current per-torrent download rate limit in bytes/sec (0 = unlimited).

pub async fn upload_limit(&self, info_hash: Id20) -> Result<u64>

Get the current per-torrent upload rate limit in bytes/sec (0 = unlimited).

pub async fn set_sequential_download( &self, info_hash: Id20, enabled: bool, ) -> Result<()>

Enable or disable sequential (in-order) piece downloading for a torrent.

pub async fn is_sequential_download(&self, info_hash: Id20) -> Result<bool>

Query whether sequential downloading is enabled for a torrent.

pub async fn set_super_seeding( &self, info_hash: Id20, enabled: bool, ) -> Result<()>

Enable or disable BEP 16 super seeding mode for a torrent.

pub async fn is_super_seeding(&self, info_hash: Id20) -> Result<bool>

Query whether BEP 16 super seeding mode is enabled for a torrent.

pub async fn set_seed_mode(&self, info_hash: Id20, enabled: bool) -> Result<()>

Enable or disable user-requested seed-only mode for a torrent (M159).

When enabled is true, the engine stops scheduling new block requests and cancels all in-flight requests for the torrent, but continues to serve uploads to interested peers. This is distinct from “naturally seeding” (all pieces downloaded): it represents an explicit user toggle layered on top of the download state.

Toggling back to false resumes normal piece scheduling.

Errors

Returns crate::Error::TorrentNotFound if info_hash is not registered in the session, or crate::Error::Shutdown if the session actor has terminated.

pub async fn add_tracker(&self, info_hash: Id20, url: String) -> Result<()>

Add a new tracker URL to a torrent.

The URL is validated and deduplicated by the tracker manager.

pub async fn replace_trackers( &self, info_hash: Id20, urls: Vec<String>, ) -> Result<()>

Replace all tracker URLs for a torrent.

pub async fn force_recheck(&self, info_hash: Id20) -> Result<()>

Trigger a full piece verification (force recheck) for a torrent.

Clears all piece completion data, re-verifies every piece, and transitions to Seeding or Downloading depending on the result. Returns after the recheck is complete.

pub async fn rename_file( &self, info_hash: Id20, file_index: usize, new_name: String, ) -> Result<()>

Rename a file within a torrent on disk.

Changes the filename of the specified file (by index) to new_name. The file stays in the same directory; only the filename component changes. Fires a FileRenamed alert on success.

pub async fn set_max_connections( &self, info_hash: Id20, limit: usize, ) -> Result<()>

Set the per-torrent maximum number of connections (0 = use global default).

pub async fn max_connections(&self, info_hash: Id20) -> Result<usize>

Get the current per-torrent maximum connection limit (0 = use global default).

pub async fn set_max_uploads(&self, info_hash: Id20, limit: usize) -> Result<()>

Set the per-torrent maximum number of upload slots (unchoke slots).

pub async fn max_uploads(&self, info_hash: Id20) -> Result<usize>

Get the current per-torrent maximum upload slots (unchoke slots).

pub async fn get_peer_info(&self, info_hash: Id20) -> Result<Vec<PeerInfo>>

Get per-peer details for all connected peers of a torrent.

pub async fn get_download_queue( &self, info_hash: Id20, ) -> Result<Vec<PartialPieceInfo>>

Get in-flight piece download status for a torrent (the download queue).

pub async fn have_piece(&self, info_hash: Id20, index: u32) -> Result<bool>

Check whether a specific piece has been downloaded for a torrent.

pub async fn piece_availability(&self, info_hash: Id20) -> Result<Vec<u32>>

Get per-piece availability counts from connected peers for a torrent.

pub async fn file_progress(&self, info_hash: Id20) -> Result<Vec<u64>>

Get per-file bytes-downloaded progress for a torrent.

pub async fn info_hashes(&self, info_hash: Id20) -> Result<InfoHashes>

Get the torrent’s identity hashes (v1 and/or v2).

pub async fn torrent_file( &self, info_hash: Id20, ) -> Result<Option<TorrentMetaV1>>

Get the full v1 metainfo for a torrent.

Returns None for magnet links before metadata has been received.

pub async fn torrent_file_v2( &self, info_hash: Id20, ) -> Result<Option<TorrentMetaV2>>

Get the full v2 metainfo for a torrent.

Returns None if the torrent is not a v2/hybrid torrent, or for magnet links before metadata has been received.

pub async fn force_dht_announce(&self, info_hash: Id20) -> Result<()>

Force an immediate DHT announce for a torrent.

pub async fn force_lsd_announce(&self, info_hash: Id20) -> Result<()>

Force an immediate LSD (Local Service Discovery) announce for a torrent.

LSD is a session-level component — this does not go through the torrent actor.

pub async fn read_piece(&self, info_hash: Id20, index: u32) -> Result<Bytes>

Read all data for a specific piece from disk.

pub async fn flush_cache(&self, info_hash: Id20) -> Result<()>

Flush the disk write cache for a torrent.

pub async fn is_valid(&self, info_hash: Id20) -> bool

Check if a torrent exists in the session and its handle is still valid.

pub async fn clear_error(&self, info_hash: Id20) -> Result<()>

Clear the error state on a torrent, resuming it if it was paused due to error.

pub async fn file_status(&self, info_hash: Id20) -> Result<Vec<FileStatus>>

Get per-file open/mode status for a torrent.

pub async fn flags(&self, info_hash: Id20) -> Result<TorrentFlags>

Read the current torrent flags as a crate::types::TorrentFlags bitflag set.

pub async fn set_flags( &self, info_hash: Id20, flags: TorrentFlags, ) -> Result<()>

Set (enable) the specified torrent flags.

pub async fn unset_flags( &self, info_hash: Id20, flags: TorrentFlags, ) -> Result<()>

Unset (disable) the specified torrent flags.

pub async fn connect_peer( &self, info_hash: Id20, addr: SocketAddr, ) -> Result<()>

Immediately initiate a peer connection for a torrent.

pub async fn dht_put_immutable(&self, value: Vec<u8>) -> Result<Id20>

Store an immutable item in the DHT (BEP 44).

Returns the SHA-1 target hash of the stored value.

pub async fn dht_get_immutable(&self, target: Id20) -> Result<Option<Vec<u8>>>

Retrieve an immutable item from the DHT (BEP 44).

Returns Some(value) if found, None otherwise.

pub async fn dht_put_mutable( &self, keypair_bytes: [u8; 32], value: Vec<u8>, seq: i64, salt: Vec<u8>, ) -> Result<Id20>

Store a mutable item in the DHT (BEP 44).

keypair_bytes is a 32-byte Ed25519 seed. Returns the target hash.

pub async fn dht_get_mutable( &self, public_key: [u8; 32], salt: Vec<u8>, ) -> Result<Option<(Vec<u8>, i64)>>

Retrieve a mutable item from the DHT (BEP 44).

Returns Some((value, seq)) if found, None otherwise.

pub async fn list_torrent_summaries(&self) -> Result<Vec<TorrentSummary>>

List all torrents as lightweight summaries.

Fetches stats for each active torrent and converts to TorrentSummary. Torrents that fail the stats query (e.g. shutting down) are silently skipped.

pub async fn add_magnet_uri(&self, uri: &str) -> Result<InfoHashes>

Add a torrent from a magnet URI string.

Parses the URI, extracts info hashes, and adds the magnet to the session. Returns the info hashes (v1 and/or v2) for the added torrent.

pub async fn add_torrent_bytes(&self, bytes: &[u8]) -> Result<InfoHashes>

Add a torrent from raw .torrent file bytes.

Auto-detects v1, v2, or hybrid format. Returns the info hashes for the added torrent.

Trait Implementations

impl Clone for SessionHandle

fn clone(&self) -> SessionHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.