Merge pull request #123 from matrix-org/markjh/list_formatting

Fix list formatting
pull/977/head
Mark Haines 9 years ago
commit 1d7cb6937f

@ -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"}

@ -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

@ -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.

@ -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

@ -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.

@ -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

@ -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
-----------------------

@ -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

Loading…
Cancel
Save