From a9a26be85966b2fef1d676372eabe9bacd409862 Mon Sep 17 00:00:00 2001 From: Jakob Borg Date: Tue, 20 Oct 2015 13:50:39 +0200 Subject: [PATCH] Global discovery specs --- specs/globaldisco-v3.rst | 66 ++++++++++++++++++++++++++++++++++++++++ specs/index.rst | 3 ++ 2 files changed, 69 insertions(+) create mode 100644 specs/globaldisco-v3.rst diff --git a/specs/globaldisco-v3.rst b/specs/globaldisco-v3.rst new file mode 100644 index 000000000..796e0724e --- /dev/null +++ b/specs/globaldisco-v3.rst @@ -0,0 +1,66 @@ +.. _globaldisco-v3: + +Global Discovery v3 +=================== + +Announcements +------------- + +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 +course up to the discovery server). The POST has a JSON payload listing direct +connection addresses (if any) and relay addresses (if any):: + + { + direct: ["tcp://192.0.2.45:22000", "tcp://:22202"], + 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 +list (``[]``), ``null``, or missing entirely. An announcment with both fields missing +or empty is however not useful... + +Any empty or unspecified IP addresses (i.e. addresses like ``tcp://:22000``, +``tcp://0.0.0.0:22000``, ``tcp://[::]:22000``) are interpreted as referring to +the source IP address of the announcement. + +The device ID of the announcing device is not part of the announcement. +Instead, the server requires that the client perform certificate +authentication. The device ID is deduced from the presented certificate. + +The server response is empty, with code ``204`` (No Content) on success. If no +certificate was presented, status ``403`` (Forbidden) is returned. If the +posted data doesn't conform to the expected format, ``400`` (Bad Request) is +returned. + +In successfull responses, the server may return a ``Reannounce-After"``header +containing the number of seconds after which the client should perform a new +announcement. + +In error responses, the server may return a ``Retry-After`` header containing +the number of seconds after which the client should retry. + +Performing announcements significantly more often than indicated by the +``Reannounce-After`` or ``Retry-After`` headers may result in the client being +throttled. In such cases the server may respond with status code ``429`` (Too +Many Requests). + +Queries +------- + +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 +string form, i.e. ``https://announce.syncthing.net/?device=ABC12345-....`` + +Successfull 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 +empty or unspecified addresses. + +If the "device" query parameter is missing or malformed, the status code 400 +(Bad Request) is returned. + +If the device ID is of a valid format but not found in the registry, 404 (Not +Found) is returned. + +If the client has exceeded a rate limit, the server may respond with 429 (Too +Many Requests). diff --git a/specs/index.rst b/specs/index.rst index 0e71057a8..b07943cb7 100644 --- a/specs/index.rst +++ b/specs/index.rst @@ -6,5 +6,8 @@ Specifications :ref:`bep-v1` The protocol used to exchange file data and metadata between Syncthing devices. +:ref:`globaldisco-v3` + The protocol used for global discovery over the Internet. + :ref:`localdisco-v3` The protocol used for local discovery within a broadcast domain (LAN).