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

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

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd # Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
# #
# Licensed under the Apache License, Version 2.0 (the "License"); # Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License. # you may not use this file except in compliance with the License.
@ -19,7 +20,7 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: /_matrix/push/%CLIENT_MAJOR_VERSION% basePath: /_matrix/push/v1
consumes: consumes:
- application/json - application/json
produces: produces:
@ -38,14 +39,14 @@ paths:
Notifications about a particular event will normally cause the user to be Notifications about a particular event will normally cause the user to be
alerted in some way. It is therefore necessary to perform duplicate 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 retries of this HTTP API causing duplicate alerts. The operation of
updating counts of unread notifications should be idempotent and updating counts of unread notifications should be idempotent and
therefore do not require duplicate suppression. therefore do not require duplicate suppression.
Notifications are sent to the URL configured when the pusher is Notifications are sent to the URL configured when the pusher is created.
created. This means that the HTTP path may be different depending on the This means that the HTTP path may be different depending on the push
push gateway. gateway.
operationId: notify operationId: notify
parameters: parameters:
- in: body - in: body
@ -55,36 +56,36 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"notification": { "notification": {
"id": "$3957tyerfgewrf384", "id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com", "room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message", "type": "m.room.message",
"sender": "@exampleuser:matrix.org", "sender": "@exampleuser:matrix.org",
"sender_display_name": "Major Tom", "sender_display_name": "Major Tom",
"room_name": "Mission Control", "room_name": "Mission Control",
"room_alias": "#exampleroom:matrix.org", "room_alias": "#exampleroom:matrix.org",
"prio": "high", "prio": "high",
"content": { "content": {
"msgtype": "m.text", "msgtype": "m.text",
"body": "I'm floating in a most peculiar way." "body": "I'm floating in a most peculiar way."
}, },
"counts": { "counts": {
"unread" : 2, "unread" : 2,
"missed_calls": 1 "missed_calls": 1
}, },
"devices": [ "devices": [
{ {
"app_id": "org.matrix.matrixConsole.ios", "app_id": "org.matrix.matrixConsole.ios",
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
"pushkey_ts": 12345678, "pushkey_ts": 12345678,
"data" : {}, "data" : {},
"tweaks": { "tweaks": {
"sound": "bing" "sound": "bing"
}
} }
] }
} ]
} }
}
required: ["notification"] required: ["notification"]
properties: properties:
notification: notification:
@ -111,14 +112,10 @@ paths:
type: string type: string
description: |- description: |-
The type of the event as in the event's ``type`` field. The type of the event as in the event's ``type`` field.
Required if the notification relates to a specific
Matrix event.
sender: sender:
type: string type: string
description: |- description: |-
The sender of the event as in the corresponding event field. The sender of the event as in the corresponding event field.
Required if the notification relates to a specific
Matrix event.
sender_display_name: sender_display_name:
type: string type: string
description: |- description: |-
@ -148,15 +145,16 @@ paths:
type: object type: object
title: EventContent title: EventContent
description: |- description: |-
The ``content`` field from the event, if present. If the The ``content`` field from the event, if present. The pusher
event had no content field, this field is omitted. may omit this if the event had no content or for any other
reason.
counts: counts:
type: object type: object
title: Counts title: Counts
description: |- description: |-
This is a dictionary of the current number of unacknowledged This is a dictionary of the current number of unacknowledged
communications for the recipient user. Counts whose value is communications for the recipient user. Counts whose value is
zero are omitted. zero should be omitted.
properties: properties:
unread: unread:
type: integer type: integer
@ -180,10 +178,10 @@ paths:
app_id: app_id:
type: string type: string
description: |- description: |-
The app_id given when the pusher was created. The ``app_id`` given when the pusher was created.
pushkey: pushkey:
type: string type: string
description: The pushkey given when the pusher was created. description: The ``pushkey`` given when the pusher was created.
pushkey_ts: pushkey_ts:
type: integer type: integer
description: |- description: |-
@ -202,13 +200,14 @@ paths:
description: |- description: |-
A dictionary of customisations made to the way this A dictionary of customisations made to the way this
notification is to be presented. These are added by push rules. notification is to be presented. These are added by push rules.
required: ['app_id', 'pushkey']
responses: responses:
200: 200:
description: A list of rejected push keys. description: A list of rejected push keys.
examples: examples:
application/json: { application/json: {
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
} }
schema: schema:
type: object # empty json object type: object # empty json object
properties: properties:
@ -222,7 +221,8 @@ paths:
pushkeys and remove the associated pushers. It may not pushkeys and remove the associated pushers. It may not
necessarily be the notification in the request that failed: necessarily be the notification in the request that failed:
it could be that a previous notification to the same pushkey it could be that a previous notification to the same pushkey
failed. failed. May be empty.
items: items:
type: string 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 should send a "sync" command to instruct the client to get new events from the
homeserver directly. 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 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. 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}} {{push_notifier_push_http_api}}