NAME

Net::BitTorrent::Protocol::BEP06 - Packet Utilities for BEP06: Fast Extension

Synopsis

    use Net::BitTorrent::Protocol::BEP06 qw[all];
    my $index = parse_allowed_fast($data);

Description

The Fast Extension modifies the semantics of the Request, Choke, Unchoke, and Cancel, and adds a Reject Request. Now, every request is guaranteed to result in exactly one response which is either the corresponding reject or corresponding piece message. Even when a request is cancelled, the peer receiving the cancel should respond with either the corresponding reject or the corresponding piece: requests that are being processed are allowed to complete.

Choke no longer implicitly rejects all pending requests, thus eliminating some race conditions which could cause pieces to be needlessly requested multiple times.

Importing from Net::BitTorrent::Protocol::BEP06

There are four tags available for import. To get them all in one go, use the :all tag.

:types

Packet types

For more on what these packets actually mean, see the Fast Extension spec. This is a list of the currently supported packet types.

$SUGGEST

$HAVE_ALL

$HAVE_NONE

$REJECT

$ALLOWED_FAST

:build

These create packets ready-to-send to remote peers. See Building Functions.

:parse

These are used to parse unknown data into sensible packets. The same packet types we can build, we can also parse. See Parsing Functions.

:utils

Helpful functions listed in the section entitled Utility Functions.

Building Functions

build_have_all( )

Creates an advisory packet which claims you have all pieces and can seed.

You should send this rather than a bitfield of all true values.

build_have_none( )

Creates an advisory packet which claims you have no data related to the torrent.

build_suggest( $index )

Creates an advisory message meaning "you might like to download this piece." The intended usage is for 'super-seeding' without throughput reduction, to avoid redundant downloads, and so that a seed which is disk I/O bound can upload contiguous or identical pieces to avoid excessive disk seeks.

You should send this instead of a bitfield of nothing but null values.

build_reject ( $index, $offset, $length )

Creates a packet which is used to notify a requesting peer that its request will not be satisfied.

build_allowed_fast ( $index )

Creates an advisory message which means "if you ask for this piece, I'll give it to you even if you're choked."

Parsing Functions

These are the parsing counterparts for the build_ functions.

When the packet is invalid, a hash reference is returned with a single key: error. The value is a string describing what went wrong.

Return values for valid packets are explained below.

parse_have_all( $data )

Returns an empty list. HAVE ALL packets do not contain a payload.

parse_have_none( $data )

Returns an empty list. HAVE NONE packets do not contain a payload.

parse_suggest( $data )

Returns an integer.

parse_reject( $data )

Returns an array reference containing the $index, $offset, and $length.

parse_allowed_fast( $data )

Returns an integer.

Utility Functions

generate_fast_set( $k, $sz, $infohash, $ip )

Returns a list of integers. $k is the number of pieces in the set, $sz is the number of pieces in the torrent, $infohash is the packed infohash, $ip is the IPv4 (dotted quad) address of the peer this set will be generated for.

    my $data = join '',
        map { build_allowed_fast($_) }
        generate_fast_set(7, 1313, "\xAA" x 20, '80.4.4.200');

See Also

http://bittorrent.org/beps/bep_0006.html - Fast Extension

Author

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

CPAN ID: SANKO

License and Legal

Copyright (C) 2008-2012 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 notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.

Neither this module nor the Author is affiliated with BitTorrent, Inc.