wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
Matthew Hodgson 2016-01-05 02:48:14 +00:00
commit c7d11335cf
10 changed files with 113 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

9
api/client-server/definitions/event_filter.yaml
View file

@ -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
of characters.
senders are included.
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

6
api/client-server/definitions/room_event_filter.yaml
View file

@ -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'
filter. A '*' can be used as a wildcard to match any sequence of characters.
are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
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

23
api/client-server/definitions/sync_filter.yaml
View file

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

5
api/client-server/room_send.yaml
View file

@ -48,8 +48,9 @@ paths:
name: txnId
type: string
description: |-
The transaction ID for this event. Clients should generate a
unique ID; it will be used by the server to ensure idempotency of requests.
The transaction ID for this event. Clients should generate an
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

20
api/client-server/search.yaml
View file

@ -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
batch of results in the group, if exists.
Token that can be used to get the next batch
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: |-
{

1
event-schemas/examples/m.room.member#third_party_invite
View file

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

6
event-schemas/schema/m.room.member
View file

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

6
specification/index.rst
View file

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

10
specification/modules/search.rst
View file

@ -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 search query matching 1000s of results and the server truncating the
response.
The value of ``count`` gives an approximation of the total number of
results. Homeservers may give an estimate rather than an exact value for this
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

60
specification/server_server_api.rst
View file

@ -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
- What it is, when is it used, how is it done
Once a homeserver has joined a room, it receives all the events emitted by
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