Changeset 10508

dotorg/trunk/html/beps/Makefile

r10506	r10508
5	5	bep_0003.html \
6	6	bep_0004.html \
	7	bep_0005.html \
7	8	bep_0006.html \
8	9	bep_0007.html \
9	10	bep_0008.html \
10	11	bep_0009.html \
	12	bep_1000.html \
11	13
12	14	all: $(BEPS)
13	15
14	16	%.html:%.rst
15		rstbep2html.py --template=~~../template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/screen~~.css --no-toc-backlinks $? >$@ --traceback
	17	rstbep2html.py --template=template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/bep.css --no-toc-backlinks $? >$@ --traceback
16	18
17	19	#~/docutils/tools/rst2html.py --template=../template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/screen.css --no-doc-title --no-toc-backlinks $? >$@

dotorg/trunk/html/beps/bep_0000.html

r10506	r10508
	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><span>For Developers</span></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">0</td>
	37	</tr>
	38	<tr class="field"><th class="field-name">Title:</th><td class="field-body">Index of BitTorrent Enhancement Proposals</td>
	39	</tr>
	40	<tr class="field"><th class="field-name">Version:</th><td class="field-body">1</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_0000.rst">11-Jan-2008</a></td>
	43	</tr>
	44	<tr class="field"><th class="field-name">Author:</th><td class="field-body">David Harrison <dave at bittorrent.com></td>
	45	</tr>
	46	<tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
	47	</tr>
	48	<tr class="field"><th class="field-name">Type:</th><td class="field-body">Process</td>
	49	</tr>
	50	<tr class="field"><th class="field-name">Created:</th><td class="field-body">10-Jan-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	<p>The BitTorrent Community Forum coordinates the development of the
	58	BitTorrent protocol suite and its reference implementation. It is the
	59	wish of Bram Cohen that the BitTorrent mainline python implementation
	60	remain open source and that the protocol development process be
	61	modelled after the Python Enhancement Proposal (PEP) process.</p>
	62	<p>This document indexes all BitTorrent Enhancement Proposals (BEPs).
	63	When a new proposal is submitted, one of the BitTorrent.org editors
	64	assigns a BEP number and updates this index appropriately. The process
	65	is modelled after the PEP process used in the python community <a class="footnote-reference" href="#python" id="id1">[1]</a>. Each
	66	document has a number that never changes and the history of document is
	67	maintained in subversion <a class="footnote-reference" href="#svn" id="id2">[2]</a>.</p>
	68	<table border="1" class="docutils">
	69	<colgroup>
	70	<col width="13%" />
	71	<col width="88%" />
	72	</colgroup>
	73	<thead valign="bottom">
	74	<tr><th class="head">Num</th>
	75	<th class="head">Title</th>
	76	</tr>
	77	</thead>
	78	<tbody valign="top">
	79	<tr><td><span class="raw-html"><A HREF="bep_0000.html">0</A></span></td>
	80	<td>Index of BitTorrent Enhancement Proporsals</td>
	81	</tr>
	82	<tr><td><span class="raw-html"><A HREF="bep_0001.html">1</A></span></td>
	83	<td>The BEP Process</td>
	84	</tr>
	85	<tr><td><span class="raw-html"><A HREF="bep_0002.html">2</A></span></td>
	86	<td>The BitTorrent Protocol Specification</td>
	87	</tr>
	88	<tr><td><span class="raw-html"><A HREF="bep_0003.html">3</A></span></td>
	89	<td>Known Number Allocations</td>
	90	</tr>
	91	<tr><td><span class="raw-html"><A HREF="bep_0004.html">4</A></span></td>
	92	<td>DHT Protocol</td>
	93	</tr>
	94	<tr><td><span class="raw-html"><A HREF="bep_0005.html">5</A></span></td>
	95	<td>Fast Extension</td>
	96	</tr>
	97	<tr><td><span class="raw-html"><A HREF="bep_0006.html">6</A></span></td>
	98	<td>IPv6 Tracker Extension</td>
	99	</tr>
	100	<tr><td><span class="raw-html"><A HREF="bep_0007.html">7</A></span></td>
	101	<td>Tracker Peer Obfuscation</td>
	102	</tr>
	103	<tr><td><span class="raw-html"><A HREF="bep_0008.html">8</A></span></td>
	104	<td>Metadata Extension</td>
	105	</tr>
	106	<tr><td><span class="raw-html"><A HREF="bep_0009.html">9</A></span></td>
	107	<td>Extension Protocol</td>
	108	</tr>
	109	<tr><td><span class="raw-html"><A HREF="bep_1000.html">1000</A></span></td>
	110	<td>Pending Standards Track Documents</td>
	111	</tr>
	112	</tbody>
	113	</table>
	114	<table class="docutils footnote" frame="void" id="python" rules="none">
	115	<colgroup><col class="label" /><col /></colgroup>
	116	<tbody valign="top">
	117	<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://www.python.org/dev/peps/">http://www.python.org/dev/peps/</a></td></tr>
	118	</tbody>
	119	</table>
	120	<table class="docutils footnote" frame="void" id="svn" rules="none">
	121	<colgroup><col class="label" /><col /></colgroup>
	122	<tbody valign="top">
	123	<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td><a class="reference external" href="http://svn.bittorrent.org">http://svn.bittorrent.org</a></td></tr>
	124	</tbody>
	125	</table>
	126
	127
	128	</div>
	129	<div id="footer">
	130	<hr/>
	131	<p>Copyright 2006 BitTorrent.org</p>
	132	</div>
	133
	134	</div>
	135	</body>
	136	</html>

dotorg/trunk/html/beps/bep_0000.rst

r10491	r10508
3	3	Version: 1
4	4	Last-Modified: 11-Jan-2008
5		Author: David Harrison
	5	Author: David Harrison <dave@bittorrent.com>
6	6	Status: Active
7	7	Type: Process
…	…
13	13	wish of Bram Cohen that the BitTorrent mainline python implementation
14	14	remain open source and that the protocol development process be
15		modelled after the Python Enhancement Proposal~(PEP) process.
	15	modelled after the Python Enhancement Proposal (PEP) process.
16	16
17	17	This document indexes all BitTorrent Enhancement Proposals (BEPs).
18	18	When a new proposal is submitted, one of the BitTorrent.org editors
19	19	assigns a BEP number and updates this index appropriately. The process
20		is modelled after the PEP process used in the python community [#python]. Each
	20	is modelled after the PEP process used in the python community [#python]_. Each
21	21	document has a number that never changes and the history of document is
22		maintained in subversion [#svn].
	22	maintained in subversion [#svn]_.
23	23
24	24
25		===== =========================================
26		Num Title
27		===== =========================================
28		0_ Index of BitTorrent Enhancement Proporsals
29		1_ The BEP Process
30		2_ The BitTorrent Protocol Specification
31		3_ Known Number Allocations
32		4_ DHT Protocol
33		5_ Fast Extension
34		6_ IPv6 Tracker Extension
35		7_ Tracker Peer Obfuscation
36		8_ Metadata Extension
37		9_ Extension Protocol
38		===== =========================================
	25	====== ==========================================
	26	Num Title
	27	====== ==========================================
	28	\|0\| Index of BitTorrent Enhancement Proporsals
	29	\|1\| The BEP Process
	30	\|2\| The BitTorrent Protocol Specification
	31	\|3\| Known Number Allocations
	32	\|4\| DHT Protocol
	33	\|5\| Fast Extension
	34	\|6\| IPv6 Tracker Extension
	35	\|7\| Tracker Peer Obfuscation
	36	\|8\| Metadata Extension
	37	\|9\| Extension Protocol
	38	\|1000\| Pending Standards Track Documents
	39	====== ==========================================
39	40
40	41
	42	.. role:: raw-html(raw)
	43	:format: html
41	44
42	45	.. [#python] http://www.python.org/dev/peps/
43	46	.. [#svn] http://svn.bittorrent.org
44		.. _0: bep_0000.html
45		.. _1: bep_0001.html
46		.. _2: bep_0002.html
47		.. _3: bep_0003.html
48		.. _4: bep_0004.html
49		.. _5: bep_0005.html
50		.. _6: bep_0006.html
51		.. _7: bep_0007.html
52		.. _8: bep_0008.html
53		.. _9: bep_0009.html
54		.. _10: bep_0010.html
55		.. _11: bep_0011.html
	47	.. \|0\| replace:: :raw-html:`<A HREF="bep_0000.html">0</A>`
	48	.. \|1\| replace:: :raw-html:`<A HREF="bep_0001.html">1</A>`
	49	.. \|2\| replace:: :raw-html:`<A HREF="bep_0002.html">2</A>`
	50	.. \|3\| replace:: :raw-html:`<A HREF="bep_0003.html">3</A>`
	51	.. \|4\| replace:: :raw-html:`<A HREF="bep_0004.html">4</A>`
	52	.. \|5\| replace:: :raw-html:`<A HREF="bep_0005.html">5</A>`
	53	.. \|6\| replace:: :raw-html:`<A HREF="bep_0006.html">6</A>`
	54	.. \|7\| replace:: :raw-html:`<A HREF="bep_0007.html">7</A>`
	55	.. \|8\| replace:: :raw-html:`<A HREF="bep_0008.html">8</A>`
	56	.. \|9\| replace:: :raw-html:`<A HREF="bep_0009.html">9</A>`
	57	.. \|1000\| replace:: :raw-html:`<A HREF="bep_1000.html">1000</A>`

dotorg/trunk/html/beps/bep_0002.html

r10506	r10508
6	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7	7	<title></title>
8		<link rel="stylesheet" href="../css/~~screen~~.css" type="text/css" />
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9	9	</head>
10	10	<body>
…	…
14	14	<div id="wrap">
15	15	<div id="header">
16		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17	17	</div>
18	18	<div id="nav">
19	19	<ul>
20		<li><a href="./index.html">Home</a></li>
21		<li><a href="./introduction.html">For Users</a></li>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
22	22	<li><span>For Developers</span></li>
23	23	<!-- <li><a href="./blog">Blog</a></li> -->
24		<li><a href="./donate.html">Donate!</a></li>
	24	<li><a href="../donate.html">Donate!</a></li>
25	25	</ul>
26	26	</div> <!-- nav -->
…	…
112	112	<h1>The connectivity is as follows:</h1>
113	113	<ul class="simple">
114		<li>Strings are length-prefixed base ten followed by a colon and the string. For example ~~<code>4:spam</code>~~ corresponds to 'spam'.</li>
	114	<li>Strings are length-prefixed base ten followed by a colon and the string. For example <tt class="docutils literal"><span class="pre">4:spam</span></tt> corresponds to 'spam'.</li>
115	115	<li>Integers are represented by an 'i' followed by the number in base 10
116		followed by an 'e'. For example ~~<code>i3e</code>~~ corresponds to 3 and
117		<code>i-3e </code>corresponds to -3. Integers have no size
118		~~limitation. <code>i-0e</code>~~ is invalid. All encodings with a leading
119		zero, such as ~~<code>i03e</code>~~, are invalid, other than
120		~~<code>i0e</code>~~, which of course corresponds to 0.</li>
	116	followed by an 'e'. For example <tt class="docutils literal"><span class="pre">i3e</span></tt> corresponds to 3 and
	117	<tt class="docutils literal"><span class="pre">i-3e</span> <span class="pre">``corresponds</span> <span class="pre">to</span> <span class="pre">-3.</span> <span class="pre">Integers</span> <span class="pre">have</span> <span class="pre">no</span> <span class="pre">size</span>
	118	<span class="pre">limitation.</span> <span class="pre">``i-0e</span></tt> is invalid. All encodings with a leading
	119	zero, such as <tt class="docutils literal"><span class="pre">i03e</span></tt>, are invalid, other than
	120	<tt class="docutils literal"><span class="pre">i0e</span></tt>, which of course corresponds to 0.</li>
121	121	<li>Lists are encoded as an 'l' followed by their elements (also
122		bencoded) followed by an 'e'. For example ~~<code>l4:spam4:eggse</code>~~
	122	bencoded) followed by an 'e'. For example <tt class="docutils literal"><span class="pre">l4:spam4:eggse</span></tt>
123	123	corresponds to ['spam', 'eggs'].</li>
124	124	<li>Dictionaries are encoded as a 'd' followed by a list of alternating
125	125	keys and their corresponding values followed by an 'e'. For example,
126		~~<code>d3:cow3:moo4:spam4:eggse</code>~~ corresponds to {'cow': 'moo',
127		'spam': 'eggs'} and ~~<code>d4:spaml1:a1:bee</code>~~ corresponds to
	126	<tt class="docutils literal"><span class="pre">d3:cow3:moo4:spam4:eggse</span></tt> corresponds to {'cow': 'moo',
	127	'spam': 'eggs'} and <tt class="docutils literal"><span class="pre">d4:spaml1:a1:bee</span></tt> corresponds to
128	128	{'spam': ['a', 'b']}. Keys must be strings and appear in sorted order
129	129	(sorted as raw strings, not alphanumerics).</li>
…	…
137	137	<dt>info</dt>
138	138	<dd><p class="first">This maps to a dictionary, with keys described below.</p>
139		<p>The ~~<code>name</code>~~ key maps to a string which is the suggested name
	139	<p>The <tt class="docutils literal"><span class="pre">name</span></tt> key maps to a string which is the suggested name
140	140	to save the file (or directory) as. It is purely advisory.</p>
141		<p>~~<code>piece length</code>~~ maps to the number of bytes in each piece
	141	<p><tt class="docutils literal"><span class="pre">piece</span> <span class="pre">length</span></tt> maps to the number of bytes in each piece
142	142	the file is split into. For the purposes of transfer, files are
143	143	split into fixed-size pieces which are all the same length except for
144		possibly the last one which may be truncated. ~~<code>piece~~
145		~~length</code>~~ is almost always a power of two, most commonly 2 18 =
	144	possibly the last one which may be truncated. <tt class="docutils literal"><span class="pre">piece</span>
	145	<span class="pre">length</span></tt> is almost always a power of two, most commonly 2 18 =
146	146	256 K (BitTorrent prior to version 3.2 uses 2 20 = 1 M as
147	147	default).</p>
148		<p>~~<code>pieces</code>~~ maps to a string whose length is a multiple of
	148	<p><tt class="docutils literal"><span class="pre">pieces</span></tt> maps to a string whose length is a multiple of
149	149	20. It is to be subdivided into strings of length 20, each of which is
150	150	the SHA1 hash of the piece at the corresponding index.</p>
151		<p>There is also a key ~~<code>length</code> or a key <code>files</code>~~,
152		but not both or neither. If ~~<code>length</code>~~ is present then the
	151	<p>There is also a key <tt class="docutils literal"><span class="pre">length</span></tt> or a key <tt class="docutils literal"><span class="pre">files</span></tt>,
	152	but not both or neither. If <tt class="docutils literal"><span class="pre">length</span></tt> is present then the
153	153	download represents a single file, otherwise it represents a set of
154	154	files which go in a directory structure.</p>
155		<p>In the single file case, ~~<code>length</code>~~ maps to the length of
	155	<p>In the single file case, <tt class="docutils literal"><span class="pre">length</span></tt> maps to the length of
156	156	the file in bytes.</p>
157	157	<p>For the purposes of the other keys, the multi-file case is treated as
158	158	only having a single file by concatenating the files in the order they
159	159	appear in the files list. The files list is the value
160		~~<code>files</code>~~ maps to, and is a list of dictionaries containing
	160	<tt class="docutils literal"><span class="pre">files</span></tt> maps to, and is a list of dictionaries containing
161	161	the following keys:</p>
162		<p>~~<code>length</code>~~ - The length of the file, in bytes.</p>
163		<p>~~<code>path</code>~~ - A list of strings corresponding to subdirectory
	162	<p><tt class="docutils literal"><span class="pre">length</span></tt> - The length of the file, in bytes.</p>
	163	<p><tt class="docutils literal"><span class="pre">path</span></tt> - A list of strings corresponding to subdirectory
164	164	names, the last of which is the actual file name (a zero length list
165	165	is an error case).</p>
…	…
199	199	re-downloaded.</dd>
200	200	<dt>event</dt>
201		<dd>This is an optional key which maps to ~~<code>started</code>~~,
202		~~<code>completed</code>, or <code>stopped</code>~~ (or
203		~~<code>empty</code>~~, which is the same as not being present). If not
	201	<dd>This is an optional key which maps to <tt class="docutils literal"><span class="pre">started</span></tt>,
	202	<tt class="docutils literal"><span class="pre">completed</span></tt>, or <tt class="docutils literal"><span class="pre">stopped</span></tt> (or
	203	<tt class="docutils literal"><span class="pre">empty</span></tt>, which is the same as not being present). If not
204	204	present, this is one of the announcements done at regular
205		intervals. An announcement using ~~<code>started</code>~~ is sent when a
206		download first begins, and one using ~~<code>completed</code>~~ is sent
207		when the download is complete. No ~~<code>completed</code>~~ is sent if
	205	intervals. An announcement using <tt class="docutils literal"><span class="pre">started</span></tt> is sent when a
	206	download first begins, and one using <tt class="docutils literal"><span class="pre">completed</span></tt> is sent
	207	when the download is complete. No <tt class="docutils literal"><span class="pre">completed</span></tt> is sent if
208	208	the file was complete when started. Downloaders send an announcement
209		using ~~<code>stopped</code>~~ when they cease downloading.</dd>
	209	using <tt class="docutils literal"><span class="pre">stopped</span></tt> when they cease downloading.</dd>
210	210	</dl>
211	211	<p>Tracker responses are bencoded dictionaries. If a tracker response
212		has a key ~~<code>failure reason</code>~~, then that maps to a human
	212	has a key <tt class="docutils literal"><span class="pre">failure</span> <span class="pre">reason</span></tt>, then that maps to a human
213	213	readable string which explains why the query failed, and no other keys
214		are required. Otherwise, it must have two keys: ~~<code>interval</code>~~,
	214	are required. Otherwise, it must have two keys: <tt class="docutils literal"><span class="pre">interval</span></tt>,
215	215	which maps to the number of seconds the downloader should wait between
216		regular rerequests, and ~~<code>peers</code>. <code>peers</code>~~ maps to
217		a list of dictionaries corresponding to ~~<code>peers</code>~~, each of
218		which contains the keys ~~<code>peer id</code>, <code>ip</code>~~, and
219		~~<code>port</code>~~, which map to the peer's self-selected ID, IP
	216	regular rerequests, and <tt class="docutils literal"><span class="pre">peers</span></tt>. <tt class="docutils literal"><span class="pre">peers</span></tt> maps to
	217	a list of dictionaries corresponding to <tt class="docutils literal"><span class="pre">peers</span></tt>, each of
	218	which contains the keys <tt class="docutils literal"><span class="pre">peer</span> <span class="pre">id</span></tt>, <tt class="docutils literal"><span class="pre">ip</span></tt>, and
	219	<tt class="docutils literal"><span class="pre">port</span></tt>, which map to the peer's self-selected ID, IP
220	220	address or dns name as a string, and port number, respectively. Note
221	221	that downloaders may rerequest on nonscheduled times if an event
…	…
264	264	<p>Next comes the 20 byte sha1 hash of the bencoded form of the info
265	265	value from the metainfo file. (This is the same value which is
266		announced as ~~<code>info_hash</code>~~ to the tracker, only here it's raw
	266	announced as <tt class="docutils literal"><span class="pre">info_hash</span></tt> to the tracker, only here it's raw
267	267	instead of quoted here). If both sides don't send the same value, they
268	268	sever the connection. The one possible exception is if a downloader

dotorg/trunk/html/beps/bep_0002.rst

r10505	r10508
52	52	-------------------------------
53	53
54		- Strings are length-prefixed base ten followed by a colon and the string. For example ~~<code>4:spam</code>~~ corresponds to 'spam'.
	54	- Strings are length-prefixed base ten followed by a colon and the string. For example ``4:spam`` corresponds to 'spam'.
55	55
56	56	- Integers are represented by an 'i' followed by the number in base 10
57		followed by an 'e'. For example ~~<code>i3e</code>~~ corresponds to 3 and
58		~~<code>i-3e </code>~~corresponds to -3. Integers have no size
59		limitation. ~~<code>i-0e</code>~~ is invalid. All encodings with a leading
60		zero, such as ~~<code>i03e</code>~~, are invalid, other than
61		~~<code>i0e</code>~~, which of course corresponds to 0.
	57	followed by an 'e'. For example ``i3e`` corresponds to 3 and
	58	``i-3e`` corresponds to -3. Integers have no size
	59	limitation. ``i-0e`` is invalid. All encodings with a leading
	60	zero, such as ``i03e``, are invalid, other than
	61	``i0e``, which of course corresponds to 0.
62	62
63	63	- Lists are encoded as an 'l' followed by their elements (also
64		bencoded) followed by an 'e'. For example ~~<code>l4:spam4:eggse</code>~~
	64	bencoded) followed by an 'e'. For example ``l4:spam4:eggse``
65	65	corresponds to ['spam', 'eggs'].
66	66
67	67	- Dictionaries are encoded as a 'd' followed by a list of alternating
68	68	keys and their corresponding values followed by an 'e'. For example,
69		~~<code>d3:cow3:moo4:spam4:eggse</code>~~ corresponds to {'cow': 'moo',
70		'spam': 'eggs'} and ~~<code>d4:spaml1:a1:bee</code>~~ corresponds to
	69	``d3:cow3:moo4:spam4:eggse`` corresponds to {'cow': 'moo',
	70	'spam': 'eggs'} and ``d4:spaml1:a1:bee`` corresponds to
71	71	{'spam': ['a', 'b']}. Keys must be strings and appear in sorted order
72	72	(sorted as raw strings, not alphanumerics).
…	…
82	82	This maps to a dictionary, with keys described below.
83	83
84		The ~~<code>name</code>~~ key maps to a string which is the suggested name
	84	The ``name`` key maps to a string which is the suggested name
85	85	to save the file (or directory) as. It is purely advisory.
86	86
87		~~<code>piece length</code>~~ maps to the number of bytes in each piece
	87	``piece length`` maps to the number of bytes in each piece
88	88	the file is split into. For the purposes of transfer, files are
89	89	split into fixed-size pieces which are all the same length except for
90		possibly the last one which may be truncated. ~~<code>~~piece
91		length~~</code>~~ is almost always a power of two, most commonly 2 18 =
	90	possibly the last one which may be truncated. ``piece
	91	length`` is almost always a power of two, most commonly 2 18 =
92	92	256 K (BitTorrent prior to version 3.2 uses 2 20 = 1 M as
93	93	default).
94	94
95		~~<code>pieces</code>~~ maps to a string whose length is a multiple of
	95	``pieces`` maps to a string whose length is a multiple of
96	96	20. It is to be subdivided into strings of length 20, each of which is
97	97	the SHA1 hash of the piece at the corresponding index.
98	98
99		There is also a key ~~<code>length</code> or a key <code>files</code>~~,
100		but not both or neither. If ~~<code>length</code>~~ is present then the
	99	There is also a key ``length`` or a key ``files``,
	100	but not both or neither. If ``length`` is present then the
101	101	download represents a single file, otherwise it represents a set of
102	102	files which go in a directory structure.
103	103
104		In the single file case, ~~<code>length</code>~~ maps to the length of
	104	In the single file case, ``length`` maps to the length of
105	105	the file in bytes.
106	106
…	…
108	108	only having a single file by concatenating the files in the order they
109	109	appear in the files list. The files list is the value
110		~~<code>files</code>~~ maps to, and is a list of dictionaries containing
	110	``files`` maps to, and is a list of dictionaries containing
111	111	the following keys:
112	112
113		~~<code>length</code>~~ - The length of the file, in bytes.
114
115		~~<code>path</code>~~ - A list of strings corresponding to subdirectory
	113	``length`` - The length of the file, in bytes.
	114
	115	``path`` - A list of strings corresponding to subdirectory
116	116	names, the last of which is the actual file name (a zero length list
117	117	is an error case).
…	…
157	157
158	158	event
159		This is an optional key which maps to ~~<code>started</code>~~,
160		~~<code>completed</code>, or <code>stopped</code>~~ (or
161		~~<code>empty</code>~~, which is the same as not being present). If not
	159	This is an optional key which maps to ``started``,
	160	``completed``, or ``stopped`` (or
	161	``empty``, which is the same as not being present). If not
162	162	present, this is one of the announcements done at regular
163		intervals. An announcement using ~~<code>started</code>~~ is sent when a
164		download first begins, and one using ~~<code>completed</code>~~ is sent
165		when the download is complete. No ~~<code>completed</code>~~ is sent if
	163	intervals. An announcement using ``started`` is sent when a
	164	download first begins, and one using ``completed`` is sent
	165	when the download is complete. No ``completed`` is sent if
166	166	the file was complete when started. Downloaders send an announcement
167		using ~~<code>stopped</code>~~ when they cease downloading.
	167	using ``stopped`` when they cease downloading.
168	168
169	169	Tracker responses are bencoded dictionaries. If a tracker response
170		has a key ~~<code>failure reason</code>~~, then that maps to a human
	170	has a key ``failure reason``, then that maps to a human
171	171	readable string which explains why the query failed, and no other keys
172		are required. Otherwise, it must have two keys: ~~<code>interval</code>~~,
	172	are required. Otherwise, it must have two keys: ``interval``,
173	173	which maps to the number of seconds the downloader should wait between
174		regular rerequests, and ~~<code>peers</code>. <code>peers</code>~~ maps to
175		a list of dictionaries corresponding to ~~<code>peers</code>~~, each of
176		which contains the keys ~~<code>peer id</code>, <code>ip</code>~~, and
177		~~<code>port</code>~~, which map to the peer's self-selected ID, IP
	174	regular rerequests, and ``peers``. ``peers`` maps to
	175	a list of dictionaries corresponding to ``peers``, each of
	176	which contains the keys ``peer id``, ``ip``, and
	177	``port``, which map to the peer's self-selected ID, IP
178	178	address or dns name as a string, and port number, respectively. Note
179	179	that downloaders may rerequest on nonscheduled times if an event
…	…
234	234	Next comes the 20 byte sha1 hash of the bencoded form of the info
235	235	value from the metainfo file. (This is the same value which is
236		announced as ~~<code>info_hash</code>~~ to the tracker, only here it's raw
	236	announced as ``info_hash`` to the tracker, only here it's raw
237	237	instead of quoted here). If both sides don't send the same value, they
238	238	sever the connection. The one possible exception is if a downloader

dotorg/trunk/html/beps/bep_0003.html

r10506	r10508
6	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7	7	<title></title>
8		<link rel="stylesheet" href="../css/~~screen~~.css" type="text/css" />
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9	9	</head>
10	10	<body>
…	…
14	14	<div id="wrap">
15	15	<div id="header">
16		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17	17	</div>
18	18	<div id="nav">
19	19	<ul>
20		<li><a href="./index.html">Home</a></li>
21		<li><a href="./introduction.html">For Users</a></li>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
22	22	<li><span>For Developers</span></li>
23	23	<!-- <li><a href="./blog">Blog</a></li> -->
24		<li><a href="./donate.html">Donate!</a></li>
	24	<li><a href="../donate.html">Donate!</a></li>
25	25	</ul>
26	26	</div> <!-- nav -->

dotorg/trunk/html/beps/bep_0004.html

r10506	r10508
6	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7	7	<title></title>
8		<link rel="stylesheet" href="../css/~~screen~~.css" type="text/css" />
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9	9	</head>
10	10	<body>
…	…
14	14	<div id="wrap">
15	15	<div id="header">
16		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17	17	</div>
18	18	<div id="nav">
19	19	<ul>
20		<li><a href="./index.html">Home</a></li>
21		<li><a href="./introduction.html">For Users</a></li>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
22	22	<li><span>For Developers</span></li>
23	23	<!-- <li><a href="./blog">Blog</a></li> -->
24		<li><a href="./donate.html">Donate!</a></li>
	24	<li><a href="../donate.html">Donate!</a></li>
25	25	</ul>
26	26	</div> <!-- nav -->
…	…
44	44	<tr class="field"><th class="field-name">Author:</th><td class="field-body">Andrew Loewenstern <drue at bittorrent.com></td>
45	45	</tr>
46		<tr class="field"><th class="field-name">Status:</th><td class="field-body">~~Accepted~~</td>
	46	<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
47	47	</tr>
48	48	<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
…	…
58	58	<p class="topic-title first">Contents</p>
59	59	<ul class="simple">
60		<li><a class="reference internal" href="#overview" id="id5">Overview</a></li>
61		<li><a class="reference internal" href="#routing-table" id="id6">Routing Table</a></li>
62		<li><a class="reference internal" href="#bittorrent-protocol-extension" id="id7">BitTorrent Protocol Extension</a></li>
63		<li><a class="reference internal" href="#torrent-file-extensions" id="id8">Torrent File Extensions</a></li>
64		<li><a class="reference internal" href="#krpc-protocol" id="id9">KRPC Protocol</a></li>
65		<li><a class="reference internal" href="#dht-queries" id="id10">DHT Queries</a></li>
66		<li><a class="reference internal" href="#id2" id="id11">References</a></li>
	60	<li><a class="reference internal" href="#overview" id="id4">Overview</a></li>
	61	<li><a class="reference internal" href="#routing-table" id="id5">Routing Table</a></li>
	62	<li><a class="reference internal" href="#bittorrent-protocol-extension" id="id6">BitTorrent Protocol Extension</a></li>
	63	<li><a class="reference internal" href="#torrent-file-extensions" id="id7">Torrent File Extensions</a></li>
	64	<li><a class="reference internal" href="#krpc-protocol" id="id8">KRPC Protocol</a><ul>
	65	<li><a class="reference internal" href="#contact-encoding" id="id9">Contact Encoding</a></li>
	66	<li><a class="reference internal" href="#queries" id="id10">Queries</a></li>
	67	<li><a class="reference internal" href="#responses" id="id11">Responses</a></li>
	68	<li><a class="reference internal" href="#errors" id="id12">Errors</a></li>
	69	</ul>
	70	</li>
	71	<li><a class="reference internal" href="#dht-queries" id="id13">DHT Queries</a><ul>
	72	<li><a class="reference internal" href="#ping" id="id14">ping</a></li>
	73	<li><a class="reference internal" href="#find-node" id="id15">find_node</a></li>
	74	<li><a class="reference internal" href="#get-peers" id="id16">get_peers</a></li>
	75	<li><a class="reference internal" href="#announce-peer" id="id17">announce_peer</a></li>
	76	<li><a class="reference internal" href="#references" id="id18">References</a></li>
	77	</ul>
	78	</li>
67	79	</ul>
68	80	</div>
69	81	<p>BitTorrent uses a "distributed sloppy hash table" (DHT) for storing
70	82	peer contact information for "trackerless" torrents. In effect, each
71		peer becomes a tracker. The protocol is based on Kademila~~[Kademlia]_~~ and is
	83	peer becomes a tracker. The protocol is based on Kademila <a class="footnote-reference" href="#kademlia" id="id1">[1]</a> and is
72	84	implemented over UDP.</p>
73	85	<p>Please note the terminology used in this document to avoid
…	…
83	95	<p>Each node has a globally unique identifier known as the "node ID."
84	96	Node IDs are chosen at random from the same 160-bit space as BitTorrent
85		infohashes <a class="footnote-reference" href="#entropy" id="id~~1">[1~~]</a>. A "distance metric" is used to compare two node IDs or a node
	97	infohashes <a class="footnote-reference" href="#entropy" id="id2">[2]</a>. A "distance metric" is used to compare two node IDs or a node
86	98	ID and an infohash for "closeness." Nodes must maintain a routing table
87	99	containing the contact information for a small number of other nodes.
…	…
231	243	of the "y" key is one of "q" for query, "r" for response, or "e" for
232	244	error.</p>
233		<d~~l class="docutils~~">
234		<~~dt>Contact Encoding</dt~~>
235		<~~dd><p class="first"~~>Contact information for peers is encoded as a 6-byte string. Also
	245	<div class="section" id="contact-encoding">
	246	<h2>Contact Encoding</h2>
	247	<p>Contact information for peers is encoded as a 6-byte string. Also
236	248	known as "Compact IP-address/port info" the 4-byte IP address is in
237	249	network byte order with the 2 byte port in network byte order
238	250	concatenated onto the end.</p>
239		<p ~~class="last"~~>Contact information for nodes is encoded as a 26-byte string.
	251	<p>Contact information for nodes is encoded as a 26-byte string.
240	252	Also known as "Compact node info" the 20-byte Node ID in network byte
241	253	order has the compact IP-address/port info concatenated to the end.</p>
242		</dd>
243		<dt>Queries</dt>
244		<dd>Queries, or KRPC message dictionaries with a "y" value of "q",
	254	</div>
	255	<div class="section" id="queries">
	256	<h2>Queries</h2>
	257	<p>Queries, or KRPC message dictionaries with a "y" value of "q",
245	258	contain two additional keys; "q" and "a". Key "q" has a string value
246	259	containing the method name of the query. Key "a" has a dictionary value
247		containing named arguments to the query.</dd>
248		<dt>Responses</dt>
249		<dd>Responses, or KRPC message dictionaries with a "y" value of "r",
	260	containing named arguments to the query.</p>
	261	</div>
	262	<div class="section" id="responses">
	263	<h2>Responses</h2>
	264	<p>Responses, or KRPC message dictionaries with a "y" value of "r",
250	265	contain one additional key "r". The value of "r" is a dictionary
251	266	containing named return values. Response messages are sent upon
252		successful completion of a query.</dd>
253		<dt>Errors</dt>
254		<dd>Errors, or KRPC message dictionaries with a "y" value of "e",
	267	successful completion of a query.</p>
	268	</div>
	269	<div class="section" id="errors">
	270	<h2>Errors</h2>
	271	<p>Errors, or KRPC message dictionaries with a "y" value of "e",
255	272	contain one additional key "e". The value of "e" is a list. The first
256	273	element is an integer representing the error code. The second element
257	274	is a string containing the error message. Errors are sent when a query
258	275	cannot be fulfilled. The following table describes the possible error
259		codes:</dd>
260		</dl>
	276	codes:</p>
261	277	<table border="1" class="docutils">
262	278	<colgroup>
…	…
289	305	</pre>
290	306	</div>
	307	</div>
291	308	<div class="section" id="dht-queries">
292	309	<h1>DHT Queries</h1>
…	…
294	311	querying node. All responses have an "id" key and value containing the
295	312	node ID of the responding node.</p>
296		<d~~l class="docutils~~">
297		<~~dt>ping</dt~~>
298		<dd>The most basic query is a ping. "q" = "ping" A ping query has a
	313	<div class="section" id="ping">
	314	<h2>ping</h2>
	315	<p>The most basic query is a ping. "q" = "ping" A ping query has a
299	316	single argument, "id" the value is a 20-byte string containing the
300	317	senders node ID in network byte order. The appropriate response to a
301	318	ping has a single key "id" containing the node ID of the responding
302		node.</dd>
303		</dl>
	319	node.</p>
304	320	<pre class="literal-block">
305	321	arguments: {"id"&nbsp;: "<querying nodes id>"}
…	…
316	332	bencoded = d1:rd2:id20:mnopqrstuvwxyz123456e1:t2:aa1:y1:re
317	333	</pre>
318		<dl class="docutils">
319		<dt>find_node</dt>
320		<dd>Find node is used to find the contact information for a node given
	334	</div>
	335	<div class="section" id="find-node">
	336	<h2>find_node</h2>
	337	<p>Find node is used to find the contact information for a node given
321	338	its ID. "q" == "find_node" A find_node query has two arguments, "id"
322	339	containing the node ID of the querying node, and "target" containing
…	…
324	341	find_node query, it should respond with a key "nodes" and value of a
325	342	string containing the compact node info for the target node or the K
326		(8) closest good nodes in its own routing table.</dd>
327		</dl>
	343	(8) closest good nodes in its own routing table.</p>
328	344	<pre class="literal-block">
329	345	arguments: {"id"&nbsp;: "<querying nodes id>", "target"&nbsp;: "<id of target node>"}
…	…
340	356	bencoded = d1:rd2:id20:0123456789abcdefghij5:nodes9:def456...e1:t2:aa1:y1:re
341	357	</pre>
342		<dl class="docutils">
343		<dt>get_peers</dt>
344		<dd>Get peers associated with a torrent infohash. "q" = "get_peers" A
	358	</div>
	359	<div class="section" id="get-peers">
	360	<h2>get_peers</h2>
	361	<p>Get peers associated with a torrent infohash. "q" = "get_peers" A
345	362	get_peers query has two arguments, "id" containing the node ID of the
346	363	querying node, and "info_hash" containing the infohash of the torrent.
…	…
352	369	supplied in the query. In either case a "token" key is also included in
353	370	the return value. The token value is a required argument for a future
354		announce_peer query. The token value should be a short binary string.</dd>
355		</dl>
	371	announce_peer query. The token value should be a short binary string.</p>
356	372	<pre class="literal-block">
357	373	arguments: {"id"&nbsp;: "<querying nodes id>", "info_hash"&nbsp;: "<20-byte infohash of target torrent>"}
…	…
374	390	bencoded = d1:rd2:id20:abcdefghij01234567895:nodes9:def456...5:token8:aoeusnthe1:t2:aa1:y1:re
375	391	</pre>
376		<dl class="docutils">
377		<dt>announce_peer</dt>
378		<dd>Announce that the peer, controlling the querying node, is downloading
	392	</div>
	393	<div class="section" id="announce-peer">
	394	<h2>announce_peer</h2>
	395	<p>Announce that the peer, controlling the querying node, is downloading
379	396	a torrent on a port. announce_peer has four arguments: "id" containing the node ID of the
380	397	querying node, "info_hash" containing the infohash of the torrent,
…	…
384	401	querying node. Then the queried node should store the IP address of the
385	402	querying node and the supplied port number under the infohash in its
386		store of peer contact information.</dd>
387		</dl>
	403	store of peer contact information.</p>
388	404	<pre class="literal-block">
389	405	arguments: {"id" : "<querying nodes id>", "info_hash" : "<20-byte infohash of target torrent>", "port" : <port number>, "token" : "<opaque token>"}
…	…
401	417	bencoded = d1:rd2:id20:mnopqrstuvwxyz123456e1:t2:aa1:y1:re
402	418	</pre>
403		<p>Send questions, comments and corrections to <a class="reference external" href="mailto:editor%40bittorrent.org">editor<span>@</span>bittorrent<span>.</span>org</a></p>
404		<table class="docutils citation" frame="void" id="kademlia" rules="none">
	419	</div>
	420	<div class="section" id="references">
	421	<h2>References</h2>
	422	<table class="docutils footnote" frame="void" id="kademlia" rules="none">
405	423	<colgroup><col class="label" /><col /></colgroup>
406	424	<tbody valign="top">
407		<tr><td class="label">[Kademlia]</td><td>Peter Maymounkov, David Mazieres, "<a class="reference external" href="http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf">Kademlia: A Peer-to-peer Information System Based on the XOR Metric</a> <a class="footnote-reference" href="#id3" id="id4">[2]</a>", IPTPS 2002.</td></tr>
	425	<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Peter Maymounkov, David Mazieres, "Kademlia: A Peer-to-peer Information System Based on the XOR Metric", <em>IPTPS 2002</em>. <a class="reference external" href="http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf">http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf</a></td></tr>
408	426	</tbody>
409	427	</table>
…	…
411	429	<colgroup><col class="label" /><col /></colgroup>
412	430	<tbody valign="top">
413		<tr><td class="label"><a class="fn-backref" href="#id~~1">[1~~]</a></td><td>Use SHA1 and plenty of entropy to ensure a unique ID.</td></tr>
	431	<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Use SHA1 and plenty of entropy to ensure a unique ID.</td></tr>
414	432	</tbody>
415	433	</table>
416	434	</div>
417		~~<div class="section" id="id2">~~
418		~~<h1>References</h1>~~
419		~~<table class="docutils footnote" frame="void" id="id3" rules="none">~~
420		~~<colgroup><col class="label" /><col /></colgroup>~~
421		~~<tbody valign="top">~~
422		<tr><td class="label"><a class="fn-backref" href="#id4">[2]</a></td><td><a class="reference external" href="http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf">http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf</a></td></tr>
423		~~</tbody>~~
424		~~</table>~~
425	435	</div>
426	436

dotorg/trunk/html/beps/bep_0004.rst

r10505	r10508
4	4	Last-Modified: 11-Jan-2008
5	5	Author: Andrew Loewenstern <drue@bittorrent.com>
6		Status: ~~Accepted~~
	6	Status: Draft
7	7	Type: Standards Track
8	8	Created: 31-Jan-2008
…	…
11	11	BitTorrent uses a "distributed sloppy hash table" (DHT) for storing
12	12	peer contact information for "trackerless" torrents. In effect, each
13		peer becomes a tracker. The protocol is based on Kademila[Kademlia]_ and is
	13	peer becomes a tracker. The protocol is based on Kademila [#Kademlia]_ and is
14	14	implemented over UDP.
15	15
…	…
23	23	using the BitTorrent protocol.
24	24
	25
	26	--------
25	27	Overview
26	28	--------
…	…
69	71
70	72
	73	-------------
71	74	Routing Table
72	75	-------------
…	…
136	139
137	140
	141	-----------------------------
138	142	BitTorrent Protocol Extension
139	143	-----------------------------
…	…
158	162
159	163
	164	-----------------------
160	165	Torrent File Extensions
161	166	-----------------------
…	…
176	181
177	182
	183	-------------
178	184	KRPC Protocol
179	185	-------------
…	…
198	204
199	205	Contact Encoding
200		Contact information for peers is encoded as a 6-byte string. Also
201		known as "Compact IP-address/port info" the 4-byte IP address is in
202		network byte order with the 2 byte port in network byte order
203		concatenated onto the end.
204
205		Contact information for nodes is encoded as a 26-byte string.
206		Also known as "Compact node info" the 20-byte Node ID in network byte
207		order has the compact IP-address/port info concatenated to the end.
	206	----------------
	207
	208	Contact information for peers is encoded as a 6-byte string. Also
	209	known as "Compact IP-address/port info" the 4-byte IP address is in
	210	network byte order with the 2 byte port in network byte order
	211	concatenated onto the end.
	212
	213	Contact information for nodes is encoded as a 26-byte string.
	214	Also known as "Compact node info" the 20-byte Node ID in network byte
	215	order has the compact IP-address/port info concatenated to the end.
208	216
209	217	Queries
210		Queries, or KRPC message dictionaries with a "y" value of "q",
211		contain two additional keys; "q" and "a". Key "q" has a string value
212		containing the method name of the query. Key "a" has a dictionary value
213		containing named arguments to the query.
	218	-------
	219
	220	Queries, or KRPC message dictionaries with a "y" value of "q",
	221	contain two additional keys; "q" and "a". Key "q" has a string value
	222	containing the method name of the query. Key "a" has a dictionary value
	223	containing named arguments to the query.
214	224
215	225	Responses
216		Responses, or KRPC message dictionaries with a "y" value of "r",
217		contain one additional key "r". The value of "r" is a dictionary
218		containing named return values. Response messages are sent upon
219		successful completion of a query.
	226	---------
	227
	228	Responses, or KRPC message dictionaries with a "y" value of "r",
	229	contain one additional key "r". The value of "r" is a dictionary
	230	containing named return values. Response messages are sent upon
	231	successful completion of a query.
220	232
221	233	Errors
222		Errors, or KRPC message dictionaries with a "y" value of "e",
223		contain one additional key "e". The value of "e" is a list. The first
224		element is an integer representing the error code. The second element
225		is a string containing the error message. Errors are sent when a query
226		cannot be fulfilled. The following table describes the possible error
227		codes:
	234	------
	235
	236	Errors, or KRPC message dictionaries with a "y" value of "e",
	237	contain one additional key "e". The value of "e" is a list. The first
	238	element is an integer representing the error code. The second element
	239	is a string containing the error message. Errors are sent when a query
	240	cannot be fulfilled. The following table describes the possible error
	241	codes:
228	242
229	243	+----------+------------------------------------------+
…	…
248	262
249	263
	264	-----------
250	265	DHT Queries
251	266	-----------
…	…
256	271
257	272	ping
258		The most basic query is a ping. "q" = "ping" A ping query has a
259		single argument, "id" the value is a 20-byte string containing the
260		senders node ID in network byte order. The appropriate response to a
261		ping has a single key "id" containing the node ID of the responding
262		node.
	273	----
	274
	275	The most basic query is a ping. "q" = "ping" A ping query has a
	276	single argument, "id" the value is a 20-byte string containing the
	277	senders node ID in network byte order. The appropriate response to a
	278	ping has a single key "id" containing the node ID of the responding
	279	node.
263	280
264	281	::
…	…
283	300
284	301	find_node
285		Find node is used to find the contact information for a node given
286		its ID. "q" == "find_node" A find_node query has two arguments, "id"
287		containing the node ID of the querying node, and "target" containing
288		the ID of the node sought by the queryer. When a node receives a
289		find_node query, it should respond with a key "nodes" and value of a
290		string containing the compact node info for the target node or the K
291		(8) closest good nodes in its own routing table.
	302	---------
	303
	304	Find node is used to find the contact information for a node given
	305	its ID. "q" == "find_node" A find_node query has two arguments, "id"
	306	containing the node ID of the querying node, and "target" containing
	307	the ID of the node sought by the queryer. When a node receives a
	308	find_node query, it should respond with a key "nodes" and value of a
	309	string containing the compact node info for the target node or the K
	310	(8) closest good nodes in its own routing table.
292	311
293	312	::
…	…
312	331
313	332	get_peers
314		Get peers associated with a torrent infohash. "q" = "get_peers" A
315		get_peers query has two arguments, "id" containing the node ID of the
316		querying node, and "info_hash" containing the infohash of the torrent.
317		If the queried node has peers for the infohash, they are returned in a
318		key "values" as a list of strings. Each string containing "compact" format
319		peer information for a single peer. If the queried node has no
320		peers for the infohash, a key "nodes" is returned containing the K
321		nodes in the queried nodes routing table closest to the infohash
322		supplied in the query. In either case a "token" key is also included in
323		the return value. The token value is a required argument for a future
324		announce_peer query. The token value should be a short binary string.
	333	---------
	334
	335	Get peers associated with a torrent infohash. "q" = "get_peers" A
	336	get_peers query has two arguments, "id" containing the node ID of the
	337	querying node, and "info_hash" containing the infohash of the torrent.
	338	If the queried node has peers for the infohash, they are returned in a
	339	key "values" as a list of strings. Each string containing "compact" format
	340	peer information for a single peer. If the queried node has no
	341	peers for the infohash, a key "nodes" is returned containing the K
	342	nodes in the queried nodes routing table closest to the infohash
	343	supplied in the query. In either case a "token" key is also included in
	344	the return value. The token value is a required argument for a future
	345	announce_peer query. The token value should be a short binary string.
325	346
326	347	::
…	…
353	374
354	375	announce_peer
355		Announce that the peer, controlling the querying node, is downloading
356		a torrent on a port. announce_peer has four arguments: "id" containing the node ID of the
357		querying node, "info_hash" containing the infohash of the torrent,
358		"port" containing the port as an integer, and the "token" received in
359		response to a previous get_peers query. The queried node must verify
360		that the token was previously sent to the same IP address as the
361		querying node. Then the queried node should store the IP address of the
362		querying node and the supplied port number under the infohash in its
363		store of peer contact information.
	376	-------------
	377
	378	Announce that the peer, controlling the querying node, is downloading
	379	a torrent on a port. announce_peer has four arguments: "id" containing the node ID of the
	380	querying node, "info_hash" containing the infohash of the torrent,
	381	"port" containing the port as an integer, and the "token" received in
	382	response to a previous get_peers query. The queried node must verify
	383	that the token was previously sent to the same IP address as the
	384	querying node. Then the queried node should store the IP address of the
	385	querying node and the supplied port number under the infohash in its
	386	store of peer contact information.
364	387
365	388	::
…	…
383	406	bencoded = d1:rd2:id20:mnopqrstuvwxyz123456e1:t2:aa1:y1:re
384	407
385
386		Send questions, comments and corrections to editor@bittorrent.org
387
388
389		.. [Kademlia] Peter Maymounkov, David Mazieres, "`Kademlia: A Peer-to-peer Information System Based on the XOR Metric`_", IPTPS 2002.
390
391		.. _`Kademlia: A Peer-to-peer Information System Based on the XOR Metric`: http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf
	408	References
	409	----------
	410
	411	.. [#Kademlia] Peter Maymounkov, David Mazieres, "Kademlia: A Peer-to-peer Information System Based on the XOR Metric", IPTPS 2002. http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf
392	412
393	413	.. [#entropy] Use SHA1 and plenty of entropy to ensure a unique ID.

dotorg/trunk/html/beps/bep_0005.rst

r10193	r10508
1		<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2		"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.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		<title>BitTorrent.org For Developers</title>
7		<link rel="stylesheet" type="text/css" href="./css/screen.css" media="screen" />
8		</head>
9		<body id="www-bittorrent-org">
10		<div id="upper" class="clear">
11		<div id="wrap">
12		<div id="header">
13		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
14		</div>
15		<div id="nav">
16		<ul>
17		<li><a href="./index.html">Home</a></li>
18		<li><a href="./introduction.html">For Users</a></li>
19		<li><span>For Developers</span></li>
20		<!-- <li><a href="./blog">Blog</a></li> -->
21		<li><a href="./donate.html">Donate!</a></li>
22		</ul>
23		</div>
24		<!-- ### Begin Content ### -->
25		<div id="second">
26		<h1>Fast Extension</h1>
27		<p>The Fast Extension packages several extensions: <i>Have None/Have All</i>,
28		<i>Reject Requests</i>, <i>Suggestions</i> and <i>Allowed Fast.</i>
	1	BEP: 5
	2	Title: Fast Extension
	3	Version: 3
	4	Last-Modified: 02-Feb-2008
	5	Author: David Harrison <dave@bittorrent.com>, Bram Cohen <bram@bittorrent.com>
	6	Status: Draft
	7	Type: Standards Track
	8	Created: 01-Feb-2008
	9	Post-History:
	10
	11	The Fast Extension packages several extensions: Have None/Have All,
	12	Reject Requests, Suggestions and Allowed Fast.
29	13	These are enabled by setting the third least significant bit of the
30	14	last reserved byte in the BitTorrent handshake:
31		</p>
32		<pre> reserved[7] \|= 0x04
33		</pre>
34		<p>The extension is enabled only if both ends of the connection set this bit.
35		</p><p>The following proposed messages adhere to the syntax of messages found
	15
	16	::
	17
	18	reserved[7] \|= 0x04
	19
	20	The extension is enabled only if both ends of the connection set this bit.
	21
	22	The following proposed messages adhere to the syntax of messages found
36	23	in v1.0 of the BitTorrent protocol. All integers are four bytes
37		big-endian. All messages start with an integer message length. All messages
38		but the Keep-Alive follow the message length with a single byte opcode
39		and zero or more opcode-dependant arguments.
40		</p><p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
	24	big-endian. All messages start with an integer message length. All
	25	messages but the Keep-Alive follow the message length with a single
	26	byte opcode and zero or more opcode-dependant arguments.
	27
	28	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
41	29	NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
42	30	"OPTIONAL" in this document are to be interpreted as described in
43		IETF <a href='http://www.ietf.org/rfc/rfc2119.txt' class='external' title="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.
44		</p>
45		<table id='toc' class='toc'><tr><td><div id='toctitle'><h2>Contents</h2></div>
46		<ul>
47		<li class='toclevel-1'><a href="#Modifications_to_Semantics_of_Existing_Messages"><span class="tocnumber">1</span> <span class="toctext">Modifications to Semantics of Existing Messages</span></a></li>
48		<li class='toclevel-1'><a href="#Have_All.2FHave_None"><span class="tocnumber">2</span> <span class="toctext">Have All/Have None</span></a></li>
49		<li class='toclevel-1'><a href="#Suggest_Piece"><span class="tocnumber">3</span> <span class="toctext">Suggest Piece</span></a></li>
50		<li class='toclevel-1'><a href="#Reject_Request"><span class="tocnumber">4</span> <span class="toctext">Reject Request</span></a></li>
51		<li class='toclevel-1'><a href="#Allowed_Fast_Set_Generation"><span class="tocnumber">5</span> <span class="toctext">Allowed Fast Set Generation</span></a></li>
52		</ul>
53		</td></tr></table>
54		<p><script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>
55		</p>
56		<h2 id="Modifications_to_Semantics_of_Existing_Messages"> Modifications to Semantics of Existing Messages </h2>
57		<p>The Fast Extension modifies the semantics of the
58		<i>Request</i>, <i>Choke</i>, <i>Unchoke</i>, and <i>Cancel</i>
59		messages, and adds a <i>Reject Request.</i> Now, every request
	31	IETF `RFC 2119`_.
	32
	33	Modifications to Semantics of Existing Messages
	34	-----------------------------------------------
	35
	36	The Fast Extension modifies the semantics of the
	37	Request, Choke, Unchoke, and Cancel
	38	messages, and adds a Reject Request. Now, every request
60	39	is guaranteed to result in EXACTLY ONE response
61	40	which is either the corresponding reject or corresponding piece
…	…
64	43	the corresponding piece: requests that are being processed are
65	44	allowed to complete.
66		</p><p>Choke no longer implicitly rejects all pending requests,
	45
	46	Choke no longer implicitly rejects all pending requests,
67	47	thus eliminating some race conditions which could cause pieces
68	48	to be needlessly requested multiple times.
69		</p><p>Additionally, if a peer receives a piece that was never requested,
	49
	50	Additionally, if a peer receives a piece that was never requested,
70	51	the peer MUST close the connection.
71		</p>
72		<h2 id="Have_All.2FHave_None"> Have All/Have None </h2>
73		<pre> <i>Have All</i>: <len=0x0001><op=0x0E>
74		</pre>
75		<pre> <i>Have None</i>: <len=0x0001><op=0x0F>
76		</pre>
77		<p><i>Have All</i> and <i>Have None</i> specify that the message sender
78		has all or none of the pieces respectively. When present, <i>Have All</i>
79		or <i>Have None</i> replace the <i>Have Bitfield.</i> Exactly one of <i>Have All</i>,
80		<i>Have None</i>, or <i>Have Bitfield</i> MUST appear and only immediately after
	52
	53
	54	Have All/Have None
	55	------------------
	56
	57	::
	58
	59	Have All: <len=0x0001> <op=0x0E>
	60
	61	::
	62
	63	Have None: <len=0x0001><op=0x0F>
	64
	65	Have All and Have None specify that the message sender
	66	has all or none of the pieces respectively. When present, Have All
	67	or Have None replace the Have Bitfield. Exactly one of Have All,
	68	Have None, or Have Bitfield MUST appear and only immediately after
81	69	the handshake. The reason for these messages is to save bandwidth. Also
82	70	slightly to remove the idiosyncrasy of sending no message when a peer
83	71	has no pieces.
84		</p><p>When the fast extension is disabled, if a peer receives <i>Have All</i> or
85		<i>Have None</i> then the peer MUST close the connection.
86		</p>
87		<h2 id="Suggest_Piece"> Suggest Piece </h2>
88		<pre> <i>Suggest Piece</i>: <len=0x0005><op=0x0D><index>
89		</pre>
90		<p><i>Suggest Piece</i> is an advisory message meaning "you might like to
	72
	73	When the fast extension is disabled, if a peer receives Have All or
	74	Have None then the peer MUST close the connection.
	75
	76
	77	Suggest Piece
	78	-------------
	79
	80	::
	81
	82	Suggest Piece: <len=0x0005><op=0x0D><index>
	83
	84	Suggest Piece is an advisory message meaning "you might like to
91	85	download this piece." The intended usage is for 'super-seeding'
92	86	without throughput reduction, to avoid redundant downloads, and so that
…	…
94	88	pieces to avoid excessive disk seeks. In all cases, the seed SHOULD
95	89	operate to maintain a roughly equal number of copies of each piece in
96		the network. A peer MAY send more than one ~~<i>suggest piece</i>~~ message at
97		any given time. A peer receiving multiple ~~<i>suggest piece</i>~~ messages
	90	the network. A peer MAY send more than one suggest piece message at
	91	any given time. A peer receiving multiple suggest piece messages
98	92	MAY interpret this as meaning that all of the suggested pieces
99	93	are equally appropriate.
100		</p><p>When the fast extension is disabled, if a peer receives a
101		<i>Suggest Piece</i> message, the peer MUST close the connection.
102		</p>
103
104		<h2 id="Reject_Request"> Reject Request </h2>
105		<pre> <i>Reject Request</i>: <len=0x000D><op=0x10><index><begin><offset>
106		</pre>
107		<p><i>Reject Request</i> notifies a requesting peer that its request will not be satisfied.
108		</p><p>If the fast extension is disabled and a peer receives a reject
	94
	95	When the fast extension is disabled, if a peer receives a
	96	Suggest Piece message, the peer MUST close the connection.
	97
	98
	99	Reject Request
	100	--------------
	101
	102	::
	103
	104	Reject Request: <len=0x000D><op=0x10><index><begin><offset>
	105
	106	Reject Request notifies a requesting peer that its request will not be satisfied.
	107
	108	If the fast extension is disabled and a peer receives a reject
109	109	request then the peer MUST close the connection.
110		</p><p>When the fast extension is enabled:
111		</p>
112		<ul><li> If a peer receives a reject for a request that was never sent then the peer SHOULD close the connection.
113		</li><li> If a peer sends a choke, it MUST reject all requests from the peer to whom the choke was sent except it SHOULD NOT reject requests for pieces that are in the <i>allowed fast set.</i> A peer SHOULD choke first and then reject requests so that the peer receiving the choke does not re-request the pieces.
114		</li><li> If a peer receives a request from a peer its choking, the peer receiving the request SHOULD send a reject unless the piece is in the <i>allowed fast set.</i>
115		</li>
116		<li>If a peer receives an excessive number of requests from a peer it is choking, the peer receiving the requests MAY close the connection rather than reject the request. However, consider that it can take several seconds for buffers to drain and messages to propagate once a peer is choked.</li></ul>
117
118		<h2 id="Allowed_Fast">Allowed Fast</h2>
119		<pre><i> Allowed Fast: <len=0x0005><op=0x11><index></i></pre>
120		<p>With the BitTorrent protocol specified in <a href="protocol.html">[1]</a>, new peers take several minutes to ramp up before they can effectively engage in BitTorrent's tit-for-tat. The reason is simple: starting peers have few pieces to trade.</p>
121		<p><i>Allowed Fast</i> is an advisory message which means "if you ask for this piece, I'll give it to you even if you're choked." <i>Allowed Fast</i> thus shortens the awkward stage during which the peer obtains occasional optimistic unchokes but cannot sufficiently reciprocate to remain unchoked.</p>
122		<p>The pieces that can be downloaded when choked constitute a peer's <i>allowed fast set.</i> The set is generated using a canonical algorithm that produces piece indices unique to the message receiver so that if two peers offer <i>k</i> pieces fast it will be the same <i>k</i>, and if one offers <i>k+1</i> it will be the same <i>k</i> plus one more. <i>k</i> should be small enough to avoid abuse, but large enough to ramp up tit-for-tat. We currently set <i>k</i> to 10, but peers are free to change this number, e.g., to suit load.</p>
123		<p>The message sender MAY list pieces that the message sender does not have. The receiver MUST NOT interpret an Allowed Fast message as meaning that the message sender has the piece. This allows peers to generate and communicate allowed fast sets at the beginning of a connection. However, a peer MAY send Allowed Fast messages at any time.</p>
124		<p>A peer SHOULD send Allowed Fast messages to any starting peer unless the local peer lacks sufficient resources. A peer MAY reject requests for already Allowed Fast pieces if the local peer lacks sufficient resources, if the requested piece has already been sent to the requesting peer, or if the requesting peer is not a starting peer. Our current implementation rejects requests for Allowed Fast messages whenever the requesting peer has more than <i> k </i> pieces.</p>
125		<p> When the fast extension is disabled, if a peer recieves an Allowed Fast message then the peer MUST close the connection.</p>
126
127		<h2 id="Allowed_Fast_Set_Generation"> Allowed Fast Set Generation </h2>
128		<p>The canonical algorithm for computing a peer <i>P'</i>s <i>allowed fast set</i>
129		follows. All integers in this pseudocode are four bytes represented in network (big-endian) byte order. <i>[a:b]</i> denotes the sequence of consecutive bytes from <i>a</i> to <i>b</i> excluding <i>b</i>, i.e., <i>(a, a+1, a+2,..., b-1)</i>. <i>x[a:b]</i> denotes a subsequence of elements in an array <i>x</i> starting from index <i>a</i> to but not including index <i>b</i>.
130		</p><p>Let <i>ip</i> denote <i>P'</i>s IPv4 address. We currently have no
	110
	111	When the fast extension is enabled:
	112
	113	- If a peer receives a reject for a request that was never sent then
	114	the peer SHOULD close the connection.
	115
	116	- If a peer sends a choke, it MUST reject all requests from the peer
	117	to whom the choke was sent except it SHOULD NOT reject requests for
	118	pieces that are in the allowed fast set. A peer SHOULD choke first
	119	and then reject requests so that the peer receiving the choke does not
	120	re-request the pieces.
	121
	122	- If a peer receives a request from a peer its choking, the peer
	123	receiving the request SHOULD send a reject unless the piece is in the
	124	allowed fast set.
	125
	126	- If a peer receives an excessive number of requests from a peer it is
	127	choking, the peer receiving the requests MAY close the connection
	128	rather than reject the request. However, consider that it can take
	129	several seconds for buffers to drain and messages to propagate once a
	130	peer is choked.
	131
	132	Allowed Fast
	133	------------
	134
	135	::
	136
	137	* Allowed Fast: <len=0x0005><op=0x11><index>*
	138
	139	With the BitTorrent protocol specified in `BEP 0002`_, new peers take
	140	several minutes to ramp up before they can effectively engage in
	141	BitTorrent's tit-for-tat. The reason is simple: starting peers have
	142	few pieces to trade.
	143
	144	Allowed Fast is an advisory message which means "if you ask for this
	145	piece, I'll give it to you even if you're choked." Allowed Fast thus
	146	shortens the awkward stage during which the peer obtains occasional
	147	optimistic unchokes but cannot sufficiently reciprocate to remain
	148	unchoked.
	149
	150	The pieces that can be downloaded when choked constitute a peer's
	151	allowed fast set. The set is generated using a canonical algorithm
	152	that produces piece indices unique to the message receiver so that if
	153	two peers offer k pieces fast it will be the same k, and if one
	154	offers k+1 it will be the same k plus one more. k should be
	155	small enough to avoid abuse, but large enough to ramp up
	156	tit-for-tat. We currently set k to 10, but peers are free to change
	157	this number, e.g., to suit load.
	158
	159	The message sender MAY list pieces that the message sender does not
	160	have. The receiver MUST NOT interpret an Allowed Fast message as
	161	meaning that the message sender has the piece. This allows peers to
	162	generate and communicate allowed fast sets at the beginning of a
	163	connection. However, a peer MAY send Allowed Fast messages at any
	164	time.
	165
	166	A peer SHOULD send Allowed Fast messages to any starting peer unless
	167	the local peer lacks sufficient resources. A peer MAY reject requests
	168	for already Allowed Fast pieces if the local peer lacks sufficient
	169	resources, if the requested piece has already been sent to the
	170	requesting peer, or if the requesting peer is not a starting peer. Our
	171	current implementation rejects requests for Allowed Fast messages
	172	whenever the requesting peer has more than * k * pieces.
	173
	174	When the fast extension is disabled, if a peer recieves an Allowed
	175	Fast message then the peer MUST close the connection.
	176
	177	Allowed Fast Set Generation
	178	---------------------------
	179
	180	The canonical algorithm for computing a peer P's allowed fast set
	181	follows. All integers in this pseudocode are four bytes represented
	182	in network (big-endian) byte order. [a:b] denotes the sequence of
	183	consecutive bytes from a to b excluding b, i.e., *(a, a+1,
	184	a+2,..., b-1). x[a:b]* denotes a subsequence of elements in an array
	185	x starting from index a to but not including index b.
	186
	187	Let ip denote P's IPv4 address. We currently have no
131	188	provisions for IPv6. If a peer is behind a Network Address Translator
132		(NAT) then ~~<i>ip</i>~~ should be the externally facing IP address of the
133		NAT. Since the node sending the ~~<i>Allowed Fast</i>~~ messages computes
134		the set, the correct ~~<i>ip</i> is usually the <i>ip</i>~~ address on the other
135		end of the connection. The host computing the set MAY use the ~~<i>ip</i>~~
	189	(NAT) then ip should be the externally facing IP address of the
	190	NAT. Since the node sending the Allowed Fast messages computes
	191	the set, the correct ip is usually the ip address on the other
	192	end of the connection. The host computing the set MAY use the ip
136	193	address on the other end of the connection regardless
137		</p><p>Let <i>sz</i> denote the number of pieces in the torrent.
138		</p><p>Let <i>a</i> denote the allowed fast set.
139		</p><p>Let <i>k</i> denote the final number of pieces in the allowed fast set.
140		</p>
141		<pre> x = 0xFFFFFF00 & ip (1)
	194
	195	Let sz denote the number of pieces in the torrent.
	196
	197	Let a denote the allowed fast set.
	198
	199	Let k denote the final number of pieces in the allowed fast set.
	200
	201
	202	::
	203
	204	x = 0xFFFFFF00 & ip (1)
142	205	x.append(infohash) (2)
143		while \|a\| ~~<~~ k:
	206	while \|a\| < k:
144	207	x = SHA1(x) (3)
145		for i in [0:5] and \|a\| ~~<~~ k: (4)
	208	for i in [0:5] and \|a\| < k: (4)
146	209	j = i*4 (5)
147	210	y = x[j:j+4] (6)
…	…
149	212	if index not in a: (8)
150	213	add index to a (9)
151		</pre>
152		~~<p>Step (1) selects the most significant octets in peer <i>P'</i>~~s
	214
	215	Step (1) selects the most significant octets in peer P's
153	216	ip address. We do this to prevent a user that obtains more than one
154	217	IP address on the same network from obtaining more than one
155		~~<i>allowed fast set.</i>~~ Use of three bytes is heuristic and
	218	allowed fast set. Use of three bytes is heuristic and
156	219	historical.
157		</p><p>Step (3) generates a 20-byte random number on each call. By
	220
	221	Step (3) generates a 20-byte random number on each call. By
158	222	performing a SHA-1 hash on the previous iteration's hash, we can
159	223	generate an arbitrarily long pseudorandom sequence.
160		</p><p>Steps (4) through (9) partition the 20-byte hash into piece indices
	224
	225	Steps (4) through (9) partition the 20-byte hash into piece indices
161	226	and add them to the allowed fast set.
162		</p>
163		</div><a name="Example_Implementation"></a><h2> Example Implementation </h2>
164		<p>The following C++ implementation was provided by CacheLogic:
165		</p>
166		<pre>void generate_fast_set(
167		uint32 k, // number of pieces in set
168		uint32 sz, // number of pieces in torrent
169		const char infohash[20], // infohash of torrent
170		uint32 ip, // in host byte order, ie localhost is 0x7f000001
171		std::vector<uint32> &a) // generated set of piece indices
172		{
173		a.clear();
174		std::string x;
175		char buf[4];
176		(uint32)buf = htonl(ip & 0xffffff00);
177		x.assign(buf, 4);
178		x.append(infohash, 20); // (3)
179		while (a.size()<k) {
180		x = SHA1(x); // (4)
181		for ( int i=0 ; i<5 && a.size()<k ; i++ ) { // (5)
182		int j = i*4; // (6)
183		uint32 y = ntohl((uint32)(x.data()+j)); // (7)
184		uint32 index = y % sz; // (8)
185		if (std::find(a.begin(), a.end(), index)==a.end()) { // (9)
186		a.push_back(index); // (10)
	227
	228	Example Implementation
	229	----------------------
	230
	231	The following C++ implementation was provided by CacheLogic:
	232
	233
	234	::
	235
	236	void generate_fast_set(
	237	uint32 k, // number of pieces in set
	238	uint32 sz, // number of pieces in torrent
	239	const char infohash[20], // infohash of torrent
	240	uint32 ip, // in host byte order, ie localhost is 0x7f000001
	241	std::
	242	vector<uint32> &a) // generated set of piece indices
	243	{
	244	a.clear();
	245	std::string x;
	246	char buf[4];
	247	(uint32)buf = htonl(ip & 0xffffff00);
	248	x.assign(buf, 4);
	249	x.append(infohash, 20); // (3)
	250	while (a.size()<k) {
	251	x = SHA1(x); // (4)
	252	for ( int i=0 ; i<5 && a.size()<k; i++ ) { // (5)
	253	int j = i*4; // (6)
	254	uint32 y = ntohl((uint32)(x.data()+j)); // (7)
	255	uint32 index = y % sz; // (8)
	256	if (std::find(a.begin(), a.end(), index)==a.end()) { // (9)
	257	a.push_back(index); // (10)
	258	}
187	259	}
188	260	}
189		}
190		}
191		</pre>
192		<p>Example results generated by this function:
193		</p>
194		<pre>7 piece allowed fast set for torrent with 1313 pieces and hex infohash
195		aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa for node with IP 80.4.4.200:
196		1059,431,808,1217,287,376,1188
197		9 piece allowed fast set for torrent with 1313 pieces and hex infohash
198		aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa for node with IP 80.4.4.200:
199		1059,431,808,1217,287,376,1188,353,508
200		</pre>
201		</div>
202
203		<div class="section">
204		<h2><a id="authors" name="authors">authors</a></h2>
205		<div class="line-block">
206		<div class="line"><a class="reference" href="mailto:dave%40bittorrent.com">David Harrison</a></div>
207		<div class="line"><a class="reference" href="mailto:bram%40bittorrent.com">Bram Cohen</a></div>
208		</div>
209		</div>
210		<!-- ### End Content ### -->
211		</div>
212		</div>
213		<div id="footer">
214		<hr />
215		<p>Copyright 2008 BitTorrent.org</p>
216		</div>
217		</body>
218		</html>
	261	}
	262
	263	Example results generated by this function:
	264
	265
	266	::
	267
	268	7 piece allowed fast set for torrent with 1313 pieces and hex infohash
	269	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa for node with IP 80.4.4.200:
	270	1059,431,808,1217,287,376,1188
	271	9 piece allowed fast set for torrent with 1313 pieces and hex infohash
	272	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa for node with IP 80.4.4.200:
	273	1059,431,808,1217,287,376,1188,353,508
	274
	275	.. _`RFC 2119`: http://www.ietf.org/rfc/rfc2119.txt
	276	.. _`BEP 0002`: http://www.bittorrent.org/beps/bep_0002.html

dotorg/trunk/html/beps/bep_0006.html

r10506	r10508
6	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7	7	<title></title>
8		<link rel="stylesheet" href="../css/~~screen~~.css" type="text/css" />
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9	9	</head>
10	10	<body>
…	…
14	14	<div id="wrap">
15	15	<div id="header">
16		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17	17	</div>
18	18	<div id="nav">
19	19	<ul>
20		<li><a href="./index.html">Home</a></li>
21		<li><a href="./introduction.html">For Users</a></li>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
22	22	<li><span>For Developers</span></li>
23	23	<!-- <li><a href="./blog">Blog</a></li> -->
24		<li><a href="./donate.html">Donate!</a></li>
	24	<li><a href="../donate.html">Donate!</a></li>
25	25	</ul>
26	26	</div> <!-- nav -->

dotorg/trunk/html/beps/bep_0007.html

r10506	r10508
6	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7	7	<title></title>
8		<link rel="stylesheet" href="../css/~~screen~~.css" type="text/css" />
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9	9	</head>
10	10	<body>
…	…
14	14	<div id="wrap">
15	15	<div id="header">
16		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17	17	</div>
18	18	<div id="nav">
19	19	<ul>
20		<li><a href="./index.html">Home</a></li>
21		<li><a href="./introduction.html">For Users</a></li>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
22	22	<li><span>For Developers</span></li>
23	23	<!-- <li><a href="./blog">Blog</a></li> -->
24		<li><a href="./donate.html">Donate!</a></li>
	24	<li><a href="../donate.html">Donate!</a></li>
25	25	</ul>
26	26	</div> <!-- nav -->
…	…
58	58	<p class="topic-title first">Contents</p>
59	59	<ul class="simple">
60		<li><a class="reference internal" href="#announce-parameter" id="id9">announce parameter</a></li>
61		<li><a class="reference internal" href="#announce-response" id="id10">announce response</a></li>
62		<li><a class="reference internal" href="#peer-list-obfuscation" id="id11">peer list obfuscation</a></li>
63		<li><a class="reference internal" href="#optimizations" id="id12">optimizations</a></li>
64		<li><a class="reference internal" href="#backwards-compatibility" id="id13">backwards compatibility</a></li>
65		<li><a class="reference internal" href="#rationale" id="id14">rationale</a></li>
66		<li><a class="reference internal" href="#id~~4" id="id15~~">References</a></li>
	60	<li><a class="reference internal" href="#announce-parameter" id="id7">announce parameter</a></li>
	61	<li><a class="reference internal" href="#announce-response" id="id8">announce response</a></li>
	62	<li><a class="reference internal" href="#peer-list-obfuscation" id="id9">peer list obfuscation</a></li>
	63	<li><a class="reference internal" href="#optimizations" id="id10">optimizations</a></li>
	64	<li><a class="reference internal" href="#backwards-compatibility" id="id11">backwards compatibility</a></li>
	65	<li><a class="reference internal" href="#rationale" id="id12">rationale</a></li>
	66	<li><a class="reference internal" href="#id2" id="id13">References</a></li>
67	67	</ul>
68	68	</div>
…	…
77	77	<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
78	78	"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are
79		to be interpreted as described in IETF <a class="reference external" href="http://tools.ietf.org/html/rfc2119">RFC 2119</a> <a class="footnote-reference" href="#id~~5" id="id6~~">[1]</a>.</p>
	79	to be interpreted as described in IETF <a class="reference external" href="http://tools.ietf.org/html/rfc2119">RFC 2119</a> <a class="footnote-reference" href="#id3" id="id4">[1]</a>.</p>
80	80	<div class="section" id="announce-parameter">
81	81	<h1>announce parameter</h1>
…	…
174	174	that the tracker encrypted the tracker peer list starting from the
175	175	first byte in the pseudorandom string then <em>i</em> also corresponds to the
176		<~~a href="#id1"><span class="problematic" id="id2"></span></a>ith~~ ip-port pair in the tracker peer list and the starting point of
	176	<em>ith</em> ip-port pair in the tracker peer list and the starting point of
177	177	the copy into the returned request.</p>
178		~~<div class="system-message" id="id1">~~
179		~~<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">bep_0007.rst</tt>, line 139); <em><a href="#id2">backlink</a></em></p>~~
180		~~Inline emphasis start-string without end-string.</div>~~
181	178	<p>So that the client and the tracker do not have to generate an
182	179	arbitrarily long pseudorandom string to support large swarms, we
…	…
266	263	connections.</p>
267	264	<p>This hardware was presumably deployed to get around <a class="reference external" href="http://www.bittorrent.org/beps/bep_0013.html">BitTorrent
268		Protocol Encryption</a> <a class="footnote-reference" href="#id~~7" id="id8~~">[2]</a>. Peers implementing BitTorrent Protocol
	265	Protocol Encryption</a> <a class="footnote-reference" href="#id5" id="id6">[2]</a>. Peers implementing BitTorrent Protocol
269	266	Encryption obfuscate peer-to-peer connections by employing RC4
270	267	encryption on every byte from the first byte transferred. BitTorrent
…	…
341	338	operation is lighter weight than performing a random shuffle.</p>
342	339	</div>
343		<div class="section" id="id4">
	340	<div class="section" id="id2">
344	341	<h1>References</h1>
	342	<table class="docutils footnote" frame="void" id="id3" rules="none">
	343	<colgroup><col class="label" /><col /></colgroup>
	344	<tbody valign="top">
	345	<tr><td class="label"><a class="fn-backref" href="#id4">[1]</a></td><td><a class="reference external" href="http://tools.ietf.org/html/rfc2119">http://tools.ietf.org/html/rfc2119</a></td></tr>
	346	</tbody>
	347	</table>
345	348	<table class="docutils footnote" frame="void" id="id5" rules="none">
346	349	<colgroup><col class="label" /><col /></colgroup>
347	350	<tbody valign="top">
348		<tr><td class="label"><a class="fn-backref" href="#id6">[1]</a></td><td><a class="reference external" href="http://tools.ietf.org/html/rfc2119">http://tools.ietf.org/html/rfc2119</a></td></tr>
349		</tbody>
350		</table>
351		<table class="docutils footnote" frame="void" id="id7" rules="none">
352		<colgroup><col class="label" /><col /></colgroup>
353		<tbody valign="top">
354		<tr><td class="label"><a class="fn-backref" href="#id8">[2]</a></td><td><a class="reference external" href="http://www.bittorrent.org/beps/bep_0013.html">http://www.bittorrent.org/beps/bep_0013.html</a></td></tr>
	351	<tr><td class="label"><a class="fn-backref" href="#id6">[2]</a></td><td><a class="reference external" href="http://www.bittorrent.org/beps/bep_0013.html">http://www.bittorrent.org/beps/bep_0013.html</a></td></tr>
355	352	</tbody>
356	353	</table>

dotorg/trunk/html/beps/bep_0007.rst

r10506	r10508
143	143	that the tracker encrypted the tracker peer list starting from the
144	144	first byte in the pseudorandom string then i also corresponds to the
145		ith ip-port pair in the tracker peer list and the starting point of
	145	ith ip-port pair in the tracker peer list and the starting point of
146	146	the copy into the returned request.
147	147

dotorg/trunk/html/beps/bep_0008.html

r10506	r10508
6	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7	7	<title></title>
8		<link rel="stylesheet" href="../css/~~screen~~.css" type="text/css" />
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9	9	</head>
10	10	<body>
…	…
14	14	<div id="wrap">
15	15	<div id="header">
16		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17	17	</div>
18	18	<div id="nav">
19	19	<ul>
20		<li><a href="./index.html">Home</a></li>
21		<li><a href="./introduction.html">For Users</a></li>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
22	22	<li><span>For Developers</span></li>
23	23	<!-- <li><a href="./blog">Blog</a></li> -->
24		<li><a href="./donate.html">Donate!</a></li>
	24	<li><a href="../donate.html">Donate!</a></li>
25	25	</ul>
26	26	</div> <!-- nav -->

dotorg/trunk/html/beps/bep_0009.html

r10506	r10508
6	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7	7	<title></title>
8		<link rel="stylesheet" href="../css/~~screen~~.css" type="text/css" />
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9	9	</head>
10	10	<body>
…	…
14	14	<div id="wrap">
15	15	<div id="header">
16		<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17	17	</div>
18	18	<div id="nav">
19	19	<ul>
20		<li><a href="./index.html">Home</a></li>
21		<li><a href="./introduction.html">For Users</a></li>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
22	22	<li><span>For Developers</span></li>
23	23	<!-- <li><a href="./blog">Blog</a></li> -->
24		<li><a href="./donate.html">Donate!</a></li>
	24	<li><a href="../donate.html">Donate!</a></li>
25	25	</ul>
26	26	</div> <!-- nav -->

dotorg/trunk/html/beps/bep_1000.rst

r10506	r10508
1	1	BEP: 1000
2		Title: ~~Request for~~ Standards Track Documents
3		Version: 1
	2	Title: Pending Standards Track Documents
	3	Version: 2
4	4	Last-Modified: 02-Feb-2008
5	5	Author: David Harrison <dave@bittorrent.com>
…	…
10	10
11	11	This documents lists BitTorrent extensions with known implementations
12		that have been assinged BEP numbers, and are awaiting submission of
	12	that have been assigned BEP numbers, and are awaiting submission of
13	13	the formal standards track document.
14	14
…	…
17	17	Num Title
18	18	===== =========================================
19		10_ Peer Exchange
20		11_ Announce List
21		12_ Protocol Encryption
22		13_ Local Service Discovery
23		14_ UDP Tracker Protocol
24		15_ Super-seeding
	19	10 Peer Exchange
	20	11 Announce List
	21	12 Protocol Encryption
	22	13 Local Service Discovery
	23	14 UDP Tracker Protocol
	24	15 Super-seeding
25	25	===== =========================================
26	26
27	27
28		~~.. _10: bep_0010.html~~
29		~~.. _11: bep_0011.html~~
30		~~.. _12: bep_0012.html~~
31		~~.. _13: bep_0013.html~~
32		~~.. _14: bep_0014.html~~
33		~~.. _15: bep_0015.html~~

dotorg/trunk/html/beps/makefile

r10506	r10508
5	5	bep_0003.html \
6	6	bep_0004.html \
	7	bep_0005.html \
7	8	bep_0006.html \
8	9	bep_0007.html \
9	10	bep_0008.html \
10	11	bep_0009.html \
	12	bep_1000.html \
11	13
12	14	all: $(BEPS)
13	15
14	16	%.html:%.rst
15		rstbep2html.py --template=~~../template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/screen~~.css --no-toc-backlinks $? >$@ --traceback
	17	rstbep2html.py --template=template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/bep.css --no-toc-backlinks $? >$@ --traceback
16	18
17	19	#~/docutils/tools/rst2html.py --template=../template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/screen.css --no-doc-title --no-toc-backlinks $? >$@

dotorg/trunk/html/introduction.html

r10154	r10508
18	18	<li><a href="./index.html">Home</a></li>
19	19	<li><span>For Users</span></li>
20		<li><a href="~~./developer~~.html">For Developers</a></li>
	20	<li><a href="beps/bep_0000.html">For Developers</a></li>
21	21	<!-- <li><a href="./blog.html">Blog</a></li> -->
22	22	<li><a href="./donate.html">Donate!</a></li>

BitTorrent.org

Context Navigation

Legend:

dotorg/trunk/html/beps/Makefile

dotorg/trunk/html/beps/bep_0000.html

dotorg/trunk/html/beps/bep_0000.rst

dotorg/trunk/html/beps/bep_0002.html

dotorg/trunk/html/beps/bep_0002.rst

dotorg/trunk/html/beps/bep_0003.html

dotorg/trunk/html/beps/bep_0004.html

dotorg/trunk/html/beps/bep_0004.rst

dotorg/trunk/html/beps/bep_0005.rst

dotorg/trunk/html/beps/bep_0006.html

dotorg/trunk/html/beps/bep_0007.html

dotorg/trunk/html/beps/bep_0007.rst

dotorg/trunk/html/beps/bep_0008.html

dotorg/trunk/html/beps/bep_0009.html

dotorg/trunk/html/beps/bep_1000.rst

dotorg/trunk/html/beps/makefile

dotorg/trunk/html/introduction.html

Download in other formats: