root / dotorg / v9 / html / beps / bep_0017.html

Revision 10883, 7.3 kB (checked in by dave, 11 months ago)

"For Developers" on each html now links back to the BEP index, i.e., bep_0000.html.

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