From 750635d72955b5e1f3fda52c45242dc1eaba0af0 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 6 May 2022 14:29:28 +0100 Subject: [PATCH] Remodel to lean heavily on MSC3489, instead of repeating --- .../3672-ephemeral-location-streaming.md | 185 ++++++------------ 1 file changed, 64 insertions(+), 121 deletions(-) diff --git a/proposals/3672-ephemeral-location-streaming.md b/proposals/3672-ephemeral-location-streaming.md index fd701f8b..626a25ec 100644 --- a/proposals/3672-ephemeral-location-streaming.md +++ b/proposals/3672-ephemeral-location-streaming.md @@ -2,153 +2,96 @@ ## Problem -[MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489) +[MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489) focuses on streaming persistent location data for applications that require -historical knowledge. +historical knowledge. -While that's perfect for situations in which long term storage of the data is a -non-issue and implied (e.g. flight paths, strava style exercises, fleet -tracking), there are also cases in doing so is undesirable for either privacy +While that's perfect for situations in which long term storage of the data is a +non-issue and implied (e.g. flight paths, strava style exercises, fleet +tracking), there are also cases in doing so is undesirable for either privacy or performance reasons. -Sharing user live location updates is one of the cases in which privacy is -paramount and where we need the ability to share data in a safe and +Sharing user live location updates is one of the cases in which privacy is +paramount and where we need the ability to share data in a safe and non-persistent fashion. ## Proposal -This MSC adds the ability to publish short-lived location beacons through the -the use of custom Ephemeral Data Units (EDUs) by building on top of [MSC2477](https://github.com/matrix-org/matrix-doc/pull/2477). - -Ephemeral data units (EDUs) are Matrix's default mechanism for broadcasting -short-lived data to a group of users and with the advent of user-defined ones -they perfectly fit live location sharing. -They are intended to be non-persistent, not take part in a room's history and -are currently used for typing notifications, event receipts, and presence -updates. As an extra precaution they can also be encrypted as defined in [MSC3673](https://github.com/matrix-org/matrix-doc/pull/3673). - -We will start by introducing `m.beacon_info` as a new state event type; the event shape originally taken from [MSC3489](https://github.com/matrix-org/matrix-doc/pull/3489), but with some slight tweaks. - -The `state_key` of this state event must be send to the sender's MXID. As per [event auth rules](https://spec.matrix.org/v1.2/rooms/v9/#authorization-rules), this restricts the state event to only be editable by the sender. - -**`m.beacon_info` state event `content` field definitions** - -| key | type | value | description | Required | -| ---- | ----| ----- | ----------- | -------- | -| `timeout` | int | A positive number of milliseconds | The maximum length of the location sharing session, relative to `m.ts`. | yes -| `description` | string | Optional descriptive text | A human-readable description of the live location sharing session. | no | -| `live` | bool | true | A boolean describing whether the location sharing session is currently active. Also denotes this session as ephemeral. | yes -| `m.ts` | int | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The timestamp of when the location sharing session was started by the sender. **Milliseconds** since the unix epoch. | yes -| `m.asset` | dict | A dictionary (see below) | Describes the object being tracked. From [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488). | yes - -TODO: This design does not currently allow for a user to have multiple live location sharing sessions active simultaneously. Incorporating either [MSC3671](https://github.com/matrix-org/matrix-spec-proposals/pull/3671) or [MSC3757](https://github.com/matrix-org/matrix-spec-proposals/pull/3757) will help here. - -TODO: Is `m.ts` really needed on `m.beacon_info`? Or can we just simply use `origin_server_ts`? - -**`m.asset` dictionary definition** - -| key | type | value | description | required | -| ---- | --- | ----- | ----------- | -------- | -| `type` | string | `m.self` | A string identifying the asset being tracked, as defined by [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488). `m.self` means this session tracks the sender's location. | yes | - - -A full example of the `m.beacon_info` state event: - -```json5 -{ - "type": "m.beacon_info", - "state_key": "@stefan:matrix.org", - "content": { - "timeout": 600000, - "description": "Stefan's live location", - "live": true, - "m.ts": 1436829458432, - "m.asset": { - "type": "m.self" - } - }, - "origin_server_ts": 1436829458474, - "event_id": "$abcd:domain", - "room_id": "!1234:domain" -} -``` - -Subsequently clients will start sending beacon data EDUs to the new -`rooms/{roomId}/ephemeral/{eventType}/{txnId}` endpoint where `eventType` equals -`m.beacon` with the following payload. - -**`m.beacon` ephemeral event `content` field definitions** - -| key | type | value | description | Required | -| ---- | ----| ----- | ----------- | -------- | -| `m.relates_to` | dictionary | Event reference, defined in [MSC2674](https://github.com/matrix-org/matrix-spec-proposals/pull/2674) | A reference to the state event defining a live location share that this location update is related to. | yes -| `m.location` | dictionary | An extensible event containing location data, defined in [MSC3267](https://github.com/matrix-org/matrix-spec-proposals/pull/3267) | The asset's location, and an optional description | yes | -| `m.ts` | int | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) | The optional timestamp of when the location was recorded. If missing, clients should use `origin_server_ts`. | no - -An full example of a `m.beacon` EDU as received by a client: - -```json5 -{ - "content": { - "m.relates_to": { - "rel_type": "m.reference", - "event_id": "$beacon_info" - }, - "m.location": { - "uri": "geo:51.5008,0.1247;u=35", - "description": "Arbitrary beacon information" - }, - "m.ts": 1636829458432, - }, - "type": "m.beacon", - "sender": "@stefan:matrix.org", - "origin_server_ts": 1636829518182 -} -``` - -If multiple live beacons exist, clients have the option of either aggregating -all available location EDUs into one render or just those referencing a particular -`m.beacon_info` state event. - -When the user decides they would like to stop sharing their live location the -original `m.beacon_info`'s `live` property should be set to `false`. +This MSC adds the ability to publish short-lived location beacons through +the use of Ephemeral Data Units (EDUs). It is almost identical to MSC3489, +apart from this change. -## Security considerations +Ephemeral data units (EDUs) are Matrix's default mechanism for broadcasting +short-lived data to a group of users. They are intended to be +non-persistent, not take part in a room's history and are currently used +for typing notifications, event receipts, and presence updates. + +To allow the use of EDUs for live location sharing, this MSC depends on +[MSC2477](https://github.com/matrix-org/matrix-spec-proposals/pull/2477/) +for user-defined EDUs, and +[MSC3673](https://github.com/matrix-org/matrix-spec-proposals/pull/3673) +for encrypted EDUs. + +Clients announce a share, and stop a share exactly as in MSC3489, by +emitting an `m.beacon_info` state event. + +Clients share locations by emitting an `m.beacon` event which is identical +to those described in MSC3489, except that it is an EDU (whereas in MSC3489 +the events are PDUs). + +All other behaviour is the same as in MSC3489. The only difference is that +`m.beacon` events are EDUs. -End-to-end encryption for ephemeral data units isn't currently available, but a -mechanism for achieving that is defined separately in [MSC3673](https://github.com/matrix-org/matrix-doc/pull/3673). This would prevent location data from being readable by homeservers participating in the room. +### Delivery guarantees -Likewise, end-to-end encryption for state events could be provided by [MSC3414](https://github.com/matrix-org/matrix-spec-proposals/pull/3414). This would hide the metadata that a user has started or stopped sharing their location from being known to the homeservers participating in the room. +MSC2477 specifically avoids defining delivery guarantees for user-defined EDUs, +so we avoid making hard recommendations here. We expect that future MSCs will +clarify the available options. When that happens, clients should choose the +available option that suits their use case, which we expect will be broadly in +line with the following paragraph. +Servers should attempt to deliver `m.beacon` EDUs to all clients, and delete +them as soon as possible. Servers should implement a timeout mechanism to ensure +they are always deleted, even if undelivered. For the expected use cases, we +suggest 30 minutes would be a suitable timeout. + +## Security considerations + +The security considerations are identical to MSC3489, except that EDUs +provide a better privacy situation because they are not persisted long-term. ## Alternatives -Alternatively, we could negotiate a WebRTC data channel using [MSC3401](https://github.com/matrix-org/matrix-doc/pull/3401) -and stream low-latency geospatial data over the participating devices in the -room. However it would be useful to support plain HTTP like the rest of Matrix -and requiring a WebRTC stack is prohibitively complicated for simple clients +Alternatively, we could negotiate a WebRTC data channel using +[MSC3401](https://github.com/matrix-org/matrix-doc/pull/3401) +and stream low-latency geospatial data over the participating devices in the +room. However it would be useful to support plain HTTP like the rest of Matrix +and requiring a WebRTC stack is prohibitively complicated for simple clients (e.g. basic IOT devices reporting spatial telemetry). Another alternative is to use to-device events but that comes with disadvantages -of its own as they're 1:1, single message per transaction and not intended for +of its own as they're 1:1, single message per transaction and not intended for conversational data. ## Dependencies This proposal relies on the following MSCs: -* [MSC2477: User-defined ephemeral events in rooms](https://github.com/matrix-org/matrix-doc/pull/2477) -* [MSC3488: Extending events with location data](https://github.com/matrix-org/matrix-spec-proposals/pull/3488) +* [MSC2477: User-defined ephemeral events in rooms](https://github.com/matrix-org/matrix-spec-proposals/pull/2477) +* [MSC3673: Encrypted ephemeral data units](https://github.com/matrix-org/matrix-spec-proposals/pull/3673) +* [MSC3489: Sharing streams of location data with history](https://github.com/matrix-org/matrix-spec-proposals/pull/3489) -## Unstable prefix +For live location shares to work in appservices, these MSCs will also be +required: -Until this MSC is merged, the following unstable prefixes should be used: +* [MSC2409: Proposal to send EDUs to appservices](https://github.com/matrix-org/matrix-spec-proposals/pull/2409) +* [MSC3202: Encrypted appservices](https://github.com/matrix-org/matrix-spec-proposals/pull/3202) - * `m.beacon_info` should be referred to as `org.matrix.msc3672.beacon_info` - * `m.beacon` should be referred to as `org.matrix.msc3672.beacon` +## Unstable prefix - Until [MSC3488](https://github.com/matrix-org/matrix-spec-proposals/pull/3488) is merged, the following unstable prefix should be used: +This MSC uses the same unstable prefixes as +[MSC3489](https://github.com/matrix-org/matrix-spec-proposals/pull/3489). - * `m.location` should be referred to as `org.matrix.msc3488.location` - * `m.ts` should be referred to as `org.matrix.msc3488.ts` - * `m.asset` should be referred to as `org.matrix.msc3488.asset` \ No newline at end of file +Note that MSC3489 actually uses prefixes that match this MSC's numbering. +This is an historical artifact of the various revision histories of these +proposals.