wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1506 from turt2live/travis/general/pushers

Browse source 
Improve documentation for pushers and push gateways
This commit is contained in:
Travis Ralston 2018-08-16 09:23:57 -06:00 • committed by GitHub
commit 94091a12fb
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 121 additions and 84 deletions
Download patch file Download diff file Expand all files Collapse all files

105
api/client-server/pusher.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -31,30 +32,30 @@ paths:
get:
summary: Gets the current pushers for the authenticated user
description: |-
Gets all currently active pushers for the authenticated user
Gets all currently active pushers for the authenticated user.
operationId: getPushers
security:
- accessToken: []
responses:
200:
description: The pushers for this user
description: The pushers for this user.
examples:
application/json: {
"pushers": [
{
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
"kind": "http",
"app_id": "face.mcapp.appy.prod",
"app_display_name": "Appy McAppface",
"device_display_name": "Alice's Phone",
"profile_tag": "xyz",
"lang": "en-US",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
}
"pushers": [
{
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
"kind": "http",
"app_id": "face.mcapp.appy.prod",
"app_display_name": "Appy McAppface",
"device_display_name": "Alice's Phone",
"profile_tag": "xyz",
"lang": "en-US",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
}
]
}
}
]
}
schema:
type: object
properties:
@ -70,7 +71,7 @@ paths:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. See `/set` for
This is a unique identifier for this pusher. See ``/set`` for
more detail.
Max length, 512 bytes.
kind:
@ -115,6 +116,19 @@ paths:
description: |-
Required if ``kind`` is ``http``. The URL to use to send
notifications to.
format:
type: string
description: |-
The format to use when sending notifications to the Push
Gateway.
required:
- pushkey
- app_id
- kind
- app_display_name
- device_display_name
- lang
- data
tags:
- Push notifications
"/pushers/set":
@ -130,23 +144,24 @@ paths:
parameters:
- in: body
name: pusher
description: The pusher information
description: The pusher information.
required: true
schema:
type: object
example: {
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"profile_tag": "xxyyzz",
"app_id": "com.example.app.ios",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
"data": {
"url": "https://push-gateway.location.here"
},
"append": false
}
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"profile_tag": "xxyyzz",
"app_id": "com.example.app.ios",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
"data": {
"url": "https://push-gateway.location.here/_matrix/push/v1/notify",
"format": "event_id_only"
},
"append": false
}
properties:
pushkey:
type: string
@ -157,11 +172,15 @@ paths:
for APNS or the Registration ID for GCM. If your notification
client has no such concept, use any unique identifier.
Max length, 512 bytes.
If the ``kind`` is ``"email"``, this is the email address to
send notifications to.
kind:
type: string
description: |-
The kind of pusher to configure. ``"http"`` makes a pusher that
sends HTTP pokes. ``null`` deletes the pusher.
sends HTTP pokes. ``"email"`` makes a pusher that emails the
user with unread notifications. ``null`` deletes the pusher.
app_id:
type: string
description: |-
@ -169,6 +188,8 @@ paths:
It is recommended that this end with the platform, such that
different platform versions get different app identifiers.
Max length, 64 chars.
If the ``kind`` is ``"email"``, this is ``"m.email"``.
app_display_name:
type: string
description: |-
@ -188,7 +209,7 @@ paths:
type: string
description: |-
The preferred language for receiving notifications (e.g. 'en'
or 'en-US')
or 'en-US').
data:
type: object
description: |-
@ -202,6 +223,14 @@ paths:
description: |-
Required if ``kind`` is ``http``. The URL to use to send
notifications to.
format:
type: string
description: |-
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: |-
@ -216,17 +245,17 @@ paths:
200:
description: The pusher was set.
examples:
application/json: {
}
application/json: {}
schema:
type: object # empty json object
type: object
description: An empty object.
400:
description: One or more of the pusher values were invalid.
examples:
application/json: {
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:

92
api/push-gateway/push_notifier.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -19,7 +20,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
basePath: /_matrix/push/v1
consumes:
- application/json
produces:
@ -38,14 +39,14 @@ paths:
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
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 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.
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.
operationId: notify
parameters:
- in: body
@ -55,36 +56,36 @@ paths:
schema:
type: object
example: {
"notification": {
"id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message",
"sender": "@exampleuser:matrix.org",
"sender_display_name": "Major Tom",
"room_name": "Mission Control",
"room_alias": "#exampleroom:matrix.org",
"prio": "high",
"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"
}
"notification": {
"id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message",
"sender": "@exampleuser:matrix.org",
"sender_display_name": "Major Tom",
"room_name": "Mission Control",
"room_alias": "#exampleroom:matrix.org",
"prio": "high",
"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"
}
]
}
}
]
}
}
required: ["notification"]
properties:
notification:
@ -111,14 +112,10 @@ paths:
type: string
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.
Required if the notification relates to a specific
Matrix event.
sender_display_name:
type: string
description: |-
@ -148,15 +145,16 @@ paths:
type: object
title: EventContent
description: |-
The ``content`` field from the event, if present. If the
event had no content field, 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
description: |-
This is a dictionary of the current number of unacknowledged
communications for the recipient user. Counts whose value is
zero are omitted.
zero should be omitted.
properties:
unread:
type: integer
@ -180,10 +178,10 @@ paths:
app_id:
type: string
description: |-
The app_id given when the pusher was created.
The ``app_id`` given when the pusher was created.
pushkey:
type: string
description: The pushkey given when the pusher was created.
description: The ``pushkey`` given when the pusher was created.
pushkey_ts:
type: integer
description: |-
@ -202,13 +200,14 @@ paths:
description: |-
A dictionary of customisations made to the way this
notification is to be presented. These are added by push rules.
required: ['app_id', 'pushkey']
responses:
200:
description: A list of rejected push keys.
examples:
application/json: {
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
}
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
}
schema:
type: object # empty json object
properties:
@ -222,7 +221,8 @@ paths:
pushkeys and remove the associated pushers. It may not
necessarily be the notification in the request that failed:
it could be that a previous notification to the same pushkey
failed.
failed. May be empty.
items:
type: string
description: A pushkey
description: A pushkey that has been rejected.
required: ['rejected']

1
changelogs/client_server/newsfragments/1506.feature Normal file
View file

@ -0,0 +1 @@
Document and improve client interaction with pushers.

2
specification/modules/push.rst
View file

@ -622,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

5
specification/push_gateway.rst
View file

@ -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}}