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.

Errors

Returns an error if the connection or binding fails.

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.

Errors

Returns an error if the connection or binding fails.

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.

Errors

Returns an error if the connection or binding fails.

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.

Errors

Returns an error if the connection or binding fails.

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.

Errors

Returns an error if the connection or binding fails.

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.

Errors

Returns an error if the connection or binding fails.

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

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

Low-level entry point; used by the irontide facade and internal sim/test code. For user-facing adds, prefer add_torrent with AddTorrentParams, which resolves categories and download_dir via M170 semantics.

Errors

Returns an error if the torrent cannot be added or the session is shut down.

pub async fn add_torrent(&self, params: AddTorrentParams) -> Result<Id20>

Unified add entry (M170).

Resolves the download directory using the precedence documented on AddTorrentParams and the category registry, then delegates to the magnet or bytes-add path as appropriate. Returns the v1 info hash of the new torrent.

Errors

• Error::CategoryNotFound when params.category names a category that is not in the registry.
• Error::TorrentBeingRemoved when another task is currently deleting files for the same info hash (mapped to 409 Conflict by the qBt API).
• Propagates parsing errors for bad magnet URIs / .torrent bytes.
• Propagates the existing DuplicateTorrent / SessionAtCapacity error shapes unchanged.

pub async fn create_category( &self, name: String, save_path: PathBuf, ) -> Result<(), CategoryError>

Create a new qBt-compat category (M170).

Errors

Returns CategoryError on name validation failure, duplicate name, or persistence I/O error.

pub async fn edit_category( &self, name: String, save_path: PathBuf, ) -> Result<(), CategoryError>

Update the save_path on an existing category (M170).

Errors

Returns CategoryError::NotFound when the category does not exist, plus the same persistence / validation error shapes as create_category.

pub async fn remove_categories(&self, names: Vec<String>) -> Vec<String>

Remove zero or more categories (M170). Unknown names are tolerated (qBt behaviour). Returns the names that were actually removed. After removal, any torrent assigned to a removed category has its category label cleared and its resume data marked dirty.

pub async fn list_categories(&self) -> Vec<CategoryMetadata>

Snapshot the current category list (M170).

pub async fn list_tags(&self) -> Vec<String>

List every tag name currently in the registry (M171). Sorted.

pub async fn create_tags(&self, names: Vec<String>) -> Vec<Result<(), TagError>>

Create a batch of tags (M171). Returns one Result<(), TagError> per requested name so the caller can distinguish which names already existed and which were newly created. Persistence is best-effort on success; any partial persistence failure warns but does not change the per-call reply.

pub async fn delete_tags(&self, names: Vec<String>) -> Vec<String>

Delete a batch of tags (M171). Returns the subset of names that were actually present at call time (unknown names are silently skipped, matching qBt’s idempotent deleteTags).

pub async fn add_tags_to_torrents( &self, hashes: Vec<Id20>, tags: Vec<String>, ) -> Result<()>

Add the given tags to each torrent in hashes (M171). Idempotent — tags that a torrent already has are left alone. Unknown info hashes are silently skipped.

Errors

Returns Error::Shutdown if the session’s command channel has closed.

pub async fn remove_tags_from_torrents( &self, hashes: Vec<Id20>, tags: Vec<String>, ) -> Result<()>

Remove the given tags from each torrent in hashes (M171). Unknown info hashes are silently skipped.

Errors

Returns Error::Shutdown if the session’s command channel has closed.

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

Remove a torrent and delete its on-disk files (M170, deleteFiles=true).

Pauses the torrent, closes storage handles, then dispatches a spawn_blocking file-removal walk via delete_torrent_files_sync. The info hash is placed in a deletion grace set for the duration of the walk; concurrent calls to add_torrent with the same hash return Error::TorrentBeingRemoved.

Errors

Returns Error::TorrentNotFound if the info hash is not in the session. I/O failures during file removal are logged and swallowed — always returns Ok(()) when the torrent is found.

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.

Errors

Returns an error if the torrent cannot be added or the session is shut down.

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

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

Errors

Returns an error if the torrent cannot be added or the session is shut down.

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.

Errors

Returns an error if the torrent cannot be added or the session is shut down.

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

Remove a torrent from the session.

Errors

Returns an error if the torrent is not found or the session is shut down.

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

Pause a torrent.

Errors

Returns an error if the session is shut down.

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

Resume a paused torrent.

Errors

Returns an error if the session is shut down.

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

Force-resume a torrent, bypassing queue limits.

Errors

Returns an error if the session is shut down.

pub async fn set_torrent_seed_ratio( &self, info_hash: Id20, limit: Option<f64>, ) -> Result<()>

Set a per-torrent seed ratio limit override (None = use session default).

Errors

Returns an error if the session is shut down.

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

Get statistics for a specific torrent.

Errors

Returns an error if the session is shut down.

pub async fn peer_unchoke_durations( &self, info_hash: Id20, ) -> Result<Option<HashMap<SocketAddr, Duration>>>

Snapshot per-peer cumulative unchoke duration for the given torrent.

Returns Ok(Some(map)) when the torrent exists. Each entry is the total time we (this session) had that peer unchoked over the torrent’s lifetime, including reconnects (durations are flushed into a per-(SocketAddr × torrent) map on disconnect and re-merged here at query time).

Returns Ok(None) when the torrent is unknown to this session — the explicit contract distinguishes “torrent missing” from “exists but no peers were ever unchoked”.

Errors

Returns an error if the session is shut down.

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

Get metadata info for a specific torrent.

Errors

Returns an error if the session is shut down.

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

List all active torrent info hashes.

Errors

Returns an error if the session is shut down.

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

Get aggregate session statistics.

Errors

Returns an error if the session is shut down.

pub async fn debug_state(&self) -> Result<DebugState>

Collect per-torrent and per-peer debug state for diagnosing dispatch throughput regressions (M187).

Individual torrents that do not respond within 500 ms are skipped so the endpoint always returns partial results rather than failing.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

Gracefully shut down the session and all torrents.

Errors

Returns an error if the session is shut down.

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

Save resume data for a specific torrent.

Errors

Returns an error if the I/O operation fails.

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

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

Errors

Returns an error if the I/O operation fails.

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.

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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

Move a torrent one position down.

Errors

Returns an error if the session is shut down.

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

Move a torrent to position 0 (highest priority).

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

Get a clone of the current IP filter.

Errors

Returns an error if the session is shut down.

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

Get a clone of the current session settings.

Errors

Returns an error if the session is shut down.

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 for the fields that remain in restart_required; listen_port, dht, lsd are now applied live (M173 Lane B B10).

Errors

Returns crate::Error::ConcurrentReconfig if another apply_settings / apply_settings_classified call is still in flight (M173 Lane B B11). Caller should retry shortly.

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

Apply new settings and return a classification of which fields took effect immediately versus which require a session restart (M171 D3.5).

Identical behaviour to apply_settings, but the return value lets callers surface the “restart to apply” UX — specifically the X-IronTide-Restart-Pending response header on the qBt v2 setPreferences endpoint and the GUI restart-banner.

M173 Lane B (B11): the in-flight guard is acquired BEFORE the snapshot read, so concurrent callers cannot race the read-modify-write. The second caller hits crate::Error::ConcurrentReconfig.

Errors

Returns crate::Error::ConcurrentReconfig if another reconfig is still in flight. Returns crate::Error::InvalidSettings if the patch fails validation. Returns crate::Error::Shutdown if the session has shut down.

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

Get the current DHT routing-table size, summed across IPv4 and IPv6 instances (M171 D4).

Returns Ok(0) when DHT is disabled for both address families, or when neither instance has bootstrapped yet. Wired into the qBt v2 transferInfo.dht_nodes field and the DHT pseudo-tracker’s num_peers column on /api/v2/torrents/trackers.

Errors

Returns an error if the session is shut down.

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

Get the list of currently banned peer IPs.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

M178 Lane B3 / TODO-2: cumulative count of UNIQUE peers received via PEX (BEP 11) for this torrent since the actor started.

Errors

• Error::TorrentNotFound when the hash is unknown.
• Error::Shutdown on actor shutdown.

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

M178 Lane B3 / TODO-2: cumulative count of UNIQUE peers received via LSD (BEP 14) multicast for this torrent since the actor started.

Errors

• Error::TorrentNotFound when the hash is unknown.
• Error::Shutdown on actor shutdown.

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

M178 Lane C: per-URL web-seed stats snapshot for the qBt v2 webseeds endpoint and the GUI HTTP Sources tab.

Errors

• Error::TorrentNotFound when the hash is unknown.
• Error::Shutdown on actor shutdown.

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

M171 Lane B: list the web seed URLs (BEP 19 + BEP 17 merged) for a torrent.

BEP 19 url-list URLs come first, followed by BEP 17 httpseeds URLs — the wire order. Returns an empty vec when the torrent’s metadata has not yet been fetched (magnet still resolving the info dictionary).

Errors

• Error::TorrentNotFound if the info-hash is unknown.
• Error::Shutdown if the session’s command channel has closed.

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

M171 Lane B: snapshot the per-piece qBt state codes for a torrent.

Returns a Vec<u8> one byte per piece — 0 = not downloaded, 1 = downloading, 2 = downloaded + checked. An empty vec is returned when metadata hasn’t resolved yet (magnet still fetching the info dictionary) — callers should map that to a 404.

Errors

• Error::TorrentNotFound if the info-hash is unknown.
• Error::Shutdown if the session’s command channel has closed.

pub async fn get_piece_hashes( &self, info_hash: Id20, offset: u32, limit: u32, ) -> Result<Vec<String>>

M171 Lane B: paginated piece hash list for a torrent.

v1 / hybrid torrents return SHA-1 hashes (40-char hex strings); v2-only torrents return SHA-256 hashes (64-char hex strings). offset and limit are clamped to the real hash count inside the actor — callers can pass arbitrary values without overflow concerns. An empty vec is returned when metadata hasn’t resolved yet — callers should map that to a 404.

Errors

• Error::TorrentNotFound if the info-hash is unknown.
• Error::Shutdown if the session’s command channel has closed.

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

Scrape trackers for seeder/leecher counts for a torrent.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

Get the current per-file priorities for a torrent.

Errors

Returns an error if the session is shut down.

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).

Errors

Returns an error if the data cannot be parsed or I/O fails.

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).

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

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

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

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

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

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

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

Query whether sequential downloading is enabled for a torrent.

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

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

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

Replace all tracker URLs for a torrent.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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).

Errors

Returns an error if the connection or binding fails.

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

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

Errors

Returns an error if the connection or binding fails.

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

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

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

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

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

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

Errors

Returns an error if the session is shut down.

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).

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

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

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

Force an immediate DHT announce for a torrent.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

Read all data for a specific piece from disk.

Errors

Returns an error if the data cannot be parsed or I/O fails.

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

Flush the disk write cache for a torrent.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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

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

Errors

Returns an error if the session is shut down.

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

Set (enable) the specified torrent flags.

Errors

Returns an error if the session is shut down.

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

Unset (disable) the specified torrent flags.

Errors

Returns an error if the session is shut down.

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

Immediately initiate a peer connection for a torrent.

Errors

Returns an error if the connection or binding fails.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the session is shut down.

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.

Errors

Returns an error if the torrent cannot be added or the session is shut down.

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.

Errors

Returns an error if the torrent cannot be added or the session is shut down.

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.