Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Publish a BEP explaining how to add support for WebTorrent #881

Open
wants to merge 4 commits into
base: beps
Choose a base branch
from
Open

Publish a BEP explaining how to add support for WebTorrent #881

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a85a200
First revision of the webtorrent BEP!
yciabaud Aug 5, 2016
ab730e7
Typos and to_peer_id property
yciabaud Aug 5, 2016
486a94d
Fix footnote ref
yciabaud Aug 6, 2016
0544a16
Change the error response to have an action prop
yciabaud Aug 29, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 241 additions & 0 deletions bep_webrtc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,241 @@
:BEP: XXX
:Title: Websocket tracker protocol for WebRTC transport
:Version: $Revision$
:Last-Modified: $Date$
:Author: Yoann Ciabaud <y.ciabaud@gmail.com>
: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 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 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 this BEP is written, Websockets [2] are the only compatible
standard technology.

WebRTC signaling process
=========================
The diagram below explains the messages involved in the WebRTC signaling
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 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I STRONGLY recommend that we formally drop support for insecure websockets. It's almost 2017, there is no reason to introduce a potential security vulnerability or vector for surveillance. Especially with Let's Encrypt available for free, there is simply no excuse for running an insecure public service. WebRTC itself already disallows insecure connections, we should incorporate that momentum into this BEP.

I suggest we change this explicitly disallow 'ws' and only allow 'wss' here.

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 signaling service.

After the connection is open, the client can begin announcing itself by using
the JSON messages below.

signaling related message format
---------------------------------
announce request::

{
"action": "announce",
"info_hash": "",
"peer_id": ""
"numwant": 0,
"uploaded": 0,
"downloaded": 0,
"left": 0,
"event": "",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Analyzing a bit the payloads from wss://tracker.openwebtorrent.com/, this field is not present for announce done at regular intervals. However, for consistency with the BT protocol it should be mentionned that a missing event, or an event that is represented by an empty string is one of those made at regular intervals.

"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": ""
Copy link
Contributor Author

@yciabaud yciabaud Aug 8, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed from "answer" to "sdp" as this property can be either an offer or a response.

Copy link

@wI2L wI2L Oct 11, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am thinking that a message like this one is not really related to Bittorrent annoucing, and that maybe we could use two new action events offer and answer. It would simplify server side parsing of messages and ensure that we know exactly how to deal with sdp.

EDIT: It seems to be either offer or answer in the payloads returned by tracker.openwebtorrent.com, and this field is an object containing the fields type and sdp. type seems to be consistent with the name of the field.

}

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": ""
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

answer is an object with the fields type and sdp.

}

A client can answer to an offer by sending the data in an announce message with
an "answer" property. The "to_peer_id" property tells the tracker to which
peer it has to forward the message.


other message format
--------------------

scrape request::

{
"action": "scrape",
"info_hash": ""
}


scrape response::

{
"announce": "",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to https://github.com/feross/bittorrent-tracker/blob/master/server.js#L677-L680, there is no such field announce.

"info_hash": "",
Copy link
Contributor Author

@yciabaud yciabaud Aug 8, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed the scrape response format from "infoHash" to "info_hash" to be consistent with the other messages.

Copy link

@wI2L wI2L Nov 6, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually I "think" (still not sure) that the response is created here : https://github.com/feross/bittorrent-tracker/blob/master/server.js#L698-L701, and that the "infoHash" field is used as a key in the forEachloop when creating a new entry in files list.

To me, it seems that either for a single or multi scrape request the response will contains a field list where the keys are the info_hash and the value an object with the stats of the related swarm.

"complete": 0,
"incomplete": 0,
"downloaded": 0
}


multi-scrape request::

{
"action": "scrape",
"info_hash": ["ih1", "ih2", ...]
}


multi-scrape response::
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same thing for the multiscrape...


{
"ih1": {
"announce": "",
Copy link

@wI2L wI2L Nov 6, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to https://github.com/feross/bittorrent-tracker/blob/master/server.js#L691-L695 and https://github.com/feross/bittorrent-tracker/blob/master/server.js#L698-L701, there is no shuch field 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": ""
Copy link
Contributor Author

@yciabaud yciabaud Aug 8, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here I changed from "failure reason" to "error" to be cleaner.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the UDP tracker BEP, I've found it uses a type of action called error whenever an error is return. And then a message attribute for the error message.

It could make sense adding it (at least the action attribute), just to be consistent in the response.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with you, it is definitely more consistent with the other messages. Pushing it right now!

}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed the error response message for it to look like the other messages like in other beps.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tbh, I think that both failure reason and an extra error field are necesseray. The first one wpuld stay for legacy reasons and would be used only for Bittorrent protocol related failures (either announce or scrape) while another extra field (or object, with code/message ?) could describe a signalling error.



Existing implementations
========================

bittorrent-tracker [4] support this protocol, it is used in all WebTorrent [3]
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: