CW Cyrix's Git Repository Mirror
Browse code

Import from the old rivettracker git repository at sourceforge (amisaph/amisapphire branch)

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