{"id":13474244,"url":"https://github.com/vimpunk/cratetorrent","last_synced_at":"2025-04-05T14:07:16.854Z","repository":{"id":38138648,"uuid":"243376667","full_name":"vimpunk/cratetorrent","owner":"vimpunk","description":"A BitTorrent V1 engine library for Rust (and currently Linux)","archived":false,"fork":false,"pushed_at":"2022-03-29T20:29:31.000Z","size":8394,"stargazers_count":481,"open_issues_count":45,"forks_count":35,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-29T13:10:02.500Z","etag":null,"topics":["bittorrent","library","p2p","peer-to-peer","rust","torrent"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vimpunk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-26T22:10:20.000Z","updated_at":"2025-03-19T11:58:18.000Z","dependencies_parsed_at":"2022-08-27T09:50:13.862Z","dependency_job_id":null,"html_url":"https://github.com/vimpunk/cratetorrent","commit_stats":null,"previous_names":["vimpunk/cratetorrent","mandreyel/cratetorrent"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimpunk%2Fcratetorrent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimpunk%2Fcratetorrent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimpunk%2Fcratetorrent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimpunk%2Fcratetorrent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vimpunk","download_url":"https://codeload.github.com/vimpunk/cratetorrent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345853,"owners_count":20924102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bittorrent","library","p2p","peer-to-peer","rust","torrent"],"created_at":"2024-07-31T16:01:10.640Z","updated_at":"2025-04-05T14:07:16.839Z","avatar_url":"https://github.com/vimpunk.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# cratetorrent\n\nCratetorrent is a Rust crate implementing the BitTorrent version 1 protocol.\n\n[![Cargo](https://img.shields.io/crates/v/cratetorrent.svg)](\nhttps://crates.io/crates/cratetorrent)\n[![Documentation](https://docs.rs/cratetorrent/badge.svg)](\nhttps://docs.rs/cratetorrent)\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](\nhttps://github.com/mandreyel/cratetorrent)\n\n---\n\nIt can be used as a library and also provides a simple example CLI torrent app.\nIt is built on top of [tokio](https://github.com/tokio-rs/tokio) and uses async\nIO for high performance.\n\n![](https://raw.githubusercontent.com/mandreyel/cratetorrent/master/assets/partial-download.gif)\n\nThe name is a homage to the C++\n[libtorrent](https://github.com/arvidn/libtorrent) library, from which many\nlessons were learned when I first wrote my torrent engine in C++.\n\n\n## Features\n\n- Multiple torrent downloads or uploads, with an arbitrary number of peer\n  connections.\n- Manually specify seeds to download from.\n- Get peers from HTTP trackers.\n- Basic per-torrent configurability.\n- Decent performance:\n  \u003e On my fairly slow internet connection with peak download rates of about 9\n  MBps, Ubuntu 20.04 LTS (~2.8 GB) is downloaded in about 5 minutes at a\n  download rate of 8-9 MBps, that is, almost fully utilizing the link. When\n  testing on localhost, the thruput rate goes up to 270 MBps.\n\nFeatures are continuously added, see the [project\nmilestones](https://github.com/mandreyel/cratetorrent/issues/26).\n\nEventually, I hope to develop cratetorrent into a full-fledged BitTorrent engine\nlibrary that can be used as the engine underneath torrent clients. This means\nthat features supported by popular clients (such as DHT, magnet links,\nBitTorrent protocol 2, stream encryption, and others) will be supported by\ncratetorrent in the future.\n\n\n## Download example\n\n```rust\nuse cratetorrent::prelude::*;\n                                                                             \n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // spawn the engine with a default config\n    let conf = Conf::new(\"/tmp/downloads\");\n    let (engine, mut alert_rx) = engine::spawn(conf)?;\n                                                                             \n    // parse torrent metainfo and start the download\n    let metainfo = tokio::fs::read(\"/tmp/imaginary.torrent\").await?;\n    let metainfo = Metainfo::from_bytes(\u0026metainfo)?;\n    let torrent_id = engine.create_torrent(TorrentParams {\n        metainfo,\n        // tell the engine to assign a randomly chosen free port\n        listen_addr: None,\n        // here we could specify peers we knew of that we'd want\n        // to connect to\n        mode: Mode::Download { seeds: Vec::new() },\n        conf: None,\n    })?;\n                                                                             \n    // listen to alerts from the engine\n    while let Some(alert) = alert_rx.next().await {\n        match alert {\n            Alert::TorrentStats { id, stats } =\u003e {\n                println!(\"{}: {:#?}\", id, stats);\n            }\n            Alert::TorrentComplete(id) =\u003e {\n                println!(\"{} complete, shutting down\", id);\n                break;\n            }\n            Alert::Error(e) =\u003e {\n              // this is where you'd handle recoverable errors\n              println!(\"Engine error: {}\", e);\n            }\n            _ =\u003e (),\n        }\n    }\n                                                                             \n    // Don't forget to call shutdown on the engine to gracefully stop all\n    // entities in the engine. This will wait for announcing the client's\n    // leave to all trackers of torrent, finish pending disk and network IO,\n    // as well as wait for peer connections to cleanly shut down.\n    engine.shutdown().await?;\n                                                                             \n    Ok(())\n}\n```\n\n## Project structure\n\nThe project is split up in two:\n- the `cratetorrent` library, that defines most of the functionality,\n- and a `cratetorrent-cli` binary for downloading torrents via the CLI. Note,\n  however, that this is extremely simple at present and serves more as a toy for\n  demonstration purposes.\n\n\n## How to run\n\nTested on stable Rust 1.48.\n\n**Requires Linux!**\n\nThis is because file IO is done using the\n[`pwritev(2)`](https://linux.die.net/man/2/pwritev) and\n[`preadv(2)`](https://linux.die.net/man/2/preadv) APIs for optimal performance.\nIn the future, API shims for Windows and Darwin may be supported, but at the\nmoment there is no capacity to do this.\n\n### Binary\n\nThe CLI binary is currently very basic, but you can perform downloads either by\ndirectly connecting to seeds or if the torrent is backed by a HTTP tracker.\n\nRun the following from the repo root:\n```\ncargo run --release -p cratetorrent-cli -- \\\n    --seeds 192.168.0.10:50051,192.168.0.172:49985 \\\n    --metainfo path/to/mytorrent.torrent \\\n    --download-dir ~/Downloads\n```\n\n\n## Tests\n\nCratetorrent is well tested to ensure correct functionality. It includes:\n- an exhaustive suite of inline unit tests,\n- and integration tests of various downloads and uploads, in the [integration\ntests folder](tests).\n\n\n## Design\n\nThe cratetorrent design is documented in the [design doc](DESIGN.md). This\nmostly concerns developers of cratetorrent, as it contains fairly low-level\ndescriptions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvimpunk%2Fcratetorrent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvimpunk%2Fcratetorrent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvimpunk%2Fcratetorrent/lists"}