{"id":35507485,"url":"https://github.com/yoep/fx-torrent","last_synced_at":"2026-05-10T22:06:47.606Z","repository":{"id":330743531,"uuid":"1123729259","full_name":"yoep/fx-torrent","owner":"yoep","description":"FX Torrent is a feature rich Bittorrent protocol implementation written in rust supporting Linux, MacOS and Windows","archived":false,"fork":false,"pushed_at":"2026-02-03T22:04:55.000Z","size":2105,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-04T11:02:32.769Z","etag":null,"topics":["bittorent","dht","library","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yoep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T13:51:01.000Z","updated_at":"2026-02-03T22:05:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yoep/fx-torrent","commit_stats":null,"previous_names":["yoep/fx-torrent"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/yoep/fx-torrent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoep%2Ffx-torrent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoep%2Ffx-torrent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoep%2Ffx-torrent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoep%2Ffx-torrent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yoep","download_url":"https://codeload.github.com/yoep/fx-torrent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoep%2Ffx-torrent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29237141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T14:18:14.570Z","status":"ssl_error","status_checked_at":"2026-02-08T14:18:14.071Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bittorent","dht","library","rust"],"created_at":"2026-01-03T20:13:12.717Z","updated_at":"2026-05-10T22:06:47.598Z","avatar_url":"https://github.com/yoep.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FX-Torrent\n\n![Build](https://github.com/yoep/fx-torrent/workflows/Build/badge.svg)\n[![Crates](https://img.shields.io/crates/v/fx-torrent)](https://crates.io/crates/fx-torrent)\n[![License: Apache-2.0](https://img.shields.io/github/license/yoep/fx-torrent)](./LICENSE)\n[![Documentation](https://docs.rs/fx-torrent/badge.svg)](https://docs.rs/fx-torrent/0.9.1/fx_torrent/)\n[![codecov](https://codecov.io/gh/yoep/fx-torrent/graph/badge.svg?token=CDT6SG6YEL)](https://codecov.io/gh/yoep/fx-torrent)\n\nFX-Torrent is the most complete BitTorrent implementation fully written in Rust, which supports both Linux, MacOS, and Windows.\nIt supports most of the Bittorrent protocol specifications, such as multi-file torrents, validating existing files, resuming torrent files,\nand is based on the `libtorrent` library for functionality and naming convention.\n\n- [Getting Started](#getting-started)\n- [Features](#features)\n- [CLI example](#cli-example)\n- [DHT](#dht)\n- [Extensions](#extensions)\n\n## Getting Started\n\nCreate a new `FxTorrentSession` which manages one or more torrents.\nA `Torrent` can be created from a magnet link, torrent file, or passing the raw `TorrentMetadata`.\n\n_create a new session with torrent_\n```rust\nuse std::io;\nuse fx_torrent::{FxTorrentSession, Session, SessionConfig, TorrentFlags, TorrentMetadata};\n\n// The fx-torrent crate makes use of async tokio runtimes\n// this requires that new sessions and torrents need to be created within an async context\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), io::Error\u003e {\n    let session = FxTorrentSession::builder()\n        .config(\n            SessionConfig::builder()\n                .base_path(\"/torrent/location/directory\")\n                .client_name(\"MyClient\")\n                .build(),\n        )\n        .default_extensions()\n        .build()\n        .map_err(|e| io::Error::new(io::ErrorKind::Other, e))?;\n\n    // Create a torrent from a magnet link\n    let magnet_torrent = session.add_torrent_from_uri(\"magnet:?XXX\", TorrentFlags::default()).await;\n\n    // Create a torrent from a torrent file\n    let file_torrent = session.add_torrent_from_uri(\"/tmp/example.torrent\", TorrentFlags::default()).await;\n\n    // Create a torrent from metadata info\n    let data: \u0026[u8] = \u0026[0; 1024];\n    let metadata: TorrentMetadata = TorrentMetadata::try_from(data)\n        .map_err(|e| io::Error::new(io::ErrorKind::InvalidInput, e))?;\n    let metadata_torrent = session.add_torrent_from_metadata(metadata, TorrentFlags::Paused).await;\n\n    Ok(())\n}\n```\n\nFor more examples, see the [examples](./examples) directory.\n\n### CLI example\n\nThe CLI example makes use of most of the functionality provided by the library and \ncan be used to download torrents from magnet links or torrent files.\nThe CLI also allows the introspection of the DHT network and Trackers.\n\nThe example is built on top of the [Ratatui](https://ratatui.rs/) as terminal UI library.\n\n#### Tracing \u0026 Tokio Unstable\n\nThe CLI example enables the **tracing** feature by default to support the `tokio-console` subscriber. \nThis requires the `tokio_unstable` configuration flag to be passed to the compiler.\n\n```shell\nRUSTFLAGS=\"--cfg tokio_unstable\" cargo run --example cli\n```\n\nIf you do not wish to use experimental tokio features, you must disable the `tracing` feature in the example.\n\n## DHT\n\nWhen using the `dht` feature, enabled by default, one of the following additional features should be enabled:\n- `ed25519-dalek`\n- `ring-compat`\n\nThese crypto providers are used within the DHT network to verify mutable items within the network.\nWhen both features are missing, a `Error::MissingCryptoProvider` error will be returned.\n\n## Extensions\n\nThe `fx_torrent` crate is designed to be highly extensible.\nYou can modify the core behavior of components by implementing and registering \"extension\" traits.\nThese allow for custom logic in peer communication and data persistence.\n\n### Peer Extension\n\nPeer extensions allow you to extend the BitTorrent protocol with custom messaging and handshake\ncapabilities, following the **BEP 10** specification.\n\nTo modify peer protocol behavior, implement the `peer::extension::Extension` trait.\nOnce implemented, these extensions can be attached to individual torrents or globally across a session.\n\n_example peer extension_\n```rust\n#[derive(Debug)]\npub struct MyPeerExtension;\nimpl Extension for MyPeerExtension {\n    fn name(\u0026self) -\u003e \u0026str {\n        \"my-extension\"\n    }\n\n    // Additional trait methods\n}\n\nfn example() {\n    // 1. Peer extension directly in a torrent\n    let torrent = Torrent::request()\n        .extension(|| MyPeerExtension.into())\n        .build()\n        .unwrap();\n\n    // 2. Peer extension in a session\n    let session = FxTorrentSession::builder()\n        .extension(|| MyPeerExtension.into())\n        .build()\n        .unwrap();\n}\n```\n\n### Storage Extension\n\nStorage extensions allow you to customize how data is read from and written to disk (or memory).\nThis is useful for implementing custom caching layers, encrypted storage, or cloud-backed persistence.\n\nTo create your own storage backend, implement the `storage::Extension` trait.\n\n_example storage extension_\n```rust\n#[derive(Debug)]\npub struct MyStorageExtension;\nimpl MyStorageExtension {\n    pub fn new(_params: StorageParams) -\u003e Self {\n        Self\n    }\n}\nimpl Extension for MyStorageExtension {\n    async fn read(\u0026self, buffer: \u0026mut [u8], piece: \u0026PieceIndex, offset: usize) -\u003e Result\u003cusize\u003e {\n        // Read piece data from storage\n        Ok(0)\n    }\n\n    // Additional trait methods\n}\n\nfn example() {\n    // 1. Storage extension directly in a torrent\n    let torrent = Torrent::request()\n        .storage(|params| MyStorageExtension::new(params).into())\n        .build()\n        .unwrap();\n\n    // 2. Storage extension in a session\n    let session = FxTorrentSession::builder()\n        .storage(|params| MyStorageExtension::new(params).into())\n        .build().unwrap();\n}\n```\n\n### Operation Extension\n\nOperation extensions are **tick-based** tasks invoked by the `TorrentContext`.\nThese operations are executed sequentially in an order-dependent chain,\nmeaning the sequence in which you register them determines their execution priority.\n\n_example operation extension_\n```rust\n#[derive(Debug)]\npub struct MyOperation;\n#[async_trait]\nimpl Extension for MyOperation {\n    /// The `tick` method is called periodically by the torrent engine.\n    async fn tick(\u0026self, context: \u0026mut TorrentContext, peer_discoveries: \u0026[PeerDiscovery]) -\u003e TorrentOperationResult {\n        // Logic for your custom operation goes here\n        TorrentOperationResult::Continue\n    }\n\n    // Additional trait methods\n}\n\nfn example() {\n    // 1. Operation extension directly in a torrent\n    let torrent = Torrent::request()\n        .operation(MyOperation.into())\n        .build()\n        .unwrap();\n\n    // 2. Operation extension in a session\n    let session = FxTorrentSession::builder()\n        .operation(|| MyOperation.into())\n        .build()\n        .unwrap();\n}\n```\n\n## Features\n\n- [x] [BEP3](https://www.bittorrent.org/beps/bep_0003.html) - The BitTorrent Protocol Specification\n- [x] [BEP4](https://www.bittorrent.org/beps/bep_0004.html) - Assigned Numbers\n- [x] [BEP5](https://www.bittorrent.org/beps/bep_0005.html) - DHT Protocol\n- [x] [BEP6](https://www.bittorrent.org/beps/bep_0006.html) - Fast Extension\n- [x] [BEP7](https://www.bittorrent.org/beps/bep_0007.html) - IPv6 Tracker Extension\n- [x] [BEP9](https://www.bittorrent.org/beps/bep_0009.html) - Extension for Peers to Send Metadata Files\n- [x] [BEP10](https://www.bittorrent.org/beps/bep_0010.html) - Extension Protocol\n- [x] [BEP11](https://www.bittorrent.org/beps/bep_0011.html) - Peer Exchange (PEX)\n- [x] [BEP12](https://www.bittorrent.org/beps/bep_0012.html) - Multitracker Metadata Extension\n- [x] [BEP14](https://www.bittorrent.org/beps/bep_0014.html) - Local Service Discovery\n- [x] [BEP15](https://www.bittorrent.org/beps/bep_0015.html) - UDP Tracker Protocol for BitTorrent\n- [x] [BEP19](https://www.bittorrent.org/beps/bep_0019.html) - WebSeed - HTTP/FTP Seeding (GetRight style)\n- [x] [BEP20](https://www.bittorrent.org/beps/bep_0020.html) - Peer ID Conventions\n- [x] [BEP21](https://www.bittorrent.org/beps/bep_0021.html) - Extension for partial seeds\n- [x] [BEP24](https://www.bittorrent.org/beps/bep_0024.html) - Tracker Returns External IP\n- [x] [BEP29](https://www.bittorrent.org/beps/bep_0029.html) - uTorrent transport protocol\n- [x] [BEP32](https://www.bittorrent.org/beps/bep_0032.html) - BitTorrent DHT Extensions for IPv6\n- [x] [BEP33](https://www.bittorrent.org/beps/bep_0033.html) - DHT scrape\n- [x] [BEP40](https://www.bittorrent.org/beps/bep_0040.html) - Canonical Peer Priority\n- [x] [BEP42](https://www.bittorrent.org/beps/bep_0042.html) - DHT Security extension\n- [x] [BEP43](https://www.bittorrent.org/beps/bep_0043.html) - Read-only DHT Nodes\n- [x] [BEP44](https://www.bittorrent.org/beps/bep_0044.html) - Storing arbitrary data in the DHT\n- [x] [BEP47](https://www.bittorrent.org/beps/bep_0047.html) - Padding files and extended file attributes\n- [x] [BEP48](https://www.bittorrent.org/beps/bep_0048.html) - Tracker Protocol Extension: Scrape\n- [x] [BEP51](https://www.bittorrent.org/beps/bep_0051.html) - DHT Infohash Indexing\n- [ ] [BEP52](https://www.bittorrent.org/beps/bep_0052.html) - The BitTorrent Protocol Specification v2 (WIP)\n- [x] [BEP53](https://www.bittorrent.org/beps/bep_0053.html) - Magnets\n- [x] [BEP54](https://www.bittorrent.org/beps/bep_0054.html) - The lt_donthave extension\n- [x] [BEP55](https://www.bittorrent.org/beps/bep_0055.html) - Holepunch extension\n\n## License\n\nThis project is licensed under the [Apache-2.0 license](./LICENSE).\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license,\nshall be licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoep%2Ffx-torrent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoep%2Ffx-torrent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoep%2Ffx-torrent/lists"}