distribustream 0.2.1 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGES +18 -0
- data/README +5 -41
- data/bin/dsclient +23 -10
- data/bin/dstream +70 -7
- data/distribustream.gemspec +6 -6
- data/lib/pdtp/client.rb +35 -19
- data/lib/pdtp/client/callbacks.rb +18 -7
- data/lib/pdtp/client/connection.rb +31 -25
- data/lib/pdtp/client/file_buffer.rb +14 -2
- data/lib/pdtp/client/file_service.rb +17 -11
- data/lib/pdtp/client/http_client.rb +18 -19
- data/lib/pdtp/client/http_handler.rb +21 -11
- data/lib/pdtp/client/transfer.rb +29 -29
- data/lib/pdtp/common.rb +19 -4
- data/lib/pdtp/common/file_service.rb +14 -2
- data/lib/pdtp/common/http_server.rb +217 -0
- data/lib/pdtp/common/length_prefix_protocol.rb +14 -2
- data/lib/pdtp/common/protocol.rb +23 -16
- data/lib/pdtp/server.rb +101 -26
- data/lib/pdtp/server/client_info.rb +14 -2
- data/lib/pdtp/server/connection.rb +31 -9
- data/lib/pdtp/server/dispatcher.rb +37 -87
- data/lib/pdtp/server/file_service.rb +17 -2
- data/lib/pdtp/server/file_service_protocol.rb +23 -38
- data/lib/pdtp/server/status_handler.rb +103 -0
- data/lib/pdtp/server/transfer.rb +21 -9
- data/lib/pdtp/server/trust.rb +14 -2
- data/pdtp-specification.xml +831 -0
- metadata +8 -8
- data/bin/dsseed +0 -32
- data/lib/pdtp/common/common_init.rb +0 -122
- data/lib/pdtp/server/stats_handler.rb +0 -23
@@ -1,11 +1,23 @@
|
|
1
1
|
#--
|
2
2
|
# Copyright (C) 2006-07 ClickCaster, Inc. (info@clickcaster.com)
|
3
|
-
#
|
3
|
+
#
|
4
|
+
# This program is free software: you can redistribute it and/or modify
|
5
|
+
# it under the terms of the GNU General Public License as published by
|
6
|
+
# the Free Software Foundation, either version 3 of the License, or
|
7
|
+
# (at your option) any later version.
|
8
|
+
#
|
9
|
+
# This program is distributed in the hope that it will be useful,
|
10
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
11
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
12
|
+
# GNU General Public License for more details.
|
13
|
+
#
|
14
|
+
# You should have received a copy of the GNU General Public License
|
15
|
+
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
4
16
|
#
|
5
17
|
# This source file is distributed as part of the
|
6
18
|
# DistribuStream file transfer system.
|
7
19
|
#
|
8
|
-
# See http://distribustream.
|
20
|
+
# See http://distribustream.org/
|
9
21
|
#++
|
10
22
|
|
11
23
|
require "uri"
|
@@ -55,6 +67,9 @@ module PDTP
|
|
55
67
|
@default_chunk_size = 512
|
56
68
|
end
|
57
69
|
|
70
|
+
# Retrieve information about a file. This should really be persistent
|
71
|
+
# FIXME the only authentication regarding registered files is performed
|
72
|
+
# by checking whether the registered file exists
|
58
73
|
def get_info(url)
|
59
74
|
begin
|
60
75
|
host = URI.split(url)[2]
|
@@ -1,18 +1,30 @@
|
|
1
|
-
#!/usr/bin/env ruby
|
2
1
|
#--
|
3
2
|
# Copyright (C) 2006-07 ClickCaster, Inc. (info@clickcaster.com)
|
4
|
-
#
|
3
|
+
#
|
4
|
+
# This program is free software: you can redistribute it and/or modify
|
5
|
+
# it under the terms of the GNU General Public License as published by
|
6
|
+
# the Free Software Foundation, either version 3 of the License, or
|
7
|
+
# (at your option) any later version.
|
8
|
+
#
|
9
|
+
# This program is distributed in the hope that it will be useful,
|
10
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
11
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
12
|
+
# GNU General Public License for more details.
|
13
|
+
#
|
14
|
+
# You should have received a copy of the GNU General Public License
|
15
|
+
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
5
16
|
#
|
6
17
|
# This source file is distributed as part of the
|
7
18
|
# DistribuStream file transfer system.
|
8
19
|
#
|
9
|
-
# See http://distribustream.
|
20
|
+
# See http://distribustream.org/
|
10
21
|
#++
|
11
22
|
|
12
23
|
require 'digest/md5'
|
13
|
-
require 'thread'
|
14
24
|
|
25
|
+
require File.dirname(__FILE__) + '/../common'
|
15
26
|
require File.dirname(__FILE__) + '/../common/protocol'
|
27
|
+
require File.dirname(__FILE__) + '/../common/http_server'
|
16
28
|
require File.dirname(__FILE__) + '/../server/file_service'
|
17
29
|
require File.dirname(__FILE__) + '/../client/connection'
|
18
30
|
require File.dirname(__FILE__) + '/../client/http_handler'
|
@@ -26,64 +38,35 @@ module PDTP
|
|
26
38
|
|
27
39
|
def initialize *args
|
28
40
|
@transfers = []
|
29
|
-
@lock = Mutex.new
|
30
41
|
@client = self
|
31
42
|
@connection = self
|
32
43
|
@client_id = Digest::MD5.hexdigest "#{Time.now.to_f}#{$$}"
|
33
44
|
|
45
|
+
@listen_addr = '0.0.0.0'
|
46
|
+
@listen_port = 60860
|
47
|
+
@vhost = @listen_addr
|
34
48
|
super
|
35
49
|
end
|
36
50
|
|
37
51
|
# Called after a connection to the server has been established
|
38
52
|
def connection_completed
|
39
53
|
begin
|
40
|
-
@
|
41
|
-
@listen_port = @@config[:listen_port]
|
42
|
-
|
43
|
-
#create the client
|
44
|
-
#client = PDTP::Client.new
|
45
|
-
#PDTP::Protocol.listener = client
|
46
|
-
#client.server_connection = self
|
47
|
-
#client.generate_client_id listen_port
|
48
|
-
|
49
|
-
# Start a mongrel server on the specified port. If it isnt available, keep trying higher ports
|
50
|
-
begin
|
51
|
-
mongrel_server = Mongrel::HttpServer.new @listen_addr, @listen_port
|
52
|
-
rescue Exception => e
|
53
|
-
@listen_port += 1
|
54
|
-
retry
|
55
|
-
end
|
56
|
-
|
57
|
-
#@@log.info "listening on port #{@listen_port}"
|
58
|
-
@http_handler = Client::HttpHandler.new(self)
|
59
|
-
|
60
|
-
@@log.info "listening on port #{@listen_port}"
|
61
|
-
mongrel_server.register "/", @http_handler
|
62
|
-
mongrel_server.run
|
54
|
+
@http_server.register "/", Client::HttpHandler.new(self)
|
63
55
|
|
64
56
|
# Register our client_id and listen_port
|
65
57
|
send_message :register, :listen_port => @listen_port, :client_id => @client_id
|
66
58
|
|
67
|
-
@@log.info 'This client is providing'
|
68
59
|
@file_service = PDTP::Server::FileService.new
|
69
60
|
@file_service.root = @base_path
|
70
|
-
#client.file_service = sfs #give this client access to all data
|
71
|
-
|
72
|
-
hostname = @@config[:vhost]
|
73
61
|
|
74
62
|
# Provide all the files in the root directory
|
75
63
|
files = find_files @base_path
|
76
|
-
files.each { |file| send_message :provide, :url => "http://#{
|
64
|
+
files.each { |file| send_message :provide, :url => "http://#{@vhost}/#{file}" }
|
77
65
|
rescue Exception => e
|
78
66
|
puts "Exception in connection_completed: #{e}"
|
79
67
|
puts e.backtrace.join("\n")
|
80
68
|
exit
|
81
69
|
end
|
82
|
-
end
|
83
|
-
|
84
|
-
def unbind
|
85
|
-
super
|
86
|
-
puts "Disconnected from PDTP server."
|
87
70
|
end
|
88
71
|
|
89
72
|
#########
|
@@ -91,6 +74,8 @@ module PDTP
|
|
91
74
|
#########
|
92
75
|
|
93
76
|
# Fine all suitable files in the give path
|
77
|
+
# FIXME This should really be moved to a lazy approach where we look
|
78
|
+
# for files as they're requested by clients
|
94
79
|
def find_files(base_path)
|
95
80
|
require 'find'
|
96
81
|
|
@@ -0,0 +1,103 @@
|
|
1
|
+
#--
|
2
|
+
# Copyright (C) 2006-07 ClickCaster, Inc. (info@clickcaster.com)
|
3
|
+
#
|
4
|
+
# This program is free software: you can redistribute it and/or modify
|
5
|
+
# it under the terms of the GNU General Public License as published by
|
6
|
+
# the Free Software Foundation, either version 3 of the License, or
|
7
|
+
# (at your option) any later version.
|
8
|
+
#
|
9
|
+
# This program is distributed in the hope that it will be useful,
|
10
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
11
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
12
|
+
# GNU General Public License for more details.
|
13
|
+
#
|
14
|
+
# You should have received a copy of the GNU General Public License
|
15
|
+
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
16
|
+
#
|
17
|
+
# This source file is distributed as part of the
|
18
|
+
# DistribuStream file transfer system.
|
19
|
+
#
|
20
|
+
# See http://distribustream.org/
|
21
|
+
#++
|
22
|
+
|
23
|
+
require 'rubygems'
|
24
|
+
require 'mongrel'
|
25
|
+
require 'erb'
|
26
|
+
|
27
|
+
require File.dirname(__FILE__) + '/../common/http_server'
|
28
|
+
|
29
|
+
module PDTP
|
30
|
+
class Server
|
31
|
+
#set up the mongrel server for serving the stats page
|
32
|
+
class StatusHandler < Mongrel::HttpHandler
|
33
|
+
def initialize(dispatcher)
|
34
|
+
@dispatcher = dispatcher
|
35
|
+
end
|
36
|
+
|
37
|
+
# process an incoming request to the admin page
|
38
|
+
def process(request, response)
|
39
|
+
response.start(200) do |head, out|
|
40
|
+
out.write begin
|
41
|
+
generate_html_stats
|
42
|
+
rescue Exception => e
|
43
|
+
"Exception: #{e}\n#{e.backtrace.join("\n")}"
|
44
|
+
end
|
45
|
+
end
|
46
|
+
end
|
47
|
+
|
48
|
+
#builds an html page with information about the server's internal workings
|
49
|
+
def generate_html_stats
|
50
|
+
s = ERB.new <<EOF
|
51
|
+
<html><head><title>DistribuStream Status</title></head>
|
52
|
+
<body>
|
53
|
+
<h1>DistribuStream Status</h1>
|
54
|
+
Time=<%= Time.now %><br> Connected Clients=<%= @dispatcher.connections.size %>
|
55
|
+
<center><table border="1">
|
56
|
+
<tr><th>Client</th><th>Transfers</th><th>Files</th></tr>
|
57
|
+
<% @dispatcher.connections.each do |c| %>
|
58
|
+
<tr><td>
|
59
|
+
<% if c.file_service? %>
|
60
|
+
<b>File Service</b>
|
61
|
+
<% else %>
|
62
|
+
<%= @dispatcher.connection_name(c) %>
|
63
|
+
<% end %>
|
64
|
+
<% host, port = c.get_peer_info %>
|
65
|
+
<br><%= host %>:<%= port %>
|
66
|
+
</td>
|
67
|
+
<td>
|
68
|
+
<%
|
69
|
+
@dispatcher.client_info(c).transfers.each do |key,t|
|
70
|
+
if c==t.giver
|
71
|
+
type="UP: "
|
72
|
+
peer=t.taker
|
73
|
+
else
|
74
|
+
type="DOWN: "
|
75
|
+
peer=t.giver
|
76
|
+
end
|
77
|
+
%>
|
78
|
+
<%= type %> id=<%= t.transfer_id %><br>
|
79
|
+
<%
|
80
|
+
end
|
81
|
+
%>
|
82
|
+
</td>
|
83
|
+
<td>
|
84
|
+
<%
|
85
|
+
@dispatcher.client_info(c).chunk_info.get_file_stats.each do |fs|
|
86
|
+
%>
|
87
|
+
<%= fs.url %> size=<%= fs.file_chunks %> req=<%= fs.chunks_requested %>
|
88
|
+
prov=<%= fs.chunks_provided %> transf=<%= fs.chunks_transferring %><br>
|
89
|
+
<%
|
90
|
+
end
|
91
|
+
%>
|
92
|
+
</td></tr>
|
93
|
+
<%
|
94
|
+
end
|
95
|
+
%>
|
96
|
+
</table>
|
97
|
+
</body></html>
|
98
|
+
EOF
|
99
|
+
s.result binding
|
100
|
+
end
|
101
|
+
end
|
102
|
+
end
|
103
|
+
end
|
data/lib/pdtp/server/transfer.rb
CHANGED
@@ -1,11 +1,23 @@
|
|
1
1
|
#--
|
2
2
|
# Copyright (C) 2006-07 ClickCaster, Inc. (info@clickcaster.com)
|
3
|
-
#
|
3
|
+
#
|
4
|
+
# This program is free software: you can redistribute it and/or modify
|
5
|
+
# it under the terms of the GNU General Public License as published by
|
6
|
+
# the Free Software Foundation, either version 3 of the License, or
|
7
|
+
# (at your option) any later version.
|
8
|
+
#
|
9
|
+
# This program is distributed in the hope that it will be useful,
|
10
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
11
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
12
|
+
# GNU General Public License for more details.
|
13
|
+
#
|
14
|
+
# You should have received a copy of the GNU General Public License
|
15
|
+
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
4
16
|
#
|
5
17
|
# This source file is distributed as part of the
|
6
18
|
# DistribuStream file transfer system.
|
7
19
|
#
|
8
|
-
# See http://distribustream.
|
20
|
+
# See http://distribustream.org/
|
9
21
|
#++
|
10
22
|
|
11
23
|
module PDTP
|
@@ -18,6 +30,13 @@ module PDTP
|
|
18
30
|
attr_accessor :creation_time
|
19
31
|
attr_accessor :verification_asked
|
20
32
|
|
33
|
+
#generates a transfer id based on 2 client ids, a url, and a byte range
|
34
|
+
def self.gen_transfer_id(id1,id2,url,byte_range)
|
35
|
+
a = id1<id2 ? id1 : id2
|
36
|
+
b = id1<id2 ? id2 : id1
|
37
|
+
"#{a}$#{b}$#{url}$#{byte_range}"
|
38
|
+
end
|
39
|
+
|
21
40
|
def initialize(taker,giver,url,chunkid,byte_range,connector_receives=true)
|
22
41
|
@taker,@giver,@url,@chunkid,@byte_range=taker,giver,url,chunkid,byte_range
|
23
42
|
|
@@ -41,13 +60,6 @@ module PDTP
|
|
41
60
|
@transfer_id=Transfer::gen_transfer_id(id1,id2,@url,@byte_range)
|
42
61
|
end
|
43
62
|
|
44
|
-
#generates a transfer id based on 2 client ids, a url, and a byte range
|
45
|
-
def self.gen_transfer_id(id1,id2,url,byte_range)
|
46
|
-
a = id1<id2 ? id1 : id2
|
47
|
-
b = id1<id2 ? id2 : id1
|
48
|
-
"#{a}$#{b}$#{url}$#{byte_range}"
|
49
|
-
end
|
50
|
-
|
51
63
|
def to_s
|
52
64
|
"taker=#{@taker}, giver=#{@giver}, connector=#{@connector}, acceptor=#{@acceptor}, url=#{@url}, chunk_id=#{@chunkid} range=#{@byte_range}"
|
53
65
|
end
|
data/lib/pdtp/server/trust.rb
CHANGED
@@ -1,11 +1,23 @@
|
|
1
1
|
#--
|
2
2
|
# Copyright (C) 2006-07 ClickCaster, Inc. (info@clickcaster.com)
|
3
|
-
#
|
3
|
+
#
|
4
|
+
# This program is free software: you can redistribute it and/or modify
|
5
|
+
# it under the terms of the GNU General Public License as published by
|
6
|
+
# the Free Software Foundation, either version 3 of the License, or
|
7
|
+
# (at your option) any later version.
|
8
|
+
#
|
9
|
+
# This program is distributed in the hope that it will be useful,
|
10
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
11
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
12
|
+
# GNU General Public License for more details.
|
13
|
+
#
|
14
|
+
# You should have received a copy of the GNU General Public License
|
15
|
+
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
4
16
|
#
|
5
17
|
# This source file is distributed as part of the
|
6
18
|
# DistribuStream file transfer system.
|
7
19
|
#
|
8
|
-
# See http://distribustream.
|
20
|
+
# See http://distribustream.org/
|
9
21
|
#++
|
10
22
|
|
11
23
|
module PDTP
|
@@ -0,0 +1,831 @@
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
2
|
+
<!DOCTYPE rfc SYSTEM "http://xml.resource.org/authoring/rfc2629.dtd">
|
3
|
+
<?rfc toc='yes' ?>
|
4
|
+
<rfc docName="draft-distribustream-pdtp-rfcs-01" ipr="full3978">
|
5
|
+
<front>
|
6
|
+
<title abbrev="PDTP Specification">Peer Distributed Transfer Protocol Specification</title>
|
7
|
+
|
8
|
+
<author fullname="Tony Arcieri" initials="T.A." surname="Arcieri">
|
9
|
+
<organization>ClickCaster, Inc.</organization>
|
10
|
+
|
11
|
+
<address>
|
12
|
+
<email>tony@clickcaster.com</email>
|
13
|
+
</address>
|
14
|
+
</author>
|
15
|
+
|
16
|
+
<author fullname="Ashvin Mysore" initials="A.M." surname="Mysore">
|
17
|
+
<organization>ClickCaster, Inc.</organization>
|
18
|
+
|
19
|
+
<address>
|
20
|
+
<email>ashvin@clickcaster.com</email>
|
21
|
+
</address>
|
22
|
+
</author>
|
23
|
+
|
24
|
+
<author fullname="Galen Pahlke" initials="G.P." surname="Pahlke">
|
25
|
+
<organization>ClickCaster, Inc.</organization>
|
26
|
+
|
27
|
+
<address>
|
28
|
+
<email>galen@clickcaster.com</email>
|
29
|
+
</address>
|
30
|
+
</author>
|
31
|
+
|
32
|
+
<author fullname="James Sanders" initials="J.S." surname="Sanders">
|
33
|
+
<organization>University of Colorado</organization>
|
34
|
+
|
35
|
+
<address>
|
36
|
+
<email>sanderjd@gmail.com</email>
|
37
|
+
</address>
|
38
|
+
</author>
|
39
|
+
|
40
|
+
<author fullname="Tom Stapleton" initials="T.S." surname="Stapleton">
|
41
|
+
<organization>University of Colorado</organization>
|
42
|
+
|
43
|
+
<address>
|
44
|
+
<email>tstapleton@gmail.com</email>
|
45
|
+
</address>
|
46
|
+
</author>
|
47
|
+
|
48
|
+
<date month="November" year="2007" />
|
49
|
+
|
50
|
+
<area>Internet</area>
|
51
|
+
|
52
|
+
<keyword>I-D</keyword>
|
53
|
+
|
54
|
+
<keyword>Internet-Draft</keyword>
|
55
|
+
|
56
|
+
<keyword>PDTP</keyword>
|
57
|
+
|
58
|
+
<keyword>DistribuStream</keyword>
|
59
|
+
|
60
|
+
<abstract>
|
61
|
+
<t>Peer Distributed Transfer Protocol is a high performance peer-to-peer
|
62
|
+
file distribution system that provides streaming downloads of files
|
63
|
+
originating from a central server. The files are then shared over a peer
|
64
|
+
network, allowing the aggregate bandwidth of the network to scale with
|
65
|
+
the number of clients.</t>
|
66
|
+
</abstract>
|
67
|
+
</front>
|
68
|
+
|
69
|
+
<middle>
|
70
|
+
<section title="Introduction">
|
71
|
+
<t>This document describes version 2 of PDTP, an enhancement of <xref
|
72
|
+
target="refs.PDTP">PDTP version 1</xref>. PDTP currently only allows for
|
73
|
+
operation on IPv4 networks, though support for IPv6 networks is
|
74
|
+
planned.</t>
|
75
|
+
|
76
|
+
<t>PDTP is based on an extensible set of asynchronous messages. These
|
77
|
+
messages are comprised of a type, and a sequence of key-value pairs. The
|
78
|
+
possible data types are described in Appendix A. Due to the structure of
|
79
|
+
PDTP, protocol messages can be grouped into two distinct categories:
|
80
|
+
<list style="symbols">
|
81
|
+
<t><xref target="server-to-client-messages">Server to client
|
82
|
+
messages</xref> manage the file transfer process and provide
|
83
|
+
infomation of files requested by the client.</t>
|
84
|
+
|
85
|
+
<t><xref target="client-to-server-messages">Client to server
|
86
|
+
messages</xref> handle requests for files by the client, inform the
|
87
|
+
server of files the client can provide, and report the status of
|
88
|
+
transfers.</t>
|
89
|
+
|
90
|
+
<t><xref target="client-to-client-communication">Client to client
|
91
|
+
communication</xref> makes use of the standard <xref
|
92
|
+
target="refs.HTTP">HTTP 1.1</xref> protocol</t>
|
93
|
+
</list></t>
|
94
|
+
</section>
|
95
|
+
|
96
|
+
<section title="Message Format">
|
97
|
+
<t>All <xref target="client-to-server-messages">client to server</xref>
|
98
|
+
and <xref target="server-to-client-messages">server to client</xref>
|
99
|
+
communication utilizes a lightweight form of asynchronous messaging over
|
100
|
+
TCP with <xref target="refs.JSON">JavaScript Object Notation (JSON)</xref>
|
101
|
+
providing underlying data serialization format. Messages are
|
102
|
+
length-prefix framed with a JSON message body. The IANA approved TCP
|
103
|
+
port for all PDTP client/server intercommunication is 6086.</t>
|
104
|
+
|
105
|
+
<t>Each frame consists of a 16-bit unsigned integer in network byte order
|
106
|
+
representing the length of the message body, followed by the message
|
107
|
+
body itself. Because the length prefix is 16-bit, the maximum allowed
|
108
|
+
length of the message body is 65,535 bytes, with a maximum frame size
|
109
|
+
of 65,537 bytes including the header. Messages are sent in succession
|
110
|
+
over a persistent TCP connection.</t>
|
111
|
+
|
112
|
+
<t>Message bodies consist of JSON messages in the following format:</t>
|
113
|
+
|
114
|
+
<figure>
|
115
|
+
<artwork>["type", {"arg1": "value1", "arg2": "value2", ..., "argN": "valueN"}]</artwork>
|
116
|
+
</figure>
|
117
|
+
|
118
|
+
<t>Each message is composed of an outer JSON array with two members.
|
119
|
+
The first member is a string which represents the message type. The second
|
120
|
+
member is a JSON object which contains a message-specific collection of
|
121
|
+
arguments. Unless otherwise specified, all members are represented as JSON strings.
|
122
|
+
</t>
|
123
|
+
|
124
|
+
<t>To improve the readability of the protocol on the wire, it is recommended that
|
125
|
+
CRLF be appended to the end of the JSON message. This is ignored as whitespace by
|
126
|
+
JSON parsers, but meaningful to humans who may be reading wire dumps. However, this
|
127
|
+
is not an explicit requirement of the protocol, nor should its presence be required
|
128
|
+
by any implementation.</t>
|
129
|
+
</section>
|
130
|
+
|
131
|
+
<section anchor="server-to-client-messages"
|
132
|
+
title="Server to Client Messages">
|
133
|
+
<section title="Overview">
|
134
|
+
<t>These messages are sent from the server to the client to respond to
|
135
|
+
information requests by the client and manage the file transfer
|
136
|
+
process. <list style="symbols">
|
137
|
+
<t><xref target="tellinfo">TELLINFO</xref> provides the client
|
138
|
+
with information about the object located at the specified
|
139
|
+
URL.</t>
|
140
|
+
|
141
|
+
<t><xref target="transfer">TRANSFER</xref> tells the client to
|
142
|
+
initiate a peer-to-peer data transfer.</t>
|
143
|
+
|
144
|
+
<t><xref target="tellverify">TELLVERIFY</xref> tells the client
|
145
|
+
whether the specified transfer is authorized.</t>
|
146
|
+
|
147
|
+
<t><xref target="hashverify">HASHVERIFY</xref> informs the client
|
148
|
+
whether the successful transfer had the correct file hash.</t>
|
149
|
+
</list></t>
|
150
|
+
</section>
|
151
|
+
|
152
|
+
<section anchor="tellinfo" title="TELLINFO">
|
153
|
+
<figure>
|
154
|
+
<artwork>tell_info url [size] [chunkSize] [streaming]</artwork>
|
155
|
+
</figure>
|
156
|
+
|
157
|
+
<t>The tell_info datagram is the expected response from the ask_info
|
158
|
+
datagram, and contains information that the client can use to
|
159
|
+
determine its chunk request policy and the manner in which a file is
|
160
|
+
handled. Since the server only arranges for chunks to be sent when
|
161
|
+
they are explicitly requested, a client must know how many chunks are
|
162
|
+
in a file so that it knows how many to request. In order to determine
|
163
|
+
the number of chunks in a file, the size of each chunk and the total
|
164
|
+
size of the file are sent. The number of chunks is then the 'fileSize'
|
165
|
+
divided by the 'chunkSize', rounded up to the first integer. The
|
166
|
+
'chunkSize' could also be used to determine a policy on caching or
|
167
|
+
memory management and the 'fileSize' could be used to alleviate
|
168
|
+
complications arising from the case of incomplete final chunks, and
|
169
|
+
perhaps other things.</t>
|
170
|
+
|
171
|
+
<t>Fields:</t>
|
172
|
+
|
173
|
+
<figure>
|
174
|
+
<artwork>url: String</artwork>
|
175
|
+
|
176
|
+
<postamble>A unique file identifier. The server uses this field to
|
177
|
+
specify which file it is sending information about.</postamble>
|
178
|
+
</figure>
|
179
|
+
|
180
|
+
<figure>
|
181
|
+
<artwork>size: Integer (Optional)</artwork>
|
182
|
+
|
183
|
+
<postamble>The exact size in bytes of the file. Since the last chunk
|
184
|
+
in the file might not be completely filled, it is necessary to know
|
185
|
+
the total file size as well as the chunk size and the chunk
|
186
|
+
count.</postamble>
|
187
|
+
</figure>
|
188
|
+
|
189
|
+
<figure>
|
190
|
+
<artwork>chunkSize: Integer (Optional)</artwork>
|
191
|
+
|
192
|
+
<postamble>The size in bytes of each chunk in the file.</postamble>
|
193
|
+
</figure>
|
194
|
+
|
195
|
+
<figure>
|
196
|
+
<artwork>streaming: Boolean (Optional)</artwork>
|
197
|
+
|
198
|
+
<postamble>If true, the file is assumed to be a streaming media file
|
199
|
+
and chunks near the beginning will be sent first. If false, chunks
|
200
|
+
from all over the file will have equal priority. Default is
|
201
|
+
false.</postamble>
|
202
|
+
</figure>
|
203
|
+
</section>
|
204
|
+
|
205
|
+
<section anchor="transfer" title="TRANSFER">
|
206
|
+
<figure>
|
207
|
+
<artwork>transfer peer port method url range peer_id</artwork>
|
208
|
+
</figure>
|
209
|
+
|
210
|
+
<t>The server controls all data flowing over the network. It uses the
|
211
|
+
transfer message to initiate a chunk transfer between two peers. The
|
212
|
+
transfer message is always sent to the peer that should initiate the
|
213
|
+
connection to the other peer.</t>
|
214
|
+
|
215
|
+
<t>When a client receives a transfer message, it should connect to the
|
216
|
+
specified peer and carry out the transfer as specified in <xref
|
217
|
+
target="client-to-client-communication">Section 4</xref> and reply to
|
218
|
+
the server with a <xref target="completed">completed</xref> message
|
219
|
+
upon success.</t>
|
220
|
+
|
221
|
+
<t>Fields:</t>
|
222
|
+
|
223
|
+
<figure>
|
224
|
+
<artwork>peer: String</artwork>
|
225
|
+
|
226
|
+
<postamble>This is the network address of the peer with which the
|
227
|
+
transfer should take place.</postamble>
|
228
|
+
</figure>
|
229
|
+
|
230
|
+
<figure>
|
231
|
+
<artwork>port: Integer</artwork>
|
232
|
+
|
233
|
+
<postamble>The port on the peer to connect to.</postamble>
|
234
|
+
</figure>
|
235
|
+
|
236
|
+
<figure>
|
237
|
+
<artwork>method: Enumeration</artwork>
|
238
|
+
|
239
|
+
<postamble>The HTTP method to be used for this transfer. Possible
|
240
|
+
values are GET and PUT, with the same semantics as in the HTTP
|
241
|
+
protocol. That is, if method is GET, this client is receiving data
|
242
|
+
from a peer, and if method is PUT, this client is sending data to a
|
243
|
+
peer.</postamble>
|
244
|
+
</figure>
|
245
|
+
|
246
|
+
<figure>
|
247
|
+
<artwork>url: String</artwork>
|
248
|
+
|
249
|
+
<postamble>This is a unique file identifier for the file to
|
250
|
+
transfer.</postamble>
|
251
|
+
</figure>
|
252
|
+
|
253
|
+
<figure>
|
254
|
+
<artwork>range: Range</artwork>
|
255
|
+
|
256
|
+
<postamble>This is the byte range being transferred. This, combined
|
257
|
+
with the url, provides a unique identifier for the data to
|
258
|
+
transfer.</postamble>
|
259
|
+
</figure>
|
260
|
+
|
261
|
+
<figure>
|
262
|
+
<artwork>peer_id: Integer</artwork>
|
263
|
+
|
264
|
+
<postamble>The unique id of the peer in this transfer.</postamble>
|
265
|
+
</figure>
|
266
|
+
</section>
|
267
|
+
|
268
|
+
<section anchor="tellverify" title="TELLVERIFY">
|
269
|
+
<figure>
|
270
|
+
<artwork>tell_verify peer url range peer_id authorized</artwork>
|
271
|
+
</figure>
|
272
|
+
|
273
|
+
<t>The tell_verify datagram is sent to the client in response to an
|
274
|
+
<xref target="askverify">ask_verify</xref> message to inform it of the
|
275
|
+
authorization status of a transfer.</t>
|
276
|
+
|
277
|
+
<t>Fields:</t>
|
278
|
+
|
279
|
+
<figure>
|
280
|
+
<artwork>peer: IP Address</artwork>
|
281
|
+
|
282
|
+
<postamble>The address of the connecting peer.</postamble>
|
283
|
+
</figure>
|
284
|
+
|
285
|
+
<figure>
|
286
|
+
<artwork>url: String</artwork>
|
287
|
+
|
288
|
+
<postamble>A unique file identifier.</postamble>
|
289
|
+
</figure>
|
290
|
+
|
291
|
+
<figure>
|
292
|
+
<artwork>range: Range</artwork>
|
293
|
+
|
294
|
+
<postamble>The byte range to verify.</postamble>
|
295
|
+
</figure>
|
296
|
+
|
297
|
+
<figure>
|
298
|
+
<artwork>peer_id: String</artwork>
|
299
|
+
|
300
|
+
<postamble>The unique identifier of the peer.</postamble>
|
301
|
+
</figure>
|
302
|
+
|
303
|
+
<figure>
|
304
|
+
<artwork>authorized: Boolean</artwork>
|
305
|
+
|
306
|
+
<postamble>A boolean value specifying whether or not the transfer is
|
307
|
+
authorized.</postamble>
|
308
|
+
</figure>
|
309
|
+
</section>
|
310
|
+
|
311
|
+
<section anchor="hashverify" title="HASHVERIFY">
|
312
|
+
<figure>
|
313
|
+
<artwork>hash_verify url range hash_ok</artwork>
|
314
|
+
</figure>
|
315
|
+
|
316
|
+
<t>The hash_verify message is sent to a client after a completed
|
317
|
+
message with a hash has been received. The value of hash_ok denotes
|
318
|
+
whether or not the hash sent in the completed message matches the
|
319
|
+
expected hash of the chunk containing the specified range.</t>
|
320
|
+
|
321
|
+
<t>Fields:</t>
|
322
|
+
|
323
|
+
<figure>
|
324
|
+
<artwork>url: String</artwork>
|
325
|
+
|
326
|
+
<postamble>The url of the file being transferred.</postamble>
|
327
|
+
</figure>
|
328
|
+
|
329
|
+
<figure>
|
330
|
+
<artwork>range: Range</artwork>
|
331
|
+
|
332
|
+
<postamble>The byte range of the file, which this message refers
|
333
|
+
to.</postamble>
|
334
|
+
</figure>
|
335
|
+
|
336
|
+
<figure>
|
337
|
+
<artwork>hash_ok: Boolean</artwork>
|
338
|
+
|
339
|
+
<postamble>If true, the has sent in the completed message matched
|
340
|
+
the expected hash of the byte range it referred to.</postamble>
|
341
|
+
</figure>
|
342
|
+
</section>
|
343
|
+
|
344
|
+
<section anchor="protocolerror" title="PROTOCOLERROR">
|
345
|
+
<figure>
|
346
|
+
<artwork>protocol_error message</artwork>
|
347
|
+
</figure>
|
348
|
+
|
349
|
+
<t>The protocol_error message is sent to a client whenever a protocol
|
350
|
+
error has occurred. The message field is meant to be read by a human
|
351
|
+
to determine what went wrong. In most cases, the error is due to a
|
352
|
+
programming error and is fatal. One notable exception to this is the
|
353
|
+
case when a client generates a Peer Id that is not unique.</t>
|
354
|
+
|
355
|
+
<t>Fields:</t>
|
356
|
+
|
357
|
+
<figure>
|
358
|
+
<artwork>message: String</artwork>
|
359
|
+
|
360
|
+
<postamble>An error message. This error message is not meant to be
|
361
|
+
parsed programmatically, but rather to be logged and read as an aid
|
362
|
+
to debugging.</postamble>
|
363
|
+
</figure>
|
364
|
+
</section>
|
365
|
+
</section>
|
366
|
+
|
367
|
+
<section anchor="client-to-server-messages"
|
368
|
+
title="Client to Server Messages">
|
369
|
+
<section title="Overview">
|
370
|
+
<t>These messages are sent from the client to the server to request
|
371
|
+
files, inform the server of completed transfers and handle files the
|
372
|
+
client can provide to the network. <list style="symbols">
|
373
|
+
<t><xref target="register">REGISTER</xref> informs the server
|
374
|
+
that the client exists and provides the server with information
|
375
|
+
about itself.</t>
|
376
|
+
|
377
|
+
<t><xref target="request">REQUEST</xref> informs the server that
|
378
|
+
the client wants the specified object range.</t>
|
379
|
+
|
380
|
+
<t><xref target="request">UNREQUEST</xref> informs the server that
|
381
|
+
the client no longer needs the specified object range.</t>
|
382
|
+
|
383
|
+
<t><xref target="provide">PROVIDE</xref> informs the server that
|
384
|
+
the client has the specified object range and can provide it to
|
385
|
+
peers.</t>
|
386
|
+
|
387
|
+
<t><xref target="provide">UNPROVIDE</xref> informs the server that
|
388
|
+
the client no longer has the specified object range, and therefore
|
389
|
+
cannot provide it.</t>
|
390
|
+
|
391
|
+
<t><xref target="askinfo">ASKINFO</xref> requests information from
|
392
|
+
the server about the specified URL.</t>
|
393
|
+
|
394
|
+
<t><xref target="askverify">ASKVERIFY</xref> asks the server
|
395
|
+
whether the specified transfer is authorized.</t>
|
396
|
+
|
397
|
+
<t><xref target="completed">COMPLETED</xref> informs the server
|
398
|
+
that a transfer has successfully completed.</t>
|
399
|
+
</list></t>
|
400
|
+
</section>
|
401
|
+
|
402
|
+
<section anchor="register" title="REGISTER">
|
403
|
+
<figure>
|
404
|
+
<artwork>register client_id listen_port</artwork>
|
405
|
+
</figure>
|
406
|
+
|
407
|
+
<t>The register message is the first message a client sends to the
|
408
|
+
server. The client must send this message to alert the server of its
|
409
|
+
presence so that it may be included in the server's actions.</t>
|
410
|
+
|
411
|
+
<t>Fields:</t>
|
412
|
+
|
413
|
+
<figure>
|
414
|
+
<artwork>client_id: String</artwork>
|
415
|
+
|
416
|
+
<postamble>A unique identifier, which the client generates. The
|
417
|
+
server will identify this client on the network based on this
|
418
|
+
identifier. The identifier must be a string less than 4 KB in
|
419
|
+
length. It is the client's responsibility to generate an identifier
|
420
|
+
that is unique. The server should respond with a <xref
|
421
|
+
target="protocolerror">protocol_error</xref> message if the
|
422
|
+
identifier is too long or not unique.</postamble>
|
423
|
+
</figure>
|
424
|
+
|
425
|
+
<figure>
|
426
|
+
<artwork>listen_port: Integer</artwork>
|
427
|
+
|
428
|
+
<postamble>The port on which the client will listen for incoming
|
429
|
+
connections from other peers. The server will pass this information
|
430
|
+
along to other clients wishing to connect to this client for peer to
|
431
|
+
peer chunk transfers.</postamble>
|
432
|
+
</figure>
|
433
|
+
</section>
|
434
|
+
|
435
|
+
<section anchor="request" title="REQUEST and UNREQUEST">
|
436
|
+
<figure>
|
437
|
+
<artwork>request url [range] unrequest url [range]</artwork>
|
438
|
+
</figure>
|
439
|
+
|
440
|
+
<t>The request and unrequest messages are used by the client to
|
441
|
+
indicate what data it needs to receive. A request datagram indicates
|
442
|
+
that the client needs the specified object bytes; an unrequest
|
443
|
+
datagram indicates that the client no longer needs the specified
|
444
|
+
bytes. The completed and provide messages may also be used to cancel a
|
445
|
+
request, though they carry additional semantics.</t>
|
446
|
+
|
447
|
+
<t>If the range of a request or unrequest message isn't specified, it
|
448
|
+
is assumed to include all bytes in the file.</t>
|
449
|
+
|
450
|
+
<t>The server is expected to continuously arrange for the data in the
|
451
|
+
client's request set to be delivered to the client through peer to
|
452
|
+
peer transfer channels. A request set is informally the set of chunks
|
453
|
+
that a client wants. Formally, we may say that a given unique chunk C
|
454
|
+
with the URL L and the id K is in a client's request set if and only
|
455
|
+
if: <list style="symbols">
|
456
|
+
<t>The client has sent at least one request message with a URL
|
457
|
+
equivalent to L and a byte range containing chunk K.</t>
|
458
|
+
|
459
|
+
<t>Since the last such message was sent, the client has not sent
|
460
|
+
an unrequest message with a URL equivalent to L and a byte range
|
461
|
+
containing chunk K,</t>
|
462
|
+
|
463
|
+
<t>...nor has it sent a completed message with a URL equivalent to
|
464
|
+
L and a byte range containing chunk K,</t>
|
465
|
+
|
466
|
+
<t>...nor has it sent a provide message with a URL equivalent to L
|
467
|
+
and a byte range containing chunk K.</t>
|
468
|
+
</list></t>
|
469
|
+
|
470
|
+
<t>In short, requests are standing and additive; unrequests are
|
471
|
+
transient and subtractive. The server is expected to handle any
|
472
|
+
possible combination of requests and unrequests that clients can send.
|
473
|
+
(For example, a client may request a URL in its entirety, and then
|
474
|
+
later unrequest certain parts of the URL. This is useful if, say, a
|
475
|
+
client needs to complete a partial download, repair a damaged file, or
|
476
|
+
optimize its network usage in response to user actions.)</t>
|
477
|
+
|
478
|
+
<t>Fields:</t>
|
479
|
+
|
480
|
+
<figure>
|
481
|
+
<artwork>url: String</artwork>
|
482
|
+
|
483
|
+
<postamble>The object being requested. The server may discard
|
484
|
+
requests for URLs it does not understand.</postamble>
|
485
|
+
</figure>
|
486
|
+
|
487
|
+
<figure>
|
488
|
+
<artwork>range: Range (Optional)</artwork>
|
489
|
+
|
490
|
+
<postamble>The range of bytes being requested, inclusive. If
|
491
|
+
unspecified, it is taken to be the complete range of bytes in the
|
492
|
+
file.</postamble>
|
493
|
+
</figure>
|
494
|
+
</section>
|
495
|
+
|
496
|
+
<section anchor="provide" title="PROVIDE and UNPROVIDE">
|
497
|
+
<figure>
|
498
|
+
<artwork>provide url [range] unprovide url [range]</artwork>
|
499
|
+
</figure>
|
500
|
+
|
501
|
+
<t>The provide and unprovide datagrams are used to tell the server
|
502
|
+
which chunks of a file it is able to provide to peers. Each client in
|
503
|
+
the system can have a cache of file chunks that it has already
|
504
|
+
downloaded and depending on the client's individual capabilities, this
|
505
|
+
cache may or may not be empty on startup. If a client has data in a
|
506
|
+
cache on startup, the provide message can be used to inform the
|
507
|
+
server. If the cache is empty on startup, the provide message is never
|
508
|
+
needed because the server is expected to keep track of each chunk that
|
509
|
+
has been transferred. On the other hand, if a client evicts one or
|
510
|
+
more chunks from its cache, it should immediately send an unprovide
|
511
|
+
message. Although there is no firm requirement on a client to send
|
512
|
+
appropriate unprovide datagrams, it is in the client's best interest
|
513
|
+
to do so, as it could lose standing in the network if it were asked to
|
514
|
+
send a chunk it did not have.</t>
|
515
|
+
|
516
|
+
<t>A client can send as many provide messages as necessary to inform
|
517
|
+
the server of its entire chunk cache. These messages should be
|
518
|
+
interpreted by the server additively. That is, if a client first sends
|
519
|
+
a message specifying that it provides byte range A to B and then
|
520
|
+
another specifying that it provides byte range C to D, the server
|
521
|
+
should conclude that it has byte range A to B and byte range C to D.
|
522
|
+
Furthermore, a client can send provide and unprovide messages for
|
523
|
+
multiple files, as specified by the url field.</t>
|
524
|
+
|
525
|
+
<t>If the range in a provide or unprovide message isn't specified, it
|
526
|
+
is taken to include the entire range of bytes in the file specified by
|
527
|
+
the url field.</t>
|
528
|
+
|
529
|
+
<t>Fields:</t>
|
530
|
+
|
531
|
+
<figure>
|
532
|
+
<artwork>url: String</artwork>
|
533
|
+
|
534
|
+
<postamble>A unique file identifier. The client uses this field to
|
535
|
+
specify a file in its cache.</postamble>
|
536
|
+
</figure>
|
537
|
+
|
538
|
+
<figure>
|
539
|
+
<artwork>range: Range (Optional)</artwork>
|
540
|
+
|
541
|
+
<postamble>The range of relevant bytes, inclusive. If unspecified,
|
542
|
+
it is taken to be the complete range of chunks in the
|
543
|
+
file.</postamble>
|
544
|
+
</figure>
|
545
|
+
</section>
|
546
|
+
|
547
|
+
<section anchor="askinfo" title="ASKINFO">
|
548
|
+
<figure>
|
549
|
+
<artwork>ask_info url</artwork>
|
550
|
+
</figure>
|
551
|
+
|
552
|
+
<t>The ask_info datagram is sent to the server when a client wants
|
553
|
+
information about a file. Specifically, the client needs information
|
554
|
+
about the file type, the file size, the number of chunks, and the size
|
555
|
+
of each chunk in order to successfully receive a file. This
|
556
|
+
information is used to determine when a file is finished transferring
|
557
|
+
and how to handle a file, among other things.</t>
|
558
|
+
|
559
|
+
<t>It is expected that the server will always respond to an ask_info
|
560
|
+
datagram with a <xref target="tellinfo">tell_info</xref> datagram.</t>
|
561
|
+
|
562
|
+
<t>Fields:</t>
|
563
|
+
|
564
|
+
<figure>
|
565
|
+
<artwork>url: String</artwork>
|
566
|
+
|
567
|
+
<postamble>A unique file identifier. The client uses this field to
|
568
|
+
specify which file it would like information about.</postamble>
|
569
|
+
</figure>
|
570
|
+
</section>
|
571
|
+
|
572
|
+
<section anchor="askverify" title="ASKVERIFY">
|
573
|
+
<figure>
|
574
|
+
<artwork>ask_verify peer url range peer_id</artwork>
|
575
|
+
</figure>
|
576
|
+
|
577
|
+
<t>The ask_verify datagram is sent to the server when a client wants
|
578
|
+
to know whether a transfer is authorized. This is sent upon receipt of
|
579
|
+
a put or get from a peer.</t>
|
580
|
+
|
581
|
+
<t>It is expected that the server will always respond to an ask_verify
|
582
|
+
datagram with a <xref target="tellverify">tell_verify</xref>
|
583
|
+
datagram.</t>
|
584
|
+
|
585
|
+
<t>Fields:</t>
|
586
|
+
|
587
|
+
<figure>
|
588
|
+
<artwork>peer: String</artwork>
|
589
|
+
|
590
|
+
<postamble>The network address of the connecting peer.</postamble>
|
591
|
+
</figure>
|
592
|
+
|
593
|
+
<figure>
|
594
|
+
<artwork>url: String</artwork>
|
595
|
+
|
596
|
+
<postamble>A unique file identifier. The client uses this field to
|
597
|
+
specify which file it would like information about.</postamble>
|
598
|
+
</figure>
|
599
|
+
|
600
|
+
<figure>
|
601
|
+
<artwork>range: Range</artwork>
|
602
|
+
|
603
|
+
<postamble>The range of bytes in the file referred to by the url for
|
604
|
+
which we are asking verification.</postamble>
|
605
|
+
</figure>
|
606
|
+
|
607
|
+
<figure>
|
608
|
+
<artwork>peer_id: String</artwork>
|
609
|
+
|
610
|
+
<postamble>The unique identifier of the peer.</postamble>
|
611
|
+
</figure>
|
612
|
+
</section>
|
613
|
+
|
614
|
+
<section anchor="completed" title="COMPLETED">
|
615
|
+
<figure>
|
616
|
+
<artwork>completed peer url range peer_id [hash]</artwork>
|
617
|
+
</figure>
|
618
|
+
|
619
|
+
<t>The completed message is used by the client to indicate that a
|
620
|
+
transfer has completed in either success or failure. Upon success, a
|
621
|
+
completed message will include a hash of the chunk that it has
|
622
|
+
received. The lack of a hash field denotes transfer failure. The
|
623
|
+
server may use this information to inform its network optimization, so
|
624
|
+
the appropriate use of completed messages is highly recommended.
|
625
|
+
(Specifically, it is likely that the server will initiate another
|
626
|
+
transfer after it has been informed that one has completed.)</t>
|
627
|
+
|
628
|
+
<t>Fields:</t>
|
629
|
+
|
630
|
+
<figure>
|
631
|
+
<artwork>peer: String</artwork>
|
632
|
+
|
633
|
+
<postamble>The network address of the peer associated with this
|
634
|
+
transfer.</postamble>
|
635
|
+
</figure>
|
636
|
+
|
637
|
+
<figure>
|
638
|
+
<artwork>url: String</artwork>
|
639
|
+
|
640
|
+
<postamble>The url of the transferred chunk.</postamble>
|
641
|
+
</figure>
|
642
|
+
|
643
|
+
<figure>
|
644
|
+
<artwork>range: Range</artwork>
|
645
|
+
|
646
|
+
<postamble>The byte range of the completed transfer.</postamble>
|
647
|
+
</figure>
|
648
|
+
|
649
|
+
<figure>
|
650
|
+
<artwork>peer_id: String</artwork>
|
651
|
+
|
652
|
+
<postamble>A unique identifier of the peer associated with the
|
653
|
+
transfer.</postamble>
|
654
|
+
</figure>
|
655
|
+
|
656
|
+
<figure>
|
657
|
+
<artwork>hash: String (Optional)</artwork>
|
658
|
+
|
659
|
+
<postamble>A hash of the transferred chunk. Denotes failure if
|
660
|
+
blank.</postamble>
|
661
|
+
</figure>
|
662
|
+
</section>
|
663
|
+
</section>
|
664
|
+
|
665
|
+
<section anchor="client-to-client-communication"
|
666
|
+
title="Client to Client Communication">
|
667
|
+
<section title="Overview">
|
668
|
+
<t>All client to client communication is done using the <xref
|
669
|
+
target="refs.HTTP">HTTP 1.1</xref> protocol. Each client is both an
|
670
|
+
HTTP client and server. During a transfer, the connecting peer for
|
671
|
+
that particular transfer acts as the client and the listening peer
|
672
|
+
acts as the server. While full HTTP functionality may be implemented
|
673
|
+
and implementation-specifically desirable, only the subset of the HTTP
|
674
|
+
protocol that includes the GET and PUT requests and the full range of
|
675
|
+
responses is strictly required for the PDTP protocol.</t>
|
676
|
+
|
677
|
+
<t>The listening client is truly an HTTP server and the connecting
|
678
|
+
client is truly an HTTP client. By this we mean simply that not only
|
679
|
+
the syntax but also the semantics of the GET and PUT requests and any
|
680
|
+
responses received are identical to that of the HTTP protocol.</t>
|
681
|
+
|
682
|
+
<t>A connecting peer will include the following information in the
|
683
|
+
request sent to a listening peer:</t>
|
684
|
+
|
685
|
+
<t><list style="symbols">
|
686
|
+
<t>A compliant <xref target="refs.HTTP">HTTP</xref> Request-Line
|
687
|
+
for either a GET or PUT request. The method to use should be taken
|
688
|
+
from the method parameter of the <xref
|
689
|
+
target="transfer">transfer</xref> message received from the
|
690
|
+
server. Similarly, the Request-URI portion of the Request-Line is
|
691
|
+
taken from the url field from the server.</t>
|
692
|
+
|
693
|
+
<t>A Host header, identifying the host in the url specified by the
|
694
|
+
server. This host should be recognized as a virtual host on the
|
695
|
+
listening peer. It is important to note that this field does not
|
696
|
+
necessarily represent any identifier associated with the listening
|
697
|
+
peer, but rather the host in the url field from the server.</t>
|
698
|
+
|
699
|
+
<t>A Range header, identifying the byte range to be transferred,
|
700
|
+
taken from the range field in the transfer message.</t>
|
701
|
+
|
702
|
+
<t>An X-PDTP-Peer-Id header. The value of this header is the Peer
|
703
|
+
Id of the connecting client. That is, it is the Peer Id of the
|
704
|
+
client sending this request. It is important to note that this is
|
705
|
+
not the peer_id field from the transfer message, which represents
|
706
|
+
the Peer Id of the listening peer and is necessary when notifying
|
707
|
+
the server of transfer completion.</t>
|
708
|
+
|
709
|
+
<t>If the method is PUT, a body containing the data is also
|
710
|
+
sent</t>
|
711
|
+
</list></t>
|
712
|
+
|
713
|
+
<t>Upon receiving a request from a connecting peer, a listening peer
|
714
|
+
processes the request in an appropriate manner and sends an
|
715
|
+
appropriate response. The listening client may choose to ask the
|
716
|
+
server for verification of this transfer using the <xref
|
717
|
+
target="askverify">ask_verify</xref> message. If verification fails, a
|
718
|
+
403 Forbidden response should be sent. Similarly, if the file cannot
|
719
|
+
be found, or the range is unsatisfiable, the 404 File Not Found or 416
|
720
|
+
Requested Range Unsatisfiable responses should be sent. Upon success,
|
721
|
+
either 206 Partial Content, 200 OK, or 201 Created should be sent,
|
722
|
+
depending on the situation.</t>
|
723
|
+
</section>
|
724
|
+
</section>
|
725
|
+
</middle>
|
726
|
+
|
727
|
+
<back>
|
728
|
+
<references>
|
729
|
+
<reference anchor="refs.PDTP"
|
730
|
+
target="http://pdtp.org/specification/draft-arcieri-peer-distributed-transfer-protocol.html">
|
731
|
+
<front>
|
732
|
+
<title>Peer Distributed Transfer Protocol</title>
|
733
|
+
|
734
|
+
<author fullname="Anthony Arcieri" initials="A.A." surname="Arcieri">
|
735
|
+
<organization>ClickCaster.com</organization>
|
736
|
+
</author>
|
737
|
+
|
738
|
+
<date day="30" month="November" year="2005" />
|
739
|
+
</front>
|
740
|
+
</reference>
|
741
|
+
|
742
|
+
<reference anchor="refs.HTTP">
|
743
|
+
<front>
|
744
|
+
<title>Hypertext Transfer Protocol - HTTP/1.1</title>
|
745
|
+
|
746
|
+
<author fullname="" initials="R.F." surname="Fielding">
|
747
|
+
<organization>UC Irvine</organization>
|
748
|
+
</author>
|
749
|
+
|
750
|
+
<author fullname="" initials="J.G." surname="Gettys">
|
751
|
+
<organization>Compaq/W3C</organization>
|
752
|
+
</author>
|
753
|
+
|
754
|
+
<author fullname="" initials="J.M." surname="Mogul">
|
755
|
+
<organization>Compaq</organization>
|
756
|
+
</author>
|
757
|
+
|
758
|
+
<author fullname="" initials="H.F." surname="Frystyk">
|
759
|
+
<organization>W3C/MIT</organization>
|
760
|
+
</author>
|
761
|
+
|
762
|
+
<author fullname="" initials="L.M." surname="Masinter">
|
763
|
+
<organization>Xerox</organization>
|
764
|
+
</author>
|
765
|
+
|
766
|
+
<author fullname="" initials="P.L." surname="Fielding">
|
767
|
+
<organization>Microsoft</organization>
|
768
|
+
</author>
|
769
|
+
|
770
|
+
<author fullname="" initials="T.B." surname="Berners-Lee">
|
771
|
+
<organization>W3C/MIT</organization>
|
772
|
+
</author>
|
773
|
+
|
774
|
+
<date month="June" year="1999" />
|
775
|
+
</front>
|
776
|
+
|
777
|
+
<seriesInfo name="RFC" value="2616" />
|
778
|
+
</reference>
|
779
|
+
|
780
|
+
<reference anchor="refs.JSON">
|
781
|
+
<front>
|
782
|
+
<title>The application/json Media Type for JavaScript Object
|
783
|
+
Notation (JSON)</title>
|
784
|
+
|
785
|
+
<author initials="D.C." surname="Crockford">
|
786
|
+
<organization>JSON.org</organization>
|
787
|
+
</author>
|
788
|
+
|
789
|
+
<date month="July" year="2006" />
|
790
|
+
</front>
|
791
|
+
|
792
|
+
<seriesInfo name="RFC" value="4627" />
|
793
|
+
</reference>
|
794
|
+
</references>
|
795
|
+
|
796
|
+
<section title="Glossary">
|
797
|
+
<t><list style="symbols">
|
798
|
+
<t>Client: a system that accesses a service on a remote computer via
|
799
|
+
a network, equivalent to a 'peer'.</t>
|
800
|
+
|
801
|
+
<t>Connecting peer: The peer that initiates the connection over
|
802
|
+
which a transfer takes place.</t>
|
803
|
+
|
804
|
+
<t>Enumeration: a set of acceptable values.</t>
|
805
|
+
|
806
|
+
<t>Integer: a unsigned integer field.</t>
|
807
|
+
|
808
|
+
<t>Listening peer: The peer that accepts the connection over which a
|
809
|
+
transfer takes place.</t>
|
810
|
+
|
811
|
+
<t>Peer: a system that accesses a service on a remote computer via a
|
812
|
+
network, equivalent to a 'client'.</t>
|
813
|
+
|
814
|
+
<t>Peer Id: a unique identifier generated by a client and sent to
|
815
|
+
the server, uniquely identifying the client on the network.</t>
|
816
|
+
|
817
|
+
<t>Range: a representation of a sequence of indices implemented as a
|
818
|
+
tuple containing Integer values for minimum and maximum values. All
|
819
|
+
ranges referred to in this document are inclusive.</t>
|
820
|
+
|
821
|
+
<t>Request Set: the set of all chunks that a client has requested
|
822
|
+
and not subsequently unrequested.</t>
|
823
|
+
|
824
|
+
<t>Server: the system that manages the network and distribution of
|
825
|
+
information among clients.</t>
|
826
|
+
|
827
|
+
<t>String: a string of ASCII characters.</t>
|
828
|
+
</list></t>
|
829
|
+
</section>
|
830
|
+
</back>
|
831
|
+
</rfc>
|