diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml index efc82578..f8dfdea5 100644 --- a/api/client-server/v1/membership.yaml +++ b/api/client-server/v1/membership.yaml @@ -52,8 +52,9 @@ paths: 403: description: |- You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are: - - The room is invite-only and the user was not invited. - - The user has been banned from the room. + + - The room is invite-only and the user was not invited. + - The user has been banned from the room. examples: application/json: |- {"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} @@ -119,10 +120,11 @@ paths: 403: description: |- You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are: - - The invitee has been banned from the room. - - The invitee is already a member of the room. - - The inviter is not currently in the room. - - The inviter's power level is insufficient to invite users to the room. + + - The invitee has been banned from the room. + - The invitee is already a member of the room. + - The inviter is not currently in the room. + - The inviter's power level is insufficient to invite users to the room. examples: application/json: |- {"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} @@ -164,13 +166,13 @@ paths: user ID, the identity server will give the user a list of pending invitations, each containing: - - The room ID to which they were invited + - The room ID to which they were invited - - The token given to the homeserver + - The token given to the homeserver - - A signature of the token, signed with the identity server's private key + - A signature of the token, signed with the identity server's private key - - The matrix user ID who invited them to the room + - The matrix user ID who invited them to the room If a token is requested from the identity server, the home server will append a ``m.room.third_party_invite`` event to the room. @@ -221,10 +223,11 @@ paths: 403: description: |- You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are: - - The invitee has been banned from the room. - - The invitee is already a member of the room. - - The inviter is not currently in the room. - - The inviter's power level is insufficient to invite users to the room. + + - The invitee has been banned from the room. + - The invitee is already a member of the room. + - The inviter is not currently in the room. + - The inviter's power level is insufficient to invite users to the room. examples: application/json: |- {"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} diff --git a/api/client-server/v2_alpha/registration.yaml b/api/client-server/v2_alpha/registration.yaml index a53d4f41..2bd86e73 100644 --- a/api/client-server/v2_alpha/registration.yaml +++ b/api/client-server/v2_alpha/registration.yaml @@ -82,9 +82,9 @@ paths: description: |- Part of the request was invalid. This may include one of the following error codes: - * ``M_USER_IN_USE`` : The desired user ID is already taken. - * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace - claimed by an application service. + * ``M_USER_IN_USE`` : The desired user ID is already taken. + * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace + claimed by an application service. These errors may be returned at any stage of the registration process, including after authentication if the requested user ID was registered diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 89b6666a..43c1ee0b 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -735,23 +735,23 @@ it to be redacted, which may include a reason. Upon receipt of a redaction event, the server should strip off any keys not in the following list: - - ``event_id`` - - ``type`` - - ``room_id`` - - ``user_id`` - - ``state_key`` - - ``prev_state`` - - ``content`` +- ``event_id`` +- ``type`` +- ``room_id`` +- ``user_id`` +- ``state_key`` +- ``prev_state`` +- ``content`` The content object should also be stripped of all keys, unless it is one of one of the following event types: - - ``m.room.member`` allows key ``membership`` - - ``m.room.create`` allows key ``creator`` - - ``m.room.join_rules`` allows key ``join_rule`` - - ``m.room.power_levels`` allows keys ``ban``, ``events``, ``events_default``, +- ``m.room.member`` allows key ``membership`` +- ``m.room.create`` allows key ``creator`` +- ``m.room.join_rules`` allows key ``join_rule`` +- ``m.room.power_levels`` allows keys ``ban``, ``events``, ``events_default``, ``kick``, ``redact``, ``state_default``, ``users``, ``users_default``. - - ``m.room.aliases`` allows key ``aliases`` +- ``m.room.aliases`` allows key ``aliases`` .. TODO Need to update m.room.power_levels to reflect new power levels formatting @@ -771,9 +771,9 @@ which serves as the root of the event graph for this room. This event also has a generate several other events in order to manage permissions in this room. This includes: - - ``m.room.power_levels`` : Sets the power levels of users and required power +- ``m.room.power_levels`` : Sets the power levels of users and required power levels for various actions within the room such as sending events. - - ``m.room.join_rules`` : Whether the room is "invite-only" or not. +- ``m.room.join_rules`` : Whether the room is "invite-only" or not. See `Room Events`_ for more information on these events. To create a room, a client has to use the the following API. @@ -847,11 +847,11 @@ Joining rooms Users need to be a member of a room in order to send and receive events in that room. There are several states in which a user may be, in relation to a room: - - Unrelated (the user cannot send or receive events in the room) - - Invited (the user has been invited to participate in the room, but is not - yet participating) - - Joined (the user can send and receive events in the room) - - Banned (the user is not allowed to join the room) +- Unrelated (the user cannot send or receive events in the room) +- Invited (the user has been invited to participate in the room, but is not + yet participating) +- Joined (the user can send and receive events in the room) +- Banned (the user is not allowed to join the room) There is an exception to the requirement that a user join a room before sending events to it: users may send an ``m.room.member`` event to a room with @@ -942,11 +942,11 @@ many places of a client's display, changes to these fields cause an automatic propagation event to occur, informing likely-interested parties of the new values. This change is conveyed using two separate mechanisms: - - a ``m.room.member`` event is sent to every room the user is a member of, - to update the ``displayname`` and ``avatar_url``. - - a ``m.presence`` presence status update is sent, again containing the new - values of the ``displayname`` and ``avatar_url`` keys, in addition to the - required ``presence`` key containing the current presence state of the user. +- a ``m.room.member`` event is sent to every room the user is a member of, + to update the ``displayname`` and ``avatar_url``. +- a ``m.presence`` presence status update is sent, again containing the new + values of the ``displayname`` and ``avatar_url`` keys, in addition to the + required ``presence`` key containing the current presence state of the user. Both of these should be done automatically by the home server when a user successfully changes their display name or avatar URL fields. diff --git a/specification/events.rst b/specification/events.rst index 0eb4d933..7d64882b 100644 --- a/specification/events.rst +++ b/specification/events.rst @@ -18,11 +18,11 @@ Size limits The total size of any event MUST NOT exceed 65 KB. There are additional restrictions on sizes per key: - - ``user_id`` MUST NOT exceed 255 bytes (including domain). - - ``room_id`` MUST NOT exceed 255 bytes. - - ``state_key`` MUST NOT exceed 255 bytes. - - ``type`` MUST NOT exceed 255 bytes. - - ``event_id`` MUST NOT exceed 255 bytes. +- ``user_id`` MUST NOT exceed 255 bytes (including domain). +- ``room_id`` MUST NOT exceed 255 bytes. +- ``state_key`` MUST NOT exceed 255 bytes. +- ``type`` MUST NOT exceed 255 bytes. +- ``event_id`` MUST NOT exceed 255 bytes. Some event types have additional size restrictions which are specified in the description of the event. Additional keys have no limit other than that diff --git a/specification/modules/content_repo.rst b/specification/modules/content_repo.rst index 52937ead..29dae059 100644 --- a/specification/modules/content_repo.rst +++ b/specification/modules/content_repo.rst @@ -64,21 +64,20 @@ UTF-8 encoded traversals, etc). Homeservers have additional content-specific concerns: - - Clients may try to upload very large files. Homeservers should not store files - that are too large and should not serve them to clients. +- Clients may try to upload very large files. Homeservers should not store files + that are too large and should not serve them to clients. - - Clients may try to upload very large images. Homeservers should not attempt to - generate thumbnails for images that are too large. +- Clients may try to upload very large images. Homeservers should not attempt to + generate thumbnails for images that are too large. - - Remote homeservers may host very large files or images. Homeservers should not - proxy or thumbnail large files or images from remote homeservers. +- Remote homeservers may host very large files or images. Homeservers should not + proxy or thumbnail large files or images from remote homeservers. - - Clients may try to upload a large number of files. Homeservers should limit the - number and total size of media that can be uploaded by clients. +- Clients may try to upload a large number of files. Homeservers should limit the + number and total size of media that can be uploaded by clients. - - Clients may try to access a large number of remote files through a homeserver. - Homeservers should restrict the number and size of remote files that it caches. - - - Clients or remote homeservers may try to upload malicious files targeting - vulnerabilities in either the homeserver thumbnailing or the client decoders. +- Clients may try to access a large number of remote files through a homeserver. + Homeservers should restrict the number and size of remote files that it caches. +- Clients or remote homeservers may try to upload malicious files targeting + vulnerabilities in either the homeserver thumbnailing or the client decoders. diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 79151c4f..3602d105 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -5,10 +5,10 @@ Presence Each user has the concept of presence information. This encodes: - * Whether the user is currently online - * How recently the user was last active (as seen by the server) - * Whether a given client considers the user to be currently idle - * Arbitrary information about the user's current status (e.g. "in a meeting"). +* Whether the user is currently online +* How recently the user was last active (as seen by the server) +* Whether a given client considers the user to be currently idle +* Arbitrary information about the user's current status (e.g. "in a meeting"). This information is collated from both per-device (``online``, ``idle``, ``last_active``) and per-user (status) data, aggregated by the user's homeserver @@ -24,14 +24,14 @@ who must accept the invitation. User's presence state is represented by the ``presence`` key, which is an enum of one of the following: - - ``online`` : The default state when the user is connected to an event - stream. - - ``unavailable`` : The user is not reachable at this time e.g. they are - idle. - - ``offline`` : The user is not connected to an event stream or is - explicitly suppressing their profile information from being sent. - - ``free_for_chat`` : The user is generally willing to receive messages - moreso than default. +- ``online`` : The default state when the user is connected to an event + stream. +- ``unavailable`` : The user is not reachable at this time e.g. they are + idle. +- ``offline`` : The user is not connected to an event stream or is + explicitly suppressing their profile information from being sent. +- ``free_for_chat`` : The user is generally willing to receive messages + moreso than default. Events ------ @@ -94,10 +94,10 @@ pro-active event from the user. A pro-active event may be sending a message to a room or changing presence state to a higher level of availability. Levels of availability are defined from low to high as follows: - - ``offline`` - - ``unavailable`` - - ``online`` - - ``free_for_chat`` +- ``offline`` +- ``unavailable`` +- ``online`` +- ``free_for_chat`` Based on this list, changing state from ``unavailable`` to ``online`` counts as a pro-active event, whereas ``online`` to ``unavailable`` does not. This diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 525e730d..893e9481 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -37,19 +37,19 @@ The above diagram shows the flow of push notifications being sent to a handset where push notifications are submitted via the handset vendor, such as Apple's APNS or Google's GCM. This happens as follows: - 1. The client app signs in to a homeserver. - 2. The client app registers with its vendor's Push Provider and - obtains a routing token of some kind. - 3. The mobile app uses the Client/Server API to add a 'pusher', providing the - URL of a specific Push Gateway which is configured for that - application. It also provides the routing token it has acquired from the - Push Provider. - 4. The homeserver starts sending HTTP requests to the Push Gateway using the - supplied URL. The Push Gateway relays this notification to - the Push Provider, passing the routing token along with any - necessary private credentials the provider requires to send push - notifications. - 5. The Push Provider sends the notification to the device. +1. The client app signs in to a homeserver. +2. The client app registers with its vendor's Push Provider and + obtains a routing token of some kind. +3. The mobile app uses the Client/Server API to add a 'pusher', providing the + URL of a specific Push Gateway which is configured for that + application. It also provides the routing token it has acquired from the + Push Provider. +4. The homeserver starts sending HTTP requests to the Push Gateway using the + supplied URL. The Push Gateway relays this notification to + the Push Provider, passing the routing token along with any + necessary private credentials the provider requires to send push + notifications. +5. The Push Provider sends the notification to the device. Definitions for terms used in this section are below: @@ -127,16 +127,16 @@ affect delivery of notifications via pushers with a matching ``profile_tag``. All device-specific rules have a higher priority than global rules. This means that the full list of rule kinds, in descending priority order, is as follows: - * Device-specific Override - * Device-specific Content - * Device-specific Room - * Device-specific Sender - * Device-specific Underride - * Global Override - * Global Content - * Global Room - * Global Sender - * Global Underride +* Device-specific Override +* Device-specific Content +* Device-specific Room +* Device-specific Sender +* Device-specific Underride +* Global Override +* Global Content +* Global Room +* Global Sender +* Global Underride Rules with the same ``kind`` can specify an ordering priority. This determines which rule is selected in the event of multiple matches. For example, a rule @@ -315,16 +315,17 @@ rule determines its behaviour. The following conditions are defined: ``event_match`` This is a glob pattern match on a field of the event. Parameters: - * ``key``: The dot-separated field of the event to match, e.g. ``content.body`` - * ``pattern``: The glob-style pattern to match against. Patterns with no - special glob characters should be treated as having asterisks - prepended and appended when testing the condition. + + * ``key``: The dot-separated field of the event to match, e.g. ``content.body`` + * ``pattern``: The glob-style pattern to match against. Patterns with no + special glob characters should be treated as having asterisks + prepended and appended when testing the condition. ``profile_tag`` Matches the ``profile_tag`` of the device that the notification would be delivered to. Parameters: - * ``profile_tag``: The profile_tag to match with. + * ``profile_tag``: The profile_tag to match with. ``contains_display_name`` This matches unencrypted messages where ``content.body`` contains the owner's @@ -334,10 +335,11 @@ rule determines its behaviour. The following conditions are defined: ``room_member_count`` This matches the current number of members in the room. Parameters: - * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``, - ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member - count is strictly less than the given number and so forth. If no prefix is - present, this parameter defaults to ``==``. + + * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``, + ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member + count is strictly less than the given number and so forth. If no prefix is + present, this parameter defaults to ``==``. Push Rules: API ~~~~~~~~~~~~~~~ @@ -418,12 +420,12 @@ client app and its' push gateway to agree on. As APNS requires that the sender has a private key owned by the app developer, each app must have its own push gateway. It is recommended that: - * The APNS token be base64 encoded and used as the pushkey. - * A different app_id be used for apps on the production and sandbox - APS environments. - * APNS push gateways do not attempt to wait for errors from the APNS - gateway before returning and instead to store failures and return - 'rejected' responses next time that pushkey is used. +* The APNS token be base64 encoded and used as the pushkey. +* A different app_id be used for apps on the production and sandbox + APS environments. +* APNS push gateways do not attempt to wait for errors from the APNS + gateway before returning and instead to store failures and return + 'rejected' responses next time that pushkey is used. Security considerations ----------------------- diff --git a/specification/modules/voip_events.rst b/specification/modules/voip_events.rst index a7b02538..6945a09e 100644 --- a/specification/modules/voip_events.rst +++ b/specification/modules/voip_events.rst @@ -62,19 +62,19 @@ As calls are "placed" to rooms rather than users, the glare resolution algorithm outlined below is only considered for calls which are to the same room. The algorithm is as follows: - - If an ``m.call.invite`` to a room is received whilst the client is - **preparing to send** an ``m.call.invite`` to the same room: +- If an ``m.call.invite`` to a room is received whilst the client is + **preparing to send** an ``m.call.invite`` to the same room: - * the client should cancel its outgoing call and instead - automatically accept the incoming call on behalf of the user. + * the client should cancel its outgoing call and instead + automatically accept the incoming call on behalf of the user. - - If an ``m.call.invite`` to a room is received **after the client has sent** - an ``m.call.invite`` to the same room and is waiting for a response: +- If an ``m.call.invite`` to a room is received **after the client has sent** + an ``m.call.invite`` to the same room and is waiting for a response: - * the client should perform a lexicographical comparison of the call IDs of - the two calls and use the *lesser* of the two calls, aborting the - greater. If the incoming call is the lesser, the client should accept - this call on behalf of the user. + * the client should perform a lexicographical comparison of the call IDs of + the two calls and use the *lesser* of the two calls, aborting the + greater. If the incoming call is the lesser, the client should accept + this call on behalf of the user. The call setup should appear seamless to the user as if they had simply placed