@ -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 bec aon
This lets us track an arbitrary number of beacons per user, and avoids beac on
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.
.* ` should be referred to as `.* ` 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.
Stefan Ceriu
4 years ago
committed by