Crate irontide_session 

BitTorrent session management: peers, torrents, and piece selection.

Modules

alert

Session alert stream: categories, kinds, and the broadcast surface. Alert/event system for push-based notifications.

apply

Transactional apply_settings skeleton with phase-ordered rollback (M173 Lane B). Transactional apply_settings skeleton with phase-ordered rollback (M173 Lane B, B1).

category_manager

qBt-compat category registry (M170). qBt-compat category registry (M170).

disk

Disk I/O manager: configuration, handles, and statistics.

disk_backend

Pluggable disk I/O backend trait and implementations. Pluggable disk I/O backend abstraction.

extension

Extension-protocol (BEP 10) plugin surface. Extension plugin interface for custom BEP 10 extensions.

hash_pool

Parallel SHA-1/SHA-256 piece-hashing pool. Dedicated thread pool for CPU-bound piece hash verification (M96).

i2p

I2P support via the SAM v3.1 bridge protocol.

notification

M226: engine-side OS notification dispatcher (completion + error toasts via notify-rust / zbus). M226: engine-side OS notification dispatcher.

resume_file

Resume file persistence: serialize, deserialize, atomic write, and directory helpers. Resume file persistence: serialize, deserialize, atomic write, and directory helpers.

save_path

Save-path token expansion (M173 Lane A — Decision 5). Save-path token expansion (M173 Lane A — Decision 5).

stats

Session statistics metric registry and atomic counter array.

streaming

Sequential / streaming file read surface. File streaming — AsyncRead + AsyncSeek over individual torrent files.

tag_manager

qBt-compat tag registry (M171). qBt-compat tag registry (M171).

transport

Network transport abstraction layer.

url_guard

SSRF-safe URL validation + redirect policy for user-supplied URLs. URL security validation — SSRF mitigation, IDNA rejection, HTTPS enforcement.

verify_before_download

Verify-Before-Download: fast file-size pre-scan (M205). Verify-Before-Download: fast file-size pre-scan (M205).

watched_folder

M226: engine-side watched-folder auto-add dispatcher (notify-debouncer-full → add_torrent). M226 Step 6: engine-side watched-folder subsystem.

Structs

AddTorrentParams

Unified parameters for SessionHandle::add_torrent (M170).

Alert

A timestamped event from the session or a torrent.

AlertCategory

Bitmask categories for filtering alerts.

AlertStream

A filtered view of the alert broadcast channel.

AppliedSettings

Classification of settings-patch fields into “took effect immediately” versus “requires session restart to apply”.

BanConfig

Configuration for smart banning behaviour.

BoxedStream

A type-erased bidirectional async stream.

CategoryMetadata

Metadata for a single category.

CategoryRegistry

In-memory category store, persisted to a single TOML file.

DebugDispatchState

Dispatch-level diagnostic counters (session-wide + per-torrent).

DebugPeerState

Per-peer debug state for diagnosing throughput issues.

DebugState

Top-level debug state snapshot for all torrents in the session.

DebugTorrentState

Per-torrent debug state including dispatch counters and peer details.

DhtNodeEntry

A DHT bootstrap node entry for session persistence.

DisabledDiskIo

No-op disk I/O backend for network throughput benchmarking.

DiskConfig

Configuration for the disk I/O subsystem.

DiskHandle

Per-torrent handle for async disk I/O.

DiskIoStats

Aggregate I/O statistics for a disk backend.

DiskJobFlags

Hint flags for disk I/O operations.

DiskManagerHandle

Session-level handle for managing the disk subsystem.

DiskStats

Disk I/O performance counters.

FileInfo

Info about a file within a torrent.

FileStatus

Status of a single file within a torrent.

FileStream

Async reader/seeker over a single file within a torrent.

HashPool

A thread pool dedicated to CPU-bound piece hash verification.

HashResult

Result of a hash verification.

I2pDestination

An I2P destination address (~516 bytes, Base64-encoded for display/storage).

IpFilter

IP address filter supporting both IPv4 and IPv6 ranges.

NetworkFactory

Factory for creating TCP listeners and outbound connections.

PartialPieceInfo

In-flight piece download status for the download queue.

PeerInfo

Per-peer details exported for client UI introspection.

PeerPipelineSnapshot

Point-in-time snapshot of the per-torrent peer-pipeline counters.

PeerStrikeEntry

A peer strike entry for session persistence.

Phase

A single phase of the transactional apply pipeline.

PortFilter

Port range filter.

ProxyConfig

Proxy connection settings.

QbtCompatSettings

qBittorrent WebUI v2 compatibility layer configuration.

ReconfigGuard

RAII guard returned by ReconfigInFlight::try_lock. Releases the slot when dropped.

ReconfigInFlight

In-flight reconfig guard. Used by SessionActor to detect concurrent setPreferences calls and reject the second one with ApplyError::ConcurrentReconfig.

ResumeLoadResult

Result of loading resume state from disk (M161 Phase 4).

SessionCounters

Atomic counter array shared between session and torrent actors.

SessionHandle

Cloneable handle for interacting with a running session.

SessionSnapshot

Lock-free read-model published by the [SessionActor] (M245 A1).

SessionState

Persisted session state containing a DHT node cache and torrent resume data.

SessionStats

Aggregate statistics for the whole session.

SessionStatsMetric

Static metadata for a single session metric.

Settings

Unified session settings (replaces SessionConfig).

TagRegistry

In-memory tag store, persisted to a single TOML file.

TorrentConfig

Configurable parameters for a torrent session.

TorrentFlags

Bitflag convenience wrapper for common torrent state flags.

TorrentHandle

Cloneable handle for interacting with a running torrent.

TorrentInfo

Metadata about a torrent (available after metadata is fetched).

TorrentSavePathContext

Per-torrent context used to expand {tracker} / {yyyy} / {mm} / {content_type} tokens.

TorrentStats

Aggregate statistics for a torrent.

TorrentSummary

Lightweight summary of a torrent for the HTTP API.

TrackerInfo

Public info about a single tracker.

WebSeedStats

Per-URL stats for a single web-seed source, surfaced to the qBt v2 /api/v2/torrents/webseeds endpoint and the GUI’s HTTP Sources tab.

Enums

AddSource

Source for a torrent add (M170).

AlertKind

The specific event that occurred.

ApplyError

Errors that can be returned by the transactional apply_settings path.

CategoryError

Errors from category registry operations.

ChokingAlgorithm

Top-level choking algorithm variant.

Error

Errors that can occur during session operations.

ExpandSavePathError

Errors from save-path expansion.

FileMode

Whether a file in a torrent is open and its I/O access mode.

HashJob

Job submitted to the hash pool.

I2pDestinationError

Error type for I2P destination parsing.

IpFilterError

Errors from parsing IP filter files.

MaxRatioAction

M171: Action taken when a torrent’s seed ratio reaches its configured limit.

MetricKind

Whether a metric is a monotonically increasing counter or a point-in-time gauge.

MixedModeAlgorithm

Mixed-mode bandwidth allocation algorithm for TCP/uTP coexistence.

PeerSource

Origin of a peer address.

ProxyType

Supported proxy protocols (matching libtorrent).

QbtCredentialMigration

Outcome of a legacy-plaintext migration pass (M172a A3 / C2).

QbtMigrationError

Errors raised by migrate_qbt_credentials.

ResumeFileError

Errors that can occur during resume file operations.

SeedChokingAlgorithm

Choking algorithm used when we are seeding.

SettingsError

Validation failure produced by Settings::validate.

SimpleContentType

Coarse content-type classification surfaced as {content_type}.

TagError

Errors raised by the tag registry.

TorrentState

Current state of a torrent.

TrackerStatus

Public tracker status (simplified view of internal TrackerState).

WebSeedState

Coarse state of a single web-seed source.

Constants

DEFAULT_ADMINADMIN_HASH

Argon2id PHC hash of the default “adminadmin” password (M172a A3).

NUM_METRICS

Total number of metrics tracked by the session.

Traits

DiskIoBackend

Trait for pluggable disk I/O backends.

ExtensionPlugin

A custom BEP 10 extension message handler.

TransportListener

An object-safe listener that accepts inbound connections.

Functions

apply_phases_with_rollback

Run a sequence of phases in order. On the first failure, roll back all already-applied phases in REVERSE order, then return the failure.

build_wanted_pieces

Build a bitfield marking which pieces are wanted based on file priorities.

default_resume_dir

Return the default resume directory.

expand_save_path_for_category

Convenience wrapper that pulls the save_path template out of a CategoryRegistry then delegates to expand_save_path_template.

expand_save_path_template

Expand the five locked tokens inside template against ctx.

hash_qbt_password

Hash plaintext with OWASP-recommended argon2id parameters and return the PHC-format encoded string (M172a).

migrate_qbt_credentials

One-shot legacy-plaintext → argon2id migration for QbtCompatSettings.

parse_dat

Parse an eMule .dat format blocklist.

parse_p2p

Parse a P2P plaintext format blocklist.

resolve_category_registry_path

Resolve the category registry path from settings, falling back to the standard XDG/platform location when no override is configured.

resolve_tag_registry_path

Resolve the filesystem path at which the tag registry is stored. If explicit is Some, use it verbatim; otherwise fall back to $XDG_CONFIG_HOME/irontide/tags.toml (via directories::ProjectDirs). Final fallback (e.g. if the XDG dirs cannot be resolved) is the relative path ./.irontide/tags.toml.

session_stats_metrics

Return static metadata for all session metrics.

validate_resume_bitfield

Returns true if the pieces bitfield has the correct length for num_pieces pieces (i.e. ceil(num_pieces / 8) bytes).

Type Aliases

Result

Convenience alias for Result<T, Error>.

StorageFactory

Type alias for a factory that creates per-torrent storage.