IronTide

https://docs.rs/irontide/1.7.0/irontide/
Admin
IronTide is a Rust BitTorrent library providing an ergonomic API for session management, peer wire...
Tokens:110,635
Snippets:1,427
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### start

Source: https://docs.rs/irontide/1.7.0/irontide/dht/struct.DhtHandle.html

Starts the DHT actor and returns a handle along with an IP consensus channel.

```APIDOC
## pub async fn start(config: DhtConfig) -> Result<(DhtHandle, Receiver<IpAddr>), Error>

### Description
Starts the DHT actor and returns a handle plus an IP consensus channel. The consensus channel fires when the BEP 42 ExternalIpVoter reaches agreement on the external IP address.

### Errors
Returns an error if the UDP socket cannot be bound.
```

--------------------------------

### Basic Pinning Example

Source: https://docs.rs/irontide/1.7.0/irontide/session/type.StorageFactory.html

Demonstrates basic pinning of a boxed value.

```rust
let foo = Box::new(());
let bar = Pin::from(foo);
```

--------------------------------

### ClientBuilder Lifecycle Methods

Source: https://docs.rs/irontide/1.7.0/irontide/client/struct.ClientBuilder.html

Methods for finalizing configuration and starting the session.

```APIDOC
## Session Lifecycle

### into_settings() -> Settings
Consumes the builder instance and returns the underlying Settings object.

### start() -> Result<SessionHandle>
Starts the session by spawning the background actor. Returns an error if the session fails to initialize.
```

--------------------------------

### Initialize a Torrent Session

Source: https://docs.rs/irontide/1.7.0/irontide/client/struct.ClientBuilder.html

Demonstrates the fluent builder pattern to configure and start a new torrent session.

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

--------------------------------

### Session Initialization Methods

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Methods to start a new session with various configurations including plugins, disk backends, and network factories.

```APIDOC
## SessionHandle::start

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

### Signature
`pub async fn start(settings: Settings) -> Result<SessionHandle, Error>`

## SessionHandle::start_with_backend

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

### Signature
`pub async fn start_with_backend(settings: Settings, backend: Arc<dyn DiskIoBackend>) -> Result<SessionHandle, Error>`

## SessionHandle::start_with_plugins

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

### Signature
`pub async fn start_with_plugins(settings: Settings, plugins: Arc<Vec<Box<dyn ExtensionPlugin>>>) -> Result<SessionHandle, Error>`

## SessionHandle::start_with_plugins_and_backend

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

### Signature
`pub async fn start_with_plugins_and_backend(settings: Settings, plugins: Arc<Vec<Box<dyn ExtensionPlugin>>>, backend: Arc<dyn DiskIoBackend>) -> Result<SessionHandle, Error>`

## SessionHandle::start_with_transport

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

### Signature
`pub async fn start_with_transport(settings: Settings, factory: Arc<NetworkFactory>) -> Result<SessionHandle, Error>`

## SessionHandle::start_full

### Description
Start a new session with all customizable parameters.

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

--------------------------------

### Start NatActor

Source: https://docs.rs/irontide/1.7.0/irontide/nat/actor/struct.NatHandle.html

Spawns a NatActor and returns a handle and an event receiver.

```rust
pub fn start(config: NatConfig) -> (NatHandle, Receiver<NatEvent>)
```

--------------------------------

### bind

Source: https://docs.rs/irontide/1.7.0/irontide/utp/struct.UtpSocket.html

Binds a UDP socket and starts the actor with default settings.

```APIDOC
## pub async fn bind(config: UtpConfig) -> Result<(UtpSocket, UtpListener), Error>

### Description
Binds a UDP socket and starts the actor with no global admit gate. This is a backwards-compatible wrapper that uses `AdmitGate::unlimited`.

### Errors
Returns an error if the UDP socket cannot be bound to the configured address.
```

--------------------------------

### Construct Box from raw pointer

Source: https://docs.rs/irontide/1.7.0/irontide/session/type.StorageFactory.html

Examples demonstrating how to recreate a Box from a raw pointer or manually allocate memory for a Box using the system allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(5, System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };
```

```rust
#![feature(allocator_api, slice_ptr_get)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, System);
}
```

--------------------------------

### Demonstrating ambiguous From implementation

Source: https://docs.rs/irontide/1.7.0/irontide/session/type.StorageFactory.html

An example of a discouraged From implementation that causes ambiguity with Pin::from.

```rust
struct Foo; // A type defined in this crate.
impl From<Box<()>> for Pin<Foo> {
    fn from(_: Box<()>) -> Pin<Foo> {
        Pin::new(Foo)
    }
}
```

--------------------------------

### bind_with_admit_gate

Source: https://docs.rs/irontide/1.7.0/irontide/utp/struct.UtpSocket.html

Binds a UDP socket and starts the actor wired into a session-global admit gate.

```APIDOC
## pub async fn bind_with_admit_gate(config: UtpConfig, admit: AdmitGate) -> Result<(UtpSocket, UtpListener), Error>

### Description
Binds and starts the actor wired into the session-global admit gate, enforcing IP filtering and connection caps.

### Errors
Returns an error if the UDP socket cannot be bound to the configured address.
```

--------------------------------

### Construct Box from NonNull pointer

Source: https://docs.rs/irontide/1.7.0/irontide/session/type.StorageFactory.html

Examples demonstrating how to recreate a Box from a NonNull pointer or manually allocate memory for a Box using the system allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(5, System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
let x = unsafe { Box::from_non_null_in(non_null, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let non_null = System.allocate(Layout::new::<i32>())?.cast::<i32>();
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null_in(non_null, System);
}
```

--------------------------------

### get_download_queue

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Get in-flight piece download status for a torrent.

```APIDOC
## get_download_queue(info_hash: Id20)

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

### Parameters
- **info_hash** (Id20) - Required - The identifier of the torrent.

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

--------------------------------

### Copying Result Contents

Source: https://docs.rs/irontide/1.7.0/irontide/core/type.Result.html

Examples of using .copied() and .cloned() to transform Result<&T, E> into Result<T, E>.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### ClientBuilder API

Source: https://docs.rs/irontide/1.7.0/irontide/client/struct.ClientBuilder.html

The ClientBuilder allows for the configuration of a torrent session. Methods are chained to set various parameters, and the session is initialized by calling start().

```APIDOC
## ClientBuilder

### Description
An ergonomic builder for creating a torrent session. It wraps settings and provides a fluent API to configure the session before spawning the session actor.

### Methods
- **new() -> Self**: Create a new builder with default settings.
- **from_settings(settings: Settings) -> Self**: Create a builder from an existing Settings struct.
- **add_extension(plugin: Box<dyn ExtensionPlugin>) -> Self**: Register a custom BEP 10 extension plugin.
- **listen_port(port: u16) -> Self**: Set the TCP listen port.
- **download_dir(path: impl Into<PathBuf>) -> Self**: Set the default download directory.
- **max_torrents(n: usize) -> Self**: Set the maximum number of concurrent torrents.
- **enable_dht(v: bool) -> Self**: Enable or disable DHT peer discovery.
- **enable_lsd(v: bool) -> Self**: Enable or disable Local Service Discovery.
- **enable_pex(v: bool) -> Self**: Enable or disable Peer Exchange.
- **enable_fast_extension(v: bool) -> Self**: Enable or disable BEP 6 Fast Extension.
- **seed_ratio_limit(ratio: f64) -> Self**: Set the seed ratio limit.
- **alert_mask(mask: AlertCategory) -> Self**: Set the alert category mask.
- **alert_channel_size(size: usize) -> Self**: Set the alert broadcast channel capacity.
- **active_downloads(n: i32) -> Self**: Set the maximum number of concurrent auto-managed downloading torrents.
- **active_seeds(n: i32) -> Self**: Set the maximum number of concurrent auto-managed seeding torrents.
- **active_limit(n: i32) -> Self**: Set the hard cap on all active auto-managed torrents.
- **active_checking(n: i32) -> Self**: Set the maximum number of concurrent hash-check operations.
- **dont_count_slow_torrents(v: bool) -> Self**: Set whether inactive torrents are exempt from limits.
- **auto_manage_interval(secs: u64) -> Self**: Set the interval between queue evaluations.
- **auto_manage_startup(secs: u64) -> Self**: Set the startup grace period.
- **auto_manage_prefer_seeds(v: bool) -> Self**: Set whether seeding slots are allocated before download slots.
- **encryption_mode(mode: EncryptionMode) -> Self**: Set the connection encryption mode.
- **enable_utp(v: bool) -> Self**: Enable or disable uTP.
- **enable_upnp(v: bool) -> Self**: Enable or disable UPnP IGD port mapping.
- **enable_natpmp(v: bool) -> Self**: Enable or disable NAT-PMP / PCP port mapping.
- **enable_holepunch(v: bool) -> Self**: Enable or disable BEP 55 holepunch extension.
- **enable_ipv6(v: bool) -> Self**: Enable or disable IPv6 dual-stack support.

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

--------------------------------

### fetch_text

Source: https://docs.rs/irontide/1.7.0/irontide/nat/upnp/soap/fn.fetch_text.html

Fetches text content from an HTTP URL via raw TCP GET.

```APIDOC
## fetch_text

### Description
Fetches text content from an HTTP URL via raw TCP GET.

### Signature
`pub async fn fetch_text(url: &str) -> Result<String, Error>`

### Parameters
- **url** (&str) - The URL to fetch text content from.

### Errors
Returns an error if the URL is invalid, the TCP connection fails, or the request times out.
```

--------------------------------

### pub fn parse_dat(input: &str) -> Result<IpFilter, IpFilterError>

Source: https://docs.rs/irontide/1.7.0/irontide/session/fn.parse_dat.html

Parses an eMule .dat format blocklist. The expected format is 'first_ip - last_ip , level , description', with lines starting with '#' treated as comments.

```APIDOC
## parse_dat

### Description
Parses an eMule .dat format blocklist. Lines starting with '#' are ignored as comments.

### Signature
`pub fn parse_dat(input: &str) -> Result<IpFilter, IpFilterError>`

### Parameters
- **input** (&str) - The raw string content of the .dat blocklist file.

### Returns
- **Result<IpFilter, IpFilterError>** - Returns an IpFilter object on success, or an IpFilterError if the data cannot be parsed.
```

--------------------------------

### pub async fn send_request

Source: https://docs.rs/irontide/1.7.0/irontide/nat/natpmp/fn.send_request.html

Sends a NAT-PMP request to the gateway and waits for a response. Uses exponential backoff retransmission starting at 250ms, doubling each attempt up to MAX_ATTEMPTS.

```APIDOC
## Function: send_request

### Signature
`pub async fn send_request(gateway: Ipv4Addr, request: &[u8]) -> Result<Vec<u8>, Error>`

### Description
Sends a NAT-PMP request to the gateway and waits for a response. The function implements exponential backoff retransmission starting at 250ms, doubling each attempt up to MAX_ATTEMPTS.

### Parameters
- **gateway** (Ipv4Addr) - The IPv4 address of the NAT-PMP gateway.
- **request** (&[u8]) - The byte slice containing the NAT-PMP request payload.

### Returns
- **Result<Vec<u8>, Error>** - Returns a Result containing the response bytes on success, or an Error on socket I/O failure or if all retransmission attempts time out.
```

--------------------------------

### Leaking a Box

Source: https://docs.rs/irontide/1.7.0/irontide/session/type.StorageFactory.html

Examples of consuming a Box to produce a mutable reference with a static lifetime.

```rust
let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);
```

```rust
let x = vec![1, 2, 3].into_boxed_slice();
let static_ref = Box::leak(x);
static_ref[0] = 4;
assert_eq!(*static_ref, [4, 2, 3]);
```

--------------------------------

### queue_position

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Get the queue position of a torrent.

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

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

### Errors
Returns an error if the session is shut down.
```

--------------------------------

### session_stats

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Get aggregate session statistics.

```APIDOC
## pub async fn session_stats(&self) -> Result<SessionStats, Error>

### Description
Get aggregate session statistics.

### Errors
Returns an error if the session is shut down.
```

--------------------------------

### max_uploads

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.TorrentHandle.html

Gets the maximum number of uploads.

```APIDOC
## pub async fn max_uploads(&self) -> Result<usize, Error>

### Description
Returns the maximum allowed number of uploads for this torrent.

### Errors
Returns `crate::Error::Shutdown` if the torrent actor has stopped.
```

--------------------------------

### max_connections

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.TorrentHandle.html

Gets the maximum number of connections.

```APIDOC
## pub async fn max_connections(&self) -> Result<usize, Error>

### Description
Returns the maximum allowed number of connections for this torrent.

### Errors
Returns `crate::Error::Shutdown` if the torrent actor has stopped.
```

--------------------------------

### ClientBuilder Configuration Methods

Source: https://docs.rs/irontide/1.7.0/irontide/client/struct.ClientBuilder.html

Methods for configuring the session parameters prior to startup.

```APIDOC
## ClientBuilder Configuration

### stats_report_interval(ms: u64) -> Self
Sets the interval in milliseconds for periodic SessionStatsAlert emissions. Default is 1000ms; 0 disables periodic alerts.

### dht_saved_nodes(nodes: Vec<String>) -> Self
Provides previously saved DHT routing table nodes to accelerate the bootstrap process.

### dht_node_id(id: Id20) -> Self
Reuses a persisted BEP 42-compliant DHT node ID to maintain routing table consistency across sessions.

### runtime_worker_threads(n: usize) -> Self
Configures the number of tokio worker threads. Setting to 0 uses the default.

### pin_cores(v: bool) -> Self
Enables or disables pinning of tokio worker threads to CPU cores for improved cache locality.

### disk_io_backend(backend: Arc<dyn DiskIoBackend>) -> Self
Sets a custom disk I/O backend, overriding the default positioned-write implementation.
```

--------------------------------

### upload_limit

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.TorrentHandle.html

Gets the current upload limit.

```APIDOC
## pub async fn upload_limit(&self) -> Result<u64, Error>

### Description
Returns the current upload limit in bytes per second.

### Errors
Returns `crate::Error::Shutdown` if the torrent actor has stopped.
```

--------------------------------

### download_limit

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.TorrentHandle.html

Gets the current download limit.

```APIDOC
## pub async fn download_limit(&self) -> Result<u64, Error>

### Description
Returns the current download limit in bytes per second.

### Errors
Returns `crate::Error::Shutdown` if the torrent actor has stopped.
```

--------------------------------

### NatHandle::start

Source: https://docs.rs/irontide/1.7.0/irontide/nat/actor/struct.NatHandle.html

Spawns a NatActor and returns a handle along with an event receiver.

```APIDOC
## pub fn start(config: NatConfig) -> (NatHandle, Receiver<NatEvent>)

### Description
Spawns a `NatActor` and returns a handle plus an event receiver for monitoring NAT events.
```

--------------------------------

### stats

Source: https://docs.rs/irontide/1.7.0/irontide/dht/struct.DhtHandle.html

Get current DHT statistics.

```APIDOC
## pub async fn stats(&self) -> Result<DhtStats, Error>

### Description
Get current DHT statistics.

### Errors
Returns Error::Shutdown if the actor has stopped.
```

--------------------------------

### Create DiskManagerHandle

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.DiskManagerHandle.html

Methods to initialize the disk manager with either default or custom backends.

```rust
pub fn new(config: DiskConfig) -> (DiskManagerHandle, JoinHandle<()>)
```

```rust
pub fn new_with_backend( config: DiskConfig, backend: Arc<dyn DiskIoBackend>, spawner: BlockingSpawner, ) -> (DiskManagerHandle, JoinHandle<()>)
```

--------------------------------

### dht_node_count

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.SessionHandle.html

Gets the current DHT routing-table size.

```APIDOC
## dht_node_count() -> Result<usize, Error>

### Description
Get the current DHT routing-table size, summed across IPv4 and IPv6 instances.

### Errors
Returns an error if the session is shut down.
```

--------------------------------

### DiskManagerHandle::new

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.DiskManagerHandle.html

Creates a new disk manager with the default backend selected from the provided configuration.

```APIDOC
## pub fn new(config: DiskConfig) -> (DiskManagerHandle, JoinHandle<()>) 

### Description 
Creates a new disk manager with the default backend selected from config. Returns the handle and a JoinHandle for the background actor task.
```

--------------------------------

### info_hashes

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Get the torrent’s identity hashes.

```APIDOC
## info_hashes(info_hash: Id20)

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

### Parameters
- **info_hash** (Id20) - Required - The identifier of the torrent.

### Errors
Returns an error if the session is shut down.
```

--------------------------------

### banned_peers

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.SessionHandle.html

Gets the list of currently banned peer IPs.

```APIDOC
## banned_peers() -> Result<Vec<IpAddr>, Error>

### Description
Get the list of currently banned peer IPs.

### Errors
Returns an error if the session is shut down.
```

--------------------------------

### piece_availability

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Get per-piece availability counts from connected peers.

```APIDOC
## piece_availability(info_hash: Id20)

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

### Parameters
- **info_hash** (Id20) - Required - The identifier of the torrent.

### Errors
Returns an error if the session is shut down.
```

--------------------------------

### Construct a SigningKey from bytes

Source: https://docs.rs/irontide/1.7.0/irontide/dht/struct.Ed25519SigningKey.html

Demonstrates initializing a SigningKey using a 32-byte secret key array.

```rust
use ed25519_dalek::SigningKey;
use ed25519_dalek::SECRET_KEY_LENGTH;
use ed25519_dalek::SignatureError;

let secret_key_bytes: [u8; SECRET_KEY_LENGTH] = [
   157, 097, 177, 157, 239, 253, 090, 096,
   186, 132, 074, 244, 146, 236, 044, 196,
   068, 073, 197, 105, 123, 050, 105, 025,
   112, 059, 172, 003, 028, 174, 127, 096, ];

let signing_key: SigningKey = SigningKey::from_bytes(&secret_key_bytes);
assert_eq!(signing_key.to_bytes(), secret_key_bytes);
```

--------------------------------

### Construct a VerifyingKey from bytes

Source: https://docs.rs/irontide/1.7.0/irontide/dht/struct.Ed25519VerifyingKey.html

Demonstrates how to initialize a VerifyingKey from a byte array. Note that this method performs ZIP-215 point validation.

```rust
use ed25519_dalek::VerifyingKey;
use ed25519_dalek::PUBLIC_KEY_LENGTH;
use ed25519_dalek::SignatureError;

let public_key_bytes: [u8; PUBLIC_KEY_LENGTH] = [
   215,  90, 152,   1, 130, 177,  10, 183, 213,  75, 254, 211, 201, 100,   7,  58,
    14, 225, 114, 243, 218, 166,  35,  37, 175,   2,  26, 104, 247,   7,   81, 26];

let public_key = VerifyingKey::from_bytes(&public_key_bytes)?;
```

--------------------------------

### max_uploads

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Get the current per-torrent maximum upload slots.

```APIDOC
## max_uploads(info_hash: Id20)

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

### Parameters
- **info_hash** (Id20) - Required - The identifier of the torrent.

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

--------------------------------

### UdpTracker::new

Source: https://docs.rs/irontide/1.7.0/irontide/tracker/struct.UdpTracker.html

Creates a new UDP tracker client with default settings.

```APIDOC
## pub fn new() -> UdpTracker

### Description
Creates a new UDP tracker client with default settings.
```

--------------------------------

### max_connections

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

Get the current per-torrent maximum connection limit.

```APIDOC
## max_connections(info_hash: Id20)

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

### Parameters
- **info_hash** (Id20) - Required - The identifier of the torrent.

### Errors
Returns an error if the connection or binding fails.
```

--------------------------------

### pub async fn discover_control_url(timeout: Duration) -> Result<(String, String), Error>

Source: https://docs.rs/irontide/1.7.0/irontide/nat/upnp/fn.discover_control_url.html

Discovers the UPnP IGD control URL by searching for gateway devices and parsing the device description XML.

```APIDOC
## discover_control_url

### Description
Discover the UPnP IGD control URL. This function performs SSDP M-SEARCH (v1 + v2) to find the gateway device, probes the default gateway directly on common UPnP ports if SSDP fails, fetches the device description XML, and parses the controlURL for WANIPConnection or WANPPPConnection.

### Signature
`pub async fn discover_control_url(timeout: Duration) -> Result<(String, String), Error>`

### Parameters
- **timeout** (Duration) - The duration to wait for discovery operations.

### Returns
- **Result<(String, String), Error>** - Returns a tuple containing the control URL and device information on success, or an error if discovery fails.
```

--------------------------------

### Alert::new

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.Alert.html

Creates a new Alert instance with the current system time.

```APIDOC
## Alert::new(kind: AlertKind) -> Alert

### Description
Creates a new alert with the current wall-clock time.

### Parameters
- **kind** (AlertKind) - Required - The specific event that occurred.
```

--------------------------------

### DiskManagerHandle::new_with_backend

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.DiskManagerHandle.html

Creates a new disk manager with a custom disk I/O backend.

```APIDOC
## pub fn new_with_backend(config: DiskConfig, backend: Arc<dyn DiskIoBackend>, spawner: BlockingSpawner) -> (DiskManagerHandle, JoinHandle<()>) 

### Description 
Create a new disk manager with a custom disk I/O backend. Returns the handle and a JoinHandle for the background actor task.
```

--------------------------------

### lsd_peer_count

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.SessionHandle.html

Gets the cumulative count of unique peers received via LSD.

```APIDOC
## lsd_peer_count(info_hash: Id20) -> Result<usize, Error>

### Description
Cumulative count of UNIQUE peers received via LSD (BEP 14) multicast for this torrent since the actor started.

### Errors
Returns Error::TorrentNotFound when the hash is unknown or Error::Shutdown on actor shutdown.
```

--------------------------------

### connect

Source: https://docs.rs/irontide/1.7.0/irontide/utp/struct.UtpSocket.html

Establishes a connection to a remote peer.

```APIDOC
## pub async fn connect(&self, addr: SocketAddr) -> Result<UtpStream, Error>

### Description
Connects to a remote peer and awaits until the connection is established.

### Errors
Returns an error if the socket actor has shut down or the connection attempt fails.
```

--------------------------------

### pex_peer_count

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.SessionHandle.html

Gets the cumulative count of unique peers received via PEX.

```APIDOC
## pex_peer_count(info_hash: Id20) -> Result<usize, Error>

### Description
Cumulative count of UNIQUE peers received via PEX (BEP 11) for this torrent since the actor started.

### Errors
Returns Error::TorrentNotFound when the hash is unknown or Error::Shutdown on actor shutdown.
```

--------------------------------

### HttpTracker Initialization Methods

Source: https://docs.rs/irontide/1.7.0/irontide/tracker/struct.HttpTracker.html

Various constructors for creating an HttpTracker instance with different security and connectivity configurations.

```rust
pub fn new() -> HttpTracker
```

```rust
pub fn with_anonymous() -> HttpTracker
```

```rust
pub fn with_proxy(proxy_url: Option<&str>) -> HttpTracker
```

```rust
pub fn with_security( proxy_url: Option<&str>, validate_tls: bool, ssrf_mitigation: bool, ) -> HttpTracker
```

--------------------------------

### Get local address

Source: https://docs.rs/irontide/1.7.0/irontide/utp/struct.UtpListener.html

Retrieves the local address to which the listener is currently bound.

```rust
pub fn local_addr(&self) -> SocketAddr
```

--------------------------------

### build_server_config

Source: https://docs.rs/irontide/1.7.0/irontide/wire/ssl/fn.build_server_config.html

Builds a rustls ServerConfig using the provided SSL configuration. Returns an error if certificates or keys are invalid or cannot be parsed.

```APIDOC
## Function: build_server_config

### Description
Builds a rustls `ServerConfig` using the provided certificate and key information from the `SslConfig` object.

### Signature
`pub fn build_server_config(config: &SslConfig) -> Result<Arc<ServerConfig>, Error>`

### Parameters
- **config** (&SslConfig) - Required - The SSL configuration containing the necessary certificate and key data.

### Returns
- **Result<Arc<ServerConfig>, Error>** - Returns an `Arc<ServerConfig>` on success, or an `Error` if the certificates or key cannot be parsed or are invalid.
```

--------------------------------

### QbtCompatSettings Struct Definition

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.QbtCompatSettings.html

The structure containing configuration fields for the qBittorrent WebUI compatibility layer.

```rust
pub struct QbtCompatSettings {Show 20 fields
    pub enabled: bool,
    pub username: String,
    pub password_hash: String,
    pub password: String,
    pub spoof_app_version: String,
    pub spoof_webapi_version: String,
    pub session_ttl_secs: u64,
    pub max_sessions: usize,
    pub max_concurrent_argon2_ops: Option<u32>,
    pub port: u16,
    pub bind_address: String,
    pub csrf_protection_enabled: bool,
    pub host_header_validation_enabled: bool,
    pub web_ui_reverse_proxy_enabled: bool,
    pub web_ui_reverse_proxies_list: Vec<String>,
    pub max_failed_auth_count: u32,
    pub ban_duration_secs: u64,
    pub bypass_local_auth: bool,
    pub bypass_auth_subnet_whitelist: Vec<String>,
    pub brute_force_registry_capacity: Option<usize>,
}
```

--------------------------------

### from_torrent

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.TorrentHandle.html

Creates a torrent session from parsed .torrent metadata and spawns the actor event loop.

```APIDOC
## pub async fn from_torrent(...)

### Description
Create a torrent session from parsed .torrent metadata. Spawns the actor event loop and returns a handle for sending commands.

### Errors
Returns an error if disk registration fails or the torrent actor cannot be started.
```

--------------------------------

### Manually create Box from raw pointer

Source: https://docs.rs/irontide/1.7.0/irontide/session/type.StorageFactory.html

Manually create a Box from scratch by using the global allocator.

```rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
```

--------------------------------

### Accept incoming uTP connections

Source: https://docs.rs/irontide/1.7.0/irontide/utp/struct.UtpListener.html

Asynchronously accepts the next incoming connection, returning the stream and the remote peer's address.

```rust
pub async fn accept(&mut self) -> Result<(UtpStream, SocketAddr), Error>
```

--------------------------------

### Clone from reference

Source: https://docs.rs/irontide/1.7.0/irontide/session/type.StorageFactory.html

Experimental APIs to allocate memory and clone a reference into the new box.

```rust
#![feature(clone_from_ref)]

let hello: Box<str> = Box::clone_from_ref("hello");
```

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

let hello: Box<str> = Box::try_clone_from_ref("hello")?;
```

--------------------------------

### parse_p2p

Source: https://docs.rs/irontide/1.7.0/irontide/session/fn.parse_p2p.html

Parses a P2P plaintext format blocklist. The expected format is 'description:first_ip-last_ip', with lines starting with '#' treated as comments.

```APIDOC
## pub fn parse_p2p(input: &str) -> Result<IpFilter, IpFilterError>

### Description
Parses a P2P plaintext format blocklist. Lines starting with '#' are ignored as comments.

### Parameters
- **input** (&str) - Required - The P2P plaintext blocklist string to parse.

### Returns
- **Result<IpFilter, IpFilterError>** - Returns an IpFilter on success, or an IpFilterError if the data cannot be parsed or I/O fails.
```

--------------------------------

### migrate_qbt_credentials Function Signature

Source: https://docs.rs/irontide/1.7.0/irontide/session/fn.migrate_qbt_credentials.html

The function signature for migrating qBittorrent credentials, returning a migration result or an error.

```rust
pub fn migrate_qbt_credentials(
    qbt: &mut QbtCompatSettings,
) -> Result<QbtCredentialMigration, QbtMigrationError>
```

--------------------------------

### FileStream Implementation Methods

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.FileStream.html

Methods for constructing a FileStream and retrieving file metadata.

```rust
pub fn from_handle(h: FileStreamHandle) -> FileStream
```

```rust
pub fn file_length(&self) -> u64
```

```rust
pub fn position(&self) -> u64
```

--------------------------------

### set_geometry

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/trait.DiskIoBackend.html

Registers a torrent’s piece geometry for hash-on-arrival. This must be called before peers start writing blocks to enable incremental hashing.

```APIDOC
## fn set_geometry(&self, _info_hash: Id20, _lengths: Lengths, _want_v2: bool)

### Description
Register a torrent’s piece geometry for hash-on-arrival. Once geometry is known, the backend can feed landing blocks into an incremental hasher to verify pieces without read-back.

### Parameters
- **_info_hash** (Id20) - The identifier for the torrent.
- **_lengths** (Lengths) - The piece geometry lengths.
- **_want_v2** (bool) - Whether to record per-block SHA-256 Merkle leaves.
```

--------------------------------

### Configuration and Limits

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.TorrentHandle.html

Methods to configure download/upload limits, connections, and seeding modes.

```APIDOC
## set_download_limit(bytes_per_sec: u64)
### Description
Sets the download limit for the torrent.

## set_upload_limit(bytes_per_sec: u64)
### Description
Sets the upload limit for the torrent.

## set_max_connections(limit: usize)
### Description
Sets the maximum number of connections for the torrent.

## set_max_uploads(limit: usize)
### Description
Sets the maximum number of uploads for the torrent.
```

--------------------------------

### TorrentSavePathContext Implementation Methods

Source: https://docs.rs/irontide/1.7.0/irontide/session/struct.TorrentSavePathContext.html

Methods for creating a default context and resolving path tokens.

```rust
pub fn new(added_at_utc_secs: i64) -> TorrentSavePathContext
```

```rust
pub fn primary_tracker_host(&self) -> &str
```

```rust
pub fn classified_content_type(&self) -> &'static str
```

--------------------------------

### HashPicker Implementation Methods

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.HashPicker.html

Methods for managing hash requests, including creation, picking, adding, and verification.

```rust
pub fn new(files: &[FileHashInfo], blocks_per_piece: u32) -> HashPicker
```

```rust
pub fn pick_hashes( &self, has_piece: impl Fn(u32) -> bool, ) -> Option<HashRequest>
```

```rust
pub fn add_hashes( &mut self, req: &HashRequest, hashes: &[Id32], ) -> Result<AddHashesResult, Error>
```

```rust
pub fn set_block_hash( &mut self, file_index: usize, block_index: u32, hash: Id32, ) -> SetBlockResult
```

```rust
pub fn verify_block_hashes(&mut self, piece: u32)
```

```rust
pub fn hashes_rejected(&mut self, req: &HashRequest)
```

```rust
pub fn have_piece_hash(&self, file_index: usize, piece: u32) -> bool
```

```rust
pub fn piece_verified(&self, file_index: usize, piece: u32) -> bool
```

```rust
pub fn tree_depth(&self, file_index: usize) -> Option<u32>
```

```rust
pub fn load_piece_layers( &mut self, piece_layers: &BTreeMap<Id32, Vec<u8>>, ) -> Vec<u32>
```

--------------------------------

### pub async fn accept(&mut self) -> Result<(UtpStream, SocketAddr), Error>

Source: https://docs.rs/irontide/1.7.0/irontide/utp/struct.UtpListener.html

Accepts the next incoming uTP connection. Returns a tuple containing the UtpStream and the remote peer's SocketAddr.

```APIDOC
## pub async fn accept(&mut self) -> Result<(UtpStream, SocketAddr), Error>

### Description
Accepts the next incoming connection. Returns the stream and the remote peer’s address.

### Errors
Returns an error if the listener has been shut down.
```

--------------------------------

### into_ok

Source: https://docs.rs/irontide/1.7.0/irontide/core/type.Result.html

Returns the contained Ok value, but never panics.

```APIDOC
## pub const fn into_ok(self) -> T

### Description
Returns the contained `Ok` value, but never panics. This method is known to never panic on the result types it is implemented for.

### Parameters
- **self** (Result<T, E>) - The Result instance.

### Returns
- **T** - The contained `Ok` value.
```

--------------------------------

### MerkleTreeState Methods

Source: https://docs.rs/irontide/1.7.0/irontide/core/struct.MerkleTreeState.html

Methods for initializing and interacting with the MerkleTreeState, including verification logic.

```rust
pub fn new(root: Id32, num_blocks: u32, num_pieces: u32) -> MerkleTreeState
```

```rust
pub fn root(&self) -> Id32
```

```rust
pub fn num_pieces(&self) -> u32
```

```rust
pub fn num_blocks(&self) -> u32
```

```rust
pub fn has_piece_hash(&self, piece_index: u32) -> bool
```

```rust
pub fn set_piece_hashes(&mut self, hashes: Vec<Id32>)
```

```rust
pub fn set_piece_hashes_and_verify( &mut self, hashes: Vec<Id32>, blocks_per_piece: u32, ) -> Vec<u32>
```

```rust
pub fn set_block_hash(&mut self, block_index: u32, hash: Id32) -> SetBlockResult
```

```rust
pub fn is_block_verified(&self, block_index: u32) -> bool
```

```rust
pub fn piece_verified(&self, piece_index: u32, blocks_per_piece: u32) -> bool
```

```rust
pub fn piece_hashes(&self) -> Option<&[Id32]>
```

--------------------------------

### ClientBuilder Configuration Methods

Source: https://docs.rs/irontide/1.7.0/irontide/client/struct.ClientBuilder.html

A collection of configuration methods available on the ClientBuilder to customize client behavior.

```APIDOC
## ClientBuilder Configuration

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

### allow_i2p_mixed(v: bool)
Allow mixing I2P and clearnet peers. Default: false.

### ssl_listen_port(v: u16)
Set the TCP listen port for incoming SSL torrent connections. Default: 0 (disabled).

### ssl_cert_path(v: impl Into<PathBuf>)
Set the path to a PEM-encoded certificate file for SSL torrent connections.

### ssl_key_path(v: impl Into<PathBuf>)
Set the path to a PEM-encoded private key file for SSL torrent connections.

### disk_channel_capacity(n: usize)
Set the disk I/O channel capacity. Default: 1024.

### seed_choking_algorithm(algorithm: SeedChokingAlgorithm)
Set the seed-mode choking algorithm.

### choking_algorithm(algorithm: ChokingAlgorithm)
Set the choking algorithm.

### piece_extent_affinity(enabled: bool)
Enable or disable piece extent affinity for disk cache locality. Default: true.

### suggest_mode(enabled: bool)
Enable or disable suggest mode (BEP 6 SuggestPiece). Default: false.

### max_suggest_pieces(count: usize)
Set the maximum number of SuggestPiece messages per peer. Default: 10.

### predictive_piece_announce(ms: u64)
Set the predictive piece announce delay in milliseconds. Default: 0 (disabled).

### mixed_mode_algorithm(algorithm: MixedModeAlgorithm)
Set the mixed-mode TCP/uTP bandwidth allocation algorithm.

### auto_sequential(enable: bool)
Enable or disable automatic sequential mode switching.

### max_metadata_size(bytes: u64)
Set the maximum BEP 9 metadata size accepted from peers. Default: 4 MiB.

### max_message_size(bytes: usize)
Set the maximum wire protocol message size. Default: 16 MiB.

### max_piece_length(bytes: u64)
Set the maximum accepted piece length when adding a torrent. Default: 32 MiB.

### max_outstanding_requests(n: usize)
Set the maximum outstanding incoming requests per peer. Default: 500.

### ssrf_mitigation(v: bool)
Enable or disable SSRF mitigation for tracker and web seed URLs. Default: true.

### allow_idna(v: bool)
Allow or reject internationalised (non-ASCII) domain names in URLs. Default: false.

### validate_https_trackers(v: bool)
Enable or disable HTTPS validation for HTTP tracker announces. Default: true.

### peer_dscp(dscp: u8)
Set the DSCP value for peer traffic (TCP and uTP). Default: 0x08.
```

--------------------------------

### pub fn auto_piece_size(total: u64) -> u64

Source: https://docs.rs/irontide/1.7.0/irontide/core/fn.auto_piece_size.html

Calculates the optimal piece size for a given total content size.

```APIDOC
## pub fn auto_piece_size(total: u64) -> u64

### Description
Auto-selects the piece size based on the total content size using libtorrent-style logic.

### Parameters
- **total** (u64) - The total size of the content.

### Returns
- **u64** - The calculated piece size.
```

--------------------------------

### connect_peer

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.TorrentHandle.html

Initiates a peer connection to the specified address.

```APIDOC
## pub async fn connect_peer(&self, addr: SocketAddr) -> Result<(), Error>

### Description
Immediately initiate a peer connection to the given address, bypassing the normal peer selection queue.

### Errors
Returns an error if the connection or binding fails.
```

--------------------------------

### pub async fn discover_igd(timeout: Duration) -> Result<String, Error>

Source: https://docs.rs/irontide/1.7.0/irontide/nat/upnp/ssdp/fn.discover_igd.html

Discovers an Internet Gateway Device via SSDP multicast by sending an M-SEARCH request. It filters responses to return only valid IGD v1 or v2 location URLs.

```APIDOC
## discover_igd

### Description
Sends an M-SEARCH request to discover an Internet Gateway Device (IGD) via SSDP multicast. It specifically targets IGD v1 and v2 devices and returns the first valid LOCATION URL found, ignoring non-IGD responders.

### Signature
`pub async fn discover_igd(timeout: Duration) -> Result<String, Error>`

### Parameters
- **timeout** (Duration) - The duration to wait for a response before timing out.

### Returns
- **Result<String, Error>** - Returns the LOCATION URL of the discovered IGD on success, or an Error if a socket I/O failure occurs or no IGD responds within the specified timeout.
```

--------------------------------

### pub async fn accept_tls<S>(stream: S, server_config: Arc<ServerConfig>) -> Result<TlsStream<S>, Error>

Source: https://docs.rs/irontide/1.7.0/irontide/wire/ssl/fn.accept_tls.html

Accepts a TLS connection on the server side using the provided stream and server configuration.

```APIDOC
## accept_tls

### Description
Accept a TLS connection on the server side.

### Signature
`pub async fn accept_tls<S>(stream: S, server_config: Arc<ServerConfig>) -> Result<TlsStream<S>, Error>`

### Parameters
- **stream** (S) - The underlying stream (must implement AsyncRead + AsyncWrite + Unpin).
- **server_config** (Arc<ServerConfig>) - The TLS server configuration.

### Returns
- **Result<TlsStream<S>, Error>** - Returns a TlsStream on success, or an Error if the TLS accept fails.
```

--------------------------------

### ClientBuilder Configuration Methods

Source: https://docs.rs/irontide/1.7.0/irontide/client/struct.ClientBuilder.html

Methods available on the ClientBuilder to configure client behavior.

```APIDOC
## ClientBuilder Configuration

### enable_web_seed(v: bool) -> Self
Enable or disable HTTP/web seeding. Default: true.

### super_seeding(v: bool) -> Self
Enable or disable BEP 16 super seeding. Default: false.

### upload_only_announce(v: bool) -> Self
Enable or disable BEP 21 upload-only announcement. Default: true.

### smart_ban_max_failures(n: u32) -> Self
Set the number of hash-failure involvements before a peer is auto-banned. Default: 3.

### smart_ban_parole(enabled: bool) -> Self
Enable or disable parole mode for smart banning. Default: true.

### disk_io_threads(n: usize) -> Self
Set the number of concurrent disk I/O threads. Default: 4.

### preallocate_mode(mode: PreallocateMode) -> Self
Set the file pre-allocation strategy. Default: PreallocateMode::None.

### hashing_threads(n: usize) -> Self
Set the number of concurrent piece hash verifications. Default: 2.

### max_request_queue_depth(n: usize) -> Self
Set the maximum per-peer request queue depth. Default: 250.

### request_queue_time(secs: f64) -> Self
Set the request queue time multiplier (seconds). Default: 3.0.

### block_request_timeout_secs(secs: u32) -> Self
Set the block request timeout in seconds. Default: 60.

### max_concurrent_stream_reads(n: usize) -> Self
Set the maximum concurrent file stream readers. Default: 8.

### proxy(proxy: ProxyConfig) -> Self
Set the proxy configuration for peer and tracker connections.

### force_proxy(v: bool) -> Self
Enable force proxy mode. Disables listen sockets, UPnP, NAT-PMP, DHT, and LSD.

### anonymous_mode(v: bool) -> Self
Enable anonymous mode. Suppresses identifying information and disables DHT, LSD, UPnP, and NAT-PMP.

### apply_ip_filter_to_trackers(v: bool) -> Self
Set whether the IP filter applies to tracker connections. Default: true.

### dht_queries_per_second(n: usize) -> Self
Set the DHT query rate. Default: 5.

### dht_query_timeout_secs(secs: u64) -> Self
Set the DHT query timeout in seconds. Default: 5.

### dht_enforce_node_id(v: bool) -> Self
Enforce node ID verification in the DHT routing table. Default: true.

### dht_restrict_routing_ips(v: bool) -> Self
Restrict the DHT routing table to one node per IP. Default: true.

### dht_max_items(v: usize) -> Self
Set the maximum number of stored DHT items. Default: 700.

### dht_item_lifetime_secs(v: u64) -> Self
Set the DHT item lifetime in seconds. Default: 7200.

### upnp_lease_duration(secs: u32) -> Self
Set the UPnP lease duration in seconds. Default: 3600.

### natpmp_lifetime(secs: u32) -> Self
Set the NAT-PMP mapping lifetime in seconds. Default: 3600.

### utp_max_connections(n: usize) -> Self
Set the maximum uTP connections. Default: 256.

### enable_i2p(v: bool) -> Self
Enable I2P anonymous network support.

### i2p_hostname(host: impl Into<String>) -> Self
Set the SAM bridge hostname. Default: 127.0.0.1.

### i2p_port(port: u16) -> Self
Set the SAM bridge port. Default: 7656.

### i2p_inbound_quantity(n: u8) -> Self
Set the number of inbound I2P tunnels. Default: 3.

### i2p_outbound_quantity(n: u8) -> Self
Set the number of outbound I2P tunnels. Default: 3.

### i2p_inbound_length(n: u8) -> Self
Set the number of hops in inbound I2P tunnels. Default: 3.
```

--------------------------------

### sample_infohashes

Source: https://docs.rs/irontide/1.7.0/irontide/dht/struct.DhtHandle.html

Queries a DHT node for a random sample of info hashes.

```APIDOC
## pub async fn sample_infohashes(&self, target: Id20) -> Result<SampleInfohashesResult, Error>

### Description
Query a DHT node for a random sample of info hashes (BEP 51). Routes toward the target to find the responding node.

### Parameters
- **target** (Id20) - Required - The target ID to route towards.

### Errors
- Returns `Error::Shutdown` if the actor has stopped.
```

--------------------------------

### load_resume_state

Source: https://docs.rs/irontide/1.7.0/irontide/prelude/struct.SessionHandle.html

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

```APIDOC
## pub async fn load_resume_state(&self) -> Result<ResumeLoadResult, Error>

### Description
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.

### Errors
Returns crate::Error::Shutdown if the session has been shut down.
```
Tokens:
Raw