Tortillas

A terminal-based TUI (Text User Interface) torrent client built in Rust 🫓.

🚧 Project Status

Note: This project is currently under active development and is not yet feature-complete. It is by no means ready for use.

🛠️ Roadmap

See our roadmap here.

✅ Currently Supported

• Parsing and handling Magnet URIs
• Parsing and handling .torrent files
• uTP and TCP peer connections
• Full implementation of the BitTorrent protocol
• Mainline DHT peer discovery for public and trackerless torrents

🔄 In Development

• Completion of libtortillas library

📈 Future Plans

• TUI (Text User Interface)

❌ Not Planned

• WebTorrent connections: Due to the lack of clear documentation and complex, undocumented protocols WebTorrent support is not currently planned.

🧪 Testing

We use Nextest for running tests. To run tests locally, you may need to install Nextest:

# Install Nextest (example using pre-built binaries)
# See: https://nexte.st/docs/installation/pre-built-binaries/

The default suite should be deterministic and must not depend on public trackers, public peers, or mutable internet state:

cargo nextest run --workspace

Tests that intentionally exercise public BitTorrent infrastructure are marked #[ignore] and should only be run explicitly:

cargo nextest run --workspace --run-ignored ignored-only

The Arch Linux fixture exercises a trackerless torrent through the public DHT and passes only after downloading real ISO data:

cargo nextest run -p libtortillas --test dht_network --run-ignored ignored-only

Test names use this convention:

subject_when_condition_then_expected_result

Examples:

magnet_uri_when_query_is_missing_then_returns_error
peer_stream_when_handshake_is_valid_then_returns_peer_id

Keep tests focused on one behavior, prefer deterministic fixtures with include_str! or include_bytes!, and avoid public network access unless the test is explicitly ignored.

📦 Installation

Tortillas

Tortillas is the TUI (Text User Interface) application most people will use.

There are plans to publish tortillas to registries such as crates.io and the AUR. However, for now, you can install it from source using cargo:

cargo install --git https://github.com/artrixdotdev/tortillas

This will install tortillas to your local Rust toolchain.

Libtortillas

Libtortillas is the engine behind the TUI. It can also be embedded in other applications that need BitTorrent downloads, seeding, and observable progress.

cargo add --git https://github.com/artrixdotdev/tortillas libtortillas

The live feature is enabled by default and provides views, metrics, event streams, and listener handles. Applications that only need actor-backed commands and direct state queries can remove that projection and publication overhead:

[dependencies]
libtortillas = { git = "https://github.com/artrixdotdev/tortillas", default-features = false }

Runtime Contract

libtortillas is a Tokio-first library. Applications that use it must run engine and torrent operations inside a Tokio runtime.

For the Tortillas TUI, the binary should own a single application runtime, typically through #[tokio::main], and create libtortillas::engine::Engine inside that runtime. UI rendering or terminal input that blocks should run on a dedicated thread or, for bounded work, through Tokio blocking tasks, then send application actions into async engine tasks. Long-lived input loops should use a dedicated thread because spawn_blocking tasks cannot be aborted once they start. The library does not currently support swapping in a different async runtime, HTTP client, clock, listener, or storage executor.

With the default live feature, use listeners for current state and incremental updates, and call Engine and Torrent methods for operations. Do not poll persistence snapshots to drive a display. See the libtortillas::live API documentation and the live example.

🤝 Contributing

We welcome contributions! If you'd like to help improve tortillas, please check out our CONTRIBUTING.md for guidelines and tips.

📊 Analytics