root / dotorg / trunk / html / beps / bep_0017.html

Revision 11040, 7.5 kB (checked in by dave, 8 weeks ago)

All HTML docs now reference the new SVN server running at bittorrent.org

Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7<title></title>
8<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9</head>
10<body>
11<div class="document">
12
13<div id="upper" class="clear">
14<div id="wrap">
15<div id="header">
16<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17</div>
18<div id="nav">
19<ul>
20<li><a href="../index.html">Home</a></li>
21<li><a href="../introduction.html">For Users</a></li>
22<li><a href="bep_0000.html"><span>For Developers</span></a></li>
23<!-- <li><a href="./blog">Blog</a></li> -->
24<li><a href="http://forum.bittorrent.org"> Forums </li>
25<li><a href="../donate.html">Donate!</a></li>
26</ul>
27</div> <!-- nav -->
28<!-- ### Begin Content ### -->
29<div id="second">
30
31
32
33<table class="rfc2822 docutils field-list" frame="void" rules="none">
34<col class="field-name" />
35<col class="field-body" />
36<tbody valign="top">
37<tr class="field"><th class="field-name">BEP:</th><td class="field-body">17</td>
38</tr>
39<tr class="field"><th class="field-name">Title:</th><td class="field-body">HTTP Seeding</td>
40</tr>
41<tr class="field"><th class="field-name">Version:</th><td class="field-body">11020</td>
42</tr>
43<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://svn.bittorrent.org/trac/browser/dotorg/trunk/html/beps/bep_0017.rst">2008-02-25 22:14:29 -0800 (Mon, 25 Feb 2008)</a></td>
44</tr>
45<tr class="field"><th class="field-name">Author:</th><td class="field-body">John Hoffman &lt;theshadow&#32;&#97;t&#32;degreez.net&gt;, DeHackEd</td>
46</tr>
47<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
48</tr>
49<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
50</tr>
51<tr class="field"><th class="field-name">Created:</th><td class="field-body">07-Feb-2008</td>
52</tr>
53<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
54</tr>
55</tbody>
56</table>
57<hr />
58<div class="contents topic" id="contents">
59<p class="topic-title first">Contents</p>
60<ul class="simple">
61<li><a class="reference internal" href="#metadata-extension" id="id2">Metadata Extension</a></li>
62<li><a class="reference internal" href="#protocol" id="id3">Protocol</a></li>
63<li><a class="reference internal" href="#server-side-implementation-notes" id="id4">Server-side Implementation Notes</a></li>
64<li><a class="reference internal" href="#client-side-implementation-notes" id="id5">Client-side Implementation Notes</a></li>
65</ul>
66</div>
67<div class="section" id="metadata-extension">
68<h1>Metadata Extension</h1>
69<ul class="simple">
70<li>&quot;httpseeds&quot;</li>
71</ul>
72<p>In the main area of the metadata file and not part of the &quot;info&quot;
73section, will be a new key, &quot;httpseeds&quot;.  This key will refer to a
74list of URLs, and will contain a list of web addresses where torrent
75data can be retrieved.  This key may be safely ignored if the client
76is not capable of using it.</p>
77<p>Examples:</p>
78<pre class="literal-block">
79d['httpseeds'] = [ 'http://www.whatever.com/seed.php' ]
80</pre>
81<p>This specifies the client can retrieve data by accessing the given
82URL with the parameters supplied in the protocol specification
83below:</p>
84<pre class="literal-block">
85d['httpseeds'] = [ 'http://www.site1.com/source1.php',
86                   'http://www.site2.com/source2.php'  ]
87</pre>
88<p>More than one URL may be specified; if so, the client will attempt
89to access both URLs to download seed data.</p>
90</div>
91<div class="section" id="protocol">
92<h1>Protocol</h1>
93<p>The client calls the URL given, in the following format:</p>
94<pre class="literal-block">
95&lt;url&gt;?info_hash=[hash]&amp;piece=[piece]{&amp;ranges=[start]-[end]{,[start]-[end]}...}
96</pre>
97<p>Examples:</p>
98<pre class="literal-block">
99http://www.whatever.com/seed.php?info_hash=%9C%D9i%8A%F5Uu%1A%91%86%AE%06lW%EA%21W%235%E0&amp;piece=3
100http://www.whatever.com/seed.php?info_hash=%9C%D9i%8A%F5Uu%1A%91%86%AE%06lW%EA%21W%235%E0&amp;piece=8&amp;ranges=49152-131071,180224-262143
101</pre>
102<p>The URL would be for a script which has access to the files
103contained in the torrent, and to the metadata (.torrent) file
104itself, so that it may calculate what byte ranges to pull from
105what files.  One such script has been written by DeHackEd, and
106is available at <a class="reference external" href="http://bt.degreez.net">http://bt.degreez.net</a> .</p>
107<p>The script should return, if everything is okay, either a status
108of 200 (OK) and a block of data (either the entire piece if no
109ranges were given, or the ranges of data requested for that piece
110appended together), in binary format, or 503 (Service Temporarily
111Unavailable), with the body of the return being an ASCII integer
112value specifying how long the client should wait before retrying.
113The client should consider any other return code as an error.
114In the case of an error, the client should retry, but should
115retry less often if the failure to contact the seed continues.</p>
116</div>
117<div class="section" id="server-side-implementation-notes">
118<h1>Server-side Implementation Notes</h1>
119<p>The purpose of the http seed script is to limit access to the
120data being downloaded so that the web server isn't overwhelmed
121by clients asking for the data.  If it weren't for this limiting,
122there would be no way to prevent someone from coding a client
123to try to download continuously or multiply, resulting in a
124heavy load on the server.  Limiting the download rate also
125allows an http seed script to be run on a web account where
126the total amount of data downloaded is restricted or may result
127in extra service charges.</p>
128<p>The script must provide three major functions:</p>
129<ol class="arabic simple">
130<li>Limit its average upload to a reasonable level.</li>
131<li>Intelligently tell peers how long they should wait before
132retrying.</li>
133<li>translate from an info-hash and piece number to a byte range
134within a file or set of files, and return those bytes.</li>
135</ol>
136<p>Another highly desirable function is to check whether peers are
137retrying too often, and to automatically ban those peers.</p>
138<p>Other desirable features include a way of monitoring the tracker
139the torrent is using and to stop uploading data if sufficient
140P2P seeds exist, and a way to feed back to the tracker to show
141a seed is present.</p>
142</div>
143<div class="section" id="client-side-implementation-notes">
144<h1>Client-side Implementation Notes</h1>
145<p>The prototype code base has a default retry time of 30 seconds;
146after 3 retries with errors, the time is lengthened with each
147cycle.</p>
148<p>The prototype code will not display any errors with contacting
149http seeds (unless the URL given in the .torrent is incorrect)
150until it has received data from that seed.  (The prototype code
151also won't display any errors for any http reply that was
152actually received.)</p>
153<p>Current behavior is:  Request the rarest piece you're missing
154in entirety that you can locate.  If you have no pieces that
155aren't partially downloaded, skip one retry cycle, then start
156requesting partials.  If you receive a 503 response, set the
157retry time equal to the integer value received in the response.</p>
158<!-- Local Variables:
159mode: indented-text
160indent-tabs-mode: nil
161sentence-end-double-space: t
162fill-column: 70
163coding: utf-8
164End: -->
165</div>
166
167
168</div>
169        <div id="footer">
170<hr/>
171</div>
172
173</div>
174</body>
175</html>
Note: See TracBrowser for help on using the browser.