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.
-
-This specification is the ongoing result of standardising the APIs used by the
-various components of the Matrix ecosystem to communicate with one another.
+persisting and publishing/subscribing JSON objects. This specification is the
+ongoing result of standardising the APIs used by the 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.
-
-The following conceptual diagram shows an ``m.room.message`` event being sent to 
-the room ``!qporfwt:matrix.org``::
+They are case-sensitive. 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,11 +254,13 @@ 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
-instant messages, VoIP call setups, file transfers, etc. They generally describe
-communication activity.
+Message events: 
+  These describe transient 'once-off' activity in a room such as an
+  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:
+  These describe updates to a given piece of persistent information
   ('state') related to a room, such as the room's name, topic, membership,
   participating servers, etc. State is modelled as a lookup table of key/value
   pairs per room, with each key being a tuple of ``state_key`` and ``event type``.
@@ -273,13 +271,11 @@ 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 are signed by the originating server (the signature includes the parent
-relations, type, depth and payload hash) and are pushed over federation to the
-participating servers in a room, currently using full mesh topology. Servers may
-also request backfill of events over federation from the other servers
-participating in a room.
+events were received in. Events are signed by the originating server (the
+signature includes the parent relations, type, depth and payload hash) and are
+pushed over federation to the participating servers in a room, currently using
+full mesh topology. Servers may 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.
-
-.. TODO
-  We need to specify capability negotiation for extensible transports
-
-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
+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
+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.
 
 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.
-
-Events that have been redacted include a ``redacted_because`` key whose value
-is the event that caused 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.
+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
+redacted include a ``redacted_because`` key whose value is the event that caused
+it to be redacted, which may include a reason.
 
 .. 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``.
-
-When a client receives a redaction event it should change the redacted event
+The redaction event should be added under the key ``redacted_because``. 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.
-
-The power levels required for operations and the power levels for users are
-defined in ``m.room.power_levels``, where both a default and specific users'
-power levels can be set.
-
+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
+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.
-
-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 following values:
+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
+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).
-
-The Application Service API defines a standard API to allow such extensible 
-functionality to be implemented irrespective of the underlying homeserver
-implementation.
+(e.g. gateways, filters, extensible hooks etc). The Application Service API
+defines a standard API to allow such extensible 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.
-
-In order to observe events from a homeserver, the homeserver needs to be
-configured to pass certain types of traffic to the application service.  This
-is achieved by manually configuring the homeserver with information about the
-AS..
+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
+application service.  This 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.
-
-If the port is absent then the server is discovered by looking up a
-``_matrix._tcp`` SRV record for the DNS name. If this record does not exist
-then the server is discovered by looking up an AAAA or A record on the DNS
-name and taking the default fallback port number of 8448.
-
+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
+record for the DNS name. If this record does not exist then the server is
+discovered by looking up an AAAA or A record on the DNS 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.
 
-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.
 
-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.
 
-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.
 
-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.
 
-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.
 

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
-unique within the kind of rule and scope: rule_ids need not be unique 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 lower priority than user-defined rules in each scope.
-Server default rules (and only server default rules) begin with a dot ('.')
-character.
-
-In addition, all rules may be enabled or disabled. Disabled rules never match.
+Rules also have an identifier, ``rule_id``, which is a string. The ``rule_id``
+is unique within the kind of rule and scope: ``rule_ids`` need not be unique
+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
+lower priority than user-defined rules in each scope. Server default rules (and
+only server default rules) begin with a dot ('.') 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.
-
-In Matrix, calls are to rooms rather than users (even if those rooms may only
-contain one other user) so we consider calls which are to the same room. The
-rules for dealing with such a situation are as follows:
+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)
+so we consider calls which are to the same room. The 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