felixfoertsch/syncthing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

Update discovery protocol specs for v0.13

Browse Source 
GitHub-Pull-Request: https://github.com/syncthing/docs/pull/171
This commit is contained in:
Audrius Butkevicius
2016-05-21 02:08:46 +00:00
parent ddd8042732
commit c4a1600950
2 changed files with 11 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
specs/globaldisco-v3.rst
+7 -8
View File
@@ -7,17 +7,16 @@ Announcements
------------- -------------
A device should announce itself at startup. It does this by an HTTPS POST to A device should announce itself at startup. It does this by an HTTPS POST to
the announce server URL (with the path usually being "/", but this is of the announce server URL. Standard discovery currently requires the path to be
course up to the discovery server). The POST has a JSON payload listing direct "/v2/", yet this can be up to the discovery server. The POST has a JSON payload
connection addresses (if any) and relay addresses (if any):: listing connection addresses (if any)::
{ {
direct: ["tcp://192.0.2.45:22000", "tcp://:22202"], addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"],
relays: [{"url": "relay://192.0.2.99:22028", "latency": 142}]
} }
It's OK for either of the "direct" or "relays" fields to be either the empty It's OK for the "addresses" field to be either the empty list (``[]``),
list (``[]``), ``null``, or missing entirely. An announcment with both fields missing ``null``, or missing entirely. An announcement with the field missing
or empty is however not useful... or empty is however not useful...
Any empty or unspecified IP addresses (i.e. addresses like ``tcp://:22000``, Any empty or unspecified IP addresses (i.e. addresses like ``tcp://:22000``,
@@ -50,7 +49,7 @@ Queries
Queries are performed as HTTPS GET requests to the announce server URL. The Queries are performed as HTTPS GET requests to the announce server URL. The
requested device ID is passed as the query parameter "device", in canonical requested device ID is passed as the query parameter "device", in canonical
string form, i.e. ``https://announce.syncthing.net/?device=ABC12345-....`` string form, i.e. ``https://announce.syncthing.net/v2/?device=ABC12345-....``
Successful responses will have status code ``200`` (OK) and carry a JSON payload Successful responses will have status code ``200`` (OK) and carry a JSON payload
of the same format as the announcement above. The response will not contain of the same format as the announcement above. The response will not contain
specs/localdisco-v3.rst
+4 -35
View File
@@ -70,12 +70,6 @@ The Announcement packet has the following structure::
\ Zero or more Address Structures \ \ Zero or more Address Structures \
/ / / /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Relays |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ Zero or more Relay Structures \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Address Structure: Address Structure:
@@ -89,20 +83,6 @@ The Announcement packet has the following structure::
/ / / /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Relay Structure:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length of URL |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ URL (variable length) \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Latency |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The corresponding XDR representation is as follows (see The corresponding XDR representation is as follows (see
`RFC4506 <http://tools.ietf.org/html/rfc4506>`__ for the XDR format): `RFC4506 <http://tools.ietf.org/html/rfc4506>`__ for the XDR format):
@@ -117,21 +97,15 @@ The corresponding XDR representation is as follows (see
struct Device { struct Device {
opaque ID<32>; opaque ID<32>;
Address Addresses<16>; Address Addresses<16>;
Relay Relays<16>;
} }
struct Address { struct Address {
string URL<2083>; string URL<2083>;
} }
struct Relay {
string URL<2083>;
int Latency;
}
In the ``Announce`` structure field ``Magic`` is used to ensure In the ``Announce`` structure field ``Magic`` is used to ensure
a correct datagram was received and MUST be equal to ``0x9D79BC40``. a correct datagram was received and MUST be equal to ``0x7D79BC40``.
The first Device structure contains information about the sending The first Device structure contains information about the sending
device. The following zero or more Extra devices contain information device. The following zero or more Extra devices contain information
@@ -141,11 +115,6 @@ In the ``Device`` structure, field ``DeviceID`` is the SHA-256 (32
bytes) of the device X.509 certificate, as explained in section *Device bytes) of the device X.509 certificate, as explained in section *Device
ID*. ID*.
For each ``Address`` and ``Relay`` the ``URL`` field contains the actual For each ``Address`` the ``URL`` field contains the actual target address.
target address. Direct connections (the ``Address`` list) will Direct connections will typically have the ``tcp://`` scheme. Relay connections
typically have the ``tcp://`` scheme. Relay connections will typically use the will typically use the ``relay://`` scheme.
``relay://`` scheme.
The ``Latency`` field contains the approximate latency for a TCP handshake
(i.e. three packet round trips) between the other device and the relay, in
milliseconds.