Merge pull request #1142 from turt2live/travis/m.ignored_user_list

Spec ignoring users

changelogs/client_server.rst

@@ -30,6 +30,8 @@ Unreleased changes
     (`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
   - Add the room visibility options for the room directory
     (`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
+  - Add spec for ignoring users
+    (`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
 
 r0.3.0
 ======

event-schemas/examples/m.ignored_user_list

@@ -0,0 +1,8 @@
+{
+  "type": "m.ignored_user_list",
+  "content": {
+    "ignored_users": {
+      "@someone:domain.com": {}
+    }
+  }
+}

event-schemas/schema/m.ignored_user_list

@@ -0,0 +1,26 @@
+---
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  A map of users which are considered ignored is kept in ``acount_data``
+  in an event type of ``m.ignored_user_list``.
+properties:
+  content:
+    type: object
+    properties:
+      ignored_users:
+        type: object
+        patternProperties:
+          "^@":
+            type: "object"
+            title: "Ignored User"
+            description: "An empty object for future enhancement"
+            x-pattern: "$USER_ID"
+    required:
+      - ignored_users
+  type:
+    enum:
+      - m.ignored_user_list
+    type: string
+title: Ignored User List
+type: object

specification/modules/ignore_users.rst

@@ -0,0 +1,62 @@
+.. Copyright 2018 Travis Ralston
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Ignoring Users
+==============
+
+.. _module:ignore_users:
+
+With all the communication through Matrix it may be desirable to ignore a
+particular user for whatever reason. This module defines how clients and 
+servers can implement the ignoring of users.
+
+Events
+------
+
+{{m_ignored_user_list_event}}
+
+Client behaviour
+----------------
+To ignore a user, effectively blocking them, the client should add the target
+user to the ``m.ignored_user_list`` event in their account data using 
+|/user/<user_id>/account_data/<type>|_. Once ignored, the client will no longer 
+receive events sent by that user, with the exception of state events. The client 
+should either hide previous content sent by the newly ignored user or perform 
+a new ``/sync`` with no previous token.
+
+Invites to new rooms by ignored users will not be sent to the client. The server
+may optionally reject the invite on behalf of the client.
+
+State events will still be sent to the client, even if the user is ignored. 
+This is to ensure parts, such as the room name, do not appear different to the
+user just because they ignored the sender. 
+
+To remove a user from the ignored users list, remove them from the account data
+event. The server will resume sending events from the previously ignored user,
+however it should not send events that were missed while the user was ignored.
+To receive the events that were sent while the user was ignored the client 
+should perform a fresh sync. The client may also un-hide any events it previously
+hid due to the user becoming ignored.
+
+Server behaviour
+----------------
+Following an update of the ``m.ignored_user_list``, the sync API for all clients
+should immediately start ignoring (or un-ignoring) the user. Clients are responsible
+for determining if they should hide previously sent events or to start a new sync
+stream.
+
+Servers must still send state events sent by ignored users to clients.
+
+Servers must not send room invites from ignored users to clients. Servers may
+optionally decide to reject the invite, however.

specification/targets.yaml

@@ -61,6 +61,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/event_context.rst
     - modules/cas_login.rst
     - modules/dm.rst
+    - modules/ignore_users.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]