Specification for direct-to-device messages

pull/977/head
Richard van der Hoff 8 years ago
parent 459f4b953d
commit ccd7bb32d5

@ -236,6 +236,12 @@ paths:
The global private data created by this user.
allOf:
- $ref: "definitions/event_batch.yaml"
to_device:
title: ToDevice
type: object
description: |-
Information on the store-and-forward messages for the client device, as defined in
|store_and_forward_sync|_.
examples:
application/json: |-
{

@ -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 to-device event to a given set of devices.
description: |-
This endpoint is used to send store-and-forward 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": {
"tLLbenaag": {
"example_content_key": "value"
}
}
}
responses:
200:
description:
The message was successfully sent.
examples:
application/json: |-
{}
tags:
- Store-and-forward messaging

@ -35,6 +35,8 @@
- Add top-level ``account_data`` key to the responses to ``GET /sync`` and
``GET /initialSync``
(`#380 <https://github.com/matrix-org/matrix-doc/pull/380>`_).
- Add "Store-and-Forward messaging" module
(`#386 <https://github.com/matrix-org/matrix-doc/pull/386>`_).
r0.2.0
======

@ -0,0 +1,140 @@
.. 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.
Store-and-Forward 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.
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 store-and-forward 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 store-and-forward messages in
that response have been delivered successfully, and delete them from the store.
If there is a large queue of store-and-forward 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#store-and-forward-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
.. |store_and_forward_sync| replace:: Store-and-Forward messaging
.. _store_and_forward_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 store-and-forward messages
for the client device.
========= ========= =======================================================
``ToDevice``
========= ========= =============================================
Parameter Type Description
========= ========= =============================================
events [Event] List of store-and-forward 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

@ -974,3 +974,27 @@ The list of join candidates is a list of server names that are likely to hold
the given room; these are servers that the requesting server may wish to use as
resident servers as part of the remote join handshake. This list may or may not
include the server answering the query.
Store-and-forward messages
--------------------------
.. TODO: add modules to the federation spec and make this a module
The server API for store-and-forward messaging is based on the following
EDU. There are no PDUs or Federation Queries involved.
Each store-and-forward message should be sent to the destination server using
the following EDU::
EDU type: m.direct_to_device
Content keys:
sender: user ID of the sender
type: event type for the message
message_id: unique id for the message: used for idempotence
messages: 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.

@ -41,6 +41,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
- modules/receipts.rst
- modules/presence.rst
- modules/content_repo.rst
- modules/store_and_forward.rst
- modules/end_to_end_encryption.rst
- modules/history_visibility.rst
- modules/push.rst

Loading…
Cancel
Save