From e862ef60ae1b707882c6a77c1b9cdd20efb6e7a4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 3 Mar 2018 15:20:42 -0700 Subject: [PATCH 1/5] Spec ignoring users Adds https://github.com/matrix-org/matrix-doc/issues/528 Signed-off-by: Travis Ralston --- event-schemas/examples/m.ignored_user_list | 8 +++ event-schemas/schema/m.ignored_user_list | 21 ++++++++ specification/modules/ignore_users.rst | 63 ++++++++++++++++++++++ 3 files changed, 92 insertions(+) create mode 100644 event-schemas/examples/m.ignored_user_list create mode 100644 event-schemas/schema/m.ignored_user_list create mode 100644 specification/modules/ignore_users.rst diff --git a/event-schemas/examples/m.ignored_user_list b/event-schemas/examples/m.ignored_user_list new file mode 100644 index 000000000..f3a328f7f --- /dev/null +++ b/event-schemas/examples/m.ignored_user_list @@ -0,0 +1,8 @@ +{ + "type": "m.ignored_user_list", + "content": { + "ignored_users": { + "@someone:domain.com": {} + } + } +} diff --git a/event-schemas/schema/m.ignored_user_list b/event-schemas/schema/m.ignored_user_list new file mode 100644 index 000000000..dcf7b1986 --- /dev/null +++ b/event-schemas/schema/m.ignored_user_list @@ -0,0 +1,21 @@ +--- +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 + patternProperties: + "^@": + type: "object" + title: "Ignored User" + description: "An empty object for future enhancement" + x-pattern: "$USER_ID" + type: + enum: + - m.ignored_user_list + type: string +title: Ignored User List +type: object diff --git a/specification/modules/ignore_users.rst b/specification/modules/ignore_users.rst new file mode 100644 index 000000000..d25dd64ee --- /dev/null +++ b/specification/modules/ignore_users.rst @@ -0,0 +1,63 @@ +.. 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. + +Ignore 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. 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. + +Clients should be aware that split-brain + +Server behaviour +---------------- +Following an update of the ``m.ignored_user_list``, the sync API for all clients +will 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. From 1daf6af3003f9a3f55f20453304de82f3aadefa8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 3 Mar 2018 15:23:18 -0700 Subject: [PATCH 2/5] Add ignoring users to the changelog Signed-off-by: Travis Ralston --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index d86aeb63e..d24328ea1 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -19,6 +19,8 @@ Unreleased changes (`#1106 `_). - Clarify default values for some fields on the /search API (`#1109 `_). + - Add spec for ignoring users + (`#1142 `_). - Changes to the API which will be backwards-compatible for clients: From 0f7f8a8ca77a8875647c114f07075189d608f2e3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 08:59:15 -0700 Subject: [PATCH 3/5] Move the changelog entry for ignoring users Signed-off-by: Travis Ralston --- changelogs/client_server.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 55b072992..2dcda7111 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -19,8 +19,6 @@ Unreleased changes (`#1106 `_). - Clarify default values for some fields on the /search API (`#1109 `_). - - Add spec for ignoring users - (`#1142 `_). - Fix the representation of ``m.presence`` events (`#1137 `_). - Clarify that ``m.tag`` ordering is done with numbers, not strings @@ -30,6 +28,8 @@ Unreleased changes - Add 'token' parameter to /keys/query endpoint (`#1104 `_). + - Add spec for ignoring users + (`#1142 `_). r0.3.0 ====== From 331e49bd0ddb10d5c0c12ea02bbbf8b2232f56be Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 09:00:32 -0700 Subject: [PATCH 4/5] Improve the documentation of ignored users * Fix the event schema to represent the real world * Add the module to the spec targets * Remove incomplete thought from the client behaviour * Link to the account data API * Minor word choice changes Signed-off-by: Travis Ralston --- event-schemas/schema/m.ignored_user_list | 17 +++++++++++------ specification/modules/ignore_users.rst | 15 +++++++-------- specification/targets.yaml | 1 + 3 files changed, 19 insertions(+), 14 deletions(-) diff --git a/event-schemas/schema/m.ignored_user_list b/event-schemas/schema/m.ignored_user_list index dcf7b1986..79567c653 100644 --- a/event-schemas/schema/m.ignored_user_list +++ b/event-schemas/schema/m.ignored_user_list @@ -7,12 +7,17 @@ description: |- properties: content: type: object - patternProperties: - "^@": - type: "object" - title: "Ignored User" - description: "An empty object for future enhancement" - x-pattern: "$USER_ID" + 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 diff --git a/specification/modules/ignore_users.rst b/specification/modules/ignore_users.rst index d25dd64ee..56a410d13 100644 --- a/specification/modules/ignore_users.rst +++ b/specification/modules/ignore_users.rst @@ -12,7 +12,7 @@ .. See the License for the specific language governing permissions and .. limitations under the License. -Ignore Users +Ignoring Users ============== .. _module:ignore_users: @@ -29,10 +29,11 @@ Events 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. 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. +user to the ``m.ignored_user_list`` event in their account data using +|/user//account_data/|_. 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. @@ -48,12 +49,10 @@ 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. -Clients should be aware that split-brain - Server behaviour ---------------- Following an update of the ``m.ignored_user_list``, the sync API for all clients -will immediately start ignoring (or un-ignoring) the user. Clients are responsible +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. diff --git a/specification/targets.yaml b/specification/targets.yaml index 62799afeb..122904e98 100644 --- a/specification/targets.yaml +++ b/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: ["=", "-", "~", "+", "^", "`", "@", ":"] From 08356122775f684a8a5fc63ac3b620e2497d9c1a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 10:21:04 -0700 Subject: [PATCH 5/5] Represent the ignored users event correctly Signed-off-by: Travis Ralston --- event-schemas/schema/m.ignored_user_list | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/event-schemas/schema/m.ignored_user_list b/event-schemas/schema/m.ignored_user_list index 79567c653..1ea47c413 100644 --- a/event-schemas/schema/m.ignored_user_list +++ b/event-schemas/schema/m.ignored_user_list @@ -16,8 +16,8 @@ properties: title: "Ignored User" description: "An empty object for future enhancement" x-pattern: "$USER_ID" - required: - - ignored_users + required: + - ignored_users type: enum: - m.ignored_user_list