spill / docs · v0.7.6 · Source · Release notes

Rust library

Embed spill’s BitTorrent engine in your application to create torrents, download, seed, inspect magnets, and manage concurrent torrents without a separate daemon, SQLite catalog, CLI, or web server.

Dependencies and runtime

cargo add spill --no-default-features
cargo add tokio --features fs,macros,rt,net,time

The default daemon feature includes the binary and its CLI, database, and web dependencies. Disable it for engine-only applications. HTTP/TLS and filesystem support remain engine dependencies. Linux and macOS are supported.

Supply a Tokio runtime with I/O and time drivers enabled. Current-thread and multithread runtimes are supported; enable Tokio’s rt-multi-thread feature for the latter. spill creates no runtime, signal handler, or global tracing subscriber.

Download a torrent

Create an output directory first, then use spill::engine::download:

use spill::engine::{
    download,
    profile::Profile,
    torrent::{Destination, TorrentSource},
};

#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
    let bytes = tokio::fs::read("example.torrent").await?;
    let source = TorrentSource::Metainfo(Profile::default().parse_owned(&bytes)?);
    tokio::fs::create_dir_all("downloads").await?;
    download(source, Destination::Open("downloads".into())).await
}

For magnets, parse the URI with spill::protocol::magnet::Magnet::parse and pass TorrentSource::Magnet. Private torrents require metainfo, not magnets. Session::admit rejects nonempty TorrentOptions.peers for private metainfo; private outgoing peers must come from its active tracker. Private torrents also suppress metadata serving and alternate peer discovery. See Private trackers for switching and accounting policy. BEP 53 so ranges apply after metadata resolution unless TorrentOptions.settings.file_priorities is non-empty, in which case explicit priorities take precedence. Magnet::select_only() exposes compact inclusive ranges; FileSelection::select_only(meta.layout(), ranges) converts them to normal/skip priorities, preserving padding as skip, ignoring out-of-range indices and clipping ranges to the manifest. Malformed selections fail parsing; a selection containing only out-of-range indices selects no data files. See File selection for the syntax.

When restarting from saved metainfo instead of the original magnet, also save and restore effective file_priorities; metainfo alone does not carry so. The daemon persists both atomically. Session::admit still rejects duplicate executions; the daemon’s additive duplicate-selection behavior is control-layer policy, not implicit mutation of an existing library handle. See the API reference for exact signatures.

The protocol parsers can inspect v1, v2 and hybrid metainfo and magnets. Their info_hash() accessors return TorrentIdentity; use v1() or v2() for a full hash, and wire_key() only for its 20-byte routing key. TorrentHandle::info_hash() returns the admission identity; snapshots contain all hashes learned during resolution. Session::torrent accepts TorrentIdentity: a single hash matches a known hash of the execution; a hybrid lookup requires both hashes to match the same execution. A truncated v2 routing key is never a lookup identity.

The engine and daemon handle v1, v2-only and hybrid torrents the same way; see v2 and hybrid torrents for format behaviour, magnet resolution, swarms and peer protocol rules. For library users:

  • TorrentDiagnostics identifies tracker and DHT entries by their swarm key; dht contains one entry per swarm. Tracker and DHT codecs in spill::protocol take plain 20-byte keys, not v1 identities.
  • OwnedMetainfo::layers_pending() identifies hybrids that verify with SHA-1 while required v2 layers are absent. verification() returns V1 in that state.
  • resolved acknowledges magnet metainfo before payload preparation. For a pending hybrid it is called again when a background rebuild finishes after full payload verification; wait_complete() does not wait for this. Stop cancels the rebuild, so UntilComplete may leave layers pending. Store both publications; restarting with the original pending metainfo after a full-mode checkpoint rejects that resume binding and rechecks the payload. Use TorrentHandle::metainfo() to retain the latest metainfo for the next execution. inspect can return a pending hybrid without payload I/O.
  • Layout::is_multi_file() indicates that file paths are relative to name.

download() stops after the selected content completes and joins cleanup before returning. It uses an ephemeral IPv4 listener, uTP, public DHT routers, no port mapping, preferred MSE peer encryption, and no permission to contact LAN addresses. It keeps no recovery record. If interrupted, rerunning refuses to overwrite partial files; use persisted recovery for resumable transfers.

Explicit sessions select NetworkOptions::peer_encryption with spill::engine::session::PeerEncryption::{Allowed, Preferred, Required}. The default is Preferred, for both TCP and uTP. See Peer encryption for policy and security limits. PeerStatus::encryption reports the negotiated application-stream encoding, or None for web seeds and unavailable/unnegotiated observations.

Dropping the download future requests stop but cannot await cleanup. For timeouts or cancellation that must prove files have been released, use an explicit session.

Verify local payload

spill::engine::provisioning::NamedDestination::verify checks complete existing payload against an OwnedMetainfo, without a session or Tokio runtime. Supply the parent download directory; paths use spill’s normalized disk names. It is read-only, stops at the first failure, and does not use network or resume state. Keep files unchanged during the scan. Asynchronous callers should use spawn_blocking. See CLI verification and the API reference.

Create a torrent

spill::engine::create::create hashes a file or directory without a session, network access, or a Tokio runtime:

use spill::engine::create::{self, Options};

fn main() -> std::io::Result<()> {
    let options = Options {
        announce: vec![vec!["https://tracker.example/announce".into()]],
        creation_date: None,
        ..Default::default()
    };
    let torrent = create::create(std::path::Path::new("payload"), &options,
        &mut |done, total| {
            eprintln!("{done}/{total} pieces");
            Ok(())
        })?;
    std::fs::write("payload.torrent", torrent.metainfo)
}

This is a blocking API; use spawn_blocking when calling it from an async application. The progress callback runs on the calling thread. Return an error from it to cancel; creation joins its workers before returning. The result includes encoded metainfo, CreatedTorrent::info_hash as a TorrentIdentity, root name, total bytes (including alignment padding), and piece count. The caller owns output publication; the CLI additionally refuses overwrites and publishes the completed document atomically.

Options::piece_length is in bytes, unlike the CLI’s exponent. Defaults are 256 KiB pieces and the available CPU count. Options::format selects Format::V1 (the default), Format::V2 or Format::Hybrid. V1 sorts whole path bytes; v2 and hybrid sort path components and align files to pieces. Symlinks are followed, and the source is never modified. Keep it unchanged until the call returns. See Creating torrents for supported fields, source traversal, limits, and the separate add-and-seed workflow; rustdoc owns the exact API contract.

Sessions and progress

A Session shares listeners, discovery, and resource budgets across torrents. Session-wide payload rates start unlimited. Use Session::set_bandwidth_limits to set download and upload caps in bytes per second (0 means unlimited), and Session::bandwidth_limits to read them in that order. Limits apply to running and future torrents and compose with per-torrent limits. Download limits pace requests rather than bytes already in flight. Use TorrentHandle::set_bandwidth_limits to change the per-torrent caps for an existing execution without restarting it. Set rates in TorrentOptions for future executions; the library does not persist rate changes. Use Session::bind(NetworkOptions, Limits), then session.admit(TorrentOptions::new(source, destination)) to obtain a TorrentHandle. Admission validates and reserves resources synchronously; metadata resolution and destination preparation happen asynchronously.

  • NetworkOptions defaults to an ephemeral IPv4 listener, uTP enabled, no port mapping, no LAN permission, no DHT and no LSD. Set dht = Some(DhtOptions { ... }) to permit DHT discovery. Unlike download(), reusable sessions do not enable DHT implicitly. Local service discovery requires both lsd = true and allow_local_network = true; it follows each torrent’s dht setting and uses an additional shared multicast UDP port, 6771. LSD startup and I/O errors are nonfatal; interfaces are checked every minute, with socket rebuilds only on change or error. Failures appear in network_status().await.lsd; a batch counts as successful if at least one interface sends it.
  • Limits bounds aggregate resources; each torrent has a Profile and TorrentSettings. See Limits and the API reference.
  • RunPolicy::Persistent keeps serving after completion; UntilComplete stops after selected-content completion. Recheck verifies metainfo against disk without peer or discovery I/O. Offline sessions accept only metainfo rechecks.
  • Session::network_status().await reports local listener-task readiness and passive inbound TCP/uTP handshake counts, public subsets and last-public ages, plus LSD readiness, announce/receive counts and its last error. Counts are shared across clones and retained after disconnects and torrent removal; a new session resets them. Offline/stopped listeners report no addresses. This sends no probes and does not assert firewall reachability.
  • Session::inspect resolves magnet metadata without creating payload files.
  • snapshot() gives current progress; changed().await observes latest-value updates, not an event history. It returns false after the final report. TorrentStatus requires an identity and does not implement Default. TorrentStatus::identity contains the full known identity; use its enum variants or v1()/v2() accessors for format and hashes. progress.metadata_ready means metainfo sufficient for payload verification is available, independently of payload recovery. progress.layers_pending identifies hybrid SHA-1-only verification before a background layer rebuild. progress.info_validated distinguishes validated info bytes from payload-ready metainfo for v2-only magnets. hash_bytes and hash_total_bytes report authenticated v2 layer acquisition, excluding proof siblings and repeated roots. They are acquisition counters, not payload bytes; a metainfo/recovered start has no acquisition work.
  • wait_complete() waits for wanted-content completion, not termination. outcome() reports termination, errors, and cleanup. A clean incomplete stop is not a successful download.

UntilComplete allows up to five seconds for a pending tracker completed announce. This is not a deadline for blocking I/O, callbacks, or cleanup.

Destinations and recovery

All destinations require an existing root directory:

DestinationBehavior
OpenCreate new payload, or verify and adopt an already complete seed.
CreateRefuse existing payload.
AdoptVerify an existing read-only seed.
RecoverReopen a previous execution using its recorded destination binding and checkpoints.

spill never overwrites files it has no recorded authority to write. Resume records bind the format, full torrent identity and pending/full layer mode. A full hybrid cannot trust a pending-mode checkpoint without rechecking. The rebuild saves a full-mode checkpoint, so a normal completed restart needs no extra recheck. Fingerprints cover real files, including empty files, not virtual padding. Recover fully rechecks payload when a checkpoint is incompatible, using its existing destination binding. Keep that binding and payload; checkpoint incompatibility alone does not require a fresh state directory.

A resume checkpoint alone does not authorize reopening partial payload: DestinationBinding does. Store the binding, its original root directory, resume bytes, and completed-announce delivery state together. Preserve resume bytes unchanged and serialize the binding through its serde implementation. Its format may change before 1.0.

Persistence provides optional acknowledgements for resolved metadata, destination bindings, checkpoints, and completed-announce delivery. The completion_announce callback receives (swarm_key, delivered); RecoveryState::completed_announces stores (swarm_key, delivered) pairs. Preserve every swarm independently: false means pending and true means acknowledged. Acknowledging one hybrid swarm does not acknowledge the other. They run on blocking threads. Acknowledgement failures fail the execution. Callbacks must not wait synchronously for their own execution or session to stop.

Metadata acknowledgement precedes destination preparation; binding acknowledgement precedes file creation. Resume acknowledgement precedes content completion; tracker-delivery acknowledgement precedes advancing delivery state. Stop and shutdown join callbacks already in progress, without a hard deadline.

Use handle.recovery() to retain the latest acknowledged recovery state for a subsequent execution. For recovery across process restarts, persist it yourself.

Stop and shutdown

Call handle.request_stop() then await handle.outcome(), or use handle.stop(). Stop is terminal: resuming means admitting a new execution after joined cleanup. Finished executions retire automatically; old handles cannot control replacements.

Call session.shutdown().await before releasing the session. Session clones share executions; dropping one clone does not stop them. Dropping the last clone requests stop but cannot await it. A cancelled shutdown wait can be joined again through another retained handle. After shutdown, drop all session clones to release its listening port.

outcome().cleanup_complete distinguishes a failed transfer with joined cleanup from a failure that cannot prove resources were released. Inspect that outcome before reusing a destination after an error. Session admission closes if cleanup cannot be proven.

Runnable examples

From a source checkout matching your library version:

mkdir -p downloads recovery
cargo run --no-default-features --example download -- FILE.torrent downloads
cargo run --no-default-features --example download -- --magnet 'magnet:?...' downloads
cargo run --no-default-features --example progress -- downloads recovery A.torrent B.torrent

The download example is minimal; progress demonstrates concurrent downloads, progress reporting, persistence callbacks, and recovery after interruption. Examples live in examples/ in the source repository. Prefer these and the versioned API reference over inferring library methods from daemon commands.