Location streaming tweaks (#3622)

* Various tweaks following initial implementation:
- switched from `m.beacon.*` state event to `m.becon` reference relationship to original `m.beacon_info.*`
- changed `beacon_info` created to `m.ts`
- renamed `lifetime` to `timeout`
- added `m.asset` `type`

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.
+            "timeout": 86400000, // how long from the last event until we consider the beacon inactive in milliseconds
-            "lifetime": 86400000, // how long the beacon will publish for 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
+as `m.beacon` events forming a reference relationship to the original `m.beacon_info` event.
-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
+Storing the location data as references as opposed to in a state event has multiple advantages:
-location history where desirable.  If history is not wanted, then one can use
+* 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",
+    "type": "m.beacon",
-    "state_key": "@matthew:matrix.org",
+    "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
+The `m.location` section of the `m.beacon` event can include an optional
-primary asset associated with that mxid (e.g. the whereabouts of its human
+`description` field to provide user facing updates e.g. current address
-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.
 
 ## 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
+reasons - given the beacon data is stored as simple events that will be automatic.
-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.
 
 ## 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.