irontide_engine/

types.rs

use std::collections::HashMap;
use std::net::SocketAddr;
use std::path::PathBuf;

use bytes::Bytes;
use tokio::sync::oneshot;

use irontide_storage::Bitfield;
use irontide_wire::ExtHandshake;

// Payload + vocabulary types relocated to `irontide-session-types` at M244a
// (types.rs god-module decomposition). Re-exported here so `crate::types::*`
// paths resolve unchanged for internal callers and the `irontide_session`
// public facade; the actor message types below (`PeerEvent` / `PeerCommand` /
// `TorrentCommand` / `BlockEntry`) stay until the M244b/M244c actor split.
pub use irontide_session_types::{
    FileMode, FileStatus, PartialPieceInfo, PeerConnectionKind, PeerInfo, SessionStats,
    SettingsDelta, TorrentConfig, TorrentFlags, TorrentState, TorrentStats,
};
// `TorrentSummary` is referenced only by engine's inline unit tests via
// `crate::types::…`; production engine code uses `irontide_session_types::…`
// directly. Gate the re-export to `#[cfg(test)]` so neither the lib nor the
// test build flags it unused under `-D warnings`. (The other session-types
// payloads have no engine-internal `crate::types::` consumer post-M244b split.)
#[cfg(test)]
pub use irontide_session_types::TorrentSummary;

/// Lightweight record of a single block write completion,
/// carried in `PeerEvent::PieceBlocksBatch`.
#[derive(Debug, Clone)]
pub(crate) struct BlockEntry {
    pub index: u32,  // piece index
    pub begin: u32,  // byte offset within piece
    pub length: u32, // block size (usually 16384)
}

/// Events sent from a `PeerTask` back to the `TorrentActor`.
#[derive(Debug)]
#[allow(dead_code)] // consumed by peer/torrent modules (not yet implemented)
pub(crate) enum PeerEvent {
    Bitfield {
        peer_addr: SocketAddr,
        bitfield: Bitfield,
    },
    Have {
        peer_addr: SocketAddr,
        index: u32,
    },
    /// BEP 54: Peer no longer has a piece (`lt_donthave` extension).
    DontHave {
        peer_addr: SocketAddr,
        index: u32,
    },
    PieceData {
        peer_addr: SocketAddr,
        index: u32,
        begin: u32,
        data: Bytes,
    },
    /// Block completion from a peer task's direct disk write.
    /// Sent immediately on each block write for real-time `TorrentActor` visibility.
    PieceBlocksBatch {
        peer_addr: SocketAddr,
        blocks: Vec<BlockEntry>,
    },
    PeerChoking {
        peer_addr: SocketAddr,
        choking: bool,
    },
    PeerInterested {
        peer_addr: SocketAddr,
        interested: bool,
    },
    ExtHandshake {
        peer_addr: SocketAddr,
        handshake: ExtHandshake,
    },
    MetadataPiece {
        peer_addr: SocketAddr,
        piece: u32,
        data: Bytes,
        total_size: u64,
    },
    MetadataReject {
        peer_addr: SocketAddr,
        piece: u32,
    },
    PexPeers {
        new_peers: Vec<SocketAddr>,
    },
    TrackersReceived {
        tracker_urls: Vec<String>,
    },
    IncomingRequest {
        peer_addr: SocketAddr,
        index: u32,
        begin: u32,
        length: u32,
    },
    RejectRequest {
        peer_addr: SocketAddr,
        index: u32,
        begin: u32,
        length: u32,
    },
    AllowedFast {
        peer_addr: SocketAddr,
        index: u32,
    },
    SuggestPiece {
        peer_addr: SocketAddr,
        index: u32,
    },
    /// Peer successfully connected with a specific transport.
    TransportIdentified {
        peer_addr: SocketAddr,
        transport: crate::rate_limiter::PeerTransport,
    },
    /// M140: BT handshake completed successfully — peer is now truly live.
    /// Sent from `run_peer` after BT protocol handshake exchange validates
    /// `info_hash` and `peer_id`. Triggers `mark_live()` in the actor.
    HandshakeComplete {
        peer_addr: SocketAddr,
        /// M174: Whether MSE/PE negotiated RC4 encryption for this connection.
        is_encrypted: bool,
    },
    Disconnected {
        peer_addr: SocketAddr,
        reason: Option<String>,
    },
    WebSeedPieceData {
        url: String,
        index: u32,
        data: Bytes,
    },
    WebSeedError {
        url: String,
        piece: u32,
        message: String,
    },
    /// M178: Periodic per-URL progress update from `WebSeedTask`. Coalesced
    /// by the task's 250 ms throttle (configurable via
    /// `Settings::web_seed_progress_throttle_ms`); the actor accumulates
    /// `WebSeedStats` from these. `error == Some(_)` records a transition
    /// into the errored state; the field is reset to `None` on recovery
    /// emissions but the accumulated `last_error` on `WebSeedStats`
    /// persists per Issue 2.2.
    WebSeedProgress {
        url: String,
        bytes: u64,
        rate_bps: u64,
        error: Option<String>,
    },
    /// M186: Web seed completed backoff and is ready for new piece assignments.
    WebSeedRetryReady {
        url: String,
    },
    /// M186: Web seed permanently failed after max consecutive failures.
    WebSeedPermanentFailure {
        url: String,
    },
    /// BEP 52: Received hash response from peer.
    HashesReceived {
        peer_addr: SocketAddr,
        request: irontide_core::HashRequest,
        hashes: Vec<irontide_core::Id32>,
    },
    /// BEP 52: Peer rejected our hash request.
    HashRequestRejected {
        peer_addr: SocketAddr,
        request: irontide_core::HashRequest,
    },
    /// BEP 52: Peer sent a hash request to us.
    IncomingHashRequest {
        peer_addr: SocketAddr,
        request: irontide_core::HashRequest,
    },
    /// BEP 55: Received a Rendezvous request (we are the relay).
    HolepunchRendezvous {
        peer_addr: SocketAddr,
        target: SocketAddr,
    },
    /// BEP 55: Received a Connect message (we should initiate simultaneous connect).
    HolepunchConnect {
        peer_addr: SocketAddr,
        target: SocketAddr,
    },
    /// BEP 55: Received an Error message from the relay.
    HolepunchError {
        peer_addr: SocketAddr,
        target: SocketAddr,
        error_code: u32,
    },
    /// MSE handshake failed — peer is being retried with a different encryption mode.
    /// Carries the new command channel sender so the `TorrentActor` can
    /// update its `PeerState`.
    MseRetry {
        peer_addr: SocketAddr,
        cmd_tx: tokio::sync::mpsc::Sender<PeerCommand>,
    },
    /// Peer released a piece it was downloading (choke, error, disconnect).
    PieceReleased {
        peer_addr: SocketAddr,
        piece: u32,
    },
    /// M187: Requester asks the actor to acquire a piece via `PieceTracker`.
    /// Actor responds with the piece index via the oneshot, or `NoneAvailable`
    /// if the peer has no dispatchable pieces.
    AcquirePiece {
        peer_addr: SocketAddr,
        response_tx: tokio::sync::oneshot::Sender<crate::piece_reservation::AcquireResponse>,
    },
}

/// Commands sent from the `TorrentActor` to a `PeerTask`.
#[derive(Debug)]
#[allow(dead_code)] // consumed by peer/torrent modules (not yet implemented)
pub(crate) enum PeerCommand {
    Request {
        index: u32,
        begin: u32,
        length: u32,
    },
    Cancel {
        index: u32,
        begin: u32,
        length: u32,
    },
    SetChoking(bool),
    SetInterested(bool),
    Have(u32),
    RequestMetadata {
        piece: u32,
    },
    RejectRequest {
        index: u32,
        begin: u32,
        length: u32,
    },
    AllowedFast(u32),
    SendPiece {
        index: u32,
        begin: u32,
        data: Bytes,
    },
    /// Send an updated extension handshake (e.g. BEP 21 upload-only).
    SendExtHandshake(irontide_wire::ExtHandshake),
    /// BEP 6: Suggest a piece to the peer.
    SuggestPiece(u32),
    /// BEP 52: Send a hash request to the peer.
    SendHashRequest(irontide_core::HashRequest),
    /// BEP 52: Send hashes in response to a peer's request.
    SendHashes {
        request: irontide_core::HashRequest,
        hashes: Vec<irontide_core::Id32>,
    },
    /// BEP 52: Reject a peer's hash request.
    SendHashReject(irontide_core::HashRequest),
    /// BEP 11: Send a PEX message to this peer.
    SendPex {
        message: crate::pex::PexMessage,
    },
    /// BEP 55: Send a holepunch message to this peer.
    SendHolepunch(irontide_wire::HolepunchMessage),
    /// Update the piece count after BEP 9 metadata assembly.
    UpdateNumPieces(u32),
    /// M159: Tell the peer task to stop dispatching block requests.
    ///
    /// Translated to `DispatchCommand::Stop` by the reader loop. The requester
    /// transitions back to the idle state waiting for a fresh `StartRequesting`.
    /// Uploads are unaffected.
    StopRequesting,
    /// M75: Actor sends reservation state to peer task for integrated dispatch.
    /// Sent after metadata download (magnet) or at peer connection (non-magnet).
    StartRequesting {
        piece_notify: std::sync::Arc<tokio::sync::Notify>,
        disk_handle: Option<crate::disk::DiskHandle>,
        write_error_tx: tokio::sync::mpsc::Sender<crate::disk::DiskWriteError>,
        lengths: irontide_core::Lengths,
    },
    Shutdown,
}

/// Helper trait combining [`AsyncRead`] + [`AsyncWrite`] for trait-object erasure.
///
/// Rust doesn't allow `dyn AsyncRead + AsyncWrite` directly, so this trait
/// combines both into a single trait that can be used as a trait object.
pub trait AsyncReadWrite: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send {}

impl<T> AsyncReadWrite for T where T: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send {}

/// Boxed async stream (`AsyncRead` + `AsyncWrite` + Unpin + Send) with a Debug impl.
///
/// Used for incoming SSL peer connections where the concrete TLS type is erased.
pub struct BoxedAsyncStream(pub Box<dyn AsyncReadWrite>);

impl std::fmt::Debug for BoxedAsyncStream {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("BoxedAsyncStream(..)")
    }
}

/// 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`.
#[derive(Debug)]
#[allow(dead_code)] // most variants are consumed only within the engine crate
pub enum TorrentCommand {
    AddPeers {
        peers: Vec<SocketAddr>,
        source: crate::peer_state::PeerSource,
    },
    Stats {
        reply: oneshot::Sender<TorrentStats>,
    },
    Pause,
    Queue,
    Resume,
    /// Resume the torrent bypassing queue limits (force-start).
    ForceResume,
    Shutdown,
    /// M170: update the category label recorded on this torrent. `None`
    /// clears the label (uncategorised).
    SetCategory {
        category: Option<String>,
        reply: oneshot::Sender<()>,
    },
    /// 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.
    SetTags {
        tags: Vec<String>,
        reply: oneshot::Sender<()>,
    },
    /// 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.
    GetWebSeeds {
        reply: oneshot::Sender<Vec<String>>,
    },
    /// 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).
    GetPieceStates {
        reply: oneshot::Sender<Vec<u8>>,
    },
    /// 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.
    GetPieceHashes {
        offset: u32,
        limit: u32,
        reply: oneshot::Sender<Vec<Vec<u8>>>,
    },
    SaveResumeData {
        reply: oneshot::Sender<crate::Result<irontide_core::FastResumeData>>,
    },
    /// 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.
    TakeResumeIfDirty {
        reply: oneshot::Sender<crate::Result<Option<irontide_core::FastResumeData>>>,
    },
    SetFilePriority {
        index: usize,
        priority: irontide_core::FilePriority,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    FilePriorities {
        reply: oneshot::Sender<Vec<irontide_core::FilePriority>>,
    },
    ForceReannounce,
    TrackerList {
        reply: oneshot::Sender<Vec<crate::tracker_manager::TrackerInfo>>,
    },
    Scrape {
        reply: oneshot::Sender<Option<(String, irontide_tracker::ScrapeInfo)>>,
    },
    /// Incoming peer routed from the session-level accept loop (TCP or uTP).
    IncomingPeer {
        stream: crate::transport::BoxedStream,
        addr: SocketAddr,
    },
    /// Open a streaming reader for a file within the torrent.
    OpenFile {
        file_index: usize,
        reply: oneshot::Sender<crate::Result<crate::streaming::FileStreamHandle>>,
    },
    /// Update the external IP for BEP 40 peer priority calculation.
    UpdateExternalIp {
        ip: std::net::IpAddr,
    },
    /// Move torrent data files to a new directory.
    MoveStorage {
        new_path: PathBuf,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Incoming SSL peer routed from the session-level SSL listener (M42).
    ///
    /// The TLS handshake has already been completed by the session actor.
    SpawnSslPeer {
        addr: SocketAddr,
        stream: BoxedAsyncStream,
    },
    /// Set the per-torrent download rate limit (bytes/sec, 0 = unlimited).
    SetDownloadLimit {
        bytes_per_sec: u64,
        reply: oneshot::Sender<()>,
    },
    /// Set the per-torrent upload rate limit (bytes/sec, 0 = unlimited).
    SetUploadLimit {
        bytes_per_sec: u64,
        reply: oneshot::Sender<()>,
    },
    /// Get the current per-torrent download rate limit (bytes/sec, 0 = unlimited).
    DownloadLimit {
        reply: oneshot::Sender<u64>,
    },
    /// Get the current per-torrent upload rate limit (bytes/sec, 0 = unlimited).
    UploadLimit {
        reply: oneshot::Sender<u64>,
    },
    /// Enable or disable sequential (in-order) piece downloading.
    SetSequentialDownload {
        enabled: bool,
        reply: oneshot::Sender<()>,
    },
    /// Query whether sequential downloading is enabled.
    IsSequentialDownload {
        reply: oneshot::Sender<bool>,
    },
    /// M253/ER2: enable or disable first/last-pieces-first ordering.
    SetPrioritizeFirstLastPieces {
        enabled: bool,
        reply: oneshot::Sender<()>,
    },
    /// M253/ER2: query whether first/last-pieces-first ordering is enabled.
    IsPrioritizeFirstLastPieces {
        reply: oneshot::Sender<bool>,
    },
    /// Enable or disable BEP 16 super seeding mode.
    SetSuperSeeding {
        enabled: bool,
        reply: oneshot::Sender<()>,
    },
    /// Query whether super seeding mode is enabled.
    IsSuperSeeding {
        reply: oneshot::Sender<bool>,
    },
    /// 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.
    SetSeedMode {
        enabled: bool,
        reply: oneshot::Sender<()>,
    },
    /// Override the per-torrent seed ratio limit (`None` = use session default).
    SetSeedRatioLimit {
        limit: Option<f64>,
        reply: oneshot::Sender<()>,
    },
    /// Add a new tracker URL (fire-and-forget at torrent level).
    AddTracker {
        url: String,
    },
    /// Replace all tracker URLs with a new set.
    ReplaceTrackers {
        urls: Vec<String>,
        reply: oneshot::Sender<()>,
    },
    /// Trigger a full piece verification (force recheck).
    ForceRecheck {
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Rename a file within the torrent on disk.
    RenameFile {
        file_index: usize,
        new_name: String,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Set the per-torrent maximum number of connections (0 = use global default).
    SetMaxConnections {
        limit: usize,
        reply: oneshot::Sender<()>,
    },
    /// Get the current per-torrent maximum connection limit.
    MaxConnections {
        reply: oneshot::Sender<usize>,
    },
    /// Set the per-torrent maximum number of unchoke slots (upload slots).
    SetMaxUploads {
        limit: usize,
        reply: oneshot::Sender<()>,
    },
    /// Get the current per-torrent maximum unchoke slots (upload slots).
    MaxUploads {
        reply: oneshot::Sender<usize>,
    },
    /// Get per-peer details for all connected peers.
    GetPeerInfo {
        reply: oneshot::Sender<Vec<PeerInfo>>,
    },
    /// Get in-flight piece download status (the download queue).
    GetDownloadQueue {
        reply: oneshot::Sender<Vec<PartialPieceInfo>>,
    },
    /// Check whether a specific piece has been downloaded.
    HavePiece {
        index: u32,
        reply: oneshot::Sender<bool>,
    },
    /// Get per-piece availability counts from connected peers.
    PieceAvailability {
        reply: oneshot::Sender<Vec<u32>>,
    },
    /// Get per-file bytes-downloaded progress.
    FileProgress {
        reply: oneshot::Sender<Vec<u64>>,
    },
    /// Get the torrent's identity hashes (v1 and/or v2).
    InfoHashes {
        reply: oneshot::Sender<irontide_core::InfoHashes>,
    },
    /// Get the full v1 metainfo (None for magnet links before metadata received).
    TorrentFile {
        reply: oneshot::Sender<Option<irontide_core::TorrentMetaV1>>,
    },
    /// Get the full v2 metainfo (None if not a v2/hybrid torrent or before metadata received).
    TorrentFileV2 {
        reply: oneshot::Sender<Option<irontide_core::TorrentMetaV2>>,
    },
    /// Force an immediate DHT announce (fire-and-forget at torrent level).
    ForceDhtAnnounce,
    /// Read all data for a specific piece from disk.
    ReadPiece {
        index: u32,
        reply: oneshot::Sender<crate::Result<bytes::Bytes>>,
    },
    /// Flush the disk write cache for this torrent.
    FlushCache {
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Clear the error state and resume if the torrent was paused due to error.
    ClearError,
    /// Get per-file open/mode status based on torrent state.
    FileStatus {
        reply: oneshot::Sender<Vec<crate::types::FileStatus>>,
    },
    /// Read the current torrent flags as a bitflag set.
    Flags {
        reply: oneshot::Sender<TorrentFlags>,
    },
    /// Set (enable) the specified torrent flags.
    SetFlags {
        flags: TorrentFlags,
        reply: oneshot::Sender<()>,
    },
    /// Unset (disable) the specified torrent flags.
    UnsetFlags {
        flags: TorrentFlags,
        reply: oneshot::Sender<()>,
    },
    /// Immediately initiate a peer connection to the given address.
    ConnectPeer {
        addr: SocketAddr,
    },
    /// Clear the `need_save_resume` dirty flag after a successful file save (M161).
    ClearSaveResumeFlag,
    /// M245 F1 — re-arm `need_save_resume` after a failed resume WRITE.
    /// [`TakeResumeIfDirty`](Self::TakeResumeIfDirty) clears the flag on
    /// capture; without this the captured-but-unwritten state would never be
    /// retried on a later save cycle.
    MarkResumeDirty,
    /// 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.
    RestoreResumeBitmap {
        /// Raw piece bitfield bytes from resume data.
        pieces: Vec<u8>,
        /// Reply with `Ok(())` on success or an error if validation fails.
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// 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).
    RestoreWebSeedStats {
        /// Map of URL → stats from `FastResumeData::web_seed_stats`.
        stats: HashMap<String, irontide_core::WebSeedStats>,
        /// Reply with `Ok(())` on success.
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// M178 (Lane B3 / TODO-2): cumulative `(pex, lsd)` unique-peer counts
    /// for the GUI Trackers tab + qBt v2 trackers pseudo-tracker rows.
    GetPeerSourceCounts {
        /// Reply with `(pex_peer_count, lsd_peer_count)`.
        reply: oneshot::Sender<(usize, usize)>,
    },
    /// 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.
    QueryUnchokeDurations {
        /// Reply with one entry per peer ever unchoked by us.
        reply: oneshot::Sender<HashMap<SocketAddr, std::time::Duration>>,
    },
    /// 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.
    GetWebSeedStats {
        /// Reply with one entry per URL with active stats.
        reply: oneshot::Sender<Vec<irontide_core::WebSeedStats>>,
    },
    /// 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.
    PreResolvedMetadata {
        /// Raw bencoded info dictionary bytes.
        info_bytes: Vec<u8>,
        /// Peers that were successfully connected during metadata resolution
        /// (for pre-seeding the peer pipeline).
        peers: Vec<SocketAddr>,
    },
    /// 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`.
    GetMeta {
        /// Reply with `Some(meta)` when available, `None` for a magnet that
        /// hasn't resolved metadata yet.
        reply: oneshot::Sender<Option<irontide_core::TorrentMetaV1>>,
    },
    /// **TEST-ONLY (v0.173.2).** Synchronously inject a fully-assembled info-dict
    /// payload via the same internal handler as the M147 `PreResolvedMetadata`
    /// path, but with backpressure + completion-ack so tests can rely on the
    /// metadata being processed when the future resolves. The M147 fast-path
    /// uses `try_send` and is fire-and-forget by design (resolver shouldn't
    /// block); this variant is the synchronous-test counterpart.
    #[cfg(feature = "test-util")]
    TestInjectMetadata {
        /// Raw bencoded info dictionary bytes.
        info_bytes: Vec<u8>,
        /// Completion ack — fired after `handle_pre_resolved_metadata` returns.
        reply: oneshot::Sender<()>,
    },
    /// 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.
    ///
    /// Boxed since M255: the delta is ~60 `Option` fields and rarely sent —
    /// boxing keeps every `TorrentCommand` channel slot small
    /// (`clippy::large_enum_variant` tripped when the delta grew).
    UpdateSettings(Box<SettingsDelta>),
}