MSC2753: Peeking via sync (take 2)

proposals/2753-peeking-via-sync-v2.md

@@ -0,0 +1,301 @@
+# MSC2753: Peeking via Sync (Take 2)
+
+## Problem
+
+[Room previews](https://matrix.org/docs/spec/client_server/r0.6.1#id116), more
+commonly known as "peeking", has a number of usecases, such as:
+
+ * Look at a room before joining it, to preview it.
+ * Look at a user's profile room (see
+   [MSC1769](https://github.com/matrix-org/matrix-doc/issues/1769)).
+ * Browse the metadata or membership of a space (see
+   [MSC1772](https://github.com/matrix-org/matrix-doc/issues/1772)).
+ * Monitor [moderation policy lists](https://matrix.org/docs/spec/client_server/r0.6.1#moderation-policy-lists).
+
+Currently, peeking relies on the deprecated v1 `/initialSync` and `/events`
+APIs.
+
+This poses the following issues:
+
+ * Servers and clients must implement two separate sets of event-syncing logic,
+   doubling complexity.
+ * Peeking a room involves setting a stream of long-lived `/events` requests
+   going. Having multiple streams is racey, competes for resources with the
+   `/sync` stream, and doesn't scale given each room requires a new `/events`
+   stream.
+ * `/initialSync` and `/events` are deprecated and not implemented on new
+   servers.
+
+This proposal suggests a new API in which events in peeked rooms would be
+returned over `/sync`.
+
+## Proposal
+
+Peeking into a room remains per-device: if the user has multiple devices, each
+of which wants to peek into a given room, then each device must make a separate
+request.
+
+To help avoid situations where clients create peek requests and forget about
+them, each peek request is given a lifetime by the server. The client must
+*renew* the peek request before this lifetime expires. The server is free to
+pick any lifetime.
+
+### Starting a peek
+
+We add an CS API called `/peek`, which starts peeking into a given
+room. This is similar to
+[`/join/{roomIdOrAlias}`](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-join-roomidoralias)
+but has a slightly different API shape.
+
+For example:
+
+```
+POST /_matrix/client/r0/peek/{roomIdOrAlias} HTTP/1.1
+
+{
+    "servers": [
+        "server1", "server2"
+    ]
+}
+```
+
+A successful response has the following format:
+
+```
+{
+    "room_id": "<resolved room id>",
+    "peek_expiry_ts": 1605534210000
+}
+```
+
+The `servers` parameter is optional and, if present, gives a list of servers to
+try to peek through.
+
+XXX: should we limit this API to room IDs, and require clients to do a `GET
+/_matrix/client/r0/directory/room/{roomAlias}` request if they have a room
+alias? (In which case, `/_matrix/client/r0/room/{room_id}/peek` might be a
+better name for it.)  On the one hand: cleaner, simpler API. On the other: more
+requests needed for each operation.
+
+Both `room_id` and `peek_expiry_ts` are required in the
+response. `peek_expiry_ts` gives a timestamp (milliseconds since the unix
+epoch) when the server will *expire* the peek if the client does not renew it.
+
+The server ratelimit requests to `/peek` and returns a 429 error with
+`M_LIMIT_EXCEEDED` if the limit is exceeded.
+
+Otherwise, the server first resolves the given room alias to a room ID, if
+needed.
+
+If there is already an active peek for the room in question, it is renewed and
+a successful response is returned with the updated `peek_expiry_ts`.
+
+If the user is already *joined* to the room in question, the server returns a
+400 error with `M_BAD_STATE`.
+
+If the room in question does not exist, the server returns a 404 error with
+`M_NOT_FOUND`.
+
+If the room does not allow peeking (ie, it does not have `history_visibility`
+of `world_readable` <sup id="a1">[1](#f1)</sup>), the server returns a 403
+error with `M_FORBIDDEN`.
+
+Otherwise, the server starts a peek for the calling device into the given room,
+and returns a 200 response as above.
+
+When a peek first starts, the current state of the room is returned in the
+`peek` section of the next `/sync` response.
+
+### Stopping a peek
+
+To stop peeking, the client calls `rooms/<id>/unpeek`:
+
+```
+POST /_matrix/client/r0/rooms/{room_id}/unpeek HTTP/1.1
+
+{}
+```
+
+The body must be a JSON dictionary, but no parameters are specified.
+
+A successful response has an empty body.
+
+If the room is unknown or was not previously being peeked the server returns a
+400 error with `M_BAD_STATE`.
+
+### `/sync` response
+
+We add a new `peek` section to the `rooms` field of the `/sync`
+response. `peek` has the same shape as `join`.
+
+While a peek into a given room is active, any new events in the room cause that
+room to be included in the `peek` section (but only for the device with the
+active peek). When a peek first starts, the entire state of the room is
+included in the same way as when a room is first joined.
+
+If the client requests lazy-loading via `lazy_load_members`, then redundant
+membership events are excluded in the same way as they are for joined rooms.
+
+If a user subsequently `/join`s a room they are peeking, the room will
+thenceforth appear in the `join` section instead of `peek`. For devices which
+were already peeking into the room, the server should *not* include the entire
+room state for the room in the `/sync` response, allowing the client to build
+on the state and history it has already received without re-sending it down
+`/sync`.
+
+When a room stops being peeked (either because the client called `/unpeek` or
+because the server timed out the peek), the room will be included in the
+`leave` section of the `/sync` response, including any events that occured
+between the previous `/sync` and the the peek ending. If there are no such
+events, the room's entry in the `leave` section will be empty.
+
+For example:
+
+```js
+{
+  "rooms": {
+    "join": { /* ... */ },
+    "leave": {
+      "!unpeeked:example.org": {
+        "timeline": {
+          "events": [
+            { "type": "m.room.message", "content": {"body": "just one more thing"}}
+          ]
+        }
+      },
+      "!alsounpeeked:example.com": {}
+    }
+  }
+}
+```
+
+## Encrypted rooms
+
+(this para taken from MSC #2444):
+
+It is considered a feature that you cannot peek into encrypted rooms, given
+the act of peeking would leak the identity of the peeker to the joined users
+in the room (as they'd need to encrypt for the peeker). This also feels
+acceptable given there is little point in encrypting something intended to be
+world-readable.
+
+## Future extensions
+
+ * "snapshot" API, for a one-time peek operation which returns the current
+   state of the room without adding the room to future `/sync` responses. Might
+   be useful for certain usecases (eg, looking at a user's public profile)?
+
+ * "bulk peek" API, for peeking into many rooms at once. Might be useful for
+   flair (which requires peeking into lots of users' profile rooms), though
+   realistically that usecase will need server-side support.
+
+ * "cross-device" peeks could be useful for microblogging etc?
+
+## Potential issues
+
+ * Expiring peeks might be hard for clients to manage?
+
+## Alternatives
+
+### Keep /peek closer to /join
+
+Given that peeking has parallels to joining, it might be preferable to keep the
+API closer to `/join`. On the other hand, they probabably aren't actually
+similar enough to make it worth propagating the oddities of `/join` (in
+particular, the use of query-parameters
+([matrix-doc#2864](https://github.com/matrix-org/matrix-doc/issues/2864)).
+
+### Filter-based API
+
+[MSC1776](https://github.com/matrix-org/matrix-doc/pull/1776) defined an
+alternative approach, where you could use filters to add peeked rooms into a
+given `/sync` response as needed.  This however had some issues:
+
+ * You can't specify what servers to peek remote rooms via.
+ * You can't identify rooms via alias, only ID
+ * It feels hacky to bodge peeked rooms into the `join` block of a given
+   `/sync` response
+ * Fiddling around with custom filters feels clunky relative to just calling a
+   `/peek` endpoint similar to `/join`.
+
+### Use the `join` block
+
+It could be seen as controversial to add another new block to the `/sync`
+response.  We could use the existing `join` block, but:
+
+ * it's a misnomer (given the user hasn't joined the rooms)
+ * `join` refers to rooms which the *user* is in, rather than that they are
+   peeking into using a given *device*
+ * we risk breaking clients who aren't aware of the new style of peeking.
+ * there's already a precedent for per-device blocks in the sync response (for
+   to-device messages)
+
+### Per-account peeks
+
+It could be seen as controversial to make peeking a per-device rather than
+per-user feature.  When thinking through use cases for peeking, however:
+
+ 1. Peeking a chatroom before joining it is the common case, and is definitely
+    per-device - you would not expect peeked rooms to randomly pop up on other
+    devices, or consume their bandwidth.
+ 2. [MSC1769](https://github.com/matrix-org/matrix-doc/pull/1769) (Profiles as
+    rooms) is also per device: if a given client wants to look at the Member
+    Info for a given user in a room, it shouldn't pollute the others with that
+    data.
+ 3. [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) (Groups as
+    rooms) uses room joins to indicate your own membership, and peeks to query
+    the group membership of other users.  Similarly to profiles, it's not clear
+    that this should be per-user rather than per-device (and worse case, it's a
+    matter of effectively opting in rather than trying to filter out peeks you
+    don't care about).
+
+### Alternatives to expiring peeks
+
+Having servers expire peek requests could be fiddly, so we considered a number
+of alternatives:
+
+ * Allow peeks to stack up without limit and trust that clients will not forget
+   about them: after all, it is in clients' best interest not to leak
+   resources, to reduce the amount of data to be handled, and it is not obvious
+   that leaking peeks is easier than leaking joins.
+
+   Ultimately this does not align with our experience of administering
+   `matrix.org`: it seems that where a resource *can* be leaked, it ultimately
+   will be, and it is better to design the API to prevent it.
+
+ * Limit the number of peeks that can be active at once, to force clients to be
+   fastidious in their peek cleanups. However, it is hard to see what a good
+   limit would be. Furthermore: peeks could be lost through no fault of the
+   client (for example: when a `/peek` request succeeds but the client
+   does not receive the response), and these leaked peaks could stack up until
+   peeking becomes inoperative.
+
+ * Automatically clear active peeks when a `/sync` request is made without a
+   `since` parameter. However, this feels like magic at a distance, and also
+   means that if you initial-sync separately (e.g. you stole an access token
+   from the DB to manually debug something) then existing clients will be
+   broken.
+
+ * Have the client resubmit the list of active peeks every time it wants to add
+   or remove one. This could amount to a sigificant quantity of data.
+
+## Security considerations
+
+Servers should ratelimit calls to `/peek` to stop someone DoSing the
+server.
+
+## Unstable prefix
+
+The following mapping will be used for identifiers in this MSC during
+development:
+
+Proposed final identifier       | Purpose | Development identifier
+------------------------------- | ------- | ----
+`/_matrix/client/r0/peek` | API endpoint | `/_matrix/client/unstable/org.matrix.msc2753/peek`
+`/_matrix/client/r0/rooms/{roomId}/unpeek` | API endpoint | `/_matrix/client/unstable/org.matrix.msc2753/rooms/{roomId}/unpeek`
+
+## Footnotes
+
+<a id="f1"/>[1]: `join_rules` do not affect peekability - it's
+possible to have an invite-only room which joe public can still peek into, if
+`history_visibility` has been set to `world_readable`.[↩](#a1)