Merge branch 'master' into module-presence

scripts/nature.css

@@ -244,10 +244,6 @@ div.viewcode-block:target {
     border-bottom: 1px solid #ac9;
 }
 
-p {
-	margin: 0;
-}
-
 ul li dd {
 	margin-top: 0;
 }

specification/0-intro.rst

@@ -24,7 +24,6 @@ Introduction
   The Matrix specification is still evolving: the APIs are not yet frozen
   and this document is in places a work in progress or stale. We have made every 
   effort to clearly flag areas which are still being finalised.
-
   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   
@@ -34,10 +33,9 @@ Matrix is a set of open APIs for open-federated Instant Messaging (IM), Voice
 over IP (VoIP) and Internet of Things (IoT) communication, designed to create
 and support a new global real-time communication ecosystem. The intention is to
 provide an open decentralised pubsub layer for the internet for securely
-persisting and publishing/subscribing JSON objects.
+persisting and publishing/subscribing JSON objects. This specification is the
-
+ongoing result of standardising the APIs used by the various components of the
-This specification is the ongoing result of standardising the APIs used by the
+Matrix ecosystem to communicate with one another.
-various components of the Matrix ecosystem to communicate with one another.
 
 The principles that Matrix attempts to follow are:
 
@@ -214,10 +212,8 @@ which have the form::
 There is exactly one room ID for each room. Whilst the room ID does contain a
 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.
+They are case-sensitive. The following conceptual diagram shows an
-
+``m.room.message`` event being sent to the room ``!qporfwt:matrix.org``::
-The following conceptual diagram shows an ``m.room.message`` event being sent to 
-the room ``!qporfwt:matrix.org``::
 
        { @alice:matrix.org }                             { @bob:domain.com }
                |                                                 ^
@@ -258,28 +254,28 @@ the room ``!qporfwt:matrix.org``::
 Federation maintains *shared data structures* per-room between multiple home
 servers. The data is split into ``message events`` and ``state events``.
 
-``Message events`` describe transient 'once-off' activity in a room such as an
+Message events: 
-instant messages, VoIP call setups, file transfers, etc. They generally describe
+  These describe transient 'once-off' activity in a room such as an
-communication activity.
+  instant messages, VoIP call setups, file transfers, etc. They generally
+  describe communication activity.
 
-``State events`` describe updates to a given piece of persistent information
+State events:
-('state') related to a room, such as the room's name, topic, membership,
+  These describe updates to a given piece of persistent information
-participating servers, etc. State is modelled as a lookup table of key/value
+  ('state') related to a room, such as the room's name, topic, membership,
-pairs per room, with each key being a tuple of ``state_key`` and ``event type``.
+  participating servers, etc. State is modelled as a lookup table of key/value
-Each state event updates the value of a given key.
+  pairs per room, with each key being a tuple of ``state_key`` and ``event type``.
+  Each state event updates the value of a given key.
 
 The state of the room at a given point is calculated by considering all events
 preceding and including a given event in the graph. Where events describe the
 same state, a merge conflict algorithm is applied. The state resolution
 algorithm is transitive and does not depend on server state, as it must
 consistently select the same event irrespective of the server or the order the
-events were received in.
+events were received in. Events are signed by the originating server (the
-
+signature includes the parent relations, type, depth and payload hash) and are
-Events are signed by the originating server (the signature includes the parent
+pushed over federation to the participating servers in a room, currently using
-relations, type, depth and payload hash) and are pushed over federation to the
+full mesh topology. Servers may also request backfill of events over federation
-participating servers in a room, currently using full mesh topology. Servers may
+from the other servers participating in a room.
-also request backfill of events over federation from the other servers
-participating in a room.
 
 
 Room Aliases
@@ -324,12 +320,10 @@ Users in Matrix are identified via their matrix user ID (MXID). However,
 existing 3rd party ID namespaces can also be used in order to identify Matrix
 users. A Matrix "Identity" describes both the user ID and any other existing IDs
 from third party namespaces *linked* to their account.
-
 Matrix users can *link* third-party IDs (3PIDs) such as email addresses, social
 network accounts and phone numbers to their user ID. Linking 3PIDs creates a
 mapping from a 3PID to a user ID. This mapping can then be used by Matrix
 users in order to discover the MXIDs of their contacts.
-
 In order to ensure that the mapping from 3PID to user ID is genuine, a globally
 federated cluster of trusted "Identity Servers" (IS) are used to verify the 3PID
 and persist and replicate the mappings.
@@ -367,6 +361,10 @@ dedicated API.  The API is symmetrical to managing Profile data.
 API Standards
 -------------
 
+.. TODO
+  Need to specify any HMAC or access_token lifetime/ratcheting tricks
+  We need to specify capability negotiation for extensible transports
+
 The mandatory baseline for communication in Matrix is exchanging JSON objects
 over HTTP APIs. HTTPS is mandated as the baseline for server-server
 (federation) communication.  HTTPS is recommended for client-server
@@ -374,20 +372,11 @@ communication, although HTTP may be supported as a fallback to support basic
 HTTP clients. More efficient optional transports for client-server
 communication will in future be supported as optional extensions - e.g. a
 packed binary encoding over stream-cipher encrypted TCP socket for
-low-bandwidth/low-roundtrip mobile usage.
+low-bandwidth/low-roundtrip mobile usage. For the default HTTP transport, all
-
+API calls use a Content-Type of ``application/json``.  In addition, all strings
-.. TODO
+MUST be encoded as UTF-8. Clients are authenticated using opaque
-  We need to specify capability negotiation for extensible transports
+``access_token`` strings (see `Client Authentication`_ for details), passed as a
-
+query string parameter on all requests.
-For the default HTTP transport, all API calls use a Content-Type of
-``application/json``.  In addition, all strings MUST be encoded as UTF-8.
-
-Clients are authenticated using opaque ``access_token`` strings (see
-`Client Authentication`_ for details), passed as a query string parameter on
-all requests.
-
-.. TODO
-  Need to specify any HMAC or access_token lifetime/ratcheting tricks
 
 Any errors which occur at the Matrix API level MUST return a "standard error
 response". This is a JSON object which looks like::

specification/1-client_server_api.rst

@@ -672,13 +672,10 @@ to add keys that are, for example offensive or illegal. Since some events
 cannot be simply deleted, e.g. membership events, we instead 'redact' events.
 This involves removing all keys from an event that are not required by the
 protocol. This stripped down event is thereafter returned anytime a client or
-remote server requests it.
+remote server requests it. Redacting an event cannot be undone, allowing server
-
+owners to delete the offending content from the databases. Events that have been
-Events that have been redacted include a ``redacted_because`` key whose value
+redacted include a ``redacted_because`` key whose value is the event that caused
-is the event that caused it to be redacted, which may include a reason.
+it to be redacted, which may include a reason.
-
-Redacting an event cannot be undone, allowing server owners to delete the
-offending content from the databases.
 
 .. TODO
   Currently, only room admins can redact events by sending a ``m.room.redaction``
@@ -709,12 +706,10 @@ one of the following event types:
 .. TODO
   Need to update m.room.power_levels to reflect new power levels formatting
 
-The redaction event should be added under the key ``redacted_because``.
+The redaction event should be added under the key ``redacted_because``. When a
-
+client receives a redaction event it should change the redacted event
-When a client receives a redaction event it should change the redacted event
 in the same way a server does.
 
-
 Rooms
 -----
 
@@ -853,18 +848,14 @@ 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. The power levels required for operations
-
+and the power levels for users are defined in ``m.room.power_levels``, where
-The power levels required for operations and the power levels for users are
+both a default and specific users' power levels can be set.
-defined in ``m.room.power_levels``, where both a 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
 users are tracked per-room even if the user is not present in the room.
-
 The keys contained in ``m.room.power_levels`` determine the levels required for
 certain operations such as kicking, banning and sending state events. See
 `m.room.power_levels`_ for more information.
@@ -881,10 +872,9 @@ room. There are several states in which a user may be, in relation to a room:
  - Banned (the user is not allowed to join the room)
 
 Some rooms require that users be invited to it before they can join; others
-allow anyone to join.
+allow anyone to join. Whether a given room is an "invite-only" room is
-
+determined by the room config key ``m.room.join_rules``. It can have one of the
-Whether a given room is an "invite-only" room is determined by the room config
+following values:
-key ``m.room.join_rules``. It can have one of the following values:
 
 ``public``
   This room is free for anyone to join without an invite.

specification/3-application_service_api.rst

@@ -4,11 +4,9 @@ Application Service API
 The Matrix client-server API and server-server APIs provide the means to
 implement a consistent self-contained federated messaging fabric. However, they
 provide limited means of implementing custom server-side behaviour in Matrix
-(e.g. gateways, filters, extensible hooks etc).
+(e.g. gateways, filters, extensible hooks etc). The Application Service API
-
+defines a standard API to allow such extensible functionality to be implemented
-The Application Service API defines a standard API to allow such extensible 
+irrespective of the underlying homeserver implementation.
-functionality to be implemented irrespective of the underlying homeserver
-implementation.
 
 .. TODO-spec
   Add in Client-Server services? Overview of bots? Seems weird to be in the spec
@@ -18,12 +16,10 @@ Passive Application Services
 ----------------------------
 "Passive" application services can only observe events from a given home server.
 They cannot prevent events from being sent, nor can they modify the content of
-the event being sent.
+the event being sent. In order to observe events from a homeserver, the
-
+homeserver needs to be configured to pass certain types of traffic to the
-In order to observe events from a homeserver, the homeserver needs to be
+application service.  This is achieved by manually configuring the homeserver
-configured to pass certain types of traffic to the application service.  This
+with information about the AS.
-is achieved by manually configuring the homeserver with information about the
-AS..
 
 .. NOTE::
   Previously, application services could register with a homeserver via HTTP

specification/4-server_server_api.rst

@@ -59,13 +59,11 @@ and an optional TLS port.
 .. **
 
 If the port is present then the server is discovered by looking up an AAAA or
-A record for the DNS name and connecting to the specified TLS port.
+A record for the DNS name and connecting to the specified TLS port. If the port
-
+is absent then the server is discovered by looking up a ``_matrix._tcp`` SRV
-If the port is absent then the server is discovered by looking up a
+record for the DNS name. If this record does not exist then the server is
-``_matrix._tcp`` SRV record for the DNS name. If this record does not exist
+discovered by looking up an AAAA or A record on the DNS name and taking the
-then the server is discovered by looking up an AAAA or A record on the DNS
+default fallback port number of 8448.
-name and taking the default fallback port number of 8448.
-
 Home servers may use SRV records to load balance requests between multiple TLS
 endpoints or to failover to another endpoint if an endpoint fails.
 

specification/modules/content_repo.rst

@@ -56,21 +56,21 @@ Homeservers must never upscale images.
 Security considerations
 -----------------------
 
-Clients may try to upload very large files. Homeservers should not store files
+ - Clients may try to upload very large files. Homeservers should not store files
-that are too large and should not serve them to clients.
+   that are too large and should not serve them to clients.
 
-Clients may try to upload very large images. Homeservers should not attempt to
+ - Clients may try to upload very large images. Homeservers should not attempt to
-generate thumbnails for images that are too large.
+   generate thumbnails for images that are too large.
 
-Remote homeservers may host very large files or images. Homeserver should not
+ - Remote homeservers may host very large files or images. Homeserver should not
-proxy or thumbnail large files or images from remote homeservers.
+   proxy or thumbnail large files or images from remote homeservers.
 
-Clients may try to upload a large number of files. Homeservers should limit the
+ - 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.
+   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.
+ - 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.
+   Homeservers should restrict the number and size of remote files that it caches.
 
-Clients or remote homeservers may try to upload malicious files targeting
+ - Clients or remote homeservers may try to upload malicious files targeting
-vulnerabilities in either the homeserver thumbnailing or the client decoders.
+   vulnerabilities in either the homeserver thumbnailing or the client decoders.
 

specification/modules/push_cs_api.rst

@@ -99,16 +99,13 @@ be redundant. Actions for the highest priority rule and only that rule apply
 (for example, a set_tweak action in a lower priority rule will not apply if a
 higher priority rule matches, even if that rule does not specify any tweaks).
 
-Rules also have an identifier, rule_id, which is a string. The rule_id is
+Rules also have an identifier, ``rule_id``, which is a string. The ``rule_id``
-unique within the kind of rule and scope: rule_ids need not be unique between
+is unique within the kind of rule and scope: ``rule_ids`` need not be unique
-rules of the same kind on different devices.
+between rules of the same kind on different devices. A home server may also have
-
+server default rules of each kind and in each scope. Server default rules are
-A home server may also have server default rules of each kind and in each scope.
+lower priority than user-defined rules in each scope. Server default rules (and
-Server default rules are lower priority than user-defined rules in each scope.
+only server default rules) begin with a dot ('.') character. In addition, all
-Server default rules (and only server default rules) begin with a dot ('.')
+rules may be enabled or disabled. Disabled rules never match.
-character.
-
-In addition, all rules may be enabled or disabled. Disabled rules never match.
 
 If no rules match an event, the Home Server should not notify for the message
 (that is to say, the default action is "dont-notify"). Events that the user sent

specification/modules/voip_events.rst

@@ -44,11 +44,10 @@ Glare
 This specification aims to address the problem of two users calling each other
 at roughly the same time and their invites crossing on the wire. It is a far
 better experience for the users if their calls are connected if it is clear
-that their intention is to set up a call with one another.
+that their intention is to set up a call with one another. In Matrix, calls are
-
+to rooms rather than users (even if those rooms may only contain one other user)
-In Matrix, calls are to rooms rather than users (even if those rooms may only
+so we consider calls which are to the same room. The rules for dealing with such
-contain one other user) so we consider calls which are to the same room. The
+a situation are as follows:
-rules for dealing with such a situation are as follows:
 
  - If an invite to a room is received whilst the client is preparing to send an
    invite to the same room, the client should cancel its outgoing call and