Merge branch 'master' of git+ssh://github.com/matrix-org/matrix-doc

api/client-server/definitions/event_filter.yaml

@@ -5,28 +5,27 @@ properties:
   not_senders:
     description: A list of sender IDs to exclude. If this list is absent then no senders
       are excluded. A matching sender will be excluded even if it is listed in the
-      'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.
+      ``'senders'`` filter.
     items:
       type: string
     type: array
   not_types:
     description: A list of event types to exclude. If this list is absent then no
       event types are excluded. A matching type will be excluded even if it is listed
-      in the 'types' filter. A '*' can be used as a wildcard to match any sequence
+      in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string
     type: array
   senders:
     description: A list of senders IDs to include. If this list is absent then all
-      senders are included. A '*' can be used as a wildcard to match any sequence
+      senders are included.
-      of characters.
     items:
       type: string
     type: array
   types:
     description: A list of event types to include. If this list is absent then all
-      event types are included. A '*' can be used as a wildcard to match any sequence
+      event types are included. A ``'*'`` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string

api/client-server/definitions/room_event_filter.yaml

@@ -3,14 +3,14 @@ allOf:
 properties:
   not_rooms:
     description: A list of room IDs to exclude. If this list is absent then no rooms
-      are excluded. A matching room will be excluded even if it is listed in the 'rooms'
+      are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
-      filter. A '*' can be used as a wildcard to match any sequence of characters.
+      filter.
     items:
       type: string
     type: array
   rooms:
     description: A list of room IDs to include. If this list is absent then all rooms
-      are included. A '*' can be used as a wildcard to match any sequence of characters.
+      are included.
     items:
       type: string
     type: array

api/client-server/definitions/sync_filter.yaml

@@ -20,8 +20,27 @@ properties:
     allOf:
     - $ref: event_filter.yaml
     description: The presence updates to include.
+  account_data:
+    allOf:
+    - $ref: event_filter.yaml
+    description: The user account data that isn't associated with rooms to include.
   room:
     properties:
+      not_rooms:
+        description: A list of room IDs to exclude. If this list is absent then no rooms
+          are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
+          filter. This filter is applied before the filters in ``ephemeral``, 
+          ``state``, ``timeline`` or ``account_data``
+        items:
+          type: string
+        type: array
+      rooms:
+        description: A list of room IDs to include. If this list is absent then all rooms
+          are included. This filter is applied before the filters in ``ephemeral``,
+          ``state``, ``timeline`` or ``account_data``
+        items:
+          type: string
+        type: array
       ephemeral:
         allOf:
         - $ref: room_event_filter.yaml
@@ -38,5 +57,9 @@ properties:
         allOf:
         - $ref: room_event_filter.yaml
         description: The message and state update events to include for rooms.
+      account_data:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The per user account data to include for rooms.
     type: object
 type: object

api/client-server/room_send.yaml

@@ -48,8 +48,9 @@ paths:
           name: txnId
           type: string
           description: |-
-            The transaction ID for this event. Clients should generate a
+            The transaction ID for this event. Clients should generate an
-            unique ID; it will be used by the server to ensure idempotency of requests.
+            ID unique across requests with the same access token; it will be
+            used by the server to ensure idempotency of requests.
           required: true
           x-example: "35"
         - in: body

api/client-server/search.yaml

@@ -20,12 +20,19 @@ securityDefinitions:
 paths:
   "/search":
     post:
-      summary: Search server side for things.
+      summary: Perform a server-side search.
       description: |-
         Performs a full text search across different categories.
       security:
         - accessToken: []
       parameters:
+        - in: query
+          name: next_batch
+          type: string
+          description: |-
+            The point to return events from. If given, this should be a
+            `next_batch` result from a previous call to this endpoint.
+          x-example: "YWxsCgpOb25lLDM1ODcwOA"
         - in: body
           name: body
           schema:
@@ -260,8 +267,11 @@ paths:
                                 type: string
                                 title: Next Batch in Group
                                 description: |-
-                                  Token that can be used to get the next
+                                  Token that can be used to get the next batch
-                                  batch of results in the group, if exists.
+                                  of results in the group, by passing as the
+                                  `next_batch` parameter to the next call. If
+                                  this field is absent, there are no more
+                                  results in this group.
                               order:
                                 type: integer
                                 title: Group Order
@@ -280,7 +290,9 @@ paths:
                         title: Next Batch
                         description: |-
                           Token that can be used to get the next batch of
-                          results, if exists.
+                          results, by passing as the `next_batch` parameter to
+                          the next call. If this field is absent, there are no
+                          more results.
           examples:
             application/json: |-
                {

event-schemas/examples/m.room.member#third_party_invite

@@ -5,6 +5,7 @@
     "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
     "displayname": "Alice Margatroid",
     "third_party_invite": {
+      "display_name": "alice",
       "signed": {
         "mxid": "@alice:localhost",
         "signatures": {

event-schemas/schema/m.room.member

@@ -27,6 +27,10 @@
                     "type": "object",
                     "title": "Invite",
                     "properties": {
+                        "display_name": {
+                            "type": "string",
+                            "description": "A name which can be displayed to represent the user instead of their third party identifier"
+                        },
                         "signed": {
                             "type": "object",
                             "title": "signed",
@@ -49,7 +53,7 @@
                             "required": ["mxid", "signatures", "token"]
                         }
                     },
-                    "required": ["signed"]
+                    "required": ["display_name", "signed"]
                 }
             },
             "required": ["membership"]

specification/index.rst

@@ -26,6 +26,12 @@ Any developments since the latest release can be found `here`__.
 
 .. __: https://matrix.org/speculator/spec/head/
 
+Old releases of the spec:
+
+- Client-Server API: `r0.0.0`__
+
+.. __: https://matrix.org/docs/spec/r0.0.0
+
 Before we formally started releasing the specification, the last working copy
 we had can be found `here`__.
 

specification/modules/search.rst

@@ -10,6 +10,8 @@ events in rooms that happened after you left.
 
 Client behaviour
 ----------------
+There is a single HTTP API for performing server-side search, documented below.
+
 {{search_http_api}}
 
 Search Categories
@@ -36,9 +38,9 @@ The search will *not* include rooms that are end to end encrypted.
 The results include a ``rank`` key that can be used to sort the results by
 relevancy. The higher the ``rank`` the more relevant the result is.
 
-The value of ``count`` may not match the number of results. For example due to
+The value of ``count`` gives an approximation of the total number of
-the search query matching 1000s of results and the server truncating the
+results. Homeservers may give an estimate rather than an exact value for this
-response.
+field.
 
 Ordering
 --------
@@ -84,7 +86,7 @@ The currently supported locations for the ``next_batch`` token are:
 - ``search_categories.<category>.groups.<group_key>.<group_id>.next_batch``
 
 A server need not support pagination, even if there are more matching results.
-In which case they must not return a ``next_batch`` token in the response.
+In that case, they must not return a ``next_batch`` token in the response.
 
 
 Security considerations

specification/server_server_api.rst

@@ -485,15 +485,6 @@ The destination name will be set to that of the receiving server itself. Each
 embedded PDU in the transaction body will be processed.
 
 
-To fetch a particular PDU::
-
-  GET .../pdu/<origin>/<pdu_id>/
-    Response: JSON encoding of a single Transaction containing one 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 room::
 
   GET .../state/<room_id>/
@@ -503,6 +494,17 @@ Retrieves a snapshot of the entire current state of the given room. The
 response will contain a single Transaction, inside which will be a list of PDUs
 that encode the state.
 
+
+To fetch a particular event::
+
+  GET .../event/<event_id>/
+    Response: JSON encoding of a partial Transaction containing the event
+
+Retrieves a single event. The response will contain a partial Transaction,
+having just the ``origin``, ``origin_server_ts`` and ``pdus`` fields; the
+event will be encoded as the only PDU in the ``pdus`` list.
+
+
 To backfill events on a given room::
 
   GET .../backfill/<room_id>/
@@ -512,7 +514,6 @@ To backfill events on a given room::
 Retrieves a sliding-window history of previous PDUs that occurred on the given
 room. Starting from the PDU ID(s) given in the "v" argument, the PDUs that
 preceded it are retrieved, up to a total number given by the "limit" argument.
-These are then returned in a new Transaction containing all of the PDUs.
 
 
 To stream events all the events::
@@ -690,11 +691,42 @@ following keys:
 
 Backfilling
 -----------
-.. NOTE::
-  This section is a work in progress.
 
-.. TODO-doc
+Once a homeserver has joined a room, it receives all the events emitted by
-  - What it is, when is it used, how is it done
+other homeservers in that room, and is thus aware of the entire history of the
+room from that moment onwards. Since users in that room are able to request the
+history by the ``/messages`` client API endpoint, it's possible that they might
+step backwards far enough into history before the homeserver itself was a
+member of that room.
+
+To cover this case, the federation API provides a server-to-server analog of
+the ``/messages`` client API, allowing one homeserver to fetch history from
+another. This is the ``/backfill`` API.
+
+To request more history, the requesting homeserver picks another homeserver
+that it thinks may have more (most likely this should be a homeserver for some
+of the existing users in the room at the earliest point in history it has
+currently), and makes a ``/backfill`` request. The parameters of this request
+give an event ID that the requesting homeserver wishes to obtain, and a number
+specifying how many more events of history before that one to return at most.
+
+The response to this request is an object with the following keys:
+
+==================== ======== ============
+ Key                  Type     Description
+==================== ======== ============
+``pdus``             List     A list of events
+``origin``           String   The name of the resident homeserver
+``origin_server_ts`` Integer  A timestamp added by the resident homeserver
+==================== ======== ============
+
+The list of events given in ``pdus`` is returned in reverse chronological
+order; having the most recent event first (i.e. the event whose event ID is
+that requested by the requestor in the ``v`` parameter).
+
+.. TODO-spec
+  Specify (or remark that it is unspecified) how the server handles divergent
+  history. DFS? BFS? Anything weirder?
 
 
 Authentication