Crate magnet_url

What is a magnet url

A magnet is a URI scheme that identifies files by their hash, normally used in peer to peer file sharing networks (like Bittorrent). Basically, a magnet link identifies a torrent you want to download, and tells the torrent client how to download it. They make it very easy to share files over the internet, and use a combination of DHT and trackers to tell your torrent client where other peers who can share the file with you are.

Why use magnet_url

magnet_url has the goal of, as you may have guessed, parsing the parts of magnets. It does this using simple string parsing techniques for maximum efficiency. The crate is designed to be very simple and efficient, with a lot of flexibility. It’s also designed to be relatively easy to handle errors.

How to use this crate

Parsing a magnet is very simple:

use magnet_url::Magnet;
let magneturl = Magnet::new("magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel&tr=udp%3A%2F%2Fexplodie.org%3A6969&tr=udp%3A%2F%2Ftracker.coppersurfer.tk%3A6969&tr=udp%3A%2F%2Ftracker.empire-js.us%3A1337&tr=udp%3A%2F%2Ftracker.leechers-paradise.org%3A6969&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337&tr=wss%3A%2F%2Ftracker.btorrent.xyz&tr=wss%3A%2F%2Ftracker.fastcast.nz&tr=wss%3A%2F%2Ftracker.openwebtorrent.com&ws=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2F&xs=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2Fsintel.torrent").unwrap();

This returns the Magnet struct, which lets you access all parts of the magnet URL through getter methods:

use magnet_url::Magnet;
let magneturl = Magnet::new("magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel&tr=udp%3A%2F%2Fexplodie.org%3A6969&tr=udp%3A%2F%2Ftracker.coppersurfer.tk%3A6969&tr=udp%3A%2F%2Ftracker.empire-js.us%3A1337&tr=udp%3A%2F%2Ftracker.leechers-paradise.org%3A6969&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337&tr=wss%3A%2F%2Ftracker.btorrent.xyz&tr=wss%3A%2F%2Ftracker.fastcast.nz&tr=wss%3A%2F%2Ftracker.openwebtorrent.com&ws=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2F&xs=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2Fsintel.torrent").unwrap();
println!("{:?}", magneturl.display_name());

You can construct your own magnet URLs using the builder pattern:

use magnet_url::MagnetBuilder;
 
// Note, this magnet won't actually download, sorry :/
let magnet = MagnetBuilder::new()
    .display_name("hello_world")
    .hash_type("sha1")
    .hash("2aae6c35c94fcfb415dbe95f408b9ce91ee846ed")
    .length(1234567890)
    .add_tracker("https://example.com/")
    .search_keywords("cool+stuff")
    .build();

let magnet_string = magnet.to_string();
println!("{}", magnet_string);

Invalid magnet URLs will result in an Error, which can be handled appropriately:

use magnet_url::{Magnet, MagnetError};

// This will return an Err(MagnetError::NotAMagnetURL)
let result = Magnet::new("https://example.com");

match result {
    Ok(magnet) => {
        // Process the valid magnet
        println!("Display name: {:?}", magnet.display_name());
    },
    Err(MagnetError::NotAMagnetURL) => {
        // Handle invalid magnet URL
        println!("The provided string is not a valid magnet URL");
    }
}

Structs

Magnet

Represents a parsed magnet URL with all its components

MagnetBuilder

Builder for creating Magnet URLs

Enums

MagnetError

The various ways the Magnet parsing can fail