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:
TorrentDiagnosticsidentifies tracker and DHT entries by theirswarmkey;dhtcontains one entry per swarm. Tracker and DHT codecs inspill::protocoltake plain 20-byte keys, not v1 identities.OwnedMetainfo::layers_pending()identifies hybrids that verify with SHA-1 while required v2 layers are absent.verification()returnsV1in that state.resolvedacknowledges 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, soUntilCompletemay 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. UseTorrentHandle::metainfo()to retain the latest metainfo for the next execution.inspectcan return a pending hybrid without payload I/O.Layout::is_multi_file()indicates that file paths are relative toname.
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.
NetworkOptionsdefaults to an ephemeral IPv4 listener, uTP enabled, no port mapping, no LAN permission, no DHT and no LSD. Setdht = Some(DhtOptions { ... })to permit DHT discovery. Unlikedownload(), reusable sessions do not enable DHT implicitly. Local service discovery requires bothlsd = trueandallow_local_network = true; it follows each torrent’sdhtsetting 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 innetwork_status().await.lsd; a batch counts as successful if at least one interface sends it.Limitsbounds aggregate resources; each torrent has aProfileandTorrentSettings. See Limits and the API reference.RunPolicy::Persistentkeeps serving after completion;UntilCompletestops after selected-content completion.Recheckverifies metainfo against disk without peer or discovery I/O. Offline sessions accept only metainfo rechecks.Session::network_status().awaitreports 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::inspectresolves magnet metadata without creating payload files.snapshot()gives current progress;changed().awaitobserves latest-value updates, not an event history. It returns false after the final report.TorrentStatusrequires an identity and does not implementDefault.TorrentStatus::identitycontains the full known identity; use its enum variants orv1()/v2()accessors for format and hashes.progress.metadata_readymeans metainfo sufficient for payload verification is available, independently of payload recovery.progress.layers_pendingidentifies hybrid SHA-1-only verification before a background layer rebuild.progress.info_validateddistinguishes validated info bytes from payload-ready metainfo for v2-only magnets.hash_bytesandhash_total_bytesreport 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:
| Destination | Behavior |
|---|---|
Open | Create new payload, or verify and adopt an already complete seed. |
Create | Refuse existing payload. |
Adopt | Verify an existing read-only seed. |
Recover | Reopen 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.