Merge pull request #386 from matrix-org/rav/store_and_forward
Specification for direct-to-device messagespull/977/head
Richard van der Hoff
8 years ago
committed by
GitHub
commit
bc6c5858ea
@ -0,0 +1,89 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Send-to-device API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/sendToDevice/{eventType}/{txnId}":
|
||||
put:
|
||||
summary: Send an event to a given set of devices.
|
||||
description: |-
|
||||
This endpoint is used to send send-to-device events to a set of
|
||||
client devices.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: eventType
|
||||
description: The type of event to send.
|
||||
required: true
|
||||
x-example: "m.new_device"
|
||||
- in: path
|
||||
name: txnId
|
||||
type: string
|
||||
description: |-
|
||||
The transaction ID for this event. Clients should generate an
|
||||
ID unique across requests with the same access token; it will be
|
||||
used by the server to ensure idempotency of requests.
|
||||
required: true
|
||||
x-example: "35"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
title: body
|
||||
properties:
|
||||
messages:
|
||||
type: object
|
||||
description: |-
|
||||
The messages to send. A map from user ID, to a map from
|
||||
device ID to message body. The device ID may also be `*`,
|
||||
meaning all known devices for the user.
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: EventContent
|
||||
description: Message content
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"TLLBEANAAG": {
|
||||
"example_content_key": "value"
|
||||
}
|
||||
}
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The message was successfully sent.
|
||||
examples:
|
||||
application/json: |-
|
||||
{}
|
||||
tags:
|
||||
- Send-to-Device messaging
|
||||
@ -0,0 +1,146 @@
|
||||
.. Copyright 2016 OpenMarket Ltd
|
||||
..
|
||||
.. Licensed under the Apache License, Version 2.0 (the "License");
|
||||
.. you may not use this file except in compliance with the License.
|
||||
.. You may obtain a copy of the License at
|
||||
..
|
||||
.. http://www.apache.org/licenses/LICENSE-2.0
|
||||
..
|
||||
.. Unless required by applicable law or agreed to in writing, software
|
||||
.. distributed under the License is distributed on an "AS IS" BASIS,
|
||||
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
.. See the License for the specific language governing permissions and
|
||||
.. limitations under the License.
|
||||
|
||||
Send-to-Device messaging
|
||||
========================
|
||||
|
||||
.. _module:to_device:
|
||||
|
||||
This module provides a means by which clients can exchange signalling messages
|
||||
without them being stored permanently as part of a shared communication
|
||||
history. A message is delivered exactly once to each client device.
|
||||
|
||||
The primary motivation for this API is exchanging data that is meaningless or
|
||||
undesirable to persist in the room DAG - for example, one-time authentication
|
||||
tokens or key data. It is not intended for conversational data, which should be
|
||||
sent using the normal |/rooms/<room_id>/send|_ API for consistency throughout
|
||||
Matrix.
|
||||
|
||||
Client behaviour
|
||||
----------------
|
||||
To send a message to other devices, a client should call |/sendToDevice|_.
|
||||
Only one message can be sent to each device per transaction, and they must all
|
||||
have the same event type. The device ID in the request body can be set to ``*``
|
||||
to request that the message be sent to all known devices.
|
||||
|
||||
If there are send-to-device messages waiting for a client, they will be
|
||||
returned by |/sync|_, as detailed in `Extensions to /sync`_. Clients should
|
||||
inspect the ``type`` of each returned event, and ignore any they do not
|
||||
understand.
|
||||
|
||||
Server behaviour
|
||||
----------------
|
||||
Servers should store pending messages for local users until they are
|
||||
successfully delivered to the destination device. When a client calls |/sync|_
|
||||
with an access token which corresponds to a device with pending messages, the
|
||||
server should list the pending messages, in order of arrival, in the response
|
||||
body.
|
||||
|
||||
When the client calls ``/sync`` again with the ``next_batch`` token from the
|
||||
first response, the server should infer that any send-to-device messages in
|
||||
that response have been delivered successfully, and delete them from the store.
|
||||
|
||||
If there is a large queue of send-to-device messages, the server should
|
||||
limit the number sent in each ``/sync`` response. 100 messages is recommended
|
||||
as a reasonable limit.
|
||||
|
||||
If the client sends messages to users on remote domains, those messages should
|
||||
be sent on to the remote servers via
|
||||
`federation`_.
|
||||
|
||||
.. _`federation`: ../server_server/latest.html#send-to-device-messages
|
||||
|
||||
.. TODO-spec:
|
||||
|
||||
* Is a server allowed to delete undelivered messages? After how long? What
|
||||
about if the device is deleted?
|
||||
|
||||
* If the destination HS doesn't support the ``m.direct_to_device`` EDU, it
|
||||
will just get dumped. Should we indicate that to the client?
|
||||
|
||||
|
||||
Protocol definitions
|
||||
--------------------
|
||||
|
||||
{{to_device_cs_http_api}}
|
||||
|
||||
.. TODO-spec:
|
||||
|
||||
* What should a server do if the user id or device id is unknown? Presumably
|
||||
it shouldn't reject the request outright, because some of the destinations
|
||||
may be valid. Should we add something to the response?
|
||||
|
||||
.. anchor for link from /sync api spec
|
||||
.. |send_to_device_sync| replace:: Send-to-Device messaging
|
||||
.. _send_to_device_sync:
|
||||
|
||||
Extensions to /sync
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This module adds the following properties to the |/sync|_ response:
|
||||
|
||||
.. todo: generate this from a swagger definition?
|
||||
|
||||
========= ========= =======================================================
|
||||
Parameter Type Description
|
||||
========= ========= =======================================================
|
||||
to_device ToDevice Optional. Information on the send-to-device messages
|
||||
for the client device.
|
||||
========= ========= =======================================================
|
||||
|
||||
``ToDevice``
|
||||
|
||||
========= ========= =============================================
|
||||
Parameter Type Description
|
||||
========= ========= =============================================
|
||||
events [Event] List of send-to-device messages
|
||||
========= ========= =============================================
|
||||
|
||||
``Event``
|
||||
|
||||
================ ============ ==================================================
|
||||
Parameter Type Description
|
||||
================ ============ ==================================================
|
||||
content EventContent The content of this event. The fields in this
|
||||
object will vary depending on the type of event.
|
||||
sender string The Matrix user ID of the user who sent this
|
||||
event.
|
||||
type string The type of event.
|
||||
================ ============ ==================================================
|
||||
|
||||
|
||||
Example response:
|
||||
|
||||
.. code:: json
|
||||
|
||||
{
|
||||
"next_batch": "s72595_4483_1934",
|
||||
"rooms": {"leave": {}, "join": {}, "invite": {}},
|
||||
"to_device": {
|
||||
"events": [
|
||||
{
|
||||
"sender": "@alice:example.com",
|
||||
"type": "m.new_device",
|
||||
"content": {
|
||||
"device_id": "XYZABCDE",
|
||||
"rooms": ["!726s6s6q:example.com"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
.. |/sendToDevice| replace:: ``/sendToDevice``
|
||||
.. _/sendToDevice: #put-matrix-client-%CLIENT_MAJOR_VERSION%-sendtodevice-eventtype-txnid
|
||||
Loading…
Reference in New Issue