Merge pull request #28 from matrix-org/history_visibility

Document m.room.history_visibility

event-schemas/examples/v1/m.room.history_visibility

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "history_visibility": "shared"
+  },
+  "state_key": "",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.history_visibility",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/schema/v1/m.room.history_visibility

@@ -0,0 +1,31 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "title": "Controls visibility of history.",
+    "description": "This event controls whether a member of a room can see the events that happened in a room from before they joined.",
+    "allOf": [{
+        "$ref": "core#/definitions/state_event"
+    }],
+    "properties": {
+        "content": {
+            "type": "object",
+            "properties": {
+                "history_visibility": {
+                    "type": "string",
+                    "description": "Who can see the room history.",
+                    "enum": ["invited","joined","shared"]
+                }
+            },
+            "required": ["history_visibility"]
+        },
+        "state_key": {
+            "type": "string",
+            "description": "A zero-length string.",
+            "pattern": "^$"
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.room.history_visibility"]
+        }
+    }
+}

specification/47_history_visibility.rst

@@ -0,0 +1,24 @@
+Room History Visibility
+=======================
+
+Whether a member of a room can see the events that happened in a room from
+before they joined the room is controlled by the ``history_visibility`` key
+of the ``m.room.history_visibility`` state event. The valid values for
+``history_visibility`` are:
+
+- ``shared``
+- ``invited``
+- ``joined``
+
+By default if no ``history_visibility`` is set it 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.
+