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

Download history 118/week @ 2025-01-17 105/week @ 2025-01-24 225/week @ 2025-01-31 151/week @ 2025-02-07 128/week @ 2025-02-14 184/week @ 2025-02-21 332/week @ 2025-02-28 114/week @ 2025-03-07 188/week @ 2025-03-14 237/week @ 2025-03-21 577/week @ 2025-03-28 195/week @ 2025-04-04 127/week @ 2025-04-11 74/week @ 2025-04-18 121/week @ 2025-04-25 247/week @ 2025-05-02

588 downloads per month
Used in 3 crates

MIT license

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 Name
  • xt - Exact Topic (hash type and hash)
  • xl - Exact Length
  • tr - Tracker URL
  • kt - Keyword Topic
  • ws - Web Seed
  • xs - Exact Source
  • as - Acceptable Source
  • mt - 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.

No runtime deps