10 stable releases
new 3.0.0 | May 9, 2025 |
---|---|
2.0.0 | Jul 29, 2021 |
1.2.2 | May 20, 2021 |
1.2.1 | Feb 18, 2021 |
#204 in Network programming
588 downloads per month
Used in 3 crates
31KB
374 lines
Magnet URL Parser
A simple, efficient magnet URL parser in Rust with zero dependencies.
What is a magnet URL?
A magnet URL is a URI scheme that identifies files by their hash, normally used in peer-to-peer file sharing networks (like BitTorrent). Magnet links identify a torrent you want to download and tell the torrent client how to download it. They make it very easy to share files over the internet, using a combination of DHT and trackers to find peers who can share the file with you.
Features
- Zero dependencies for lightweight integration
- Simple, efficient string parsing
- Comprehensive magnet URL component support
- Builder pattern for easy creation
- Proper error handling
- 100% safe Rust
Usage
Add this to your Cargo.toml
:
[dependencies]
magnet-url = "3.0.0"
Parsing a Magnet URL
use magnet_url::Magnet;
fn main() {
let magnet_str = "magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel";
// Parse the magnet URL
match Magnet::new(magnet_str) {
Ok(magnet) => {
println!("Display name: {:?}", magnet.display_name());
println!("Hash type: {:?}", magnet.hash_type());
println!("Hash: {:?}", magnet.hash());
println!("Trackers: {:?}", magnet.trackers());
},
Err(err) => {
println!("Error parsing magnet URL: {}", err);
}
}
}
Creating a Magnet URL
Use the builder pattern to create magnet URLs:
use magnet_url::MagnetBuilder;
fn main() {
let magnet = MagnetBuilder::new()
.display_name("My Torrent")
.hash_type("btih")
.hash("1234567890abcdef1234567890abcdef12345678")
.length(12345)
.add_tracker("udp://tracker.example.com:6969")
.add_trackers(&["udp://tracker2.example.com:6969", "wss://tracker3.example.com"])
.web_seed("https://example.com/seed")
.build();
println!("Generated magnet URL: {}", magnet.to_string());
}
Error Handling
The library uses proper error handling with the Result
type:
use magnet_url::{Magnet, MagnetError};
fn main() {
// This will return an Err(MagnetError::NotAMagnetURL)
let result = Magnet::new("https://example.com");
match result {
Ok(magnet) => {
println!("Display name: {:?}", magnet.display_name());
},
Err(MagnetError::NotAMagnetURL) => {
println!("The provided string is not a valid magnet URL");
}
}
}
Converting to String
You can convert a Magnet
instance back to a string:
use magnet_url::MagnetBuilder;
fn main() {
let magnet = MagnetBuilder::new()
.display_name("My Torrent")
.hash_type("btih")
.hash("1234567890abcdef1234567890abcdef12345678")
.build();
// Convert to a magnet URL string
let magnet_url = magnet.to_string();
println!("{}", magnet_url);
// Output: magnet:?xt=urn:btih:1234567890abcdef1234567890abcdef12345678&dn=My%20Torrent
}
Supported Magnet Components
All standard magnet URL components are supported:
dn
- Display Namext
- Exact Topic (hash type and hash)xl
- Exact Lengthtr
- Tracker URLkt
- Keyword Topicws
- Web Seedxs
- Exact Sourceas
- Acceptable Sourcemt
- Manifest Topic
Accessing Magnet Components
Each component can be accessed through getter methods:
use magnet_url::Magnet;
fn main() {
let magnet = Magnet::new("magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel").unwrap();
// Access components
println!("Display name: {:?}", magnet.display_name());
println!("Hash type: {:?}", magnet.hash_type());
println!("Hash: {:?}", magnet.hash());
println!("Exact Length: {:?}", magnet.length());
println!("Tracker URLs: {:?}", magnet.trackers());
println!("Web Seed: {:?}", magnet.web_seed());
println!("Source: {:?}", magnet.source());
println!("Search Keywords: {:?}", magnet.search_keywords());
println!("Acceptable Source: {:?}", magnet.acceptable_source());
println!("Manifest: {:?}", magnet.manifest());
}
Performance
The library uses simple string parsing techniques without any regex or other heavy dependencies, making it very efficient for parsing magnet URLs. Benchmark results show that parsing a typical magnet URL takes around 500-600 nanoseconds, and generating a magnet URL string takes about 1.3-1.4 microseconds.
License
This project is licensed under the MIT License - see the LICENSE.md file for details.