Merge pull request #276 from matrix-org/rav/room_peeking

Split room previews into a separate module

api/client-server/peeking_events.yaml

@@ -26,10 +26,10 @@ paths:
         them to the caller. This will block until an event is received, or until
         the ``timeout`` is reached.
 
-        This API is the same as the non-guest /events endpoint, but can be
-        called by guest users.
+        This API is the same as the normal ``/events`` endpoint, but can be
+        called by users who have not joined the room.
 
-        Note that the non-guest ``/events`` endpoint has been deprecated. This
+        Note that the normal ``/events`` endpoint has been deprecated. This
         API will also be deprecated at some point, but its replacement is not
         yet known.
       security:
@@ -50,15 +50,12 @@ paths:
           required: false
           x-example: "35000"
         - in: query
-          type: array
-          items:
-            type: string
+          type: string
           name: room_id
           description: |-
-            The room IDs for which events should be returned.
+            The room ID for which events should be returned.
           x-example:
-            - "!somewhere:over"
-            - "!the:rainbow"
+            - "!somewhere:over.the.rainbow"
       responses:
         200:
           description: "The events received, which may be none."
@@ -105,4 +102,4 @@ paths:
                     - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
         400:
           description: "Bad pagination ``from`` parameter."
-        # No tags to exclude this from the swagger UI - use the non-guest version instead.
+        # No tags to exclude this from the swagger UI - use the normal version instead.

specification/modules/guest_access.rst

@@ -1,4 +1,4 @@
-Guest access
+Guest Access
 ============
 
 .. _module:guest-access:
@@ -39,7 +39,10 @@ retrieving events:
 * `GET /rooms/:room_id/state/:event_type/:state_key <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype-statekey>`_
 * `GET /rooms/:room_id/messages <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages>`_
 * `GET /rooms/:room_id/initialSync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync>`_
-* `GET /rooms/:room_id/sync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-sync>`_
+* `GET /sync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-sync>`_
+* `GET /events`__ as used for room previews.
+
+__  `peeking_events_api`_
 
 The following API endpoints are allowed to be accessed by guest accounts for
 sending events:
@@ -48,35 +51,13 @@ sending events:
 * `POST /rooms/:room_id/leave <#post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-leave>`_
 * `PUT /rooms/:room_id/send/m.room.message/:txn_id <#put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-send-eventtype-txnid>`_
 
-Guest clients *do* need to join rooms in order to send events to them.
-
 The following API endpoints are allowed to be accessed by guest accounts for
 their own account maintenance:
 
 * `PUT /profile/:user_id/displayname <#put-matrix-client-%CLIENT_MAJOR_VERSION%-profile-userid-displayname>`_
 
-There is also a special version of the
-`GET /events <#get-matrix-client-%CLIENT_MAJOR_VERSION%-events>`_ endpoint:
-
-{{guest_events_http_api}}
-
-They will only return events which happened while the room state had the
-``m.room.history_visibility`` state event present with ``history_visibility``
-value ``world_readable``. Guest clients do not need to join rooms in order to
-receive events for them.
-
-The intention is that guest users will call ``/events`` once per room in
-parallel for rooms they wish to view without joining. For rooms they wish to
-join, they will call ``/join`` and receive events by calling ``/sync`` as
-non-guest users do.
-
 Server behaviour
 ----------------
-Servers are required to only return events to guest accounts for rooms where
-the room state at the event had the  ``m.room.history_visibility`` state event
-present with ``history_visibility`` value ``world_readable``. These events may
-be returned even if the anonymous user is not joined to the room.
-
 Servers MUST only allow guest users to join rooms if the ``m.room.guest_access``
 state event is present on the room, and has the ``guest_access`` value
 ``can_join``. If the ``m.room.guest_access`` event is changed to stop this from
@@ -90,11 +71,6 @@ is a guest account or not is not information passed from server to server.
 Accordingly, any server participating in a room is trusted to properly enforce
 the permissions outlined in this section.
 
-Clients may wish to display to their users that rooms which are
-``world_readable`` *may* be showing messages to non-joined users. There is no
-way using this module to find out whether any non-joined guest users *do* see
-events in the room, or to list or count any guest users.
-
 Homeservers may want to enable protections such as captchas for guest
 registration to prevent spam, denial of service, and similar attacks.
 

specification/modules/room_previews.rst

@@ -0,0 +1,44 @@
+Room Previews
+=============
+
+.. _module:room-previews:
+
+It is sometimes desirable to offer a preview of a room, where a user can "lurk"
+and read messages posted to the room, without joining the room. This can be
+particularly effective when combined with `Guest Access`_.
+
+Previews are implemented via the ``world_readable`` `Room History Visibility`_.
+setting, along with a special version of the
+`GET /events <#get-matrix-client-%CLIENT_MAJOR_VERSION%-events>`_ endpoint.
+
+Client behaviour
+----------------
+A client wishing to view a room without joining it should call
+`GET /rooms/:room_id/initialSync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync>`_,
+followed by `GET /events`__. Clients will need to do this
+in parallel for each room they wish to view.
+
+__  `peeking_events_api`_
+
+Clients can of course also call other endpoints such as
+`GET /rooms/:room_id/messages <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages>`_
+and `GET /search <#get-matrix-client-%CLIENT_MAJOR_VERSION%-search>`_ to access
+events outside the ``/events`` stream.
+
+.. _peeking_events_api:
+
+{{peeking_events_http_api}}
+
+Server behaviour
+----------------
+For clients which have not joined a room, servers are required to only return
+events where the room state at the event had the ``m.room.history_visibility``
+state event present with ``history_visibility`` value ``world_readable``.
+
+Security considerations
+-----------------------
+Clients may wish to display to their users that rooms which are
+``world_readable`` *may* be showing messages to non-joined users. There is no
+way using this module to find out whether any non-joined guest users *do* see
+events in the room, or to list or count any lurking users.
+

specification/targets.yaml

@@ -36,6 +36,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/third_party_invites.rst
     - modules/search.rst
     - modules/guest_access.rst
+    - modules/room_previews.rst
     - modules/tags.rst
     - modules/account_data.rst
     - modules/admin.rst