Net::BitTorrent::Notes - Annotated Guide to the Ins and Outs of Net::BitTorrent
This is a first draft attempt at defining a road map for future
"Net::BitTorrent" development and a behavioral reference for
third-party client developers. A few bits for users might slip in too.
.---- N::B::T::T::UDP
/
.-------- N::B::T::Tracker
/ \
/ .-- N::B::T::File `--- N::B::T::T::HTTP
/ /
.---- Net::BitTorrent::Torrent
/
/ .--- Net::BitTorrent::DHT
/ /
Net::BitTorrent
\
`---- Net::BitTorrent::Peer
The following utility modules also come with the distribution and will be of
great use if you decide to whip together your own BitTorrent module.
- "Net::BitTorrent::Protocol"
- Correctly builds and parses all known BitTorrent packets.
- "Net::BitTorrent::Util"
- Contains basic functions to parse and create .torrent metadata files, and
compact peer lists from trackers.
To pick and choose which functions will be exported into your namespace from
these modules, see their POD documentation for more information.
This distribution uses "Module::Build" for installation, so use the
following procedure:
perl Build.PL
./Build
./Build test
./Build install
See also: Automated Test Reports
"Net::BitTorrent" requires version and Digest::SHA. On Win32, we try
to use Win32API::File and Encode to handle extended charset filenames[1]. As
of perl 5.10, all of these modules are are CORE; they come bundled with the
distribution.
I have listed these modules as prerequisites in Build.PL so, unless you answer
'no' when prompted, the CPAN shell should automagically install them for you.
We also use the internal "utf8()" functions which didn't appear until
perl 5.8.1.
Parts that aren't handled internally are described here (eventually) with sample
code to get you started.
Net::BitTorrent::Torrent objects can be created directly without a parent
client. While functionally limited (obvious things like an inability to serve
data, etc.) basic information is available and some 'advanced' functions still
work (hashchecking, for example). See Net::BitTorrent::Torrent for more.
See Net::BitTorrent::Torrent::pause( ) and Net::BitTorrent::Torrent::start( )
See See Net::BitTorrent::Torrent::stop( ) and Net::BitTorrent::Torrent::start( )
Note: This section describes resume functionality as of "v0.045".
"Net::BitTorrent" is capable of restoring the state of single torrents
between sessions. To store resume data, use the save_resume_data( )
To resume a single torrent, use a variation of the following to save the data...
my $torrent = $bt->add_torrent( { Path=> 'some.torrent', Resume = '.resume' });
# later...
$torrent->save_resume_data();
...and unless "Net::BitTorrent::Torrent" decides the resume data is
bad, you'll start right were you left off. I would suggest storing resume data
on a regular basis while the client runs and again on exit.
To view a fully functioning example, see "/tatoeba/004-resume.pl".
For more on what exactly you're saving and the structure of the data, see Resume
API in the <Net::BitTorrent Internals|/"Net::BitTorrent
Internals"> section.
Unless you've hard coded everything, being able to restore client-wide state is
a necessary feature. Besides, DHT can be very slow to boot without a good set
of initial nodes and the spec states that the local nodeID should not change
very often, so resume is a useful thing.
I would use a hash with the following keys:
- ".hash"
- This would be a SHA-1 hash of the bencoded data in the ".t",
"dht", "nodes", and "torrents" keys. On
restore, I would use this to validate the data in case it was tampered
with.
- ".t"
- Timestamp.
- ".version"
- To avoid problems (API changes, etc.), I would use an API version number
and ignore resume data created with a newer/incompatible version. This
value would not be included in the SHA-1 digest used to prevent
tampering.
- "dht"
- A hash with the following keys:
- "id"
- The local node ID used in the DHT swarm. To obtain this, see node_id(
).
- "nodes"
- List of nodes in the DHT routing table.
To make life easy, each node would be a hash with the following keys:
- "ip"
- IP or hostname of the remote node.
- "port"
- UDP port number the remote port has been contacted on.
A list of nodes with this format is obtained from nodes ( ). To reload these
later, use the add_node ( ) method.
- "settings"
- These would be any client-wide settings I allow users to change.
- "torrents"
- This would be a list of filenames, their current status, and some sort of
verification that the .torrent file hasn't been replaced; the infohash
would do.
I would save a bencoded version of this data in a file for later. For now,
putting all of this into practice is an exercise for the reader.
Note: Reloading the data may require using otherwise private methods
(specifically the private "Net::BitTorrent::DHT->_set_node_id( )"
method). Changes to private methods are not listed in the changelog found in
this distribution but they are noted in the public git repository's log.
See Net::BitTorrent::Torrent::File.
[TODO]
This section describes all the behind the scenes stuff that makes
"Net::BitTorrent" work. Or not work. It depends.
Please see Net::BitTorrent::Version.
Socket6 does not seem to work with Win32 so... no plans for IPv6 right now.
The BitTorrent Community Forum coordinates the development of the BitTorrent
protocol suite, its reference implementation, and BitTorrent Enhancement
Proposals (BEPs). For more information, see BEP 0: Index of BitTorrent
Enhancement Proposals http://bittorrent.org/beps/bep_0000.html
This is the list of extensions used by this release of Net::BitTorrent sorted by
their progress toward standardization.
- •
- BEP 5: DHT Protocol - http://bittorrent.org/beps/bep_0005.html
- •
- BEP 6: Fast Extension - http://bittorrent.org/beps/bep_0006.html
Note: the Fast Extension is only partially implemented in
Net::BitTorrent.
- •
- BEP 10: Extension Protocol - http://bittorrent.org/beps/bep_0010.html
- •
- BEP 12: Multitracker Metadata Extension -
http://bittorrent.org/beps/bep_0012.html
- •
- BEP 15: UDP Tracker Protocol -
http://bittorrent.org/beps/bep_0015.html
- •
- BEP 27: Private Torrents - http://bittorrent.org/beps/bep_0027.html
- •
- BEP 32: Tracker Returns Compact Peer Lists -
http://bittorrent.org/beps/bep_0023.html
"Net::BitTorrent::Torrent"'s resume data is bencoded and stored in a
file. To restore this data, use the "Resume" parameter when calling
Net::BitTorrent::Torrent->new( ) or Net::BitTorrent->add_torrent( ).
Note: The structure and data held in the resume data is subject to
change in future versions.
Data Structure
Parsed resume data is a simple hash containing the following keys:
- ".format"
- A string describing what sort of file this is. For now, it's value is
"Net::BitTorrent resume".
- ".t"
- Timestamp when data was gathered.
- ".version"
- API version used to gather data. To avoid problems (API changes, etc.),
Net::BitTorrent::Torrent will not load resume data created with a higher
version.
- "bitfield"
- A bitvector representing the pieces we already have.
- "files"
- A list of hashes (one for each file in the .torrent) with the following
keys:
- "mtime"
- The modified times for the files (or 0 if the file does not exist).
- "priority"
- The file's download priority.
- "peers"
- Compact list of peers we've found either through DHT or from a
tracker.
- "working"
- List of hashes representing pieces we are currently downloading with the
following keys: (Subject to change)
- "Block_Count"
- Number of blocks contained in the piece.
- "Block_Length"
- Size of blocks in piece.
- "Block_Length_Last"
- Size of final block in piece.
- "Blocks_Received"
- Bitfield representing which blocks have been received and written to
disk.
- "Endgame"
- Boolean value dependent on endgame state when we began working on this
piece.
- "Index"
- Zero-based index of the piece.
- "Length"
- Total size of the piece in bytes.
- "Priority"
- Priority based (partially) on the piece's containing file.
- "Slow"
- Boolean value dependent on how long ago we received a block contained
within this piece.
- •
- All APIs are subject to change.
Changes to documented or well established parts will be clearly listed and
archived in the CHANGES file.
- •
- All undocumented functionality is subject to change without notice.
Net::BitTorrent is just asploding with incomplete bits of stuff so I reserve
the right to change or eliminate code at any time without warning
unless functionality is defined in POD documentation. If you sift
through the source and find something nifty that isn't described in
full in POD, don't expect your client to work with future
releases.
This section lists recent major changes in API or behavior between stable
releases. For older news see the
Changes file included with this
distribution. For detail see the commit logs.
- v0.050
- Protocol Encryption (MSE) is now supported and enabled by default. It is
still rather unstable, so outgoing connections use header-only encryption
but incoming connections allow for full RC4 encrypted sessions.
- v0.040
- Entire distribution was rewritten. Both the internals and the API have
broken compatibility.
If you're interested in assisting with Net::BitTorent's development but don't
know where to begin, here are a few ideas.
"Net::BitTorrent" is too large for just one person to hack on. If
you're Perl adept and would like to help, you can start by forking the project
on github: http://github.com/sanko/net-bittorrent/. When ready, send me a pull
request, I'll look over your changes and get back to you. Minor patches get
your name in the changelog. Major patches get your name in the Acknowledgments
section and an invitation to be a trusted collaborator. Oooo. Ahhh.
THIS PROJECT IS ACTIVELY SEEKING DEVELOPERS.
If you're interested in helping clear things out of the TODO list or if you have
a suggestion and are willing to see it through to completion, contact me or,
better yet, go ahead and fork the project on github:
http://github.com/sanko/net-bittorrent.
In general, N::B could use a second or third pair of eyes. So, if you're
interested in BitTorrent, p2p, or just Perl in general, let me know.
Found bugs should be reported through "Net::BitTorrent"'s Issue
Tracker. Before creating a new report through "Net::BitTorrent"'s
Issue Tracker, please review the following list:
- 1.
- Make sure you are using the most recent stable release.
- 2.
- Make sure the bug is reproducible.
- 3.
- Please write in clear English.
- 4.
- Provide "baby steps" to describe exactly how to replicate the
bug. Sample code is welcome. The issue tracker also allows attachments so,
if relevant, include the .torrent file.
- 5.
- Search the list of open and resolved issues to make sure the flaw hasn't
already been reported. If it has, star the issue to stay up to date.
- 6.
- One bug is one bug report. Please do not include multiple, separate issues
in one report unless they are explicitly related to each other.
- 7.
- Star the issue so you'll be notified of any changes.
- 8.
- Look over your report before submission to be sure you've included as much
detail as possible. Seriously. Get up, have a drink of water, come back,
read over it again to make sure you've included everything you intended,
and then submit it.
Becoming a CPAN Tester is an easy, automatic way to contribute to the quality of
your favorite module and CPAN in general. If you would like to contribute
automated test reports for "Net::BitTorrent", install
"CPAN::Reporter" from the CPAN shell first:
$ cpan
cpan> install CPAN::Reporter
cpan> reload cpan
cpan> o conf init test_report
[...follow the CPAN::Reporter setup prompts...]
cpan> o conf commit
cpan> install Net::BitTorrent
For more on becoming a CPAN Tester and why this is useful, see the
CPAN::Reporter documentation and http://cpantesters.org/.
- Website and Blog
- The official website is http://sankorobinson.com/net-bittorrent/ and
related blog entries are posted to http://sankorobinson.com/.
If you're looking for a feed with only on-topic articles, subscribe to
http://sankorobinson.com/atom/?tag=Net::BitTorrent
- Live support
- The official means of support for "Net::BitTorrent" is through
"#net-bittorrent" on the p2p IRC network:
irc://irc.p2p-network.net/net-bittorrent
- Receive Commit and Issue Tracker Updates
- These are posted to the public mailing list for which both ATOM 1.0 and
RSS 2.0 feeds are available; see
http://groups.google.com/group/net-bittorrent/feeds.
- Mailinglist
- To subscribe to the list or view the archive, visit
http://groups.google.com/group/net-bittorrent. Both ATOM 1.0 and RSS 2.0
feeds are provided; see
http://groups.google.com/group/net-bittorrent/feeds for a list.
- Issue Tracker
- Use http://github.com/sanko/net-bittorrent/issues for bug tracking. Please
include as much information as possible and review the list above.
- Twitter
- I announce stable builds and occasionally complain on Twitter:
http://twitter.com/net_bitTorrent
- •
- libtorrent (<http://www.rasterbar.com/products/libtorrent/>) is
covered by the The BSD License.
- •
- Bitflu (<http://bitflu.workaround.ch/>) is a full client written in
*nix oriented Perl. It is available under the Perl/Artistic License.
- •
- btpeer (<http://www.alhem.net/project/btpeer/>) is "a
collection of classes implementing the core client functionality of the
BitTorrent protocol" and has been released under the GPL.
- •
- Arctic (<http://dev.int64.org/arctic.html>) is a minimal client
based on libtorrent, written in C++ and released under the MIT
License.
- RFC 3986 (URI: Generic Syntax)
- Section 2.3. "Unreserved Characters"
(<http://tools.ietf.org/html/rfc3986#section-2.3>)
- PAUSE FAQ sub-section entitled "Developer Releases"
- (<http://www.cpan.org/modules/04pause.html>)
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008-2009 by Sanko Robinson <sanko@cpan.org>
This program is free software; you can redistribute it and/or modify it under
the terms of The Artistic License 2.0. See the
LICENSE file included
with this distribution or http://www.perlfoundation.org/artistic_license_2_0.
For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.
When separated from the distribution, all POD documentation is covered by the
Creative Commons Attribution-Share Alike 3.0 License. See
http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification,
see http://creativecommons.org/licenses/by-sa/3.0/us/.
Neither this module nor the Author is affiliated with BitTorrent, Inc.