diff --git a/api/client-server/guest_events.yaml b/api/client-server/peeking_events.yaml similarity index 88% rename from api/client-server/guest_events.yaml rename to api/client-server/peeking_events.yaml index 146a5335..f3f9e872 100644 --- a/api/client-server/guest_events.yaml +++ b/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. diff --git a/specification/modules/guest_access.rst b/specification/modules/guest_access.rst index 1325abe8..31cfd35d 100644 --- a/specification/modules/guest_access.rst +++ b/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. diff --git a/specification/modules/room_previews.rst b/specification/modules/room_previews.rst new file mode 100644 index 00000000..a27c7fb7 --- /dev/null +++ b/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. + diff --git a/specification/targets.yaml b/specification/targets.yaml index 98ca9322..bf2d8f11 100644 --- a/specification/targets.yaml +++ b/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