Review feedback
* store-and-forward -> send-to-device * describe motivation * device ids are 10 capital chars * etc
This commit is contained in:
parent
ccd7bb32d5
commit
ebaaa7e3b3
6 changed files with 30 additions and 21 deletions
|
@ -240,8 +240,8 @@ paths:
|
||||||
title: ToDevice
|
title: ToDevice
|
||||||
type: object
|
type: object
|
||||||
description: |-
|
description: |-
|
||||||
Information on the store-and-forward messages for the client device, as defined in
|
Information on the send-to-device messages for the client
|
||||||
|store_and_forward_sync|_.
|
device, as defined in |send_to_device_sync|_.
|
||||||
examples:
|
examples:
|
||||||
application/json: |-
|
application/json: |-
|
||||||
{
|
{
|
||||||
|
|
|
@ -30,9 +30,9 @@ securityDefinitions:
|
||||||
paths:
|
paths:
|
||||||
"/sendToDevice/{eventType}/{txnId}":
|
"/sendToDevice/{eventType}/{txnId}":
|
||||||
put:
|
put:
|
||||||
summary: Send to-device event to a given set of devices.
|
summary: Send an event to a given set of devices.
|
||||||
description: |-
|
description: |-
|
||||||
This endpoint is used to send store-and-forward events to a set of
|
This endpoint is used to send send-to-device events to a set of
|
||||||
client devices.
|
client devices.
|
||||||
security:
|
security:
|
||||||
- accessToken: []
|
- accessToken: []
|
||||||
|
@ -73,7 +73,7 @@ paths:
|
||||||
description: Message content
|
description: Message content
|
||||||
example: {
|
example: {
|
||||||
"@alice:example.com": {
|
"@alice:example.com": {
|
||||||
"tLLbenaag": {
|
"TLLBEANAAG": {
|
||||||
"example_content_key": "value"
|
"example_content_key": "value"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -86,4 +86,4 @@ paths:
|
||||||
application/json: |-
|
application/json: |-
|
||||||
{}
|
{}
|
||||||
tags:
|
tags:
|
||||||
- Store-and-forward messaging
|
- Send-to-Device messaging
|
||||||
|
|
|
@ -1258,6 +1258,9 @@ have to wait in milliseconds before they can try again.
|
||||||
.. |/rooms/<room_id>/state| replace:: ``/rooms/<room_id>/state``
|
.. |/rooms/<room_id>/state| replace:: ``/rooms/<room_id>/state``
|
||||||
.. _/rooms/<room_id>/state: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state
|
.. _/rooms/<room_id>/state: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state
|
||||||
|
|
||||||
|
.. |/rooms/<room_id>/send| replace:: ``/rooms/<room_id>/send``
|
||||||
|
.. _/rooms/<room_id>/send: #put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-send-eventtype-txnid
|
||||||
|
|
||||||
.. |/rooms/<room_id>/invite| replace:: ``/rooms/<room_id>/invite``
|
.. |/rooms/<room_id>/invite| replace:: ``/rooms/<room_id>/invite``
|
||||||
.. _/rooms/<room_id>/invite: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-invite
|
.. _/rooms/<room_id>/invite: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-invite
|
||||||
|
|
||||||
|
|
|
@ -12,8 +12,8 @@
|
||||||
.. See the License for the specific language governing permissions and
|
.. See the License for the specific language governing permissions and
|
||||||
.. limitations under the License.
|
.. limitations under the License.
|
||||||
|
|
||||||
Store-and-Forward messaging
|
Send-to-Device messaging
|
||||||
===========================
|
========================
|
||||||
|
|
||||||
.. _module:to_device:
|
.. _module:to_device:
|
||||||
|
|
||||||
|
@ -21,6 +21,12 @@ This module provides a means by which clients can exchange signalling messages
|
||||||
without them being stored permanently as part of a shared communication
|
without them being stored permanently as part of a shared communication
|
||||||
history. A message is delivered exactly once to each client device.
|
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
|
Client behaviour
|
||||||
----------------
|
----------------
|
||||||
To send a message to other devices, a client should call |/sendToDevice|_.
|
To send a message to other devices, a client should call |/sendToDevice|_.
|
||||||
|
@ -28,7 +34,7 @@ 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 ``*``
|
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.
|
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
|
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
|
returned by |/sync|_, as detailed in `Extensions to /sync`_. Clients should
|
||||||
inspect the ``type`` of each returned event, and ignore any they do not
|
inspect the ``type`` of each returned event, and ignore any they do not
|
||||||
understand.
|
understand.
|
||||||
|
@ -42,10 +48,10 @@ server should list the pending messages, in order of arrival, in the response
|
||||||
body.
|
body.
|
||||||
|
|
||||||
When the client calls ``/sync`` again with the ``next_batch`` token from the
|
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
|
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.
|
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
|
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
|
limit the number sent in each ``/sync`` response. 100 messages is recommended
|
||||||
as a reasonable limit.
|
as a reasonable limit.
|
||||||
|
|
||||||
|
@ -53,7 +59,7 @@ If the client sends messages to users on remote domains, those messages should
|
||||||
be sent on to the remote servers via
|
be sent on to the remote servers via
|
||||||
`federation`_.
|
`federation`_.
|
||||||
|
|
||||||
.. _`federation`: ../server_server/latest.html#store-and-forward-messages
|
.. _`federation`: ../server_server/latest.html#send-to-device-messages
|
||||||
|
|
||||||
.. TODO-spec:
|
.. TODO-spec:
|
||||||
|
|
||||||
|
@ -76,8 +82,8 @@ Protocol definitions
|
||||||
may be valid. Should we add something to the response?
|
may be valid. Should we add something to the response?
|
||||||
|
|
||||||
.. anchor for link from /sync api spec
|
.. anchor for link from /sync api spec
|
||||||
.. |store_and_forward_sync| replace:: Store-and-Forward messaging
|
.. |send_to_device_sync| replace:: Send-to-Device messaging
|
||||||
.. _store_and_forward_sync:
|
.. _send_to_device_sync:
|
||||||
|
|
||||||
Extensions to /sync
|
Extensions to /sync
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
@ -89,7 +95,7 @@ This module adds the following properties to the |/sync|_ response:
|
||||||
========= ========= =======================================================
|
========= ========= =======================================================
|
||||||
Parameter Type Description
|
Parameter Type Description
|
||||||
========= ========= =======================================================
|
========= ========= =======================================================
|
||||||
to_device ToDevice Optional. Information on the store-and-forward messages
|
to_device ToDevice Optional. Information on the send-to-device messages
|
||||||
for the client device.
|
for the client device.
|
||||||
========= ========= =======================================================
|
========= ========= =======================================================
|
||||||
|
|
||||||
|
@ -98,7 +104,7 @@ to_device ToDevice Optional. Information on the store-and-forward messages
|
||||||
========= ========= =============================================
|
========= ========= =============================================
|
||||||
Parameter Type Description
|
Parameter Type Description
|
||||||
========= ========= =============================================
|
========= ========= =============================================
|
||||||
events [Event] List of store-and-forward messages
|
events [Event] List of send-to-device messages
|
||||||
========= ========= =============================================
|
========= ========= =============================================
|
||||||
|
|
||||||
``Event``
|
``Event``
|
|
@ -975,15 +975,15 @@ 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
|
resident servers as part of the remote join handshake. This list may or may not
|
||||||
include the server answering the query.
|
include the server answering the query.
|
||||||
|
|
||||||
Store-and-forward messages
|
Send-to-device messaging
|
||||||
--------------------------
|
------------------------
|
||||||
|
|
||||||
.. TODO: add modules to the federation spec and make this a module
|
.. 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
|
The server API for send-to-device messaging is based on the following
|
||||||
EDU. There are no PDUs or Federation Queries involved.
|
EDU. There are no PDUs or Federation Queries involved.
|
||||||
|
|
||||||
Each store-and-forward message should be sent to the destination server using
|
Each send-to-device message should be sent to the destination server using
|
||||||
the following EDU::
|
the following EDU::
|
||||||
|
|
||||||
EDU type: m.direct_to_device
|
EDU type: m.direct_to_device
|
||||||
|
|
|
@ -41,7 +41,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
|
||||||
- modules/receipts.rst
|
- modules/receipts.rst
|
||||||
- modules/presence.rst
|
- modules/presence.rst
|
||||||
- modules/content_repo.rst
|
- modules/content_repo.rst
|
||||||
- modules/store_and_forward.rst
|
- modules/send_to_device.rst
|
||||||
- modules/end_to_end_encryption.rst
|
- modules/end_to_end_encryption.rst
|
||||||
- modules/history_visibility.rst
|
- modules/history_visibility.rst
|
||||||
- modules/push.rst
|
- modules/push.rst
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue