From 1e3f5683c8603acababbdbf87b9e6c041307c666 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 31 Aug 2017 16:56:50 +0100 Subject: [PATCH] Make clear that the /sync timeout is zero by default --- api/client-server/sync.yaml | 8 ++++++-- specification/client_server_api.rst | 10 +++++----- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 8da06f40..be2a8217 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -88,8 +88,12 @@ paths: name: timeout type: integer description: |- - The maximum time to poll in milliseconds before returning this - request. + The maximum time to wait, in milliseconds, before returning this + request. If no events (or other data) become available before this + time elapses, the server will return a response with empty fields. + + By default, this is ``0``, so the server will return immediately + even if the response is empty. x-example: 30000 responses: 200: diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 2973d1d8..ab140641 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -949,11 +949,11 @@ You can visualise the range of events being returned as:: Clients then receive new events by "long-polling" the homeserver via the ``/sync`` API, passing the value of the ``next_batch`` field from the response -to the previous call as the ``since`` parameter. This involves specifying a -timeout in the request which will hold open the HTTP connection for a short -period of time waiting for new events, returning early if an event occurs. Only -the ``/sync`` API (and the deprecated ``/events`` API) support long-polling in -this way. +to the previous call as the ``since`` parameter. The client should also pass a +``timeout`` parameter. The server will then hold open the HTTP connection for a +short period of time waiting for new events, returning early if an event +occurs. Only the ``/sync`` API (and the deprecated ``/events`` API) support +long-polling in this way. The response for such an incremental sync can be visualised as::