Struct magnet_url::Magnet

pub struct Magnet {
    pub dn: String,
    pub hash_type: String,
    pub xt: String,
    pub xl: isize,
    pub xs: String,
    pub tr: Vec<String>,
    pub kt: String,
    pub ws: String,
    pub acceptable_source: String,
    pub mt: String,
}

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 is magnet_url

While working on a side project, I realized that I had the misfortune of trying to get the component parts of a magnet-url and then do further processing of them. I quickly wrote some Regex for it, but then I realized that this would be really useful for other projects that are dealing with torrents in Rust. By making it modifiable, too, it would allow for the creation of custom magnet links, which would also be useful for torrent based projects.

Why use magnet_url

magnet_url has the goal of, as you may have guessed, parsing the parts of magnets. It does this using some relatively simple regexes. 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, and modification of it's source is greatly encouraged through documentation and it's license.

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");

This returns the Magnet struct, which is made up of the fields listed below this section. To access one of these fields is also 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");
println!("{:?}", magneturl.dn);

If you'd like to modify parts of the magnet_url to customize it, that can be done as well!

use magnet_url::Magnet;
let mut 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");
println!("{:?}", magneturl.dn);
magneturl.dn = String::from("hello_world");
println!("{:?}", magneturl.dn);

In fact, you can construct your own magnet url as well, as long as you fill in all the parameters!

use magnet_url::Magnet;
//Note, this magnet won't actually download, sorry :/
Magnet {
    dn: "hello_world".to_string(),
    hash_type: "sha1".to_string(),
    xt: "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed".to_string(),
    xl: 1234567890,
    tr:
        {
            let mut tr_vec = Vec::new();
            tr_vec.push("https://example.com/".to_string());
            tr_vec
        },
    kt: "cool+stuff".to_string(),
    ws: String::new(),
    acceptable_source: String::new(),
    mt: String::new(),
    xs: String::new(),
};

Invalid magnet url's will result in a panic! (This will be changed to an error in v2.0.0

use magnet_url::Magnet;
let _magnet_link = Magnet::new("https://example.com");

Fields

dn: String

Display Name of the torrent

hash_type: String

type of hash used in the exact topic

xt: String

eXact Topic: URN containing the file hash. The URN is specific to the protocol so a file hash URN under btih (BitTorrent) would be completely different than the file hash URN for ed2k

xl: isize

eXact Length: The size (in bytes) The length is isize instead of usize since it makes error handling easier, as -1 is given if no length is set. I considered making it a String, but decided against it since it's simpler for the developer when they can just deal with an integer

xs: String

eXact Source: Either an HTTP (or HTTPS, FTP, FTPS, etc.) download source for the file pointed to by the Magnet link, the address of a P2P source for the file or the address of a hub (in the case of DC++), by which a client tries to connect directly, asking for the file and/or its sources. This field is commonly used by P2P clients to store the source, and may include the file hash.

tr: Vec<String>

address TRacker: Tracker URL; used to obtain resources for BitTorrent downloads without a need for DHT support. The value must be URL encoded

kt: String

Keyword Topic: Specifies a string of search keywords to search for in P2P networks, rather than a particular file. Also set as a vector since there will likely be more than one

ws: String

Web Seed: The payload data served over HTTP(S)

acceptable_source: String

Acceptable Source: Refers to a direct download from a web server. Regarded as only a fall-back source in case a client is unable to locate and/or download the linked-to file in its supported P2P network(s) as is a reserved keyword in Rust, so unfortunately this library must use the full name

mt: String

Manifest Topic: Link to the metafile that contains a list of magneto (MAGMA – MAGnet MAnifest); i.e. a link to a list of links

Implementations

impl Magnet

pub fn new(magnet_str: &str) -> Magnet

Given a magnet URL, identify the specific parts, and return the Magnet struct. If the program can't identify a specific part of the magnet, then it will either give an empty version of what its value would normally be (such as an empty string, an empty vector, or in the case of xl, -1)