Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Ergonomic builder for creating a torrent session.

Wraps Settings with a fluent API. Call start() to spawn the session actor and get a SessionHandle.

Example

let session = irontide::ClientBuilder::new()
    .download_dir("/tmp/downloads")
    .listen_port(6881)
    .enable_dht(true)
    .start()
    .await?;

Implementations

impl ClientBuilder

pub fn new() -> Self

Create a new builder with default settings.

pub fn from_settings(settings: Settings) -> Self

Create a builder from an existing Settings struct.

Useful for loading settings from a JSON config file and then applying CLI overrides on top.

pub fn add_extension(self, plugin: Box<dyn ExtensionPlugin>) -> Self

Register a custom BEP 10 extension plugin.

Plugins are assigned extension IDs starting at 10 in registration order. Built-in extensions (ut_metadata=1, ut_pex=2, lt_trackers=3) cannot be overridden.

pub fn listen_port(self, port: u16) -> Self

Set the TCP listen port for incoming peer connections.

pub fn download_dir(self, path: impl Into<PathBuf>) -> Self

Set the default download directory.

pub fn max_torrents(self, n: usize) -> Self

Set the maximum number of concurrent torrents.

pub fn enable_dht(self, v: bool) -> Self

Enable or disable DHT peer discovery.

pub fn enable_lsd(self, v: bool) -> Self

Enable or disable Local Service Discovery.

pub fn enable_pex(self, v: bool) -> Self

Enable or disable Peer Exchange.

pub fn enable_fast_extension(self, v: bool) -> Self

Enable or disable BEP 6 Fast Extension.

pub fn seed_ratio_limit(self, ratio: f64) -> Self

Set the seed ratio limit. Torrents stop seeding when this ratio is reached.

pub fn alert_mask(self, mask: AlertCategory) -> Self

Set the alert category mask (default: all categories).

pub fn alert_channel_size(self, size: usize) -> Self

Set the alert broadcast channel capacity (default: 1024).

pub fn active_downloads(self, n: i32) -> Self

Set the maximum number of concurrent auto-managed downloading torrents (-1 = unlimited).

pub fn active_seeds(self, n: i32) -> Self

Set the maximum number of concurrent auto-managed seeding torrents (-1 = unlimited).

pub fn active_limit(self, n: i32) -> Self

Set the hard cap on all active auto-managed torrents (-1 = unlimited).

pub fn active_checking(self, n: i32) -> Self

Set the maximum number of concurrent hash-check operations.

pub fn dont_count_slow_torrents(self, v: bool) -> Self

Set whether inactive torrents are exempt from download/seed limits.

pub fn auto_manage_interval(self, secs: u64) -> Self

Set the interval (seconds) between queue evaluations.

pub fn auto_manage_startup(self, secs: u64) -> Self

Set the startup grace period (seconds) where a torrent is considered active regardless of speed.

pub fn auto_manage_prefer_seeds(self, v: bool) -> Self

Set whether seeding slots are allocated before download slots.

pub fn encryption_mode(self, mode: EncryptionMode) -> Self

Set the connection encryption mode (MSE/PE).

pub fn enable_utp(self, v: bool) -> Self

Enable or disable uTP (micro Transport Protocol) for peer connections.

When enabled, outbound connections try uTP first with a 5-second timeout before falling back to TCP. Inbound uTP connections are routed to the correct torrent by reading the BT preamble.

pub fn enable_upnp(self, v: bool) -> Self

Enable or disable UPnP IGD port mapping.

When enabled, the session automatically attempts to open ports on the router via UPnP as a last resort (after PCP and NAT-PMP).

pub fn enable_natpmp(self, v: bool) -> Self

Enable or disable NAT-PMP / PCP port mapping.

When enabled, the session tries PCP first (RFC 6887), then falls back to NAT-PMP (RFC 6886), to open ports on the router.

pub fn enable_holepunch(self, v: bool) -> Self

Enable or disable BEP 55 holepunch extension for NAT traversal.

When enabled, the client advertises ut_holepunch in the extension handshake and can act as initiator, relay, or target for holepunch connections. Default: true.

pub fn enable_ipv6(self, v: bool) -> Self

Enable or disable IPv6 dual-stack support (BEP 7, 24).

When enabled, the session binds listeners on both IPv4 and IPv6, starts a second DHT instance for IPv6, and processes IPv6 peers in PEX and tracker responses. Default: true.

pub fn enable_web_seed(self, v: bool) -> Self

Enable or disable HTTP/web seeding (BEP 19 GetRight, BEP 17 Hoffman).

When enabled, torrents with url-list or httpseeds will download pieces from HTTP servers alongside peer-to-peer transfers. Default: true.

pub fn super_seeding(self, v: bool) -> Self

Enable or disable BEP 16 super seeding for new torrents.

Super seeding reveals pieces one-per-peer to maximize piece diversity across the swarm. Most useful for initial seeders. Default: false.

pub fn upload_only_announce(self, v: bool) -> Self

Enable or disable BEP 21 upload-only announcement.

When enabled, the client advertises upload-only status via the extension handshake when a torrent transitions to seeding. Default: true.

pub fn smart_ban_max_failures(self, n: u32) -> Self

Set the number of hash-failure involvements before a peer is auto-banned.

Default: 3. Lower values ban faster but risk false positives.

pub fn smart_ban_parole(self, enabled: bool) -> Self

Enable or disable parole mode for smart banning.

When enabled (default), a failed piece is re-downloaded from a single uninvolved peer to definitively attribute fault before striking.

pub fn disk_io_threads(self, n: usize) -> Self

Set the number of concurrent disk I/O threads. Default: 4.

pub fn storage_mode(self, mode: StorageMode) -> Self

Set the storage allocation mode. Default: Auto.

pub fn hashing_threads(self, n: usize) -> Self

Set the number of concurrent piece hash verifications. Default: 2.

pub fn disk_cache_size(self, bytes: usize) -> Self

Set the total disk cache size in bytes. Default: 64 MiB.

pub fn max_request_queue_depth(self, n: usize) -> Self

Set the maximum per-peer request queue depth. Default: 250.

pub fn request_queue_time(self, secs: f64) -> Self

Set the request queue time multiplier (seconds). Default: 3.0.

pub fn block_request_timeout_secs(self, secs: u32) -> Self

Set the block request timeout in seconds. Default: 60.

pub fn max_concurrent_stream_reads(self, n: usize) -> Self

Set the maximum concurrent file stream readers. Default: 8.

pub fn proxy(self, proxy: ProxyConfig) -> Self

Set the proxy configuration for peer and tracker connections.

pub fn force_proxy(self, v: bool) -> Self

Enable force proxy mode.

When enabled, all connections must go through the configured proxy. Disables listen sockets, UPnP, NAT-PMP, DHT, and LSD. Fails at start if no proxy is configured.

pub fn anonymous_mode(self, v: bool) -> Self

Enable anonymous mode.

Suppresses identifying information (client version in BEP 10 handshake) and disables DHT, LSD, UPnP, and NAT-PMP.

pub fn apply_ip_filter_to_trackers(self, v: bool) -> Self

Set whether the IP filter applies to tracker connections.

When true (default), tracker IP addresses are checked against the IP filter. When false, trackers are exempt.

pub fn dht_queries_per_second(self, n: usize) -> Self

Set the DHT query rate (queries per second). Default: 5.

pub fn dht_query_timeout_secs(self, secs: u64) -> Self

Set the DHT query timeout in seconds. Default: 5.

pub fn dht_enforce_node_id(self, v: bool) -> Self

BEP 42: Enforce node ID verification in the DHT routing table. Default: true.

pub fn dht_restrict_routing_ips(self, v: bool) -> Self

BEP 42: Restrict the DHT routing table to one node per IP. Default: true.

pub fn dht_max_items(self, v: usize) -> Self

BEP 44: Set the maximum number of stored DHT items. Default: 700.

pub fn dht_item_lifetime_secs(self, v: u64) -> Self

BEP 44: Set the DHT item lifetime in seconds. Default: 7200.

pub fn upnp_lease_duration(self, secs: u32) -> Self

Set the UPnP lease duration in seconds. Default: 3600.

pub fn natpmp_lifetime(self, secs: u32) -> Self

Set the NAT-PMP mapping lifetime in seconds. Default: 3600.

pub fn utp_max_connections(self, n: usize) -> Self

Set the maximum uTP connections. Default: 256.

pub fn enable_i2p(self, v: bool) -> Self

Enable I2P anonymous network support.

Requires a local I2P router with SAM enabled (default: 127.0.0.1:7656). When enabled, the session creates a SAM session on startup and accepts anonymous peer connections.

pub fn i2p_hostname(self, host: impl Into<String>) -> Self

Set the SAM bridge hostname. Default: “127.0.0.1”.

pub fn i2p_port(self, port: u16) -> Self

Set the SAM bridge port. Default: 7656.

pub fn i2p_inbound_quantity(self, n: u8) -> Self

Set the number of inbound I2P tunnels (1-16). Default: 3.

pub fn i2p_outbound_quantity(self, n: u8) -> Self

Set the number of outbound I2P tunnels (1-16). Default: 3.

pub fn i2p_inbound_length(self, n: u8) -> Self

Set the number of hops in inbound I2P tunnels (0-7). Default: 3.

pub fn i2p_outbound_length(self, n: u8) -> Self

Set the number of hops in outbound I2P tunnels (0-7). Default: 3.

pub fn allow_i2p_mixed(self, v: bool) -> Self

Allow mixing I2P and clearnet peers. Default: false.

When false, I2P-enabled torrents only connect to I2P peers. When true, both I2P and clearnet peers are used.

pub fn ssl_listen_port(self, v: u16) -> Self

Set the TCP listen port for incoming SSL torrent connections.

When non-zero, a TLS listener is bound on this port for torrents with ssl-cert in their info dict. SNI-based routing dispatches connections to the correct torrent. Default: 0 (disabled).

pub fn ssl_cert_path(self, v: impl Into<PathBuf>) -> Self

Set the path to a PEM-encoded certificate file for SSL torrent connections.

If not set, a self-signed certificate is auto-generated on first use and persisted to resume_data_dir. Must be paired with ssl_key_path.

pub fn ssl_key_path(self, v: impl Into<PathBuf>) -> Self

Set the path to a PEM-encoded private key file for SSL torrent connections.

Must be paired with ssl_cert_path.

pub fn disk_channel_capacity(self, n: usize) -> Self

Set the disk I/O channel capacity. Default: 1024.

pub fn seed_choking_algorithm(self, algorithm: SeedChokingAlgorithm) -> Self

Set the seed-mode choking algorithm.

pub fn choking_algorithm(self, algorithm: ChokingAlgorithm) -> Self

Set the choking algorithm.

pub fn piece_extent_affinity(self, enabled: bool) -> Self

Enable or disable piece extent affinity for disk cache locality.

When enabled, the piece picker prefers pieces adjacent to those already downloaded, improving sequential disk access patterns. Default: true.

pub fn suggest_mode(self, enabled: bool) -> Self

Enable or disable suggest mode (BEP 6 SuggestPiece).

When enabled, newly verified pieces are suggested to peers that don’t have them, helping improve piece diversity in the swarm. Default: false.

pub fn max_suggest_pieces(self, count: usize) -> Self

Set the maximum number of SuggestPiece messages per peer.

Limits how many pieces are suggested to each connected peer to avoid flooding. Default: 10.

pub fn predictive_piece_announce(self, ms: u64) -> Self

Set the predictive piece announce delay in milliseconds.

When > 0, a Have message is sent to peers as soon as all blocks of a piece are received, before hash verification completes. This reduces latency for piece availability at the cost of a possible false announce if the piece fails verification. Default: 0 (disabled).

pub fn mixed_mode_algorithm(self, algorithm: MixedModeAlgorithm) -> Self

Set the mixed-mode TCP/uTP bandwidth allocation algorithm.

pub fn auto_sequential(self, enable: bool) -> Self

Enable or disable automatic sequential mode switching.

pub fn max_metadata_size(self, bytes: u64) -> Self

Set the maximum BEP 9 metadata size accepted from peers.

Protects against OOM from peers advertising enormous metadata. Default: 4 MiB.

pub fn max_message_size(self, bytes: usize) -> Self

Set the maximum wire protocol message size.

Messages exceeding this size are rejected by the codec. Default: 16 MiB.

pub fn max_piece_length(self, bytes: u64) -> Self

Set the maximum accepted piece length when adding a torrent.

Torrents with piece sizes above this are rejected at add time. Default: 32 MiB.

pub fn max_outstanding_requests(self, n: usize) -> Self

Set the maximum outstanding incoming requests per peer.

When a peer sends more Request messages than this without them being served, excess requests are silently dropped. Default: 500.

pub fn ssrf_mitigation(self, v: bool) -> Self

Enable or disable SSRF mitigation for tracker and web seed URLs.

When enabled (default), localhost tracker paths are restricted to /announce, local-network web seed URLs with query strings are rejected, and HTTP redirects from public to private IPs are blocked.

pub fn allow_idna(self, v: bool) -> Self

Allow or reject internationalised (non-ASCII) domain names in URLs.

When false (default), tracker and web seed URLs with IDNA/punycode domains are rejected to prevent homograph attacks.

pub fn validate_https_trackers(self, v: bool) -> Self

Enable or disable HTTPS validation for HTTP tracker announces.

When true (default), the HTTP client validates TLS certificates. When false, invalid certificates are accepted (useful for self-signed trackers).

pub fn peer_dscp(self, dscp: u8) -> Self

Set the DSCP value for peer traffic (TCP and uTP).

The 6-bit Differentiated Services Code Point is placed in the IP header of all peer connections. Common values: 0x00 (best effort), 0x08 (CS1 / low-priority, default), 0x20 (CS4). Default: 0x08.

pub fn stats_report_interval(self, ms: u64) -> Self

Set the interval in milliseconds between periodic SessionStatsAlert emissions.

Default: 1000 (1 second). Set to 0 to disable periodic stats alerts. Stats can still be triggered on demand via SessionHandle::post_session_stats().

pub fn dht_saved_nodes(self, nodes: Vec<String>) -> Self

Provide previously saved DHT routing table nodes for fast bootstrap.

These nodes are prepended to the default bootstrap node list so that peer discovery starts instantly instead of bootstrapping from scratch. Typically loaded from a persisted session state file on startup.

pub fn dht_node_id(self, id: Id20) -> Self

Reuse a previously persisted BEP 42-compliant DHT node ID.

Avoids routing table regeneration on startup when the external IP hasn’t changed. Without this, a random ID is generated each session and immediately discarded by BEP 42, causing saved nodes to be re-inserted into a fresh table with significant loss.

pub fn runtime_worker_threads(self, n: usize) -> Self

Set the number of tokio worker threads (0 = use tokio’s default).

pub fn pin_cores(self, v: bool) -> Self

Pin tokio worker threads to CPU cores for cache locality.

pub fn disk_io_backend(self, backend: Arc<dyn DiskIoBackend>) -> Self

Set a custom disk I/O backend.

When set, the session uses this backend instead of the default POSIX or mmap backend derived from settings. This enables custom storage implementations (e.g., cloud storage, in-memory, or the DisabledDiskIo benchmark backend).

pub fn into_settings(self) -> Settings

Consume the builder and return the underlying Settings.

pub async fn start(self) -> Result<SessionHandle>

Start the session, spawning the background actor.

Errors

Returns an error if the session fails to start.

Trait Implementations

impl Default for ClientBuilder

fn default() -> Self

Returns the “default value” for a type.