diff --git a/proposals/3489-location-streaming.md b/proposals/3489-location-streaming.md index 58fd7ba92..058f1f7b7 100644 --- a/proposals/3489-location-streaming.md +++ b/proposals/3489-location-streaming.md @@ -15,7 +15,7 @@ users in a room. This MSC adds the ability to publish real-time location beacons to Matrix by building on MSC3488 (m.location: Extending events with location data). -We introduce two types of state events to describe beacons: the first contains +We introduce two types of events to describe beacons: the first, a state event, contains the metadata about the beacons advertised by a given user: `m.beacon_info.*`. As Matrix doesn't yet have a way to stop other users overwriting an event other than setting its state_key to be the owner's mxid, we work around this @@ -24,79 +24,91 @@ by letting the final part of the event type be a unique ID for the beacon. event to indicate that it can only ever be written by its owner - we may get this via MSC3414 encrypted state events). -This lets us track an arbitrary number of beacons per user, and avoids becaon +This lets us track an arbitrary number of beacons per user, and avoids beacon metadata being duplicated as location data is shared. An example `m.beacon_info.*` event is: ```json5 { - "type": "m.beacon_info.self", + "type": "m.beacon_info.@matthew:matrix.org", "state_key": "@matthew:matrix.org", "content": { "m.beacon_info": { "description": "The Matthew Tracker", // same as an `m.location` description - "created": 1436829458432, // creation timestamp of the beacon on the client. - "lifetime": 86400000, // how long the beacon will publish for in milliseconds + "timeout": 86400000, // how long from the last event until we consider the beacon inactive in milliseconds + }, + "m.ts": 1436829458432, // creation timestamp of the beacon on the client + "m.asset": { + "type": "m.self" // the type of asset being tracked as per MSC3488 } } } ``` Separately, we have the actual location data from the beacon in question -stored in `m.beacon.*` state events. Storing the data as state events -ensures that the current location of a given beacon is trivial to determine -(rather than the client having to back-paginate history). It also gives us -location history where desirable. If history is not wanted, then one can use +as `m.beacon` events forming a reference relationship to the original `m.beacon_info` event. + +Storing the location data as references as opposed to in a state event has multiple advantages: +* Location data is easily encrypted (no dependency on MSC3414) +* Doesn't thrash state resolution by storing new location points every time they change +* Paginated history easily accessible through the `relations` endpoint. If history is not wanted, then one can use data retention policies(e.g. exploding messages) to ensure it does not accumulate unnecessarily. +* Allows other users to request data from a beacon + -`m.beacon.*` events should be sent at a variable rate which is meaningful for +`m.beacon` events should be sent at a variable rate which is meaningful for the use case for the asset being tracked. This rate should not be more frequent than sending an event every 2 seconds. If the asset is not moving, -the state event should still be refreshed on a regular basis to convey that +the location should still be refreshed on a regular basis to convey that information - e.g. every 30 seconds. -An example `m.beacon.*` event is: +An example `m.beacon` event is: -```json +```json5 { - "type": "m.beacon.self", - "state_key": "@matthew:matrix.org", + "type": "m.beacon", + "sender": "@matthew:matrix.org", "content": { + "m.relates_to": { // from MSC2674: https://github.com/matrix-org/matrix-doc/pull/2674 + "rel_type": "m.reference", // from MSC3267: https://github.com/matrix-org/matrix-doc/pull/3267 + "event_id": "$beacon_info" + }, "m.location": { "uri": "geo:51.5008,0.1247;u=35", + "description": "Arbitrary beacon information" }, "m.ts": 1636829458432, } } ``` -The special ID `self` is used to indicate that the beacon describes the -primary asset associated with that mxid (e.g. the whereabouts of its human -user). - -The `m.location` section of the `m.beacon.*` event should not include a -`description` field, as this instead resides on the matching -`m.beacon_info.*` state event. +The `m.location` section of the `m.beacon` event can include an optional +`description` field to provide user facing updates e.g. current address ## Encryption Location data should be stored end-to-end encrypted for obvious data privacy -reasons - given the beacon data is stored in state events, this should be -achieved by MSC3414. - -## Problems - -By storing a state event for every location datapoint, we put significant -load on servers' state management implementations. Current implementations -may not handle this well. However, semantically, state events provide the -behaviour we need (easy access to current value; persistent state within -a room), hence adopting them for this. +reasons - given the beacon data is stored as simple events that will be automatic. ## Alternatives -We could behave like MSC3401 and announce users' beacons in +Initially this MSC considered storing location data in a separate state event but +that had multiple downsides: +* No encryption without MSC3414 +* Difficult access to historical data, timeline pagination required +* State resolution thrasing on every location update. By storing a state event for every location datapoint, +we put significant load on servers' state management implementations. Current implementations +may not handle this well. + +Another option would be using ephemeral data units to broadcast location updates but they +do come with downsides of their own: +* they are not persisted and cannot provide historical data +* there's no per-room API for them +* they are not end to end encrypted + +Alternatively, we could behave like MSC3401 and announce users' beacons in `m.beacon_info.*` (similar to MSC3401's `m.call`), and then send location data via to-device messages to interested devices. * Pros: @@ -133,6 +145,7 @@ unencrypted or persisted. The same security considerations apply as for ## Unstable prefix * `m.beacon_info.*` should be referred to as `org.matrix.msc3489.beacon_info.*` until this MSC lands. - * `m.beacon.*` should be referred to as `org.matrix.msc3489.beacon.*` until this MSC lands. + * `m.beacon` should be referred to as `org.matrix.msc3489.beacon` until this MSC lands. * `m.location` should be referred to as `org.matrix.msc3488.location.*` until MSC3488 lands. * `m.ts` should be referred to as `org.matrix.msc3488.ts.*` until MSC3488 lands. + * `m.asset` should be referred to as `org.matrix.msc3488.asset.*` until MSC3488 lands.