=pod

=head1 NAME

Net::BitTorrent::PeerID - Peer ID Specification

=head1 DESCRIPTION

This document describes and provides examples of the Peer ID format
used by the current release of the C<Net::BitTorrent> module.

=head1 FORMAT

This non-standard format was developed to be URL-safe, unique to the
implementation, and "human parsable."

There are three distinct sections to the Peer IDs generated: the
L<header|/Header>, the L<mid-section|/Mid-section>, and the
L<signature|/Signature>.  Consider this example:

 NB004S-rogzGB1v--SVN

Here, C<NB004S> is the header, C<-rogzGB1v> is the mid-section, and
C<--SVN> is the trailing signature.

=head2 Header

Two uppercase characters ('C<NB>') followed by three digits
representing the SVN revision number with leading zeros, a single
character potentially indicating stability and how the release was
obtained, and a single hyphen (C<->).

If the client is a CPAN build, the sixth byte is the capital letter
'C<C>'.  If the client is running a version checked out from public
SVN (considered unstable), the sixth byte is the capital letter 'S'.
Any other characters in the sixth byte are unsupported and may
indicate a bad client.

=head2 Mid-section

Following that are eight random characters in the following range:

 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~

That is, all uppercase and lowercase letters, decimal digits, as well
as the hyphen, period, underscore, and tilde (66 total).  These are
all characters allowed in a URL without encoded (referred to as
"Unreserved Characters in [rfc://3986]) to reduce weight on the
tracker during announce.  On a popular tracker, every bit (and byte)
helps.

This section is inspired by the pseudo-base64 set used by SHADOW's
BitTornado client.

=head2 Signature

The final five characters may be random or static and should not be
used in identifying the version of the client software.  Some early
versions even have my name in this spot.  .:shrugs:.

=head1 CPAN VERSION NUMBERS

Stable CPAN releases will have the sixth byte set to 'C<C>' (capital
letter 'c').

Unstable releases (referred to as DEVELOPER releases on PAUSE) on CPAN
will have this bit set as if the user checked the source out from SVN,
that is, the sixth byte will be 'C<S>' (capital letter 's').  These
will be released on CPAN with version numbers matching
C<m[\d\.\d+_\d]>.  See the PAUSE FAQ section entitled "Developer
Releases" (L<http://www.cpan.org/modules/04pause.html>).

Version numbers will be some value less than one with the revision
number in the three significant decimal places.

=head1 EXAMPLES

=over

=item C<NB393C-04.9EraQ--SVN>

This would be the stable CPAN release C<v0.393>.  The C<--SVN>
signature should be ignored.

=item C<NB003X-9E-ayR6b-BTE<lt>3>

Improper Peer ID; the sixth bit is neither 'C' nor 'S'.  Possibly
fake.

=item C<NB065S--09Egae69sy8W>

Completely legal Peer ID generated by SVN/Dev r65.

=back

=head1 FUTURE IDEAS

Eventually, I would like to make a v1.0 release of Net::BitTorrent on
CPAN.  The information in this document and the means of generating
the module's version number will need to reflect that.

=head1 SEE ALSO

=over

=item RFC 3986 (URI: Generic Syntax)

Section 2.3. "Unreserved Characters"
(L<http://tools.ietf.org/html/rfc3986#section-2.3>)

=item PAUSE FAQ sub-section entitled "Developer Releases"

(L<http://www.cpan.org/modules/04pause.html>)

=item CC ANSA 3.0

That is, the Creative Commons Attribution-Noncommercial-Share Alike
3.0 License
(L<http://creativecommons.org/licenses/by-nc-sa/3.0/us/>).

=item BitTornado's Peer ID spec

This specification is inspired by the documentation found on the
BitTornado forum
(L<http://forums.degreez.net/viewtopic.php?t=7070>).

=back

=head1 CONTACT

Sanko Robinson <sanko@cpan.org> - L<http://sankorobinson.com/>

CPAN ID: SANKO

=head1 DISCLAIMER AND LEGAL

This document and the specification behind it are subject to change.
All modifications will be documented in the L</HISTORY> section of
this file and in the F<Changes> file included with this distribution.
All versions of this file can be found in the project's svn
repository.

This original documentation is covered by the Creative Commons
Attribution-Noncommercial-Share Alike 3.0  License (United States
jurisdiction).

=head1 HISTORY

This is the list of changes to this file and the specification it
describes:

=over

=item *

Current version - Feb 2nd, 2008 | r0010

Language and POD format cleanup.  No specification changes.

=item *

First version - Feb 2nd, 2008 | r001

=back

=for svn $Id: PeerID.pod 10 2008-04-05 22:06:00Z sanko@cpan.org $

=cut
