From 0f9a23c471f3da091e8b57d71c6445afa82b7a32 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 02:37:31 +0100 Subject: [PATCH 01/11] swaggerify to-device --- .../event-schemas/m.direct_to_device.yaml | 68 +++++++++++++++++++ specification/server_server_api.rst | 14 +--- 2 files changed, 69 insertions(+), 13 deletions(-) create mode 100644 api/server-server/definitions/event-schemas/m.direct_to_device.yaml diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml new file mode 100644 index 00000000..48cdc4ed --- /dev/null +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -0,0 +1,68 @@ +# Copyright 2018 New Vector 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. + +type: object +title: m.direct_to_device +description: |- + An EDU that lets servers push send events directly to a specific device on + a remote server - for instance, to maintain an Olm E2E encrypted message channel + between a local and remote device. +allOf: + - $ref: ../edu.yaml + - type: object + properties: + edu_type: + type: enum + enum: ['m.direct_to_device'] + description: The string ``m.direct_to_device`` + example: "m.direct_to_device" + content: + type: object + description: The description of the direct-to-device message + title: To Device Message + properties: + sender: + type: string + description: user ID of the sender + example: "john@example.com" + type: + type: string + description: event type for the message + example: "m.room_key_request" + message_id: + type: string + description: unique ID for the message, used for idempotence. Arbitrary + utf8 string, of maximum length 32 codepoints. + example: "hiezohf6Hoo7kaev" + messages: + type: object + description: |- + The contents of the messages to be sent. These are arranged in + a map of user IDs to a map of device IDs to message bodies. + The device ID may also be *, meaning all known devices for the user. + example: { + "alice@example.org": { + "IWHQUZUIAH": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." + } + } + } + required: + - sender + - type + - message_id + - messages diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 36d7d5d4..9f11ce9c 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1020,19 +1020,7 @@ EDU. There are no PDUs or Federation Queries involved. Each send-to-device 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 - +{{definition_ss_event_schemas_m_direct_to_device}} Content Repository ------------------ From 2c0b45fd14ec462bdc00c659eb58c0f85c865f84 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 02:41:53 +0100 Subject: [PATCH 02/11] fix example? --- .../event-schemas/m.direct_to_device.yaml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 48cdc4ed..b151158a 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -51,16 +51,17 @@ allOf: The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. The device ID may also be *, meaning all known devices for the user. - example: { - "alice@example.org": { - "IWHQUZUIAH": { - "algorithm": "m.megolm.v1.aes-sha2", - "room_id": "!Cuyf34gef24t:localhost", - "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", - "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." + example: |- + { + "alice@example.org": { + "IWHQUZUIAH": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." + } } } - } required: - sender - type From db302b66ca5e6394aeb7d404233b0389b2eef5bf Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 02:44:53 +0100 Subject: [PATCH 03/11] revert example which was corect first time; fix rst --- .../event-schemas/m.direct_to_device.yaml | 17 ++++++++--------- specification/server_server_api.rst | 2 +- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index b151158a..48cdc4ed 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -51,17 +51,16 @@ allOf: The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. The device ID may also be *, meaning all known devices for the user. - example: |- - { - "alice@example.org": { - "IWHQUZUIAH": { - "algorithm": "m.megolm.v1.aes-sha2", - "room_id": "!Cuyf34gef24t:localhost", - "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", - "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." - } + example: { + "alice@example.org": { + "IWHQUZUIAH": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." } } + } required: - sender - type diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 9f11ce9c..80da7c95 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1018,7 +1018,7 @@ The server API for send-to-device messaging is based on the following EDU. There are no PDUs or Federation Queries involved. Each send-to-device message should be sent to the destination server using -the following EDU:: +the following EDU: {{definition_ss_event_schemas_m_direct_to_device}} From d25f4412d44e844cd0d1730bf11c3b7c80b11378 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 02:46:05 +0100 Subject: [PATCH 04/11] improve wording --- specification/server_server_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 80da7c95..b423a83e 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1014,8 +1014,8 @@ Send-to-device messaging .. TODO: add modules to the federation spec and make this a module -The server API for send-to-device messaging is based on the following -EDU. There are no PDUs or Federation Queries involved. +The server API for send-to-device messaging is based on the +``m.direct_to_device`` EDU. There are no PDUs or Federation Queries involved. Each send-to-device message should be sent to the destination server using the following EDU: From 42b11e096f17d7ed54d852630f1f304387f1ff8d Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 02:48:37 +0100 Subject: [PATCH 05/11] Review --- .../definitions/event-schemas/m.direct_to_device.yaml | 10 +++++----- specification/server_server_api.rst | 1 + 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 48cdc4ed..12578f4d 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -25,24 +25,24 @@ allOf: edu_type: type: enum enum: ['m.direct_to_device'] - description: The string ``m.direct_to_device`` + description: The string ``m.direct_to_device``. example: "m.direct_to_device" content: type: object - description: The description of the direct-to-device message + description: The description of the direct-to-device message. title: To Device Message properties: sender: type: string - description: user ID of the sender + description: User ID of the sender. example: "john@example.com" type: type: string - description: event type for the message + description: Event type for the message. example: "m.room_key_request" message_id: type: string - description: unique ID for the message, used for idempotence. Arbitrary + description: Unique ID for the message, used for idempotence. Arbitrary utf8 string, of maximum length 32 codepoints. example: "hiezohf6Hoo7kaev" messages: diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index b423a83e..5203c5e0 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1022,6 +1022,7 @@ the following EDU: {{definition_ss_event_schemas_m_direct_to_device}} + Content Repository ------------------ From a842e0433d80d53602171802b28a1fad79cadff5 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 02:50:32 +0100 Subject: [PATCH 06/11] try escaping the asterisk --- .../definitions/event-schemas/m.direct_to_device.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 12578f4d..7ab3b5d3 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -50,7 +50,7 @@ allOf: description: |- The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. - The device ID may also be *, meaning all known devices for the user. + The device ID may also be \\*, meaning all known devices for the user. example: { "alice@example.org": { "IWHQUZUIAH": { From 337041610fb6bb71a744884fa90fdf2e61f67e18 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 02:53:15 +0100 Subject: [PATCH 07/11] one slash? --- .../definitions/event-schemas/m.direct_to_device.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 7ab3b5d3..287df33c 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -50,7 +50,7 @@ allOf: description: |- The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. - The device ID may also be \\*, meaning all known devices for the user. + The device ID may also be \*, meaning all known devices for the user. example: { "alice@example.org": { "IWHQUZUIAH": { From 7430c3b56fd1034416eb8dfc0a8505a557c57147 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 03:01:41 +0100 Subject: [PATCH 08/11] experiment with additionalProperties --- .../definitions/event-schemas/m.direct_to_device.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 287df33c..b6445108 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -51,6 +51,11 @@ allOf: The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. The device ID may also be \*, meaning all known devices for the user. + additionalProperties: + type: + - string + - string + - object example: { "alice@example.org": { "IWHQUZUIAH": { From f6326030ba86b4822eb814a51ad181fc782f7203 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 03:02:46 +0100 Subject: [PATCH 09/11] backtick asterisk --- .../definitions/event-schemas/m.direct_to_device.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index b6445108..94d446c7 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -50,7 +50,7 @@ allOf: description: |- The contents of the messages to be sent. These are arranged in a map of user IDs to a map of device IDs to message bodies. - The device ID may also be \*, meaning all known devices for the user. + The device ID may also be ``*``, meaning all known devices for the user. additionalProperties: type: - string From 49f0a06238b2701b3094b664c8d853b49413b839 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 03:03:51 +0100 Subject: [PATCH 10/11] experiment with additionalProperties some more --- .../definitions/event-schemas/m.direct_to_device.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 94d446c7..58143a37 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -52,10 +52,9 @@ allOf: a map of user IDs to a map of device IDs to message bodies. The device ID may also be ``*``, meaning all known devices for the user. additionalProperties: - type: - - string - - string - - object + type: string + additionalProperties: + type: string example: { "alice@example.org": { "IWHQUZUIAH": { From 43f2819702bcad418a41246c5dc117de426e30d5 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 1 Sep 2018 03:06:15 +0100 Subject: [PATCH 11/11] switch to travis' example --- .../definitions/event-schemas/m.direct_to_device.yaml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml index 58143a37..9d5a7468 100644 --- a/api/server-server/definitions/event-schemas/m.direct_to_device.yaml +++ b/api/server-server/definitions/event-schemas/m.direct_to_device.yaml @@ -52,9 +52,12 @@ allOf: a map of user IDs to a map of device IDs to message bodies. The device ID may also be ``*``, meaning all known devices for the user. additionalProperties: - type: string + type: object + title: User Devices additionalProperties: - type: string + type: object + title: Device Message Contents + properties: {} example: { "alice@example.org": { "IWHQUZUIAH": {