Skip to content

/ webtorrent

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.

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

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

Open
wants to merge 4 commits into
base: beps
from
+242 −0
Open

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

Changes from 1 commit
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 file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

Next

First revision of the webtorrent BEP!

  • Loading branch information
@yciabaud
yciabaud committed Aug 5, 2016
commit a85a200c795a07a22385f03a28762224879ef09d
239 bep_webrtc.rst
View file
Open in desktop
@@ -0,0 +1,239 @@
: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 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

This comment has been minimized.

Sign in to view
Copy link
@Miserlou

Miserlou Oct 23, 2016

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, 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": "",

This comment has been minimized.

Sign in to view
Copy link
@wI2L

wI2L Oct 11, 2016

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

This comment has been minimized.

Sign in to view
Copy link
@yciabaud

yciabaud Aug 8, 2016 •
edited

Author Contributor

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

This comment has been minimized.

Sign in to view
Copy link
@wI2L

wI2L Oct 11, 2016 •
edited

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

This comment has been minimized.

Sign in to view
Copy link
@wI2L

wI2L Oct 11, 2016

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?


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

scrape request::

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


scrape response::

{
"announce": "",

This comment has been minimized.

Sign in to view
Copy link
@wI2L

wI2L Nov 6, 2016

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

This comment has been minimized.

Sign in to view
Copy link
@yciabaud

yciabaud Aug 8, 2016 •
edited

Author Contributor

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

This comment has been minimized.

Sign in to view
Copy link
@wI2L

wI2L Nov 6, 2016 •
edited

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::

This comment has been minimized.

Sign in to view
Copy link
@yciabaud

yciabaud Aug 8, 2016

Author Contributor

Same thing for the multiscrape...

{
"ih1": {
"announce": "",

This comment has been minimized.

Sign in to view
Copy link
@wI2L

wI2L Nov 6, 2016 •
edited

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

This comment has been minimized.

Sign in to view
Copy link
@yciabaud

yciabaud Aug 8, 2016 •
edited

Author Contributor

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

This comment has been minimized.

Sign in to view
Copy link
@alxhotel

alxhotel Aug 29, 2016

Member

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.

This comment has been minimized.

Sign in to view
Copy link
@yciabaud

yciabaud Aug 29, 2016

Author Contributor

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

This comment has been minimized.

Sign in to view
Copy link
@yciabaud

yciabaud Aug 29, 2016

Author Contributor

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

This comment has been minimized.

Sign in to view
Copy link
@wI2L

wI2L Oct 11, 2016

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 [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:
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.