diff --git a/specification/00_basis.rst b/specification/00_basis.rst index 8f27f505..9e7ae8ed 100644 --- a/specification/00_basis.rst +++ b/specification/00_basis.rst @@ -12,7 +12,7 @@ WARNING We're publishing it at this point because it's complete enough to be more than useful and provide a canonical reference to how Matrix is evolving. Our end - goal is to mirror WHATWG's `Living Standard `_ + goal is to mirror WHATWG's `Living Standard `_ approach except right now Matrix is more in the process of being born than actually being living! @@ -153,7 +153,7 @@ domain, it is simply for globally namespacing room IDs. The room does NOT reside on the domain specified. Room IDs are not meant to be human readable. They ARE case-sensitive. -The following diagram shows an ``m.room.message`` event being sent in the room +The following diagram shows an ``m.room.message`` event being sent in the room ``!qporfwt:matrix.org``:: { @alice:matrix.org } { @bob:domain.com } @@ -207,7 +207,7 @@ that are in the room that can be used to join via. :: - GET + GET #matrix:domain.com !aaabaa:matrix.org | ^ | | @@ -218,7 +218,7 @@ that are in the room that can be used to join via. | #golf >> !wfeiofh:sport.com | | #bike >> !4rguxf:matrix.org | |________________________________| - + Identity ~~~~~~~~ @@ -456,7 +456,7 @@ State Resolution ++++++++++++++++ A given state section may have multiple state events associated with it in a given graph. A consistent method of selecting which state event takes -precedence is therefore required. +precedence is therefore required. This is done by taking the latest state events, i.e. the set of events that are either incomparable or after every other event in the graph. A state resolution @@ -530,7 +530,7 @@ codes should have their namespace first in ALL CAPS, followed by a single _. For example, if there was a custom namespace ``com.mydomain.here``, and a ``FORBIDDEN`` code, the error code should look like ``COM.MYDOMAIN.HERE_FORBIDDEN``. There may be additional keys depending on the -error, but the keys ``error`` and ``errcode`` MUST always be present. +error, but the keys ``error`` and ``errcode`` MUST always be present. Some standard error codes are below: diff --git a/specification/10_events.rst b/specification/10_events.rst index b9723bd4..3b9c8e03 100644 --- a/specification/10_events.rst +++ b/specification/10_events.rst @@ -79,7 +79,7 @@ State events have the additional fields: Description: Optional. Contains the previous ``content`` for this event. If there is no previous content, this key will be missing. - + .. TODO-spec How do "age" and "ts" fit in to all this? Which do we expose? @@ -95,7 +95,7 @@ prefixed with ``m.`` ``m.room.name`` Summary: Set the human-readable name for the room. - Type: + Type: State event JSON format: ``{ "name" : "string" }`` @@ -112,7 +112,7 @@ prefixed with ``m.`` ``m.room.topic`` Summary: Set a topic for the room. - Type: + Type: State event JSON format: ``{ "topic" : "string" }`` @@ -128,7 +128,7 @@ prefixed with ``m.`` ``m.room.member`` Summary: The current membership state of a user in the room. - Type: + Type: State event JSON format: ``{ "membership" : "enum[ invite|join|leave|ban ]" }`` @@ -145,20 +145,20 @@ prefixed with ``m.`` ``m.room.create`` Summary: The first event in the room. - Type: + Type: State event JSON format: ``{ "creator": "string"}`` Example: ``{ "creator": "@user:example.com" }`` Description: - This is the first event in a room and cannot be changed. It acts as the + This is the first event in a room and cannot be changed. It acts as the root of all other events. ``m.room.join_rules`` Summary: Descripes how/if people are allowed to join. - Type: + Type: State event JSON format: ``{ "join_rule": "enum [ public|knock|invite|private ]" }`` @@ -166,55 +166,55 @@ prefixed with ``m.`` ``{ "join_rule": "public" }`` Description: TODO-doc : Use docs/models/rooms.rst - + ``m.room.power_levels`` Summary: Defines the power levels of users in the room. - Type: + Type: State event JSON format: ``{ "": , ..., "default": }`` Example: - ``{ "@user:example.com": 5, "@user2:example.com": 10, "default": 0 }`` + ``{ "@user:example.com": 5, "@user2:example.com": 10, "default": 0 }`` Description: - If a user is in the list, then they have the associated power level. + If a user is in the list, then they have the associated power level. Otherwise they have the default level. If not ``default`` key is supplied, it is assumed to be 0. ``m.room.add_state_level`` Summary: Defines the minimum power level a user needs to add state. - Type: + Type: State event JSON format: ``{ "level": }`` Example: ``{ "level": 5 }`` Description: - To add a new piece of state to the room a user must have the given power + To add a new piece of state to the room a user must have the given power level. This does not apply to updating current state, which is goverened by the ``required_power_level`` event key. - + ``m.room.send_event_level`` Summary: Defines the minimum power level a user needs to send an event. - Type: + Type: State event JSON format: ``{ "level": }`` Example: ``{ "level": 0 }`` Description: - To send a new event into the room a user must have at least this power + To send a new event into the room a user must have at least this power level. This allows ops to make the room read only by increasing this level, or muting individual users by lowering their power level below this threshold. ``m.room.ops_levels`` Summary: - Defines the minimum power levels that a user must have before they can + Defines the minimum power levels that a user must have before they can kick and/or ban other users. - Type: + Type: State event JSON format: ``{ "ban_level": , "kick_level": , "redact_level": }`` @@ -222,7 +222,7 @@ prefixed with ``m.`` ``{ "ban_level": 5, "kick_level": 5 }`` Description: This defines who can ban and/or kick people in the room. Most of the time - ``ban_level`` will be greater than or equal to ``kick_level`` since + ``ban_level`` will be greater than or equal to ``kick_level`` since banning is more severe than kicking. ``m.room.aliases`` @@ -266,7 +266,7 @@ prefixed with ``m.`` ``m.room.message`` Summary: A message. - Type: + Type: Non-state event JSON format: ``{ "msgtype": "string" }`` @@ -283,7 +283,7 @@ prefixed with ``m.`` ``m.room.message.feedback`` Summary: A receipt for a message. - Type: + Type: Non-state event JSON format: ``{ "type": "enum [ delivered|read ]", "target_event_id": "string" }`` @@ -294,7 +294,7 @@ prefixed with ``m.`` are two supported acknowledgements: ``delivered`` (sent when the event has been received) and ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` should reference the ``m.room.message`` - event being acknowledged. + event being acknowledged. ``m.room.redaction`` Summary: @@ -352,10 +352,10 @@ outlined below: - ``body`` : "string" - The alt text of the image, or some kind of content description for accessibility e.g. "image attachment". - ImageInfo: + ImageInfo: Information about an image:: - - { + + { "size" : integer (size of image in bytes), "w" : integer (width of image in pixels), "h" : integer (height of image in pixels), @@ -371,7 +371,7 @@ outlined below: - ``body`` : "string" - A description of the audio e.g. "Bee Gees - Stayin' Alive", or some kind of content description for accessibility e.g. "audio attachment". - AudioInfo: + AudioInfo: Information about a piece of audio:: { @@ -390,7 +390,7 @@ outlined below: some kind of content description for accessibility e.g. "video attachment". - VideoInfo: + VideoInfo: Information about a video:: { @@ -466,7 +466,7 @@ This event is sent by the caller when they wish to establish a call. valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI. - + Optional keys: None. Example: @@ -537,7 +537,7 @@ A call is set up with messages exchanged as follows: <------ m.call.answer [...] <------ m.call.hangup - + Or a rejected call: :: diff --git a/specification/20_client_server_api.rst b/specification/20_client_server_api.rst index f45eac39..42dd9427 100644 --- a/specification/20_client_server_api.rst +++ b/specification/20_client_server_api.rst @@ -89,9 +89,9 @@ This specification defines the following login types: Password-based ~~~~~~~~~~~~~~ -:Type: +:Type: ``m.login.password`` -:Description: +:Description: Login is supported via a username and password. To respond to this type, reply with:: @@ -107,10 +107,10 @@ login process, or a standard error response. Captcha-based ~~~~~~~~~~~~~ -:Type: +:Type: ``m.login.recaptcha`` -:Description: - Login is supported by responding to a captcha (in the case of the Synapse +:Description: + Login is supported by responding to a captcha (in the case of the Synapse implementation, Google's Recaptcha library is used). To respond to this type, reply with:: @@ -131,7 +131,7 @@ login process, or a standard error response. OAuth2-based ~~~~~~~~~~~~ -:Type: +:Type: ``m.login.oauth2`` :Description: Login is supported via OAuth2 URLs. This login consists of multiple requests. @@ -154,7 +154,7 @@ the uri is a ``sevice selection URI``, it MUST point to a webpage which prompts the user to choose which service to authorize with. On selection of a service, this MUST link through to an ``Authorization Request URI``. If there is only 1 service which the home server accepts when logging in, this indirection can be -skipped and the "uri" key can be the ``Authorization Request URI``. +skipped and the "uri" key can be the ``Authorization Request URI``. The client then visits the ``Authorization Request URI``, which then shows the OAuth2 Allow/Deny prompt. Hitting 'Allow' returns the ``redirect URI`` with the @@ -165,8 +165,8 @@ When the home server gets this access token, it verifies that the cilent has authorised with the 3rd party, and can now complete the login. The OAuth2 ``redirect URI`` (with auth code) MUST respond with either new credentials, the next stage of the login process, or a standard error response. - -For example, if a home server accepts OAuth2 from Google, it would return the + +For example, if a home server accepts OAuth2 from Google, it would return the Authorization Request URI for Google:: { @@ -184,10 +184,10 @@ visits the REDIRECT_URI with the auth code= query parameter which returns:: Email-based (code) ~~~~~~~~~~~~~~~~~~ -:Type: +:Type: ``m.login.email.code`` :Description: - Login is supported by typing in a code which is sent in an email. This login + Login is supported by typing in a code which is sent in an email. This login consists of multiple requests. To respond to this type, reply with:: @@ -220,10 +220,10 @@ stage of the login process, or a standard error response. Email-based (url) ~~~~~~~~~~~~~~~~~ -:Type: +:Type: ``m.login.email.url`` :Description: - Login is supported by clicking on a URL in an email. This login consists of + Login is supported by clicking on a URL in an email. This login consists of multiple requests. To respond to this type, reply with:: @@ -251,7 +251,7 @@ client should perform another request:: } The home server MUST respond to this with either new credentials, the next -stage of the login process, or a standard error response. +stage of the login process, or a standard error response. A common client implementation will be to periodically poll until the link is clicked. If the link has not been visited yet, a standard error response with @@ -296,7 +296,7 @@ of a previous login stage:: "next": "" } -If a home server implements N-factor authentication, it MUST respond with all +If a home server implements N-factor authentication, it MUST respond with all ``stages`` when initially queried for their login requirements:: { @@ -311,7 +311,7 @@ This can be represented conceptually as:: | type: "" | | ___________________ | | |_Request_1_________| | <-- Returns "session" key which is used throughout. - | ___________________ | + | ___________________ | | |_Request_2_________| | <-- Returns a "next" value of "login type2" |_______________________| | @@ -355,9 +355,9 @@ To create a room, a client has to use the |createRoom|_ API. There are various options which can be set when creating a room: ``visibility`` - Type: + Type: String - Optional: + Optional: Yes Value: Either ``public`` or ``private``. @@ -367,9 +367,9 @@ options which can be set when creating a room: list. Rooms default to ``private`` visibility if this key is not included. ``room_alias_name`` - Type: + Type: String - Optional: + Optional: Yes Value: The room alias localpart. @@ -379,9 +379,9 @@ options which can be set when creating a room: the room, e.g. ``!qadnasoi:domain.com >>> #room_alias_name:domain.com`` ``name`` - Type: + Type: String - Optional: + Optional: Yes Value: The ``name`` value for the ``m.room.name`` state event. @@ -391,9 +391,9 @@ options which can be set when creating a room: ``m.room.name``. ``topic`` - Type: + Type: String - Optional: + Optional: Yes Value: The ``topic`` value for the ``m.room.topic`` state event. @@ -416,7 +416,7 @@ options which can be set when creating a room: Example:: { - "visibility": "public", + "visibility": "public", "room_alias_name": "thepub", "name": "The Grand Duke Pub", "topic": "All about happy hour" @@ -462,7 +462,7 @@ send update requests to other servers. Rooms store a *partial* list of room aliases via the ``m.room.aliases`` state event. This alias list is partial because it cannot guarantee that the alias -list is in any way accurate or up-to-date, as room aliases can point to +list is in any way accurate or up-to-date, as room aliases can point to different room IDs over time. Crucially, the aliases in this event are **purely informational** and SHOULD NOT be treated as accurate. They SHOULD be checked before they are used or shared with another user. If a room @@ -470,7 +470,7 @@ appears to have a room alias of ``#alias:example.com``, this SHOULD be checked to make sure that the room's ID matches the ``room_id`` returned from the request. -Room aliases can be checked in the same way they are resolved; by sending a +Room aliases can be checked in the same way they are resolved; by sending a ``GET /directory/room/``:: { @@ -489,7 +489,7 @@ Permissions Permissions for rooms are done via the concept of power levels - to do any action in a room a user must have a suitable power level. Power levels are -stored as state events in a given room. +stored as state events in a given room. Power levels for users are defined in ``m.room.power_levels``, where both a default and specific users' power levels can be set:: @@ -503,7 +503,7 @@ default and specific users' power levels can be set:: By default all users have a power level of 0, other than the room creator whose power level defaults to 100. Users can grant other users increased power levels up to their own power level. For example, user A with a power level of 50 could -increase the power level of user B to a maximum of level 50. Power levels for +increase the power level of user B to a maximum of level 50. Power levels for users are tracked per-room even if the user is not present in the room. State events may contain a ``required_power_level`` key, which indicates the @@ -514,11 +514,11 @@ to update state events in that room. To perform certain actions there are additional power level requirements defined in the following state events: -- ``m.room.send_event_level`` defines the minimum ``level`` for sending +- ``m.room.send_event_level`` defines the minimum ``level`` for sending non-state events. Defaults to 50. -- ``m.room.add_state_level`` defines the minimum ``level`` for adding new +- ``m.room.add_state_level`` defines the minimum ``level`` for adding new state, rather than updating existing state. Defaults to 50. -- ``m.room.ops_level`` defines the minimum ``ban_level`` and ``kick_level`` to +- ``m.room.ops_level`` defines the minimum ``ban_level`` and ``kick_level`` to ban and kick other users respectively. This defaults to a kick and ban levels of 50 each. @@ -563,7 +563,7 @@ received an invite. Inviting users ~~~~~~~~~~~~~~ -.. TODO-doc Invite-join dance +.. TODO-doc Invite-join dance - Outline invite join dance. What is it? Why is it required? How does it work? - What does the home server have to do? @@ -590,8 +590,8 @@ entire invitation process:: "user_id": "" } -Alternatively, the membership state for this user in this room can be modified -directly by sending the following request to +Alternatively, the membership state for this user in this room can be modified +directly by sending the following request to ``/rooms//state/m.room.member/``:: { @@ -620,8 +620,8 @@ the room. To leave a room, a request should be made to {} -Alternatively, the membership state for this user in this room can be modified -directly by sending the following request to +Alternatively, the membership state for this user in this room can be modified +directly by sending the following request to ``/rooms//state/m.room.member/``:: { @@ -633,7 +633,7 @@ See the `Room events`_ section for more information on ``m.room.member``. Once a user has left a room, that room will no longer appear on the |initialSync|_ API. -If all members in a room leave, that room becomes eligible for deletion. +If all members in a room leave, that room becomes eligible for deletion. Banning users in a room ~~~~~~~~~~~~~~~~~~~~~~~ @@ -648,7 +648,7 @@ to |/rooms//ban|_ with:: "user_id": "" } - + Banning a user adjusts the banned member's membership state to ``ban`` and adjusts the power level of this event to a level higher than the banned person. Like with other membership changes, a user can directly adjust the target @@ -842,7 +842,7 @@ There are several APIs provided to ``GET`` events for a room: ``{ "start": "", "end": "" }`` Example: TODO-doc - + |/rooms//initialSync|_ Description: Get all relevant events for a room. This includes state events, paginated diff --git a/specification/30_server_server_api.rst b/specification/30_server_server_api.rst index 44c796ae..a57a30e5 100644 --- a/specification/30_server_server_api.rst +++ b/specification/30_server_server_api.rst @@ -56,26 +56,26 @@ Each transaction has: - A list of "previous IDs". - A list of PDUs and EDUs - the actual message payload that the Transaction carries. - + ``origin`` - Type: + Type: String Description: DNS name of homeserver making this transaction. - + ``ts`` - Type: + Type: Integer Description: - Timestamp in milliseconds on originating homeserver when this transaction + Timestamp in milliseconds on originating homeserver when this transaction started. - + ``previous_ids`` Type: List of strings Description: List of transactions that were sent immediately prior to this transaction. - + ``pdus`` Type: List of Objects. @@ -125,13 +125,13 @@ All PDUs have: String Description: Event context identifier - + ``origin`` Type: String Description: DNS name of homeserver that created this PDU. - + ``pdu_id`` Type: String @@ -176,19 +176,19 @@ For state updates: Boolean Description: True if this PDU is updating state. - + ``state_key`` Type: String Description: Optional key identifying the updated state within the context. - + ``power_level`` Type: Integer Description: The asserted power level of the user performing the update. - + ``required_power_level`` Type: Integer @@ -200,13 +200,13 @@ For state updates: String Description: PDU event type. - + ``prev_state_origin`` Type: String Description: The PDU id of the update this replaces. - + ``user_id`` Type: String @@ -262,8 +262,8 @@ destination home server names, and the actual nested content. "origin":"blue", "destination":"orange", "content":...} - - + + Protocol URLs ------------- .. WARNING:: @@ -291,7 +291,7 @@ To fetch a particular PDU:: Retrieves a given PDU from the server. The response will contain a single new Transaction, inside which will be the requested PDU. - + To fetch all the state of a given context::