Review feedback

* store-and-forward -> send-to-device
* describe motivation
* device ids are 10 capital chars
* etc

api/client-server/sync.yaml

@@ -240,8 +240,8 @@ paths:
                 title: ToDevice
                 type: object
                 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:
             application/json: |-
               {

api/client-server/to_device.yaml

@@ -30,9 +30,9 @@ securityDefinitions:
 paths:
   "/sendToDevice/{eventType}/{txnId}":
     put:
-      summary: Send to-device event to a given set of devices.
+      summary: Send an event to a given set of devices.
       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.
       security:
         - accessToken: []
@@ -73,7 +73,7 @@ paths:
                     description: Message content
                 example: {
                     "@alice:example.com": {
-                      "tLLbenaag": {
+                      "TLLBEANAAG": {
                         "example_content_key": "value"
                       }
                     }
@@ -86,4 +86,4 @@ paths:
             application/json: |-
               {}
       tags:
-        - Store-and-forward messaging
+        - Send-to-Device messaging

specification/client_server_api.rst

@@ -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: #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: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-invite
 

specification/modules/send_to_device.rst

@@ -12,8 +12,8 @@
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 
-Store-and-Forward messaging
+Send-to-Device messaging
-===========================
+========================
 
 .. _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
 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|_.
@@ -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 ``*``
 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
 inspect the ``type`` of each returned event, and ignore any they do not
 understand.
@@ -42,10 +48,10 @@ 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
+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 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
 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
 `federation`_.
 
-.. _`federation`: ../server_server/latest.html#store-and-forward-messages
+.. _`federation`: ../server_server/latest.html#send-to-device-messages
 
 .. TODO-spec:
 
@@ -76,8 +82,8 @@ Protocol definitions
      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
+.. |send_to_device_sync| replace:: Send-to-Device messaging
-.. _store_and_forward_sync:
+.. _send_to_device_sync:
 
 Extensions to /sync
 ~~~~~~~~~~~~~~~~~~~
@@ -89,7 +95,7 @@ This module adds the following properties to the |/sync|_ response:
 ========= ========= =======================================================
 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.
 ========= ========= =======================================================
 
@@ -98,7 +104,7 @@ to_device ToDevice  Optional. Information on the store-and-forward messages
 ========= ========= =============================================
 Parameter Type      Description
 ========= ========= =============================================
-events    [Event]   List of store-and-forward messages
+events    [Event]   List of send-to-device messages
 ========= ========= =============================================
 
 ``Event``

specification/server_server_api.rst

@@ -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
 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
 
-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.
 
-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::
 
   EDU type: m.direct_to_device

specification/targets.yaml

@@ -41,7 +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/send_to_device.rst
     - modules/end_to_end_encryption.rst
     - modules/history_visibility.rst
     - modules/push.rst