Split room previews into a separate module

Guest access and room peeking are orthogonal
pull/276/head
Richard van der Hoff 9 years ago
parent 193e05275b
commit 68a4306773

@ -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.

@ -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.

@ -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.

@ -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

Loading…
Cancel
Save