From a85a200c795a07a22385f03a28762224879ef09d Mon Sep 17 00:00:00 2001 From: Yoann Ciabaud Date: Fri, 5 Aug 2016 12:44:58 +0200 Subject: [PATCH 1/4] First revision of the webtorrent BEP! --- bep_webrtc.rst | 239 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) diff --git a/bep_webrtc.rst b/bep_webrtc.rst index e69de29b..c0c4afaa 100644 --- a/bep_webrtc.rst +++ b/bep_webrtc.rst @@ -0,0 +1,239 @@ +:BEP: XXX +:Title: Websocket tracker protocol for WebRTC transport +:Version: $Revision$ +:Last-Modified: $Date$ +:Author: Yoann Ciabaud +:Status: Draft +:Type: Standards Track +:Content-Type: text/x-rst +:Created: 02-Aug-2016 +:Post-History: + + +Abstract +======== +Webapps are more and more used to publish and consume content over the +internet, Bittorrent could be used to optimize the server and network resources +needed to distribute files but the need for a client software prevents its +usage in a browser environment. + +This BEP documents how to add support for WebRTC signalling on a tracker in +order to make the webapps able to connect peers using the WebRTC API [1]. +Once a communication channel is open between the peers using WebRTC, the +standard Bittorent peer connection protocol is used. + +Due to the WebRTC signalling process, the tracker needs to push messages to the +clients with a full-duplex communication channel available in a web browser. +At the moment of this BEP, Websockets [2] are the only compatible standard +technology. + +WebRTC signalling process +========================= +The diagram below explains the messages involved in the WebRTC signalling +process. + +:: + + peer 1 tracker peer 2 + + | | | + | | | + | announce start | | + | numwant=x | | + | x SDP offers | | + | >-------------------> | | + | | | + | | SDP offer | + | | >-------------------> | + | | | + | | SDP answer | + | | <-------------------< | + | | | + | SDP answer | | + | <-------------------< | | + | | | connection established + .|.. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..|.. . + | | + V V + +Websocket tracker protocol +========================== + +credits +------- +The websocket tracker protocol has been designed for the Webtorrent [3] project +by Feross Aboukhadijeh and hundreds of open source contributors. + +overview +-------- +The websocket tracker uses JSON payloads reflecting the HTTP request parameters +and an additionnal action property used to switch between announce and other +actions (ex. scrape). If the announce URL of the torrent contains the ws or wss +protocol, the client establishes a websocket connection with the tracker. + +WebRTC offers and answers can be provided as an extension of the announce +message, the tracker will be responsible to forward them between the peers to +act as a signalling service. + +After the connection is open, the client can begin announcing itself by using +the JSON messages below. + +signalling related message format +--------------------------------- +announce request:: + + { + "action": "announce", + "info_hash": "", + "peer_id": "" + "numwant": 0, + "uploaded": 0, + "downloaded": 0, + "left": 0, + "event": "", + "offers": [ + { + "offer_id": "", + "offer": "" + }, + ... + ] + } + +A client can provide SDP offers that the tracker will forward to peers to +establish a connection. +"offers" is a JSON array containing a list of WebRTC SDP offers and a generated +"offer_id" used to match peers and offers. + + +announce response:: + + { + "action": "announce", + "complete": 0, + "incomplete": 0, + "interval": 0, + "info_hash": "" + } + + +offer or answer message:: + + { + "action": "announce", + "info_hash": "", + "offer_id": "", + "peer_id": "", + "sdp": "" + } + +The tracker forwards the offer or the answer to clients in an announce message +with an "sdp" property. + + +answer message:: + + { + "action": "announce", + "info_hash": "", + "offer_id": "", + "peer_id": "", + "to_peer_id": "", + "answer": "" + } + +A client can answer to an offer by sending the data in an announce message with +an "answer" property? + + +other message format +-------------------- + +scrape request:: + + { + "action": "scrape", + "info_hash": "" + } + + +scrape response:: + + { + "announce": "", + "info_hash": "", + "complete": 0, + "incomplete": 0, + "downloaded": 0 + } + + +multi-scrape request:: + + { + "action": "scrape", + "info_hash": ["ih1", "ih2", ...] + } + + +multi-scrape response:: + + { + "ih1": { + "announce": "", + "info_hash": "ih1", + "complete": 0, + "incomplete": 0, + "downloaded": 0 + }, + "ih2": + { + "announce": "", + "info_hash": "ih2", + "complete": 0, + "incomplete": 0, + "downloaded": 0 + } + } + + +If the tracker encounters an error, it might send an error message. + +error response:: + + { + "error": "" + } + + +Existing implementations +======================== + +bittorrent-tracker [4] support this protocol, it is used in all WebTorrent [2] +clients. + + +Extensions +========== + +JSON format is extensible, therefore a client or a tracker can add data to the +message structure. This way, additional fields can be added without breaking +compatibility. + +References and Footnotes +======================== + +.. [1] https://www.w3.org/TR/webrtc/ +.. [2] https://tools.ietf.org/html/rfc6455 +.. [3] https://webtorrent.io +.. [4] https://github.com/feross/bittorrent-tracker + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: From ab730e7afc7dd82984547f2e142c8ffafc7cb6b9 Mon Sep 17 00:00:00 2001 From: Yoann Ciabaud Date: Fri, 5 Aug 2016 18:44:00 +0200 Subject: [PATCH 2/4] Typos and to_peer_id property --- bep_webrtc.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/bep_webrtc.rst b/bep_webrtc.rst index c0c4afaa..2b2600d7 100644 --- a/bep_webrtc.rst +++ b/bep_webrtc.rst @@ -17,19 +17,19 @@ internet, Bittorrent could be used to optimize the server and network resources needed to distribute files but the need for a client software prevents its usage in a browser environment. -This BEP documents how to add support for WebRTC signalling on a tracker in +This BEP explains how to add support for WebRTC signaling on a tracker in order to make the webapps able to connect peers using the WebRTC API [1]. Once a communication channel is open between the peers using WebRTC, the standard Bittorent peer connection protocol is used. -Due to the WebRTC signalling process, the tracker needs to push messages to the +Due to the WebRTC signaling process, the tracker needs to push messages to the clients with a full-duplex communication channel available in a web browser. -At the moment of this BEP, Websockets [2] are the only compatible standard -technology. +At the moment this BEP is written, Websockets [2] are the only compatible +standard technology. -WebRTC signalling process +WebRTC signaling process ========================= -The diagram below explains the messages involved in the WebRTC signalling +The diagram below explains the messages involved in the WebRTC signaling process. :: @@ -67,18 +67,19 @@ by Feross Aboukhadijeh and hundreds of open source contributors. overview -------- The websocket tracker uses JSON payloads reflecting the HTTP request parameters -and an additionnal action property used to switch between announce and other +and an additional action property used to switch between "announce" and other actions (ex. scrape). If the announce URL of the torrent contains the ws or wss -protocol, the client establishes a websocket connection with the tracker. +protocol, a websocket connection is established between the client and the +tracker. WebRTC offers and answers can be provided as an extension of the announce message, the tracker will be responsible to forward them between the peers to -act as a signalling service. +act as a signaling service. After the connection is open, the client can begin announcing itself by using the JSON messages below. -signalling related message format +signaling related message format --------------------------------- announce request:: @@ -143,7 +144,8 @@ answer message:: } A client can answer to an offer by sending the data in an announce message with -an "answer" property? +an "answer" property. The "to_peer_id" property tells the tracker to which +peer it has to forward the message. other message format From 486a94d2b651e7aed86ba27b82e679f5d1d1e700 Mon Sep 17 00:00:00 2001 From: Yoann Ciabaud Date: Sat, 6 Aug 2016 09:10:57 +0200 Subject: [PATCH 3/4] Fix footnote ref --- bep_webrtc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bep_webrtc.rst b/bep_webrtc.rst index 2b2600d7..031c43da 100644 --- a/bep_webrtc.rst +++ b/bep_webrtc.rst @@ -211,7 +211,7 @@ error response:: Existing implementations ======================== -bittorrent-tracker [4] support this protocol, it is used in all WebTorrent [2] +bittorrent-tracker [4] support this protocol, it is used in all WebTorrent [3] clients. From 0544a16dd55845e785bc742861ae29ad9ea182c0 Mon Sep 17 00:00:00 2001 From: Yoann Ciabaud Date: Mon, 29 Aug 2016 09:30:12 +0200 Subject: [PATCH 4/4] Change the error response to have an action prop --- bep_webrtc.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/bep_webrtc.rst b/bep_webrtc.rst index 031c43da..b22235cf 100644 --- a/bep_webrtc.rst +++ b/bep_webrtc.rst @@ -204,7 +204,8 @@ If the tracker encounters an error, it might send an error message. error response:: { - "error": "" + "action": "error" + "message": "" }