79 lines
3.4 KiB
ReStructuredText
79 lines
3.4 KiB
ReStructuredText
.. 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.
|