Merge pull request #2026 from matrix-org/travis/1.0/msc1452-server-notices
Add server notices supportpull/977/head
commit
bf8ca3abba
@ -0,0 +1 @@
|
|||||||
|
Add support for sending server notices to clients.
|
@ -0,0 +1,11 @@
|
|||||||
|
{
|
||||||
|
"$ref": "core/room_event.json",
|
||||||
|
"type": "m.room.message",
|
||||||
|
"content": {
|
||||||
|
"body": "Human-readable message to explain the notice",
|
||||||
|
"msgtype": "m.server_notice",
|
||||||
|
"server_notice_type": "m.server_notice.usage_limit_reached",
|
||||||
|
"admin_contact": "mailto:server.admin@example.org",
|
||||||
|
"limit_type": "monthly_active_user"
|
||||||
|
}
|
||||||
|
}
|
@ -0,0 +1,39 @@
|
|||||||
|
---
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/room_event.yaml
|
||||||
|
description: Represents a server notice for a user.
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
body:
|
||||||
|
description: A human-readable description of the notice.
|
||||||
|
type: string
|
||||||
|
msgtype:
|
||||||
|
enum:
|
||||||
|
- m.server_notice
|
||||||
|
type: string
|
||||||
|
server_notice_type:
|
||||||
|
description: |-
|
||||||
|
The type of notice being represented.
|
||||||
|
type: string
|
||||||
|
admin_contact:
|
||||||
|
description: |-
|
||||||
|
A URI giving a contact method for the server administrator. Required if the
|
||||||
|
notice type is ``m.server_notice.usage_limit_reached``.
|
||||||
|
type: string
|
||||||
|
limit_type:
|
||||||
|
description: |-
|
||||||
|
The kind of usage limit the server has exceeded. Required if the notice type is
|
||||||
|
``m.server_notice.usage_limit_reached``.
|
||||||
|
type: string
|
||||||
|
required:
|
||||||
|
- msgtype
|
||||||
|
- body
|
||||||
|
- server_notice_type
|
||||||
|
type: object
|
||||||
|
type:
|
||||||
|
enum:
|
||||||
|
- m.room.message
|
||||||
|
type: string
|
||||||
|
title: ServerNoticeMessage
|
||||||
|
type: object
|
@ -0,0 +1,78 @@
|
|||||||
|
.. Copyright 2019 The Matrix.org Foundation C.I.C.
|
||||||
|
..
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
Server Notices
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. _module:server-notices:
|
||||||
|
|
||||||
|
Homeserver hosts often want to send messages to users in an official capacity,
|
||||||
|
or have resource limits which affect a user's ability to use the homeserver.
|
||||||
|
For example, the homeserver may be limited to a certain number of active users
|
||||||
|
per month and has exceeded that limit. To communicate this failure to users,
|
||||||
|
the homeserver would use the Server Notices room.
|
||||||
|
|
||||||
|
The aesthetics of the room (name, topic, avatar, etc) are left as an implementation
|
||||||
|
detail. It is recommended that the homeserver decorate the room such that it looks
|
||||||
|
like an official room to users.
|
||||||
|
|
||||||
|
Events
|
||||||
|
------
|
||||||
|
Notices are sent to the client as normal ``m.room.message`` events with a
|
||||||
|
``msgtype`` of ``m.server_notice`` in the server notices room. Events with
|
||||||
|
a ``m.server_notice`` ``msgtype`` outside of the server notice room must
|
||||||
|
be ignored by clients.
|
||||||
|
|
||||||
|
The specified values for ``server_notice_type`` are:
|
||||||
|
|
||||||
|
:``m.server_notice.usage_limit_reached``:
|
||||||
|
The server has exceeded some limit which requires the server administrator
|
||||||
|
to intervene. The ``limit_type`` describes the kind of limit reached.
|
||||||
|
The specified values for ``limit_type`` are:
|
||||||
|
|
||||||
|
:``monthly_active_user``:
|
||||||
|
The server's number of active users in the last 30 days has exceeded the
|
||||||
|
maximum. New connections are being refused by the server. What defines
|
||||||
|
"active" is left as an implementation detail, however servers are encouraged
|
||||||
|
to treat syncing users as "active".
|
||||||
|
|
||||||
|
|
||||||
|
{{m_room_message_m_server_notice_event}}
|
||||||
|
|
||||||
|
Client behaviour
|
||||||
|
----------------
|
||||||
|
Clients can identify the server notices room by the ``m.server_notice`` tag
|
||||||
|
on the room. Active notices are represented by the `pinned events <#m-room-pinned-events>`_
|
||||||
|
in the server notices room. Server notice events pinned in that room should
|
||||||
|
be shown to the user through special UI and not through the normal pinned
|
||||||
|
events interface in the client. For example, clients may show warning banners
|
||||||
|
or bring up dialogs to get the user's attention. Events which are not server
|
||||||
|
notice events and are pinned in the server notices room should be shown just
|
||||||
|
like any other pinned event in a room.
|
||||||
|
|
||||||
|
The client must not expect to be able to reject an invite to join the server
|
||||||
|
notices room. Attempting to reject the invite must result in a
|
||||||
|
``M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`` error. Servers should not prevent the user
|
||||||
|
leaving the room after joining the server notices room, however the same error
|
||||||
|
code must be used if the server will prevent leaving the room.
|
||||||
|
|
||||||
|
Server behaviour
|
||||||
|
----------------
|
||||||
|
Servers should manage exactly 1 server notices room per user. Servers must
|
||||||
|
identify this room to clients with the ``m.server_notice`` tag. Servers should
|
||||||
|
invite the target user rather than automatically join them to the server notice
|
||||||
|
room.
|
||||||
|
|
||||||
|
How servers send notices to clients, and which user they use to send the events,
|
||||||
|
is left as an implementation detail for the server.
|
Loading…
Reference in New Issue