From 71cb646541ed2611e8f623fc28fac55b3aa73fbb Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 6 Apr 2016 18:28:21 +0100 Subject: [PATCH 1/6] Change `id` in the push gateway poke to be `event_id` and spec that it's the Matrix event ID of the message. Correct the spec for badge count pushes which omit fields previously described as mandatory. Add more detail about when to use event_id to suppress dupes. Also add the push gateway doc so it's actually included in the spec. --- api/push-gateway/push_notifier.yaml | 40 +++++++++++++++++++++------- specification/index.rst | 1 + specification/push_gateway.rst | 2 +- specification/targets.yaml | 3 +++ templating/matrix_templates/units.py | 1 + 5 files changed, 36 insertions(+), 11 deletions(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 540b5686..10c5c372 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -17,7 +17,17 @@ paths: summary: Notify a push gateway about an event. description: |- This endpoint is invoked by HTTP pushers to notify a push gateway about - an event. + an event or update the number of unread notifications a user has. + In the former case it will contain selected information about the event. + In either case it may contain numeric counts of the number of unread + events of different types the user has. The counts may be sent along + with a notification about an event or by themselves. + Notifications about a particular event will normally cause the user to be + alerted in some way. It is therefore necessary to perform duplicate + suppression for such notifications using the `event_id` field to avoid + retries of this HTTP API causing duplicate alerts. The operation of + updating counts of unread notifications should be and therefore do not + require duplicate suppression. *NB: Notifications are sent to the URL configured when the pusher is created. This means that the HTTP path may be different depending on the push gateway.* @@ -65,24 +75,34 @@ paths: notification: type: object description: Information about the push notification - required: ["id", "room_id", "type", "sender"] + required: [] properties: - id: + event_id: type: string description: |- - An identifier for this notification that may be used to - detect duplicate notification requests. This is not - necessarily the ID of the event that triggered the - notification. + The Matrix event ID of the event being notified about. + This is required if the notification is about a + particular Matrix event. It may be omitted for notifications + that only contain updated badge counts. This ID can and + should be used to detect duplicate notification requests. room_id: type: string - description: The ID of the room in which this event occurred. + description: |- + The ID of the room in which this event occurred. + Required if the notification relates to a specific + Matrix event. type: type: string - description: The type of the event as in the event's ``type`` field. + description: |- + The type of the event as in the event's ``type`` field. + Required if the notification relates to a specific + Matrix event. sender: type: string - description: The sender of the event as in the corresponding event field. + description: |- + The sender of the event as in the corresponding event field. + Required if the notification relates to a specific + Matrix event. sender_display_name: type: string description: |- diff --git a/specification/index.rst b/specification/index.rst index eb2e3287..9c3897d1 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -20,6 +20,7 @@ The following APIs are documented in this specification: - `Server-Server API `_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix. - `Application Service API `_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers. - `Identity Service API `_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs. +- `Push Gateway API `_ version unstable for implementing a server that receives notifications about Matrix events a user is interested in. There are also some `appendices `_. diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index 3ed5ffe7..d239e702 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -39,4 +39,4 @@ 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. -{{push_notifier_http_api}} +{{push_notifier_push_http_api}} diff --git a/specification/targets.yaml b/specification/targets.yaml index 40a8e07f..fb18a78b 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -22,6 +22,9 @@ targets: identity_service: files: - identity_service_api.rst + push_gateway: + files: + - push_gateway.rst appendices: files: - appendices.rst diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 2ad0a9b6..3064ba7d 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -21,6 +21,7 @@ HTTP_APIS = { "../api/application-service": "as", "../api/client-server": "cs", "../api/identity": "is", + "../api/push-gateway": "push", } EVENT_EXAMPLES = "../event-schemas/examples" EVENT_SCHEMA = "../event-schemas/schema" From 7e1cb9003ccc0743311e7b54ec48dc5e52522f67 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 6 Apr 2016 18:41:15 +0100 Subject: [PATCH 2/6] Make swagger valid --- api/push-gateway/push_notifier.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 10c5c372..c4cb7f72 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -26,7 +26,7 @@ paths: alerted in some way. It is therefore necessary to perform duplicate suppression for such notifications using the `event_id` field to avoid retries of this HTTP API causing duplicate alerts. The operation of - updating counts of unread notifications should be and therefore do not + updating counts of unread notifications should be and therefore do not require duplicate suppression. *NB: Notifications are sent to the URL configured when the pusher is created. This means that the HTTP path may be different depending on the @@ -75,7 +75,6 @@ paths: notification: type: object description: Information about the push notification - required: [] properties: event_id: type: string From 7faf2cf642743bef8309fc3e8eb5e720e2f7e8f3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 6 Apr 2016 19:49:41 +0100 Subject: [PATCH 3/6] Paragraph breaks & missed word --- api/push-gateway/push_notifier.yaml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index c4cb7f72..046a9745 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -22,12 +22,15 @@ paths: In either case it may contain numeric counts of the number of unread events of different types the user has. The counts may be sent along with a notification about an event or by themselves. + Notifications about a particular event will normally cause the user to be alerted in some way. It is therefore necessary to perform duplicate suppression for such notifications using the `event_id` field to avoid retries of this HTTP API causing duplicate alerts. The operation of - updating counts of unread notifications should be and therefore do not - require duplicate suppression. + updating counts of unread notifications should be idempotent and + therefore do not require duplicate suppression. + + *NB: Notifications are sent to the URL configured when the pusher is created. This means that the HTTP path may be different depending on the push gateway.* From 64c6d30f90f3f692e8cbc2d0925a617bad416c6c Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 6 Apr 2016 19:52:54 +0100 Subject: [PATCH 4/6] hopefully fix rst --- api/push-gateway/push_notifier.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 046a9745..47f0e021 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -31,9 +31,10 @@ paths: therefore do not require duplicate suppression. - *NB: Notifications are sent to the URL configured when the pusher is + Notifications are sent to the URL configured when the pusher is created. This means that the HTTP path may be different depending on the - push gateway.* + push gateway. + parameters: - in: body name: notification From 89453bfd8c071fac995fcaf10f8864eae8cc889e Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 6 Apr 2016 19:53:45 +0100 Subject: [PATCH 5/6] Remove spurious blank line --- api/push-gateway/push_notifier.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 47f0e021..48a438e2 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -30,7 +30,6 @@ paths: updating counts of unread notifications should be idempotent and therefore do not require duplicate suppression. - Notifications are sent to the URL configured when the pusher is created. This means that the HTTP path may be different depending on the push gateway. From cf850b4270a63337314ffa9c84a4c9bad506e748 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 6 Apr 2016 20:21:08 +0100 Subject: [PATCH 6/6] Fix level of `counts` and `devices` They are actually within the notification object rather than the top level object. Add titles to objects so it works. --- api/push-gateway/push_notifier.yaml | 134 ++++++++++++++-------------- 1 file changed, 69 insertions(+), 65 deletions(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 48a438e2..e20dc8e9 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -55,29 +55,31 @@ paths: "content": { "msgtype": "m.text", "body": "I'm floating in a most peculiar way." - } - }, - "counts": { - "unread" : 2, - "missed_calls": 1 - }, - "devices": [ - { - "app_id": "org.matrix.matrixConsole.ios", - "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", - "pushkey_ts": 12345678, - "data" : {}, - "tweaks": { - "sound": "bing" - } - } - ] + }, + "counts": { + "unread" : 2, + "missed_calls": 1 + }, + "devices": [ + { + "app_id": "org.matrix.matrixConsole.ios", + "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", + "pushkey_ts": 12345678, + "data" : {}, + "tweaks": { + "sound": "bing" + } + } + ] + } } - required: ["notification", "counts", "devices"] + required: ["notification"] properties: notification: type: object + title: Notification description: Information about the push notification + required: ["devices"] properties: event_id: type: string @@ -136,56 +138,58 @@ paths: description: |- The ``content`` field from the event, if present. If the event had no content field, this field is omitted. - counts: - type: object - description: |- - This is a dictionary of the current number of unacknowledged - communications for the recipient user. Counts whose value is - zero are omitted. - properties: - unread: - type: integer + counts: + type: object + title: Counts description: |- - The number of unread messages a user has across all of the - rooms they are a member of. - missed_calls: - type: integer + This is a dictionary of the current number of unacknowledged + communications for the recipient user. Counts whose value is + zero are omitted. + properties: + unread: + type: integer + description: |- + The number of unread messages a user has across all of the + rooms they are a member of. + missed_calls: + type: integer + description: |- + The number of unacknowledged missed calls a user has + across all rooms of which they are a member. + devices: + type: array + title: Devices description: |- - The number of unacknowledged missed calls a user has - across all rooms of which they are a member. - devices: - type: array - title: Devices - description: |- - This is an array of devices that the notification should be sent to. - items: - type: object - properties: - app_id: - type: string - description: |- - The app_id given when the pusher was created. - pushkey: - type: string - description: The pushkey given when the pusher was created. - pushkey_ts: - type: integer - description: |- - The unix timestamp (in seconds) when the - pushkey was last updated. - data: - type: object - title: PusherData - description: |- - A dictionary of additional pusher-specific data. For - 'http' pushers, this is the data dictionary passed in at - pusher creation minus the ``url`` key. - tweaks: + This is an array of devices that the notification should be sent to. + items: type: object - title: Tweaks - description: |- - A dictionary of customisations made to the way this - notification is to be presented. These are added by push rules. + title: Device + properties: + app_id: + type: string + description: |- + The app_id given when the pusher was created. + pushkey: + type: string + description: The pushkey given when the pusher was created. + pushkey_ts: + type: integer + description: |- + The unix timestamp (in seconds) when the + pushkey was last updated. + data: + type: object + title: PusherData + description: |- + A dictionary of additional pusher-specific data. For + 'http' pushers, this is the data dictionary passed in at + pusher creation minus the ``url`` key. + tweaks: + type: object + title: Tweaks + description: |- + A dictionary of customisations made to the way this + notification is to be presented. These are added by push rules. responses: 200: description: A list of rejected push keys.