New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specification for direct-to-device messages #386

Merged
merged 4 commits into from Oct 4, 2016

Conversation

Projects
None yet
2 participants
@richvdh
Member

richvdh commented Sep 27, 2016

Based on Mark's doc at https://docs.google.com/document/d/1v8lxwKi1y074ggYYAjZTHN2EJYBFPtnot2nM3vVWTR0.

One particular question is over what these things should be called. At once point the idea was to call them direct-to-device messages, but then that sounded a bit like they would skip the HS altogether. I've gone with "store-and-forward" here, but will take suggestions.

@ara4n ara4n self-assigned this Sep 27, 2016

@richvdh

This comment has been minimized.

Member

richvdh commented Sep 27, 2016

@ara4n

lgtm other than feedback

@@ -236,6 +236,12 @@ paths:
The global private data created by this user.
allOf:
- $ref: "definitions/event_batch.yaml"
to_device:
title: ToDevice

This comment has been minimized.

@ara4n

ara4n Sep 28, 2016

Member

why no space? All the other titles seem to have form "Foo bar" not "Foo Bar" or "FooBar"...

This comment has been minimized.

@richvdh

richvdh Sep 29, 2016

Member

well, we've been very inconsistent on this. See http://matrix.org/speculator/spec/386/client_server/unstable.html#post-matrix-client-unstable-user-userid-filter for example.

It's supposed to be the name of a type. Indeed it wouldn't be unreasonable to auto-generate actual type objects from the swagger (that's the idea of it, of course. No idea how well it works in practice). So imho CamelCase makes more sense than the others.

paths:
"/sendToDevice/{eventType}/{txnId}":
put:
summary: Send to-device event to a given set of devices.

This comment has been minimized.

@ara4n

ara4n Sep 28, 2016

Member

using 'to-device' here without defining it feels tautological and strange. I'd just say "Send event to a given set of devices"

This comment has been minimized.

@richvdh
description: Message content
example: {
"@alice:example.com": {
"tLLbenaag": {

This comment has been minimized.

@ara4n

ara4n Sep 28, 2016

Member

given our device IDs are currently 10 capital letters, we can perhaps avoid some possible confusion by using the right shape here?

This comment has been minimized.

@richvdh
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.

This comment has been minimized.

@ara4n

ara4n Sep 28, 2016

Member

Perhaps add: "The primary motivation for this API is exchanging data that is meaningless or undesirable to persist in the room DAG, but requires reliable delivery - e.g. one-time authentication tokens or key data. It is not intended for conversational data, which should be stored in the DAG for consistency throughout Matrix"

This comment has been minimized.

@richvdh

richvdh Sep 29, 2016

Member

I was trying quite hard to avoid the words "reliable delivery", since it's not completely reliable (eg, if a device goes away for long enough, we might expire its messages). Otherwise, yes.

This comment has been minimized.

@richvdh
.. See the License for the specific language governing permissions and
.. limitations under the License.
Store-and-Forward messaging

This comment has been minimized.

@ara4n

ara4n Sep 28, 2016

Member

The inconsistency and redundancy between calling this SAF messaging v. 'Send-to-Device' messaging is bugging me. What do you think about standardising on 'Send-to-device messaging' for consistency with the endpoint naming?

This comment has been minimized.

@richvdh

richvdh Sep 29, 2016

Member

Well, hence the question in the PR. Send-to-device feels ugly to me, but probably a better compromise than the other candidates ("store-and-forward", "direct-to-device" or just "to-device"). Will amend accordingly.

This comment has been minimized.

@richvdh

richvdh Sep 29, 2016

Member

done, I hope

"sender": "@alice:example.com",
"type": "m.new_device",
"content": {
"device_id": "XYZABCDE",

This comment has been minimized.

@ara4n

ara4n Sep 28, 2016

Member

10-char device ID for familiarity?

This comment has been minimized.

@richvdh

richvdh added some commits Sep 29, 2016

Review feedback
* store-and-forward -> send-to-device
* describe motivation
* device ids are 10 capital chars
* etc
Changelog fix
store-and-forward -> send-to-device
@richvdh

This comment has been minimized.

Member

richvdh commented Oct 3, 2016

@ara4n: PTAL?

@ara4n

This comment has been minimized.

Member

ara4n commented Oct 4, 2016

lgtm, sorry for sitting on it

@richvdh richvdh merged commit bc6c585 into master Oct 4, 2016

1 check was pending

Docs (Merged PR) Build started sha1 is merged.
Details

@richvdh richvdh deleted the rav/store_and_forward branch Oct 4, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment