From b59d16c4d126cab96b2a765c98dca2a431c7eb2a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 6 Apr 2016 17:54:56 +0100 Subject: [PATCH] Clarify `history_visibility` behaviour Clear up some lies in the history_visibility section, and clarify behaviour for `m.room.history_visibility` and the user's own `m.room.member` events. --- changelogs/client_server.rst | 3 +- specification/modules/history_visibility.rst | 43 +++++++++++++------- 2 files changed, 31 insertions(+), 15 deletions(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 4e44de9e..adbdfb30 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -1,8 +1,9 @@ ============== -No changes yet. +- Spec clarifications: + - Clarify the behaviour of the "Room History Visibility" module; in particular, the behaviour of the ``shared`` history visibilty, and how events at visibility boundaries should be handled. r0.0.1 ====== diff --git a/specification/modules/history_visibility.rst b/specification/modules/history_visibility.rst index 112e2e21..df592bfa 100644 --- a/specification/modules/history_visibility.rst +++ b/specification/modules/history_visibility.rst @@ -9,24 +9,24 @@ room. In all cases except ``world_readable``, a user needs to join a room to view events in that room. Once they have joined a room, they will gain access to a subset of events in the room. How this subset is chosen is controlled by the ``m.room.history_visibility`` event -outlined below. After a user has left a room, they may seen any events which they +outlined below. After a user has left a room, they may see any events which they were allowed to see before they left the room, but no events received after they left. The four options for the ``m.room.history_visibility`` event are: +- ``world_readable`` - All events while this is the + ``m.room.history_visibility`` value may be shared by any participating + homeserver with anyone, regardless of whether they have ever joined the room. - ``shared`` - Previous events are always accessible to newly joined members. All events in the room are accessible, even those sent when the member was not a part of the room. -- ``invited`` - Previous events are accessible to newly joined members from the point +- ``invited`` - Events are accessible to newly joined members from the point they were invited onwards. Events stop being accessible when the member's state changes to something other than ``invite`` or ``join``. -- ``joined`` - Previous events are accessible to newly joined members from the point +- ``joined`` - Events are accessible to newly joined members from the point they joined the room onwards. Events stop being accessible when the member's state changes to something other than ``join``. -- ``world_readable`` - All events while this is the ``m.room.history_visibility`` value - may be shared by any participating homeserver with anyone, regardless of whether - they have ever joined the room. .. WARNING:: These options are applied at the point an event is *sent*. Checks are @@ -54,14 +54,29 @@ Server behaviour By default if no ``history_visibility`` is set, or if the value is not understood, the visibility is assumed to be ``shared``. The rules governing whether a user is allowed to see an event depend -solely on the state of the room *at that event*: - -1. If the user was joined, allow. -2. If the user was invited and the ``history_visibility`` was set to - ``invited`` or ``shared``, allow. -3. If the user was neither invited nor joined but the ``history_visibility`` - was set to ``shared``, allow. -4. Otherwise, deny. +on the state of the room *at that event*. + +1. If the ``history_visibility`` was set to ``world_readable``, allow. +2. If the user's ``membership`` was ``join``, allow. +3. If ``history_visibility`` was set to ``shared``, and the user joined the + room at any point after the event was sent, allow. +4. If the user's ``membership`` was ``invite``, and the ``history_visibility`` + was set to ``invited``, allow. +5. Otherwise, deny. + +For ``m.room.history_visibility`` events themselves, the user should be allowed +to see the event if the ``history_visibility`` before *or* after the event +would allow them to see it. (For example, a user should be able to see +``m.room.history_visibility`` events which change the ``history_visibility`` +from ``world_readable`` to ``joined`` *or* from ``joineded`` to +``world_readable``, even if that user was not a member of the room.) + +Likewise, for the user's own ``m.room.member`` events, the user should be +allowed to see the event if their ``membership`` before *or* after the event +would allow them to see it. (For example, a user can always see +``m.room.member`` events which set their membership to ``join``, or which +change their membership from ``join`` to any other value, even if +``history_visibility`` is ``joined``.) Security considerations -----------------------