pub enum TorrentCommand {
Show 69 variants
AddPeers {
peers: Vec<SocketAddr>,
source: PeerSource,
},
Stats {
reply: Sender<TorrentStats>,
},
Pause,
Queue,
Resume,
ForceResume,
Shutdown,
SetCategory {
category: Option<String>,
reply: Sender<()>,
},
SetTags {
tags: Vec<String>,
reply: Sender<()>,
},
GetWebSeeds {
reply: Sender<Vec<String>>,
},
GetPieceStates {
reply: Sender<Vec<u8>>,
},
GetPieceHashes {
offset: u32,
limit: u32,
reply: Sender<Vec<Vec<u8>>>,
},
SaveResumeData {
reply: Sender<Result<FastResumeData>>,
},
TakeResumeIfDirty {
reply: Sender<Result<Option<FastResumeData>>>,
},
SetFilePriority {
index: usize,
priority: FilePriority,
reply: Sender<Result<()>>,
},
FilePriorities {
reply: Sender<Vec<FilePriority>>,
},
ForceReannounce,
TrackerList {
reply: Sender<Vec<TrackerInfo>>,
},
Scrape {
reply: Sender<Option<(String, ScrapeInfo)>>,
},
IncomingPeer {
stream: BoxedStream,
addr: SocketAddr,
},
OpenFile {
file_index: usize,
reply: Sender<Result<FileStreamHandle>>,
},
UpdateExternalIp {
ip: IpAddr,
},
MoveStorage {
new_path: PathBuf,
reply: Sender<Result<()>>,
},
SpawnSslPeer {
addr: SocketAddr,
stream: BoxedAsyncStream,
},
SetDownloadLimit {
bytes_per_sec: u64,
reply: Sender<()>,
},
SetUploadLimit {
bytes_per_sec: u64,
reply: Sender<()>,
},
DownloadLimit {
reply: Sender<u64>,
},
UploadLimit {
reply: Sender<u64>,
},
SetSequentialDownload {
enabled: bool,
reply: Sender<()>,
},
IsSequentialDownload {
reply: Sender<bool>,
},
SetSuperSeeding {
enabled: bool,
reply: Sender<()>,
},
IsSuperSeeding {
reply: Sender<bool>,
},
SetSeedMode {
enabled: bool,
reply: Sender<()>,
},
SetSeedRatioLimit {
limit: Option<f64>,
reply: Sender<()>,
},
AddTracker {
url: String,
},
ReplaceTrackers {
urls: Vec<String>,
reply: Sender<()>,
},
ForceRecheck {
reply: Sender<Result<()>>,
},
RenameFile {
file_index: usize,
new_name: String,
reply: Sender<Result<()>>,
},
SetMaxConnections {
limit: usize,
reply: Sender<()>,
},
MaxConnections {
reply: Sender<usize>,
},
SetMaxUploads {
limit: usize,
reply: Sender<()>,
},
MaxUploads {
reply: Sender<usize>,
},
GetPeerInfo {
reply: Sender<Vec<PeerInfo>>,
},
GetDownloadQueue {
reply: Sender<Vec<PartialPieceInfo>>,
},
HavePiece {
index: u32,
reply: Sender<bool>,
},
PieceAvailability {
reply: Sender<Vec<u32>>,
},
FileProgress {
reply: Sender<Vec<u64>>,
},
InfoHashes {
reply: Sender<InfoHashes>,
},
TorrentFile {
reply: Sender<Option<TorrentMetaV1>>,
},
TorrentFileV2 {
reply: Sender<Option<TorrentMetaV2>>,
},
ForceDhtAnnounce,
ReadPiece {
index: u32,
reply: Sender<Result<Bytes>>,
},
FlushCache {
reply: Sender<Result<()>>,
},
ClearError,
FileStatus {
reply: Sender<Vec<FileStatus>>,
},
Flags {
reply: Sender<TorrentFlags>,
},
SetFlags {
flags: TorrentFlags,
reply: Sender<()>,
},
UnsetFlags {
flags: TorrentFlags,
reply: Sender<()>,
},
ConnectPeer {
addr: SocketAddr,
},
ClearSaveResumeFlag,
MarkResumeDirty,
RestoreResumeBitmap {
pieces: Vec<u8>,
reply: Sender<Result<()>>,
},
RestoreWebSeedStats {
stats: HashMap<String, WebSeedStats>,
reply: Sender<Result<()>>,
},
GetPeerSourceCounts {
reply: Sender<(usize, usize)>,
},
QueryUnchokeDurations {
reply: Sender<HashMap<SocketAddr, Duration>>,
},
GetWebSeedStats {
reply: Sender<Vec<WebSeedStats>>,
},
PreResolvedMetadata {
info_bytes: Vec<u8>,
peers: Vec<SocketAddr>,
},
GetMeta {
reply: Sender<Option<TorrentMetaV1>>,
},
UpdateSettings(SettingsDelta),
}Expand description
Commands sent from a TorrentHandle to the TorrentActor.
pub at the M244b engine split: session-core (irontide-session) sends a
subset of these (ForceResume / SetSeedRatioLimit / UpdateSettings) across
the crate boundary, re-exported there as crate::types::TorrentCommand.
Variants§
AddPeers
Stats
Fields
reply: Sender<TorrentStats>Pause
Queue
Resume
ForceResume
Resume the torrent bypassing queue limits (force-start).
Shutdown
SetCategory
M170: update the category label recorded on this torrent. None
clears the label (uncategorised).
SetTags
M171: replace the torrent’s tag set wholesale (qBt-compat).
Mirrors qBt’s addTags / removeTags wire behaviour at the API
layer — always a wholesale replacement at the engine layer.
GetWebSeeds
M171 Lane B: snapshot the list of configured web seed URLs
(BEP 19 url-list + BEP 17 httpseeds).
Returns an empty vec when metadata hasn’t resolved yet.
GetPieceStates
M171 Lane B: snapshot the per-piece state array as qBt codes.
Each element is one of {0: not downloaded, 1: downloading, 2: downloaded + checked}. Returns an empty vec when metadata hasn’t resolved yet (piece count unknown).
GetPieceHashes
M171 Lane B: return a paginated slice of per-piece hashes.
M245 L3: the reply carries the RAW hash bytes for the requested window
(v1 / hybrid: 20-byte SHA-1; v2-only: 32-byte SHA-256) — one Vec<u8>
per piece. The hex::encode is done by the caller
([TorrentHandle::get_piece_hashes]) OFF the recv loop, so the actor no
longer encodes (and discards) every hash on its hot path. Returns an
empty vec when metadata hasn’t resolved yet, or when offset is past the
end of the hash list.
SaveResumeData
Fields
reply: Sender<Result<FastResumeData>>TakeResumeIfDirty
M245 F1 — atomically take resume data IFF the torrent is dirty,
clearing need_save_resume in the SAME actor turn (no .await
between the read and the clear). Replaces the racy SaveResumeData +
ClearSaveResumeFlag two-step, where a need_save_resume set between
the build and the clear was silently lost. Ok(None) = not dirty.
Fields
reply: Sender<Result<Option<FastResumeData>>>SetFilePriority
FilePriorities
Fields
reply: Sender<Vec<FilePriority>>ForceReannounce
TrackerList
Fields
reply: Sender<Vec<TrackerInfo>>Scrape
Fields
reply: Sender<Option<(String, ScrapeInfo)>>IncomingPeer
Incoming peer routed from the session-level accept loop (TCP or uTP).
OpenFile
Open a streaming reader for a file within the torrent.
UpdateExternalIp
Update the external IP for BEP 40 peer priority calculation.
MoveStorage
Move torrent data files to a new directory.
SpawnSslPeer
Incoming SSL peer routed from the session-level SSL listener (M42).
The TLS handshake has already been completed by the session actor.
SetDownloadLimit
Set the per-torrent download rate limit (bytes/sec, 0 = unlimited).
SetUploadLimit
Set the per-torrent upload rate limit (bytes/sec, 0 = unlimited).
DownloadLimit
Get the current per-torrent download rate limit (bytes/sec, 0 = unlimited).
UploadLimit
Get the current per-torrent upload rate limit (bytes/sec, 0 = unlimited).
SetSequentialDownload
Enable or disable sequential (in-order) piece downloading.
IsSequentialDownload
Query whether sequential downloading is enabled.
SetSuperSeeding
Enable or disable BEP 16 super seeding mode.
IsSuperSeeding
Query whether super seeding mode is enabled.
SetSeedMode
Enable or disable user-requested seed-only mode (M159).
When enabled, the torrent stops scheduling new block requests and
cancels all in-flight requests, but continues to serve uploads to
interested peers. Mirrors libtorrent’s seed_mode flag.
SetSeedRatioLimit
Override the per-torrent seed ratio limit (None = use session default).
AddTracker
Add a new tracker URL (fire-and-forget at torrent level).
ReplaceTrackers
Replace all tracker URLs with a new set.
ForceRecheck
Trigger a full piece verification (force recheck).
RenameFile
Rename a file within the torrent on disk.
SetMaxConnections
Set the per-torrent maximum number of connections (0 = use global default).
MaxConnections
Get the current per-torrent maximum connection limit.
SetMaxUploads
Set the per-torrent maximum number of unchoke slots (upload slots).
MaxUploads
Get the current per-torrent maximum unchoke slots (upload slots).
GetPeerInfo
Get per-peer details for all connected peers.
GetDownloadQueue
Get in-flight piece download status (the download queue).
Fields
reply: Sender<Vec<PartialPieceInfo>>HavePiece
Check whether a specific piece has been downloaded.
PieceAvailability
Get per-piece availability counts from connected peers.
FileProgress
Get per-file bytes-downloaded progress.
InfoHashes
Get the torrent’s identity hashes (v1 and/or v2).
Fields
reply: Sender<InfoHashes>TorrentFile
Get the full v1 metainfo (None for magnet links before metadata received).
Fields
reply: Sender<Option<TorrentMetaV1>>TorrentFileV2
Get the full v2 metainfo (None if not a v2/hybrid torrent or before metadata received).
Fields
reply: Sender<Option<TorrentMetaV2>>ForceDhtAnnounce
Force an immediate DHT announce (fire-and-forget at torrent level).
ReadPiece
Read all data for a specific piece from disk.
FlushCache
Flush the disk write cache for this torrent.
ClearError
Clear the error state and resume if the torrent was paused due to error.
FileStatus
Get per-file open/mode status based on torrent state.
Fields
reply: Sender<Vec<FileStatus>>Flags
Read the current torrent flags as a bitflag set.
Fields
reply: Sender<TorrentFlags>SetFlags
Set (enable) the specified torrent flags.
UnsetFlags
Unset (disable) the specified torrent flags.
ConnectPeer
Immediately initiate a peer connection to the given address.
Fields
addr: SocketAddrClearSaveResumeFlag
Clear the need_save_resume dirty flag after a successful file save (M161).
MarkResumeDirty
M245 F1 — re-arm need_save_resume after a failed resume WRITE.
TakeResumeIfDirty clears the flag on
capture; without this the captured-but-unwritten state would never be
retried on a later save cycle.
RestoreResumeBitmap
Restore a piece bitmap from resume data (M161 Phase 4).
Replaces the chunk tracker’s bitfield with the provided raw piece bytes. The handler validates the bitfield length before applying.
Fields
RestoreWebSeedStats
M178: Restore the per-URL web-seed stats map from resume data.
Used by the post-add resume-restore path so that downloaded-byte counters and last-error / consecutive-failure state survive app restart (Tension-1 fast-resume persistence).
Fields
stats: HashMap<String, WebSeedStats>Map of URL → stats from FastResumeData::web_seed_stats.
GetPeerSourceCounts
M178 (Lane B3 / TODO-2): cumulative (pex, lsd) unique-peer counts
for the GUI Trackers tab + qBt v2 trackers pseudo-tracker rows.
QueryUnchokeDurations
Per-peer cumulative unchoke duration over the torrent’s lifetime.
Keyed by SocketAddr; merges live PeerState accumulators with
the durable per-torrent map so reconnects preserve history.
Used by libtorrent-mirror perf scenarios that gate on
optimistic-unchoke fairness.
Fields
reply: Sender<HashMap<SocketAddr, Duration>>Reply with one entry per peer ever unchoked by us.
GetWebSeedStats
M178 (Lane C): snapshot of per-URL web-seed stats for the qBt v2
/api/v2/torrents/webseeds endpoint and the GUI HTTP Sources tab.
Fields
reply: Sender<Vec<WebSeedStats>>Reply with one entry per URL with active stats.
PreResolvedMetadata
M147: Pre-resolved metadata from the background MetadataResolver.
Sent by SessionActor::spawn_metadata_resolver() when the background
resolver successfully obtains torrent metadata before the TorrentActor’s
own FetchingMetadata phase completes. This is a race: first to resolve
wins; the other path’s result is silently discarded.
Fields
peers: Vec<SocketAddr>Peers that were successfully connected during metadata resolution (for pre-seeding the peer pipeline).
GetMeta
v0.173.1: single source of truth for torrent metadata.
Returns Some(meta.clone()) if the actor has assembled metadata (via
its own ut_metadata fetch or a PreResolvedMetadata push), else
None. Replaces SessionActor.TorrentEntry.meta as the authoritative
source — see class-A archaeology in the v0.173.1 plan file at
docs/plans/2026-04-22-irontide-v0.173.1-qbt-v2-bug-sweep.md.
Fields
reply: Sender<Option<TorrentMetaV1>>Reply with Some(meta) when available, None for a magnet that
hasn’t resolved metadata yet.
UpdateSettings(SettingsDelta)
v0.187.1: broadcast changed session-level settings to a running torrent.
Patches self.config fields so that settings changes made via
Preferences → Apply take effect on existing torrents, not just
newly-added ones.