| 1 | BEP: 17 |
|---|
| 2 | Title: HTTP Seeding |
|---|
| 3 | Version: $Revision$ |
|---|
| 4 | Last-Modified: $Date$ |
|---|
| 5 | Author: John Hoffman <theshadow@degreez.net>, DeHackEd |
|---|
| 6 | Status: Draft |
|---|
| 7 | Type: Standards Track |
|---|
| 8 | Created: 07-Feb-2008 |
|---|
| 9 | Post-History: |
|---|
| 10 | |
|---|
| 11 | |
|---|
| 12 | Metadata Extension |
|---|
| 13 | ================== |
|---|
| 14 | |
|---|
| 15 | * "httpseeds" |
|---|
| 16 | |
|---|
| 17 | In the main area of the metadata file and not part of the "info" |
|---|
| 18 | section, will be a new key, "httpseeds". This key will refer to a |
|---|
| 19 | list of URLs, and will contain a list of web addresses where torrent |
|---|
| 20 | data can be retrieved. This key may be safely ignored if the client |
|---|
| 21 | is not capable of using it. |
|---|
| 22 | |
|---|
| 23 | Examples:: |
|---|
| 24 | |
|---|
| 25 | d['httpseeds'] = [ 'http://www.whatever.com/seed.php' ] |
|---|
| 26 | |
|---|
| 27 | This specifies the client can retrieve data by accessing the given |
|---|
| 28 | URL with the parameters supplied in the protocol specification |
|---|
| 29 | below:: |
|---|
| 30 | |
|---|
| 31 | d['httpseeds'] = [ 'http://www.site1.com/source1.php', |
|---|
| 32 | 'http://www.site2.com/source2.php' ] |
|---|
| 33 | |
|---|
| 34 | More than one URL may be specified; if so, the client will attempt |
|---|
| 35 | to access both URLs to download seed data. |
|---|
| 36 | |
|---|
| 37 | |
|---|
| 38 | Protocol |
|---|
| 39 | ======== |
|---|
| 40 | |
|---|
| 41 | The client calls the URL given, in the following format:: |
|---|
| 42 | |
|---|
| 43 | <url>?info_hash=[hash]&piece=[piece]{&ranges=[start]-[end]{,[start]-[end]}...} |
|---|
| 44 | |
|---|
| 45 | Examples:: |
|---|
| 46 | |
|---|
| 47 | http://www.whatever.com/seed.php?info_hash=%9C%D9i%8A%F5Uu%1A%91%86%AE%06lW%EA%21W%235%E0&piece=3 |
|---|
| 48 | http://www.whatever.com/seed.php?info_hash=%9C%D9i%8A%F5Uu%1A%91%86%AE%06lW%EA%21W%235%E0&piece=8&ranges=49152-131071,180224-262143 |
|---|
| 49 | |
|---|
| 50 | The URL would be for a script which has access to the files |
|---|
| 51 | contained in the torrent, and to the metadata (.torrent) file |
|---|
| 52 | itself, so that it may calculate what byte ranges to pull from |
|---|
| 53 | what files. One such script has been written by DeHackEd, and |
|---|
| 54 | is available at http://bt.degreez.net . |
|---|
| 55 | |
|---|
| 56 | The script should return, if everything is okay, either a status |
|---|
| 57 | of 200 (OK) and a block of data (either the entire piece if no |
|---|
| 58 | ranges were given, or the ranges of data requested for that piece |
|---|
| 59 | appended together), in binary format, or 503 (Service Temporarily |
|---|
| 60 | Unavailable), with the body of the return being an ASCII integer |
|---|
| 61 | value specifying how long the client should wait before retrying. |
|---|
| 62 | The client should consider any other return code as an error. |
|---|
| 63 | In the case of an error, the client should retry, but should |
|---|
| 64 | retry less often if the failure to contact the seed continues. |
|---|
| 65 | |
|---|
| 66 | |
|---|
| 67 | Server-side Implementation Notes |
|---|
| 68 | ================================ |
|---|
| 69 | |
|---|
| 70 | The purpose of the http seed script is to limit access to the |
|---|
| 71 | data being downloaded so that the web server isn't overwhelmed |
|---|
| 72 | by clients asking for the data. If it weren't for this limiting, |
|---|
| 73 | there would be no way to prevent someone from coding a client |
|---|
| 74 | to try to download continuously or multiply, resulting in a |
|---|
| 75 | heavy load on the server. Limiting the download rate also |
|---|
| 76 | allows an http seed script to be run on a web account where |
|---|
| 77 | the total amount of data downloaded is restricted or may result |
|---|
| 78 | in extra service charges. |
|---|
| 79 | |
|---|
| 80 | The script must provide three major functions: |
|---|
| 81 | |
|---|
| 82 | 1. Limit its average upload to a reasonable level. |
|---|
| 83 | |
|---|
| 84 | 2. Intelligently tell peers how long they should wait before |
|---|
| 85 | retrying. |
|---|
| 86 | |
|---|
| 87 | 3. translate from an info-hash and piece number to a byte range |
|---|
| 88 | within a file or set of files, and return those bytes. |
|---|
| 89 | |
|---|
| 90 | Another highly desirable function is to check whether peers are |
|---|
| 91 | retrying too often, and to automatically ban those peers. |
|---|
| 92 | |
|---|
| 93 | Other desirable features include a way of monitoring the tracker |
|---|
| 94 | the torrent is using and to stop uploading data if sufficient |
|---|
| 95 | P2P seeds exist, and a way to feed back to the tracker to show |
|---|
| 96 | a seed is present. |
|---|
| 97 | |
|---|
| 98 | |
|---|
| 99 | |
|---|
| 100 | Client-side Implementation Notes |
|---|
| 101 | ================================ |
|---|
| 102 | |
|---|
| 103 | The prototype code base has a default retry time of 30 seconds; |
|---|
| 104 | after 3 retries with errors, the time is lengthened with each |
|---|
| 105 | cycle. |
|---|
| 106 | |
|---|
| 107 | The prototype code will not display any errors with contacting |
|---|
| 108 | http seeds (unless the URL given in the .torrent is incorrect) |
|---|
| 109 | until it has received data from that seed. (The prototype code |
|---|
| 110 | also won't display any errors for any http reply that was |
|---|
| 111 | actually received.) |
|---|
| 112 | |
|---|
| 113 | Current behavior is: Request the rarest piece you're missing |
|---|
| 114 | in entirety that you can locate. If you have no pieces that |
|---|
| 115 | aren't partially downloaded, skip one retry cycle, then start |
|---|
| 116 | requesting partials. If you receive a 503 response, set the |
|---|
| 117 | retry time equal to the integer value received in the response. |
|---|
