From de961fb7d6c37bf9404e07a91c7e60db64465425 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 11:59:58 -0600 Subject: [PATCH] Improve wording on push gateways --- api/client-server/pusher.yaml | 11 +++++------ api/push-gateway/push_notifier.yaml | 6 +++--- specification/modules/push.rst | 5 ++--- specification/push_gateway.rst | 5 +++++ 4 files changed, 15 insertions(+), 12 deletions(-) diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 0e9cf641..34050d3f 100644 --- a/api/client-server/pusher.yaml +++ b/api/client-server/pusher.yaml @@ -226,12 +226,11 @@ paths: format: type: string description: |- - The format to send notifications in to Push Gateways. If - unset or unrecognized, the homeserver should populate as - many fields as it can in the push notification. If set to - ``"event_id_only"``, the homeserver should only send the - absolute minimum amount of information possible to the push - gateway by not including optional fields. + The format to send notifications in to Push Gateways if the + ``kind`` is ``http``. The details about what fields the + homeserver should send to the push gateway are defined in the + `Push Gateway Specification`_. Currently the only format + available is 'event_id_only'. append: type: boolean description: |- diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 9f57b00a..4a6cb8f7 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -145,9 +145,9 @@ paths: type: object title: EventContent description: |- - The ``content`` field from the event, if present. If the - event had no content field or the pusher wishes to not include - it, this field is omitted. + The ``content`` field from the event, if present. The pusher + may omit this if the event had no content or for any other + reason. counts: type: object title: Counts diff --git a/specification/modules/push.rst b/specification/modules/push.rst index e6a7acf5..e9ee8c90 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -65,9 +65,6 @@ APNS or Google's GCM. This happens as follows: notifications. 5. The Push Provider sends the notification to the device. -Homeservers may optionally support email notifications or other push kinds -of push, identified by the ``kind`` field of the pusher configuration. - Definitions for terms used in this section are below: Push Provider @@ -625,3 +622,5 @@ shouldn't be sent in the push itself where possible. Instead, Push Gateways should send a "sync" command to instruct the client to get new events from the homeserver directly. + +.. _`Push Gateway Specification`: ../push_gateway/unstable.html diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index 29a41bf7..e4a9d6ea 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -67,4 +67,9 @@ This describes the format used by "HTTP" pushers to send notifications of events to Push Gateways. If the endpoint returns an HTTP error code, the homeserver SHOULD retry for a reasonable amount of time using exponential backoff. +When pushing notifications for events, the hoemserver is expected to include all of +the event-related fields in the ``/notify`` request. When the homeserver is performing +a push where the ``format`` is ``"event_id_only"``, only the ``event_id``, ``room_id``, +``counts``, and ``devices`` are required to be populated. + {{push_notifier_push_http_api}}