=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::Protocol::BEP53 - Magnet URI extension

=head1 SYNOPSIS

    use Net::BitTorrent::Protocol::BEP53;

    # Parse an incoming URI
    my $m = Net::BitTorrent::Protocol::BEP53->parse( $uri_string );

    say 'Name: ' . $m->name;
    say 'V2 Hash: ' . unpack('H*', $m->infohash_v2) if $m->infohash_v2;

    # Generate a new URI
    my $new_uri = Net::BitTorrent::Protocol::BEP53->new(
        inf_hash_v2  => $ih2,
        name         => 'Special Linux Distro',
        trackers     => ['udp://tracker.example.com:80']
    )->to_string();

=head1 DESCRIPTION

C<Net::BitTorrent::Protocol::BEP53> implements the magnet URI extension (BEP 53). It provides a robust parser and
generator for magnet links, specifically updated to support the multihash SHA-256 identifiers required for BitTorrent
v2.

=head2 Multihash Support

This module correctly identifies and extracts:

=over

=item v1 (legacy): C<urn:btih:...> (SHA-1)

=item v2 (modern): C<urn:btmh:1220...> (SHA-256 multihash)

=back

=head1 METHODS

=head2 C<parse( $class, $uri )>

Class method. Deconstructs a magnet string into an object. Supports both C<&> and C<;> separators.

=head2 C<to_string( )>

Generates a URI-encoded magnet string based on the object's current state.

=head2 C<infohash_v1( )> / C<infohash_v2( )>

Returns the binary infohash strings. C<infohash_v2> is returned B<without> the 4-byte multihash prefix (C<0x12 0x20>).

=head2 C<trackers( )>

Returns an arrayref of C<tr> (tracker) URLs found in the URI.

=head2 C<nodes( )>

Returns an arrayref of C<x.pe> (peer exchange) nodes. These allow a client to connect directly to initial peers without
waiting for DHT or tracker responses.

=head1 Specifications

=over

=item * B<BEP 09>: Magnet URI format (Foundational)

=item * B<BEP 53>: Magnet URI extension (v2 and multihash)

=back

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

=cut
