...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
magnet
is a URL scheme for
identifying files by their content. These files are usually identified by
cryptographic hash value.
Magnet links are useful in peer-to-peer file sharing networks because they allow resources to be referred to without the need for a continuously available host..
This example parses a magnet link into a new view type and prints its components to standard output.
/* This example parses a magnet link into a new view type and prints its components to standard output. */ #include <boost/url/url_view.hpp> #include <boost/url/url.hpp> #include <boost/url/optional.hpp> #include <boost/url/parse.hpp> #include <boost/url/pct_string_view.hpp> #include <boost/url/rfc/absolute_uri_rule.hpp> #include <boost/url/grammar/digit_chars.hpp> #include <boost/url/grammar/parse.hpp> #include <boost/core/detail/string_view.hpp> #include "filter_view.hpp" #include <iostream> namespace urls = boost::urls; namespace core = boost::core; /** Callable to identify a magnet "exact topic" This callable evaluates if a query parameter represents a magnet "exact topic". This callable is used as a filter for the topics_view. */ struct is_exact_topic { bool operator()(urls::param_view p); }; /** Callable to identify a magnet url parameter This callable evaluates if a query parameter has a given key and a url as its value. These urls are percent-encoded twice, which means we need to decode it once before attempting to parse it. This callable is used as a filter for the keys_view. */ class is_url_with_key { core::string_view k_; public: is_url_with_key( core::string_view key) : k_(key) {} bool operator()(urls::param_view p); }; /** Callable to convert param values to urls This callable converts the value of a query parameter into a urls::url_view. This callable is used as a transform function for the topics_view. */ struct param_view_to_url { urls::url operator()(urls::param_view p); }; /** Callable to convert param values to std::string This callable converts the value of a query parameter into a std::string. This callable is used as a transform function for the keys_view. */ struct to_decoded_value { std::string operator()(urls::param_view p) { return p.value; } }; /** Callable to convert param values to info_hashes This callable converts the value of a query parameter into a core::string_view with its infohash. The infohash hash is a parameter of an exact topic field in the magnet link. This callable is used as a transform function for the info_hashes_view. */ struct param_view_to_infohash { core::string_view operator()(urls::param_view p); }; /** Callable to convert param values to protocols This callable converts the value of a query parameter into a core::string_view with its protocol. The protocol is a parameter of an exact topic field in the magnet link. This callable is used as a transform function for the protocols_view. */ struct to_protocol { core::string_view operator()(urls::param_view p); }; struct magnet_link_rule_t; /** A new url type for magnet links This class represents a reference to a magnet link. Unlike a urls::url_view, which only represents the general syntax of urls, a magnet_link_view represents a reference to fields that are relevant to magnet links, while ignoring elements of the general syntax that are not relevant to the scheme. This allows us to use the general syntax parsers to create a representation that is more appropriate for the specified scheme syntax. @par Specification @li <a href="https://www.bittorrent.org/beps/bep_0005.html" >DHT Protocol</a> @li <a href="https://www.bittorrent.org/beps/bep_0009.html" >Extension for Peers to Send Metadata Files</a> @li <a href="https://www.bittorrent.org/beps/bep_0053.html" >Magnet URI extension</a> @li <a href="https://en.wikipedia.org/wiki/Magnet_URI_scheme" >Magnet URI scheme</a> @par References @li <a href="https://github.com/webtorrent/magnet-uri" >magnet-uri</a> */ class magnet_link_view { urls::url_view u_; public: /// A view of all exact topics in the magnet_link using topics_view = filter_view< urls::params_view, urls::url, is_exact_topic, param_view_to_url>; /// A view of all info_hashes in the magnet_link using info_hashes_view = filter_view< urls::params_view, std::string, is_exact_topic, param_view_to_infohash>; /// A view of all protocols in the magnet_link using protocols_view = filter_view< urls::params_view, std::string, is_exact_topic, to_protocol>; /** A view of all urls with the specified key in the magnet_link A number of fields in a magnet link refer to a list of urls with the same query parameter keys. */ using keys_view = filter_view< urls::params_view, std::string, is_url_with_key, to_decoded_value>; /** URNs to the file or files hashes An exact topic is the main field of a magnet link. A magnet link must contain one or more exact topics with the query key "xt" or ["xt.1", "xt.2", ...]. The value of each exact topic is a URN representing the file hash and the protocol to access the file. @return A view of all exact topic URNs in the link */ topics_view exact_topics() const noexcept; /** Info hash of the file or files @return A view of all info hashes in exact topics */ info_hashes_view info_hashes() const noexcept; /** Protocol of the exact topics @return A view of all protocols in exact topics */ protocols_view protocols() const noexcept; /** Return view of address trackers A tracker URL is used to obtain resources for BitTorrent downloads. @return A view of all address trackers in the link */ keys_view address_trackers() const; /** Return view of exact sources An exact source URL is a direct download link to the file. @return A view of all exact sources */ keys_view exact_sources() const; /** Return view of acceptable sources An acceptable source URL is a direct download link to the file that can be used as a fallback for exact sources. @return A view of all acceptable sources */ keys_view acceptable_sources() const; /** Return keyword topic The keyword topic is the search keywords to use in P2P networks. @par Example kt=martin+luther+king+mp3 @return Keyword topic */ boost::optional<std::string> keyword_topic() const noexcept; /** Return manifest topics This function returns a link to the metafile that contains a list of magneto. @par Specification @li <a href="http://rakjar.de/gnuticles/MAGMA-Specsv22.txt" >MAGnet MAnifest</a> @return A view of manifest topics */ keys_view manifest_topics() const; /** Return display name This function returns a filename to display to the user. This field is only used for convenience. @par Specification @li <a href="http://rakjar.de/gnuticles/MAGMA-Specsv22.txt" >MAGnet MAnifest</a> @return Display name */ boost::optional<urls::pct_string_view> display_name() const noexcept; /** Return web seed The web seed represents the payload data served over HTTP(S). @return Web seed */ keys_view web_seed() const; /** Return extra supplement parameter This function returns informal options and parameters of the magnet link. Query parameters whose keys have the prefix "x." are used in magnet links for extra parameters. These names are guaranteed to never be standardized. @par Example x.parameter_name=parameter_data @return Web seed */ boost::optional<urls::pct_string_view> param(core::string_view key) const noexcept; friend std::ostream& operator<<(std::ostream& os, magnet_link_view m) { return os << m.u_; } private: // get a query parameter as a urls::pct_string_view boost::optional<urls::pct_string_view> encoded_param(core::string_view key) const noexcept; // get a query parameter as a urls::url_view boost::optional<urls::url_view> url_param(core::string_view key) const noexcept; friend magnet_link_rule_t; }; bool is_exact_topic:: operator()(urls::param_view p) { // These comparisons use the lazy // operator== for urls::pct_string_view // For instance, the comparison also works // if the underlying key is "%78%74"/ if (p.key == "xt") return true; return p.key.size() > 3 && *std::next(p.key.begin(), 0) == 'x' && *std::next(p.key.begin(), 1) == 't' && *std::next(p.key.begin(), 2) == '.' && std::all_of( std::next(p.key.begin(), 3), p.key.end(), urls::grammar::digit_chars); } bool is_url_with_key:: operator()(urls::param_view p) { if (p.key != k_) return false; boost::system::error_code ec; std::string buf( p.value.begin(), p.value.end()); if (ec.failed()) return false; boost::system::result<urls::url_view> r = urls::parse_uri(buf); return r.has_value(); } urls::url param_view_to_url:: operator()(urls::param_view p) { // `param_view_to_url` is used in topics_view, // where the URL is not // percent-encoded twice. // Thus, we can already parse the // encoded value. auto ur = urls::parse_uri(p.value); BOOST_ASSERT(ur); urls::url u = *ur; return u; } core::string_view param_view_to_infohash:: operator()(urls::param_view p) { urls::url_view topic = urls::parse_uri(p.value).value(); core::string_view t = topic.encoded_path(); std::size_t pos = t.find_last_of(':'); if (pos != core::string_view::npos) return t.substr(pos + 1); return t; } core::string_view to_protocol:: operator()(urls::param_view p) { urls::url_view topic = urls::parse_uri(p.value).value(); core::string_view t = topic.encoded_path(); std::size_t pos = t.find_last_of(':'); return t.substr(0, pos); } auto magnet_link_view::exact_topics() const noexcept -> topics_view { return {u_.params()}; } auto magnet_link_view::info_hashes() const noexcept -> info_hashes_view { return {u_.params()}; } auto magnet_link_view::protocols() const noexcept -> protocols_view { return {u_.params()}; } auto magnet_link_view::address_trackers() const -> keys_view { return { u_.params(), is_url_with_key{"tr"}}; } auto magnet_link_view::exact_sources() const -> keys_view { return { u_.params(), is_url_with_key{"xs"}}; } auto magnet_link_view::acceptable_sources() const -> keys_view { return { u_.params(), is_url_with_key{"as"}}; } boost::optional<std::string> magnet_link_view::keyword_topic() const noexcept { boost::optional<urls::pct_string_view> o = encoded_param("kt"); if (o) return o->decode(); return boost::none; } auto magnet_link_view::manifest_topics() const -> keys_view { return { u_.params(), is_url_with_key{"mt"}}; } boost::optional<urls::pct_string_view> magnet_link_view::display_name() const noexcept { return encoded_param("dn"); } auto magnet_link_view::web_seed() const -> keys_view { return { u_.params(), is_url_with_key{"ws"}}; } boost::optional<urls::pct_string_view> magnet_link_view::param(core::string_view key) const noexcept { urls::params_view ps = u_.params(); auto it = ps.begin(); auto end = ps.end(); while (it != end) { urls::param_view p = *it; if (p.key.size() < 2) { ++it; continue; } auto first = p.key.begin(); auto mid = std::next(p.key.begin(), 2); auto last = p.key.end(); urls::pct_string_view prefix( core::string_view(first, mid)); urls::pct_string_view suffix( core::string_view(mid, last)); if (prefix == "x." && suffix == key && p.has_value) return urls::pct_string_view(p.value); ++it; } return boost::none; } boost::optional<urls::pct_string_view> magnet_link_view::encoded_param(core::string_view key) const noexcept { urls::params_encoded_view ps = u_.encoded_params(); auto it = ps.find(key); if (it != ps.end() && (*it).has_value) return urls::pct_string_view((*it).value); return boost::none; } boost::optional<urls::url_view> magnet_link_view::url_param(core::string_view key) const noexcept { urls::params_encoded_view ps = u_.encoded_params(); auto it = ps.find(key); if (it != ps.end() && (*it).has_value) { boost::system::result<urls::url_view> r = urls::parse_uri((*it).value); if (r) return *r; } return boost::none; } /** Rule to match a magnet link */ struct magnet_link_rule_t { /// Value type returned by the rule using value_type = magnet_link_view; /// Parse a sequence of characters into a magnet_link_view boost::system::result< value_type > parse( char const*& it, char const* end ) const noexcept; }; auto magnet_link_rule_t::parse( char const*& it, char const* end ) const noexcept -> boost::system::result< value_type > { // 1) Parse url with the general uri syntax boost::system::result<urls::url_view> r = urls::grammar::parse(it, end, urls::absolute_uri_rule); if(!r) return urls::grammar::error::invalid; magnet_link_view m; m.u_ = *r; // 2) Check if exact topics are valid urls // and that we have at least one. This is the // only mandatory field in magnet links. auto ps = m.u_.params(); auto pit = ps.begin(); auto pend = ps.end(); pit = std::find_if(pit, pend, is_exact_topic{}); if (pit == pend) { // no exact topic in the magnet link return urls::grammar::error::invalid; } // all topics should parse as valid urls if (!std::all_of(pit, pend, []( urls::param_view p) { if (!is_exact_topic{}(p)) return true; boost::system::result<urls::url_view> u = urls::parse_uri(p.value); return u.has_value(); })) return urls::grammar::error::invalid; // all other fields are optional // magnet link is OK return m; } constexpr magnet_link_rule_t magnet_link_rule{}; /** Return a parsed magnet link from a string, or error. This is a more convenient user-facing function to parse magnet links. */ boost::system::result< magnet_link_view > parse_magnet_link( core::string_view s ) noexcept { return urls::grammar::parse(s, magnet_link_rule); } int main(int argc, char** argv) { // This example shows how to use custom parsing // to process alternate URI schemes, in this // case "magnet" if (argc != 2) { std::cout << argv[0] << "\n"; std::cout << "magnet <link>\n" "example: magnet magnet:?xt=urn:btih:d2474e86c95b19b8bcfdb92bc12c9d44667cfa36" "&dn=Leaves+of+Grass+by+Walt+Whitman.epub" "&tr=udp%3A%2F%2Ftracker.example4.com%3A80" "&tr=udp%3A%2F%2Ftracker.example5.com%3A80" "&tr=udp%3A%2F%2Ftracker.example3.com%3A6969" "&tr=udp%3A%2F%2Ftracker.example2.com%3A80" "&tr=udp%3A%2F%2Ftracker.example1.com%3A1337\n"; return EXIT_FAILURE; } boost::system::result<magnet_link_view> r = parse_magnet_link(argv[1]); if (!r) return EXIT_FAILURE; magnet_link_view m = *r; std::cout << "link: " << m << "\n"; auto xt = m.exact_topics(); for (auto h : xt) std::cout << "topic: " << h << "\n"; auto hs = m.info_hashes(); for (auto h : hs) std::cout << "hash: " << h << "\n"; auto ps = m.protocols(); for (auto p : ps) std::cout << "protocol: " << p << "\n"; auto tr = m.address_trackers(); for (auto h : tr) std::cout << "tracker: " << h << "\n"; auto xs = m.exact_sources(); for (auto x : xs) std::cout << "exact source: " << x << "\n"; auto as = m.acceptable_sources(); for (auto a : as) std::cout << "topic: " << a << "\n"; auto mt = m.manifest_topics(); for (auto a : mt) std::cout << "manifest topic: " << a << "\n"; auto ws = m.web_seed(); for (auto a : ws) std::cout << "web seed: " << a << "\n"; auto kt = m.keyword_topic(); if (kt) std::cout << "keyword topic: " << *kt << "\n"; auto dn = m.display_name(); if (dn) std::cout << "display name: " << *dn << "\n"; return EXIT_SUCCESS; }