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

Merge remote-tracking branch 'origin/master' into erikj/search_yet_agian

Browse source
This commit is contained in:
Erik Johnston 2015-12-07 16:28:14 +00:00
commit 856dd9100e
172 changed files with 1728 additions and 1719 deletions
Download patch file Download diff file Expand all files Collapse all files

41
CHANGELOG.rst
View file

@ -1,41 +0,0 @@
.. This file is automatically processed by the templating system. To make it
.. happy, you MUST use '=' as the title underline and you MUST stick the version
.. in the title. The version MUST follow the numbering format
.. "v<num>.<num>.<num>" - You cannot use a-z. If the templating system fails to
.. find the right info, it will be treated as a test failure and so will show up
.. in Jenkins. Comments like this are ignored by both RST and the templating
.. system. Add the newest release notes beneath this comment.
Specification changes in v0.2.0 (2015-10-02)
============================================
This update fundamentally restructures the specification. The specification has
been split into more digestible "modules" which each describe a particular
function (e.g. typing). This was done in order make the specification easier to
maintain and help define which modules are mandatory for certain types
of clients. Types of clients along with the mandatory modules can be found in a
new "Feature Profiles" section. This update also begins to aggressively
standardise on using Swagger and JSON Schema to document HTTP endpoints and
Events respectively. It also introduces a number of new concepts to Matrix.
Additions:
- New section: Feature Profiles.
- New section: Receipts.
- New section: Room history visibility.
- New event: ``m.receipt``.
- New event: ``m.room.canonical_alias``
- New event: ``m.room.history_visibility``
- New keys: ``/createRoom`` - allows room "presets" using ``preset`` and
``initial_state`` keys.
- New endpoint: ``/tokenrefresh`` - Related to refreshing access tokens.
Modifications:
- Convert most of the older HTTP APIs to Swagger documentation.
- Convert most of the older event formats to JSON Schema.
- Move selected client-server sections to be "Modules".
Specification changes in v0.1.0 (2015-06-01)
============================================
- First numbered release.
- Restructure the format of Event information. Add more information.
- Restructure the format of the Client-Server HTTP APIs.

1
api/client-server/application_service.yaml → api/application-service/application_service.yaml
View file

@ -198,4 +198,3 @@ paths:
}
schema:
type: object

14
api/check_examples.py
View file

@ -49,7 +49,8 @@ def check_parameter(filepath, request, parameter):
# Setting the 'id' tells jsonschema where the file is so that it
# can correctly resolve relative $ref references in the schema
schema['id'] = fileurl
jsonschema.validate(example, schema)
resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
jsonschema.validate(example, schema, resolver=resolver)
except Exception as e:
raise ValueError("Error validating JSON schema for %r" % (
request
@ -76,7 +77,8 @@ def check_response(filepath, request, code, response):
# Setting the 'id' tells jsonschema where the file is so that it
# can correctly resolve relative $ref references in the schema
schema['id'] = fileurl
jsonschema.validate(example, schema)
resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
jsonschema.validate(example, schema, resolver=resolver)
except Exception as e:
raise ValueError("Error validating JSON schema for %r %r" % (
request, code
@ -103,6 +105,14 @@ def check_swagger_file(filepath):
check_response(filepath, request, code, response)
def load_yaml(path):
if not path.startswith("file:///"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
return yaml.load(f)
if __name__ == '__main__':
paths = sys.argv[1:]
if not paths:

6
api/client-server/account-data.yaml
View file

@ -6,7 +6,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -57,6 +57,8 @@ paths:
200:
description:
The account_data was successfully added.
tags:
- User data
"/user/{userId}/rooms/{roomId}/account_data/{type}":
put:
summary: Set some account_data for the user.
@ -103,3 +105,5 @@ paths:
200:
description:
The account_data was successfully added.
tags:
- User data

105
api/client-server/admin.yaml Normal file
View file

@ -0,0 +1,105 @@
swagger: '2.0'
info:
title: "Matrix Client-Server Administration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
accessToken:
type: apiKey
description: The user_id or application service access_token
name: access_token
in: query
paths:
"/admin/whois/{userId}":
get:
summary: Gets information about a particular user.
description: |-
Gets information about a particular user.
This API may be restricted to only be called by the user being looked
up, or by a server admin. Server-local administrator privileges are not
specified in this document.
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user to look up.
required: true
x-example: "@peter:rabbit.rocks"
responses:
200:
description: The lookup was successful.
examples:
application/json: |-
{
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
"sessions": [
{
"connections": [
{
"ip": "127.0.0.1",
"last_seen": 1411996332123,
"user_agent": "curl/7.31.0-DEV"
},
{
"ip": "10.0.0.2",
"last_seen": 1411996332123,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
}
]
}
]
}
}
}
schema:
type: object
properties:
user_id:
type: string
description: The Matrix user ID of the user.
devices:
type: object
description: |-
Each key is an identitfier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo
properties:
sessions:
type: array
description: A user's sessions (i.e. what they did with an access token from one login).
items:
type: object
title: SessionInfo
properties:
connections:
type: array
description: Information particular connections in the session.
items:
type: object
title: ConnectionInfo
properties:
ip:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: number
description: Unix timestamp that the session was last active.
user_agent:
type: string
description: User agent string last seen in the session.
tags:
- Server administration

16
api/client-server/administrative_contact.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Account Administrative Contact API"
title: "Matrix Client-Server Account Administrative Contact API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -25,7 +25,7 @@ paths:
This API endpoint uses the User-Interactive Authentication API.
An access token should be submitted to this endpoint if the client has
an active session.
The Home Server may change the flows available depending on whether a
The homeserver may change the flows available depending on whether a
valid access token is provided.
security:
- accessToken: []
@ -54,6 +54,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data
"/account/3pid":
get:
summary: Gets a list of a user's third party identifiers.
@ -64,7 +66,7 @@ paths:
This is *not* the same as the list of third party identifiers bound to
the user's Matrix ID in Identity Servers.
Identifiers in this list may be used by the Home Server as, for example,
Identifiers in this list may be used by the homeserver as, for example,
identifiers that it will accept to reset the user's account password.
security:
- accessToken: []
@ -97,6 +99,8 @@ paths:
address:
type: string
description: The third party identifier address.
tags:
- User data
post:
summary: Adds contact information to the user's account.
description: Adds contact information to the user's account.
@ -126,7 +130,7 @@ paths:
bind:
type: boolean
description: |-
Whether the home server should also bind this third party
Whether the homeserver should also bind this third party
identifier to the account's Matrix ID with the passed identity
server. Default: ``false``.
x-example: true
@ -155,3 +159,5 @@ paths:
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
}
tags:
- User data

6
api/client-server/banning.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Banning API"
title: "Matrix Client-Server Room Banning API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,3 +74,5 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
tags:
- Room membership

12
api/client-server/content-repo.yaml
View file

@ -1,11 +1,11 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Content Repository API"
title: "Matrix Client-Server Content Repository API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/media/v1
basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
produces:
- application/json
- "*/*"
@ -43,6 +43,8 @@ paths:
{
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
tags:
- Media
"/download/{serverName}/{mediaId}":
get:
summary: "Download content from the content repository."
@ -74,6 +76,8 @@ paths:
type: "string"
schema:
type: file
tags:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: "Download a thumbnail of the content from the content repository."
@ -123,5 +127,5 @@ paths:
enum: ["image/jpeg", "image/png"]
schema:
type: file
tags:
- Media

8
api/client-server/create_room.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Creation API"
title: "Matrix Client-Server Room Creation API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -57,7 +57,7 @@ paths:
description: |-
The desired room alias **local part**. If this is included, a
room alias will be created and mapped to the newly created
room. The alias will belong on the *same* home server which
room. The alias will belong on the *same* homeserver which
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be ``#foo:example.com``.
@ -146,3 +146,5 @@ paths:
400:
description: >
The request body is malformed or the room alias specified is already taken.
tags:
- Room creation

53
api/client-server/definitions/event.json
View file

@ -1,53 +0,0 @@
{
"type": "object",
"title": "Event",
"properties": {
"content": {
"type": "object",
"title": "EventContent",
"description": "The content of this event. The fields in this object will vary depending on the type of event."
},
"origin_server_ts": {
"type": "integer",
"format": "int64",
"description": "Timestamp in milliseconds on originating homeserver when this event was sent."
},
"sender": {
"type": "string",
"description": "The MXID of the user who sent this event."
},
"state_key": {
"type": "string",
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state."
},
"type": {
"type": "string",
"description": "The type of event."
},
"unsigned": {
"type": "object",
"title": "Unsigned",
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"type": "integer",
"format": "int64",
"description": "Time in milliseconds since the event was sent."
},
"prev_content": {
"title": "EventContent",
"type": "object",
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
},
"replaces_state": {
"type": "string",
"description": "Optional. The event_id of the previous event for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
},
"transaction_id": {
"type": "string",
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API."
}
}
}
}
}

45
api/client-server/definitions/event.yaml Normal file
View file

@ -0,0 +1,45 @@
properties:
content:
description: The content of this event. The fields in this object will vary depending
on the type of event.
title: EventContent
type: object
origin_server_ts:
description: Timestamp in milliseconds on originating homeserver when this event
was sent.
format: int64
type: integer
sender:
description: The MXID of the user who sent this event.
type: string
state_key:
description: Optional. This key will only be present for state events. A unique
key which defines the overwriting semantics for this piece of room state.
type: string
type:
description: The type of event.
type: string
unsigned:
description: Information about this event which was not sent by the originating
homeserver
properties:
age:
description: Time in milliseconds since the event was sent.
format: int64
type: integer
prev_content:
description: Optional. The previous ``content`` for this state. This will
be present only for state events appearing in the ``timeline``. If this
is not a state event, or there is no previous content, this key will be
missing.
title: EventContent
type: object
transaction_id:
description: Optional. The transaction ID set when this message was sent.
This key will only be present for message events sent by the device calling
this API.
type: string
title: Unsigned
type: object
title: Event
type: object

13
api/client-server/definitions/event_batch.json
View file

@ -1,13 +0,0 @@
{
"type": "object",
"properties": {
"events": {
"type": "array",
"description": "List of events",
"items": {
"type": "object",
"allOf": [{"$ref": "event.json" }]
}
}
}
}

9
api/client-server/definitions/event_batch.yaml Normal file
View file

@ -0,0 +1,9 @@
properties:
events:
description: List of events
items:
allOf:
- $ref: event.yaml
type: object
type: array
type: object

42
api/client-server/definitions/event_filter.json
View file

@ -1,42 +0,0 @@
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description":
"The maximum number of events to return."
},
"types": {
"type": "array",
"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 of characters.",
"items": {
"type": "string"
}
},
"not_types": {
"type": "array",
"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 of characters.",
"items": {
"type": "string"
}
},
"senders": {
"type": "array",
"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.",
"items": {
"type": "string"
}
},
"not_senders": {
"type": "array",
"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.",
"items": {
"type": "string"
}
}
}
}

34
api/client-server/definitions/event_filter.yaml Normal file
View file

@ -0,0 +1,34 @@
properties:
limit:
description: The maximum number of events to return.
type: integer
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.
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
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.
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
of characters.
items:
type: string
type: array
type: object

9
api/client-server/definitions/push_condition.json
View file

@ -1,9 +0,0 @@
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": ["event_match", "profile_tag", "contains_display_name", "room_member_count"]
}
}
}

9
api/client-server/definitions/push_condition.yaml Normal file
View file

@ -0,0 +1,9 @@
properties:
kind:
enum:
- event_match
- profile_tag
- contains_display_name
- room_member_count
type: string
type: object

21
api/client-server/definitions/push_rule.json
View file

@ -1,21 +0,0 @@
{
"title": "PushRule",
"type": "object",
"properties": {
"default": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"rule_id": {
"type": "string"
},
"actions": {
"items": {
"type": ["object", "string"]
},
"type": "array"
}
}
}

15
api/client-server/definitions/push_rule.yaml Normal file
View file

@ -0,0 +1,15 @@
properties:
actions:
items:
type:
- object
- string
type: array
default:
type: boolean
enabled:
type: boolean
rule_id:
type: string
title: PushRule
type: object

65
api/client-server/definitions/push_ruleset.json
View file

@ -1,65 +0,0 @@
{
"type": "object",
"properties": {
"content": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"override": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"sender": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"underride": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"room": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
}
}
}

37
api/client-server/definitions/push_ruleset.yaml Normal file
View file

@ -0,0 +1,37 @@
properties:
content:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
override:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
room:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
sender:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
underride:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
type: object

22
api/client-server/definitions/room_event_filter.json
View file

@ -1,22 +0,0 @@
{
"type": "object",
"allOf": [{"$ref": "event_filter.json"}],
"properties": {
"rooms": {
"type": "array",
"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.",
"items": {
"type": "string"
}
},
"not_rooms": {
"type": "array",
"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.",
"items": {
"type": "string"
}
}
}
}

17
api/client-server/definitions/room_event_filter.yaml Normal file
View file

@ -0,0 +1,17 @@
allOf:
- $ref: event_filter.yaml
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.
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.
items:
type: string
type: array
type: object

44
api/client-server/definitions/sync_filter.json
View file

@ -1,44 +0,0 @@
{
"type": "object",
"properties": {
"room": {
"type": "object",
"properties": {
"state": {
"description":
"The state events to include for rooms.",
"allOf": [{"$ref": "room_event_filter.json"}]
},
"timeline": {
"description":
"The message and state update events to include for rooms.",
"allOf": [{"$ref": "room_event_filter.json"}]
},
"ephemeral": {
"description":
"The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.",
"allOf": [{"$ref": "room_event_filter.json"}]
}
}
},
"presence": {
"description":
"The presence updates to include.",
"allOf": [{"$ref": "event_filter.json"}]
},
"event_format": {
"description":
"The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
"type": "string",
"enum": ["client", "federation"]
},
"event_fields": {
"type": "array",
"description":
"List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested.",
"items": {
"type": "string"
}
}
}
}

42
api/client-server/definitions/sync_filter.yaml Normal file
View file

@ -0,0 +1,42 @@
properties:
event_fields:
description: List of event fields to include. If this list is absent then all
fields are included. The entries may include '.' charaters to indicate sub-fields.
So ['content.body'] will include the 'body' field of the 'content' object. A
literal '.' character in a field name may be escaped using a '\'. A server may
include more fields than were requested.
items:
type: string
type: array
event_format:
description: The format to use for events. 'client' will return the events in
a format suitable for clients. 'federation' will return the raw event as receieved
over federation. The default is 'client'.
enum:
- client
- federation
type: string
presence:
allOf:
- $ref: event_filter.yaml
description: The presence updates to include.
room:
properties:
ephemeral:
allOf:
- $ref: room_event_filter.yaml
description: The events that aren't recorded in the room history, e.g. typing
and receipts, to include for rooms.
include_leave:
description: Include rooms that the user has left in the sync, default false
type: boolean
state:
allOf:
- $ref: room_event_filter.yaml
description: The state events to include for rooms.
timeline:
allOf:
- $ref: room_event_filter.yaml
description: The message and state update events to include for rooms.
type: object
type: object

14
api/client-server/definitions/timeline_batch.json
View file

@ -1,14 +0,0 @@
{
"type": "object",
"allOf": [{"$ref":"event_batch.json"}],
"properties": {
"limited": {
"type": "boolean",
"description": "True if the number of events returned was limited by the ``limit`` on the filter"
},
"prev_batch": {
"type": "string",
"description": "If the batch was limited then this is a token that can be supplied to the server to retrieve earlier events"
}
}
}

12
api/client-server/definitions/timeline_batch.yaml Normal file
View file

@ -0,0 +1,12 @@
allOf:
- $ref: event_batch.yaml
properties:
limited:
description: True if the number of events returned was limited by the ``limit``
on the filter
type: boolean
prev_batch:
description: If the batch was limited then this is a token that can be supplied
to the server to retrieve earlier events
type: string
type: object

10
api/client-server/directory.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Directory API"
title: "Matrix Client-Server Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1/directory
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
consumes:
- application/json
produces:
@ -52,6 +52,8 @@ paths:
{}
schema:
type: object
tags:
- Room directory
get:
summary: Get the room ID corresponding to this room alias.
parameters:
@ -102,6 +104,8 @@ paths:
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
tags:
- Room directory
delete:
summary: Remove a mapping of room alias to room ID.
description: |-
@ -125,3 +129,5 @@ paths:
{}
schema:
type: object
tags:
- Room directory

16
api/client-server/filter.yaml
View file

@ -1,11 +1,11 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 filter API"
title: "Matrix Client-Server filter API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -22,8 +22,8 @@ paths:
summary: Upload a new filter.
description: |-
Uploads a new filter definition to the homeserver.
Returns a filter ID that may be used in /sync requests to
retrict which events are returned to the client.
Returns a filter ID that may be used in future requests to
restrict which events are returned to the client.
security:
- accessToken: []
parameters:
@ -42,7 +42,7 @@ paths:
schema:
type: object
allOf:
- $ref: "definitions/sync_filter.json"
- $ref: "definitions/sync_filter.yaml"
example: |-
{
"room": {
@ -84,6 +84,8 @@ paths:
type: string
description: |-
The ID of the filter that was created.
tags:
- Room participation
"/user/{userId}/filter/{filterId}":
get:
summary: Download a filter
@ -136,4 +138,6 @@ paths:
schema:
type: object
allOf:
- $ref: "definitions/sync_filter.json"
- $ref: "definitions/sync_filter.yaml"
tags:
- Room participation

9
api/client-server/guest_events.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Sync Guest API"
title: "Matrix Client-Server Sync Guest API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,7 +74,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
}
]
}
@ -98,6 +98,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
400:
description: "Bad pagination ``from`` parameter."
# No tags to exclude this from the swagger UI - use the non-guest version instead.

8
api/client-server/inviting.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Joining API"
title: "Matrix Client-Server Room Joining API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -38,7 +38,7 @@ paths:
Only users currently in a particular room can invite other users to
join that room.
If the user was invited to the room, the home server will append a
If the user was invited to the room, the homeserver will append a
``m.room.member`` event to the room.
.. _third party invites section: `invite-by-third-party-id-endpoint`_
@ -88,3 +88,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership

10
api/client-server/joining.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Inviting API"
title: "Matrix Client-Server Room Inviting API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -63,6 +63,8 @@ paths:
schema:
"$ref": "definitions/error.yaml"
x-alias:
canonical-link: "post-matrix-client-api-v1-rooms-roomid-join"
canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join"
aliases:
- /_matrix/client/api/v1/join/{roomId}
- /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId}
tags:
- Room membership

8
api/client-server/leaving.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Leaving API"
title: "Matrix Client-Server Room Leaving API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -55,6 +55,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership
"/rooms/{roomId}/forget":
post:
summary: Stop the requesting user remembering about a particular room.
@ -90,3 +92,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership

6
api/client-server/list_public_rooms.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Creation API"
title: "Matrix Client-Server Room Creation API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -95,3 +95,5 @@ paths:
400:
description: >
The request body is malformed or the room alias specified is already taken.
tags:
- Room discovery

10
api/client-server/login.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Registration and Login API"
title: "Matrix Client-Server Registration and Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -81,7 +81,7 @@ paths:
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
home_server:
type: string
description: The hostname of the Home Server on which the account has been registered.
description: The hostname of the homeserver on which the account has been registered.
400:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.
@ -101,6 +101,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Session management
"/tokenrefresh":
post:
summary: Exchanges a refresh token for an access token.
@ -158,3 +160,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Session management

6
api/client-server/message_pagination.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Rooms API"
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -129,3 +129,5 @@ paths:
403:
description: >
You aren't a member of the room.
tags:
- Room participation

41
api/client-server/old_sync.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Sync API"
title: "Matrix Client-Server Sync API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -60,7 +60,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
}
]
}
@ -84,9 +84,11 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
400:
description: "Bad pagination ``from`` parameter."
tags:
- Room participation
"/initialSync":
get:
summary: Get the user's current state.
@ -154,7 +156,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 343511809,
@ -166,7 +168,7 @@ paths:
"origin_server_ts": 1432804487480,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
}
],
"end": "s3456_9_0",
@ -184,13 +186,12 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.join_rules",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:localhost",
@ -199,7 +200,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@alice:localhost",
"type": "m.room.member",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 7148267200,
@ -211,7 +212,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.create",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 1622568720,
@ -226,7 +227,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@bob:localhost",
"type": "m.room.member",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
},
{
"age": 7148267004,
@ -250,7 +251,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.power_levels",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
}
],
"visibility": "private",
@ -285,7 +286,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
rooms:
type: array
items:
@ -332,7 +333,7 @@ paths:
type: object
title: RoomEvent
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
required: ["start", "end", "chunk"]
state:
type: array
@ -345,7 +346,7 @@ paths:
title: StateEvent
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
visibility:
type: string
enum: ["private", "public"]
@ -361,11 +362,13 @@ paths:
title: Event
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
required: ["room_id", "membership"]
required: ["end", "rooms", "presence"]
404:
description: There is no avatar URL for this user or this user does not exist.
tags:
- Room participation
"/events/{eventId}":
get:
summary: Get a single event by event ID.
@ -392,12 +395,14 @@ paths:
"msgtype": "m.text"
},
"room_id:": "!wfgy43Sg4a:matrix.org",
"user_id": "@bob:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
}
schema:
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
404:
description: The event was not found or you do not have permission to read this event.
tags:
- Room participation

17
api/client-server/presence.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Presence API"
title: "Matrix Client-Server Presence API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -67,6 +67,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Presence
get:
summary: Get this user's presence state.
description: |-
@ -85,8 +87,7 @@ paths:
application/json: |-
{
"presence": "unavailable",
"last_active_ago": 420845,
"status_msg": null
"last_active_ago": 420845
}
schema:
type: object
@ -107,6 +108,8 @@ paths:
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
tags:
- Presence
"/presence/list/{userId}":
post:
summary: Add or remove users from this presence list.
@ -161,6 +164,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Presence
get:
summary: Get presence events for this presence list.
description: |-
@ -205,4 +210,6 @@ paths:
type: object
title: PresenceEvent
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
tags:
- Presence

16
api/client-server/profile.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Profile API"
title: "Matrix Client-Server Profile API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -59,6 +59,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data
get:
summary: Get the user's display name.
description: |-
@ -88,6 +90,8 @@ paths:
description: The user's display name if they have set one.
404:
description: There is no display name for this user or this user does not exist.
tags:
- User data
"/profile/{userId}/avatar_url":
put:
summary: Set the user's avatar URL.
@ -129,6 +133,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data
get:
summary: Get the user's avatar URL.
description: |-
@ -158,6 +164,8 @@ paths:
description: The user's avatar URL if they have set one.
404:
description: There is no avatar URL for this user or this user does not exist.
tags:
- User data
"/profile/{userId}":
get:
summary: Get this user's profile information.
@ -192,4 +200,6 @@ paths:
type: string
description: The user's display name if they have set one.
404:
description: There is no profile information for this user or this user does not exist.
description: There is no profile information for this user or this user does not exist.
tags:
- User data

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

@ -6,7 +6,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/push/v1
basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -189,4 +189,5 @@ paths:
items:
type: string
description: A pushkey
tags:
- Push notifications

10
api/client-server/pusher.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Push API"
title: "Matrix Client-Server Push API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -60,7 +60,6 @@ paths:
Max length, 512 bytes.
kind:
type: string
enum: ["http", null]
description: |-
The kind of pusher to configure. ``"http"`` makes a pusher that
sends HTTP pokes. ``null`` deletes the pusher.
@ -114,7 +113,7 @@ paths:
description: |-
If true, the homeserver should add another pusher with the
given pushkey and App ID in addition to any others with
different user IDs. Otherwise, the Home Server must remove any
different user IDs. Otherwise, the homeserver must remove any
other pushers with the same App ID and pushkey for different
users. The default is ``false``.
required: ['profile_tag', 'kind', 'app_id', 'app_display_name',
@ -141,4 +140,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Push notifications

37
api/client-server/pushrules.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Push Rules API"
title: "Matrix Client-Server Push Rules API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -45,14 +45,14 @@ paths:
description: The ruleset for this profile tag.
title: Ruleset
allOf: [
"$ref": "definitions/push_ruleset.json"
"$ref": "definitions/push_ruleset.yaml"
]
global:
type: object
description: The global ruleset.
title: Ruleset
allOf: [
"$ref": "definitions/push_ruleset.json"
"$ref": "definitions/push_ruleset.yaml"
]
examples:
application/json: |-
@ -245,6 +245,8 @@ paths:
]
}
}
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}":
get:
summary: Retrieve a push rule.
@ -295,8 +297,10 @@ paths:
description: The push rule.
title: PushRule
allOf: [
"$ref": "definitions/push_rule.json"
"$ref": "definitions/push_rule.yaml"
]
tags:
- Push notifications
delete:
summary: Delete a push rule.
description: |-
@ -335,6 +339,8 @@ paths:
{}
schema:
type: object # empty json object
tags:
- Push notifications
put:
summary: Add or change a push rule.
description: |-
@ -414,7 +420,7 @@ paths:
items:
type: object
title: conditions
allOf: [ "$ref": "definitions/push_condition.json" ]
allOf: [ "$ref": "definitions/push_condition.yaml" ]
required: ["actions"]
responses:
200:
@ -438,6 +444,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}/enabled":
put:
summary: "Enable or disable a push rule."
@ -470,14 +478,21 @@ paths:
description: |
The identifier for the rule.
- in: body
name: <body>
name: body
description: |
Whether the push rule is enabled or not.
required: true
schema:
type: boolean
type: object
properties:
enabled:
type: boolean
description: Whether the push rule is enabled or not.
required: ["enabled"]
example: |-
true
{
"enabled": true
}
responses:
200:
description: The push rule was enabled or disabled.
@ -485,4 +500,6 @@ paths:
application/json: |-
{}
schema:
type: object # empty json object
type: object
tags:
- Push notifications

6
api/client-server/receipts.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 Receipts API"
title: "Matrix Client-Server Receipts API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -67,3 +67,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room participation

84
api/client-server/redaction.yaml Normal file
View file

@ -0,0 +1,84 @@
swagger: '2.0'
info:
title: "Matrix Client-Server message redaction API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
accessToken:
type: apiKey
description: The user_id or application service access_token
name: access_token
in: query
paths:
"/rooms/{roomId}/redact/{eventId}/{txnId}":
put:
summary: Strips all non-integrity-critical information out of an event.
description: |-
Strips all information out of an event which isn't critical to the
integrity of the server-side representation of the room.
This cannot be undone.
Users may redact their own events, and any user with a power level
greater than or equal to the `redact` power level of the room may
redact events there.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room from which to redact the event.
required: true
x-example: "!637q39766251:example.com"
- in: path
type: string
name: eventId
description: The ID of the event to redact
required: true
x-example: "bai2b1i9:matrix.org"
- in: path
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.
required: true
x-example: "37"
- in: body
name: body
schema:
type: object
example: |-
{
"reason": "Indecent material"
}
properties:
reason:
type: string
description: The reason for the event being redacted.
responses:
200:
description: "An ID for the redaction event."
examples:
application/json: |-
{
"event_id": "YUwQidLecu"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation

10
api/client-server/registration.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 Registration API"
title: "Matrix Client-Server Registration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -94,7 +94,7 @@ paths:
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
home_server:
type: string
description: The hostname of the Home Server on which the account has been registered.
description: The hostname of the homeserver on which the account has been registered.
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
@ -107,7 +107,7 @@ paths:
including after authentication if the requested user ID was registered
whilst the client was performing authentication.
Home Servers MUST perform the relevant checks and return these codes before
Homeservers MUST perform the relevant checks and return these codes before
performing `User-Interactive Authentication`_, although they may also return
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
@ -121,3 +121,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data

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

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 message event send API"
title: "Matrix Client-Server message event send API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -76,3 +76,5 @@ paths:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation

71
api/client-server/room_state.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 state event send API"
title: "Matrix Client-Server state event send API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -20,12 +20,12 @@ securityDefinitions:
paths:
"/rooms/{roomId}/state/{eventType}/{stateKey}":
put:
summary: Send a message event to the given room.
summary: Send a state event to the given room.
description: |
State events can be sent using this endpoint. These events will be
overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
match. If the state event has an empty ``state_key``, it can be
omitted from the path.
State events can be sent using this endpoint. This endpoint is
equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
with an empty `stateKey`. Previous state events with matching
`<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
Requests to this endpoint **cannot use transaction IDs**
like other ``PUT`` paths because they cannot be differentiated from the
@ -78,3 +78,60 @@ paths:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
put:
summary: Send a state event to the given room.
description: |
State events can be sent using this endpoint. These events will be
overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
match. This endpoint forces the state key to be the empty string.
Requests to this endpoint **cannot use transaction IDs**
like other ``PUT`` paths because they cannot be differentiated from the
``state_key``. Furthermore, ``POST`` is unsupported on state paths.
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to set the state in
required: true
x-example: "!636q39766251:example.com"
- in: path
type: string
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.name"
- in: body
name: body
schema:
type: object
example: |-
{
"name": "New name for the room"
}
responses:
200:
description: "An ID for the sent event."
examples:
application/json: |-
{
"event_id": "YUwRidLecu"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation

96
api/client-server/rooms.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Rooms API"
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -44,7 +44,7 @@ paths:
- in: path
type: string
name: stateKey
description: The key of the state to look up. Defaults to the empty string.
description: The key of the state to look up.
required: true
x-example: ""
responses:
@ -61,7 +61,49 @@ paths:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
get:
summary: Get the state identified by the type, with the empty state key.
description: |-
Looks up the contents of a state event in a room. If the user is
joined to the room then the state is taken from the current
state of the room. If the user has left the room then the state is
taken from the state of the room when they left.
This looks up the state event with the empty state key.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to look up the state in.
required: true
x-example: "!636q39766251:example.com"
- in: path
type: string
name: eventType
description: The type of state to look up.
required: true
x-example: "m.room.name"
responses:
200:
description: The content of the state event.
examples:
application/json: |-
{"name": "Example room name"}
schema:
type: object
404:
description: The room has no state with the given type or key.
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation
"/rooms/{roomId}/state":
get:
summary: Get all state events in the current state of a room.
@ -92,13 +134,12 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
@ -107,7 +148,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 7148267200,
@ -119,7 +160,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 1622568720,
@ -134,7 +175,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
},
{
"age": 7148267004,
@ -158,7 +199,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
}
]
schema:
@ -173,12 +214,13 @@ paths:
title: StateEvent
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation
"/rooms/{roomId}/initialSync":
get:
summary: Snapshot the current state of a room and its most recent messages.
@ -212,7 +254,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 343511809,
@ -224,7 +266,7 @@ paths:
"origin_server_ts": 1432804487480,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
}
],
"end": "s3456_9_0",
@ -242,13 +284,12 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
@ -257,7 +298,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 7148267200,
@ -269,7 +310,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 1622568720,
@ -284,7 +325,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
},
{
"age": 7148267004,
@ -308,7 +349,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
}
],
"visibility": "private",
@ -355,7 +396,7 @@ paths:
type: object
title: RoomEvent
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
required: ["start", "end", "chunk"]
state:
type: array
@ -368,7 +409,7 @@ paths:
title: StateEvent
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
visibility:
type: string
enum: ["private", "public"]
@ -383,13 +424,14 @@ paths:
title: Event
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
required: ["room_id"]
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation
"/rooms/{roomId}/members":
get:
summary: Get the m.room.member events for the room.
@ -416,7 +458,6 @@ paths:
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
@ -425,7 +466,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 1622568720,
@ -440,7 +481,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
}
]
}
@ -458,4 +499,5 @@ paths:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation

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

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Search API"
title: "Matrix Client-Server Search API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,7 +74,6 @@ paths:
type: object
title: Filter
description: |-
The filter to apply to search results.
This has the same format as v2 filter API.
order_by:
title: "Ordering"
@ -178,7 +177,7 @@ paths:
title: Event
description: The event that matched.
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
context:
type: object
title: Event Context
@ -218,7 +217,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
events_after:
type: array
title: Events After
@ -227,7 +226,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
state:
type: object
title: Current state
@ -238,7 +237,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
groups:
type: object
title: Groups
@ -309,7 +308,7 @@ paths:
"origin_server_ts": 1444298308034,
"room_id": "!qPewotXpIctQySfjSy:localhost",
"type": "m.room.message",
"user_id": "@test:localhost"
"sender": "@test:localhost"
}
}
]
@ -322,3 +321,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Search

22
api/client-server/sync.yaml
View file

@ -1,11 +1,11 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 sync API"
title: "Matrix Client-Server sync API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -114,7 +114,7 @@ paths:
``timeline``, if ``since`` is not given, or
``full_state`` is true).
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
timeline:
title: Timeline
type: object
@ -122,7 +122,7 @@ paths:
The timeline of messages and state changes in the
room.
allOf:
- $ref: "definitions/timeline_batch.json"
- $ref: "definitions/timeline_batch.yaml"
ephemeral:
title: Ephemeral
type: object
@ -131,7 +131,7 @@ paths:
recorded in the timeline or state of the room.
e.g. typing.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
account_data:
title: Account Data
type: object
@ -139,7 +139,7 @@ paths:
The private data that this user has attached to
this room.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
invite:
title: Invited Rooms
type: object
@ -166,7 +166,7 @@ paths:
delta against the archived ``state`` not the
``invite_state``.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
leave:
title: Left rooms
type: object
@ -182,7 +182,7 @@ paths:
description: |-
The state updates for the room up to the start of the timeline.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
timeline:
title: Timeline
type: object
@ -190,14 +190,14 @@ paths:
The timeline of messages and state changes in the
room up to the point when the user left.
allOf:
- $ref: "definitions/timeline_batch.json"
- $ref: "definitions/timeline_batch.yaml"
presence:
title: Presence
type: object
description: |-
The updates to the presence status of other users.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
examples:
application/json: |-
{
@ -310,3 +310,5 @@ paths:
"leave": {}
}
}
tags:
- Room participation

8
api/client-server/tags.yaml
View file

@ -6,7 +6,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -59,6 +59,8 @@ paths:
"pinned": {}
}
}
tags:
- User data
"/user/{userId}/rooms/{roomId}/tags/{tag}":
put:
summary: Add a tag to a room.
@ -107,6 +109,8 @@ paths:
examples:
application/json: |-
{}
tags:
- User data
delete:
summary: Remove a tag from the room.
description: |-
@ -145,3 +149,5 @@ paths:
examples:
application/json: |-
{}
tags:
- User data

10
api/client-server/third_party_membership.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Membership API for third party identifiers"
title: "Matrix Client-Server Room Membership API for third party identifiers"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -39,7 +39,7 @@ paths:
join that room.
If the identity server did know the Matrix user identifier for the
third party identifier, the home server will append a ``m.room.member``
third party identifier, the homeserver will append a ``m.room.member``
event to the room.
If the identity server does not know a Matrix user identifier for the
@ -62,7 +62,7 @@ paths:
- The matrix user ID who invited them to the room
If a token is requested from the identity server, the home server will
If a token is requested from the identity server, the homeserver will
append a ``m.room.third_party_invite`` event to the room.
.. _joining rooms section: `invite-by-user-id-endpoint`_
@ -121,3 +121,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership

7
api/client-server/typing.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Typing API"
title: "Matrix Client-Server Typing API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,4 +74,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room participation

9
api/client-server/voip.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Voice over IP API"
title: "Matrix Client-Server Voice over IP API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -18,7 +18,7 @@ securityDefinitions:
name: access_token
in: query
paths:
"/turnServer":
"/voip/turnServer":
get:
summary: Obtain TURN server credentials.
description: |-
@ -65,4 +65,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- VOIP

48
attic/v1_registration_login.rst
View file

@ -1,17 +1,17 @@
Registration and Login
----------------------
Clients must register with a home server in order to use Matrix. After
Clients must register with a homeserver in order to use Matrix. After
registering, the client will be given an access token which must be used in ALL
requests to that home server as a query parameter 'access_token'.
requests to that homeserver as a query parameter 'access_token'.
If the client has already registered, they need to be able to login to their
account. The home server may provide many different ways of logging in, such as
account. The homeserver may provide many different ways of logging in, such as
user/password auth, login via a social network (OAuth2), login by confirming a
token sent to their email address, etc. This specification does not define how
home servers should authorise their users who want to login to their existing
homeservers should authorise their users who want to login to their existing
accounts, but instead defines the standard interface which implementations
should follow so that ANY client can login to ANY home server. Clients login
should follow so that ANY client can login to ANY homeserver. Clients login
using the |login|_ API. Clients register using the |register|_ API.
Registration follows the same general procedure as login, but the path requests
are sent to and the details contained in them are different.
@ -26,7 +26,7 @@ In order to determine up-front what the server's requirements are, the client
can request from the server a complete description of all of its acceptable
flows of the registration or login process. It can then inspect the list of
returned flows looking for one for which it believes it can complete all of the
required stages, and perform it. As each home server may have different ways of
required stages, and perform it. As each homeserver may have different ways of
logging in, the client needs to know how they should login. All distinct login
stages MUST have a corresponding ``type``. A ``type`` is a namespaced string
which details the mechanism for logging in.
@ -64,12 +64,12 @@ ID and a new access token MUST be returned::
"access_token": "abcdef0123456789"
}
The ``user_id`` key is particularly useful if the home server wishes to support
The ``user_id`` key is particularly useful if the homeserver wishes to support
localpart entry of usernames (e.g. "user" rather than "@user:matrix.org"), as
the client may not be able to determine its ``user_id`` in this case.
If the flow has multiple stages to it, the home server may wish to create a
session to store context between requests. If a home server responds with a
If the flow has multiple stages to it, the homeserver may wish to create a
session to store context between requests. If a homeserver responds with a
``session`` key to a request, clients MUST submit it in subsequent requests
until the flow is completed::
@ -99,7 +99,7 @@ To respond to this type, reply with::
"password": "<password>"
}
The home server MUST respond with either new credentials, the next stage of the
The homeserver MUST respond with either new credentials, the next stage of the
login process, or a standard error response.
Captcha-based
@ -123,7 +123,7 @@ To respond to this type, reply with::
Recaptcha.get_challenge();
Recaptcha.get_response();
The home server MUST respond with either new credentials, the next stage of the
The homeserver MUST respond with either new credentials, the next stage of the
login process, or a standard error response.
OAuth2-based
@ -146,24 +146,24 @@ The server MUST respond with::
"uri": <Authorization Request URI OR service selection URI>
}
The home server acts as a 'confidential' client for the purposes of OAuth2. If
The homeserver acts as a 'confidential' client for the purposes of OAuth2. If
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
service which the homeserver accepts when logging in, this indirection can be
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
auth code. Home servers can choose any path for the ``redirect URI``. The
auth code. Homeservers can choose any path for the ``redirect URI``. The
client should visit the ``redirect URI``, which will then finish the OAuth2
login process, granting the home server an access token for the chosen service.
When the home server gets this access token, it verifies that the cilent has
login process, granting the homeserver an access token for the chosen service.
When the homeserver 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 homeserver accepts OAuth2 from Google, it would return the
Authorization Request URI for Google::
{
@ -171,7 +171,7 @@ Authorization Request URI for Google::
client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos"
}
The client then visits this URI and authorizes the home server. The client then
The client then visits this URI and authorizes the homeserver. The client then
visits the REDIRECT_URI with the auth code= query parameter which returns::
{
@ -195,7 +195,7 @@ To respond to this type, reply with::
"email": "<email address>"
}
After validating the email address, the home server MUST send an email
After validating the email address, the homeserver MUST send an email
containing an authentication code and return::
{
@ -212,7 +212,7 @@ code::
"code": "<code in email sent>"
}
The home server MUST respond to this with either new credentials, the next
The homeserver MUST respond to this with either new credentials, the next
stage of the login process, or a standard error response.
Email-based (url)
@ -231,7 +231,7 @@ To respond to this type, reply with::
"email": "<email address>"
}
After validating the email address, the home server MUST send an email
After validating the email address, the homeserver MUST send an email
containing an authentication URL and return::
{
@ -247,7 +247,7 @@ client should perform another request::
"session": "<session id>"
}
The home server MUST respond to this with either new credentials, the next
The homeserver MUST respond to this with either new credentials, the next
stage of the login process, or a standard error response.
A common client implementation will be to periodically poll until the link is
@ -264,7 +264,7 @@ Email-based (identity server)
Prior to submitting this, the client should authenticate with an identity
server. After authenticating, the session information should be submitted to
the home server.
the homeserver.
To respond to this type, reply with::
@ -293,7 +293,7 @@ of a previous login stage::
"next": "<next login type>"
}
If a home server implements N-factor authentication, it MUST respond with all
If a homeserver implements N-factor authentication, it MUST respond with all
``stages`` when initially queried for their login requirements::
{

37
changelogs/client_server.rst Normal file
View file

@ -0,0 +1,37 @@
r0
===
This is the first release of the client-server specification. It is largely a dump of what has currently been implemented, and there are several inconsistencies.
An upcoming minor release will deprecate many of these inconsistencies, and they will be removed in the next major release.
Since the draft stage, the following major changes have been made:
- /api/v1 and /v2_alpha path segments have been replaced with the major version of the release (i.e. 'r0').
- Some POST versions of APIs with both POST and PUT have been removed.
- The specification has been split into one specification per API. This is the client-server API. The server-server API can be found documented separately.
- All APIs are now documented using Swagger
- The following modules have been added:
- Content repository
- Instant messaging
- Push notification
- History visibility
- Search
- Invites based on third party identifiers
- Room tagging
- Guest access
- Client config
- The following APIs were added:
- ``/sync``
- ``/publicRooms``
- ``/rooms/{roomId}/forget``
- ``/admin/whois``
- ``/rooms/{roomId}/redact``
- ``/user/{userId}/filter``
- The following APIs have been significantly modified:
- Invitations now contain partial room state
- Invitations can now be rejected
- ``/directory``
- The following events have been added:
- ``m.room.avatar``
- Example signed json is included for reference
- Commentary on display name calculation was added

8
drafts/ancient_federated_versioning_design_notes.rst
View file

@ -1,11 +1,11 @@
Versioning is, like, hard for backfilling backwards because of the number of Home Servers involved.
Versioning is, like, hard for backfilling backwards because of the number of homeservers involved.
The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis.
The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis.
When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C.
Problems with opaque version strings:
- How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote home server at a time.
- How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote homeserver at a time.
If you have multiple transactions sent at once, then you might drop one transaction, receive another with a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION.
- How do you do backfilling? A version string defines a point in a stream w.r.t. a single home server, not a point in the context.
- How do you do backfilling? A version string defines a point in a stream w.r.t. a single homeserver, not a point in the context.
We only need to store the ends of the directed graph, we DO NOT need to do the whole one table of nodes and one of edges.

42
drafts/as-http-api.rst
View file

@ -13,9 +13,9 @@ Application Services HTTP API
.. sectnum::
Application Service -> Home Server
Application Service -> Homeserver
----------------------------------
This contains home server APIs which are used by the application service.
This contains homeserver APIs which are used by the application service.
Registration API ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -34,7 +34,7 @@ Output:
Side effects:
- The HS will start delivering events to the URL base specified if this 200s.
API called when:
- The application service wants to register with a brand new home server.
- The application service wants to register with a brand new homeserver.
Notes:
- An application service can state whether they should be the only ones who
can manage a specified namespace. This is referred to as an "exclusive"
@ -100,7 +100,7 @@ Notes:
Unregister API ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~~~~~
This API unregisters a previously registered AS from the home server.
This API unregisters a previously registered AS from the homeserver.
Inputs:
- AS token
@ -122,9 +122,9 @@ API called when:
}
Home Server -> Application Service
Homeserver -> Application Service
----------------------------------
This contains application service APIs which are used by the home server.
This contains application service APIs which are used by the homeserver.
User Query ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~
@ -152,9 +152,9 @@ Notes:
- This is deemed more flexible than alternative methods (e.g. returning a JSON blob with the
user's display name and get the HS to provision the user).
Retry notes:
- The home server cannot respond to the client's request until the response to
- The homeserver cannot respond to the client's request until the response to
this API is obtained from the AS.
- Recommended that home servers try a few times then time out, returning a
- Recommended that homeservers try a few times then time out, returning a
408 Request Timeout to the client.
::
@ -199,9 +199,9 @@ Notes:
style JSON blob and get the HS to provision the room). It also means that the AS knows
the room ID -> alias mapping.
Retry notes:
- The home server cannot respond to the client's request until the response to
- The homeserver cannot respond to the client's request until the response to
this API is obtained from the AS.
- Recommended that home servers try a few times then time out, returning a
- Recommended that homeservers try a few times then time out, returning a
408 Request Timeout to the client.
::
@ -236,13 +236,13 @@ Data flows:
::
Typical
HS ---> AS : Home server sends events with transaction ID T.
HS ---> AS : Homeserver sends events with transaction ID T.
<--- : AS sends back 200 OK.
AS ACK Lost
HS ---> AS : Home server sends events with transaction ID T.
HS ---> AS : Homeserver sends events with transaction ID T.
<-/- : AS 200 OK is lost.
HS ---> AS : Home server retries with the same transaction ID of T.
HS ---> AS : Homeserver retries with the same transaction ID of T.
<--- : AS sends back 200 OK. If the AS had processed these events
already, it can NO-OP this request (and it knows if it is the same
events based on the transacton ID).
@ -253,15 +253,15 @@ Retry notes:
- Since ASes by definition cannot alter the traffic being passed to it (unlike
say, a Policy Server), these requests can be done in parallel to general HS
processing; the HS doesn't need to block whilst doing this.
- Home servers should use exponential backoff as their retry algorithm.
- Home servers MUST NOT alter (e.g. add more) events they were going to
- Homeservers should use exponential backoff as their retry algorithm.
- Homeservers MUST NOT alter (e.g. add more) events they were going to
send within that transaction ID on retries, as the AS may have already
processed the events.
Ordering notes:
- The events sent to the AS should be linearised, as they are from the event
stream.
- The home server will need to maintain a queue of transactions to send to
- The homeserver will need to maintain a queue of transactions to send to
the AS.
::
@ -336,7 +336,7 @@ Notes:
Server admin style permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The home server needs to give the application service *full control* over its
The homeserver needs to give the application service *full control* over its
namespace, both for users and for room aliases. This means that the AS should
be able to create/edit/delete any room alias in its namespace, as well as
create/delete any user in its namespace. No additional API changes need to be
@ -451,15 +451,15 @@ Examples
IRC
~~~
Pre-conditions:
- Server admin stores the AS token "T_a" on the home server.
- Home server has a token "T_h".
- Home server has the domain "hsdomain.com"
- Server admin stores the AS token "T_a" on the homeserver.
- Homeserver has a token "T_h".
- Homeserver has the domain "hsdomain.com"
1. Application service registration
::
AS -> HS: Registers itself with the home server
AS -> HS: Registers itself with the homeserver
POST /register
{
url: "https://someapp.com/matrix",

6
drafts/erikj_federation.rst
View file

@ -237,7 +237,7 @@ Domain specific string
``room_id``
A domain specific string with prefix ``!`` that is static across all events
in a graph and uniquely identifies it. The ``domain`` should be that of the
home server that created the room (i.e., the server that generated the
homeserver that created the room (i.e., the server that generated the
first ``m.room.create`` event).
``sender``
@ -246,7 +246,7 @@ Domain specific string
User Id
A domain specific string with prefix ``@`` representing a user account. The
``domain`` is the home server of the user and is the server used to contact
``domain`` is the homeserver of the user and is the server used to contact
the user.
Joining a room
@ -280,7 +280,7 @@ can then process the join event itself.
Inviting a user
---------------
To invite a remote user to a room we need their home server to sign the invite
To invite a remote user to a room we need their homeserver to sign the invite
event. This is done by sending the event to the remote server, which then signs
the event, before distributing the invite to other servers.

54
drafts/general_api.rst
View file

@ -61,7 +61,7 @@ This version will change the path prefix for HTTP:
- Version 2: ``/_matrix/client/v2``
Note the lack of the ``api`` segment. This is for consistency between other
home server path prefixes.
homeserver path prefixes.
Terminology:
- ``Chunk token`` : An opaque string which can be used to return another chunk
@ -169,16 +169,16 @@ Outputs:
``content`` key. Deleted message events are ``m.room.redaction`` events.
- New position in the stream. (chunk token)
State Events Ordering Notes:
- Home servers may receive state events over federation that are superceded by
state events previously sent to the client. The home server *cannot* send
- Homeservers may receive state events over federation that are superceded by
state events previously sent to the client. The homeserver *cannot* send
these events to the client else they would end up erroneously clobbering the
superceding state event.
- As a result, the home server reserves the right to omit sending state events
- As a result, the homeserver reserves the right to omit sending state events
which are known to be superceded already.
- This may result in missed *state* events. However, the state of the room will
always be eventually consistent.
Message Events Ordering Notes:
- Home servers may receive message events over federation that happened a long
- Homeservers may receive message events over federation that happened a long
time ago. The client may or may not be interested in these message events.
- For clients which do not store scrollback for a room (they discard events
after processing them), this is not a problem as they only care about the
@ -191,11 +191,11 @@ Message Events Ordering Notes:
- The event, when it comes down the stream, will indicate which event it comes
after.
Rejected events:
- A home server may find out via federation that it should not have accepted
- A homeserver may find out via federation that it should not have accepted
an event (e.g. to send a message/state event in a room). For example, it may
send an event to another home server and receive an auth event stating
send an event to another homeserver and receive an auth event stating
that the event should not have been sent.
- If this happens, the home server will send a ``m.room.redaction`` for the
- If this happens, the homeserver will send a ``m.room.redaction`` for the
event in question. This will be a local server event (not shared with other
servers).
- If the event was a state event, it will synthesise a new state event to
@ -206,7 +206,7 @@ Unknown rooms:
- You could receive events for rooms you are unaware of (e.g. you didn't do an
initial sync, or your HS lost its database and is told from another HS that
they are in this room). How do you handle this?
- The simplest option would be to redo the initial sync with a filter on the
- The simplest option would be to redo the initial sync with a filter on the
room ID you're unaware of. This would retrieve the room state so you can
display the room.
What data flows does it address:
@ -291,7 +291,7 @@ Scrollback API ``[Draft]``
but as a purely informational display thing it would be nice.
Additional Inputs:
- flag to say if the home server should do a backfill over federation
- flag to say if the homeserver should do a backfill over federation
Additional Outputs:
- whether there are more events on the local HS / over federation.
What data flows does it address:
@ -313,7 +313,7 @@ Additional Outputs:
Room Alias API ``[Draft]``
--------------------------
This provides mechanisms for creating and removing room aliases for a room on a
home server. Typically, any user in a room can make an alias for that room. The
homeserver. Typically, any user in a room can make an alias for that room. The
alias creator (or anyone in the room?) can delete that alias. Server admins can
also delete any alias on their server.
@ -323,7 +323,7 @@ Inputs:
- Room Alias
Output:
- Room ID
- List of home servers to join via.
- List of homeservers to join via.
Mapping a room to an alias:
@ -334,7 +334,7 @@ Inputs:
Output:
- Room alias
Notes:
- The home server may add restrictions e.g. the user must be in the room.
- The homeserver may add restrictions e.g. the user must be in the room.
Deleting a mapping:
@ -347,11 +347,11 @@ Output:
Published room list API ``[Draft]``
-----------------------------------
This provides mechanisms for searching for published rooms on a home server.
This provides mechanisms for searching for published rooms on a homeserver.
Inputs:
- Search text (e.g. room alias/name/topic to search on)
- Home server to search on (this may just be the URL hit for HTTP)
- Homeserver to search on (this may just be the URL hit for HTTP)
- Any existing pagination token, can be missing if this is the first hit.
- Limit for pagination
Output:
@ -378,7 +378,7 @@ Notes:
User Profile API ``[Draft]``
----------------------------
Every user on a home server has a profile. This profile is effectively a
Every user on a homeserver has a profile. This profile is effectively a
key-value store scoped to a user ID. It can include an ``avatar_url``,
``displayname`` and other metadata. Updates to a profile should propagate to
other interested users.
@ -435,7 +435,7 @@ This had a number of problems associated with it:
flicker.
- Name/avatar changes created more ``m.room.member`` events which meant
they needed to be included in the auth chains for federation. This
created long auth chains which is suboptimal since home servers need
created long auth chains which is suboptimal since homeservers need
to store the auth chains forever.
These problems can be resolved by creating an ``m.room.member.profile``
@ -448,7 +448,7 @@ However, this introduces its own set of problems, namely flicker. The
client would receive the ``m.room.member`` event first, followed by
the ``m.room.member.profile`` event, which could cause a flicker. In
addition, federation may not send both events in a single transaction,
resulting in missing information on the receiving home server.
resulting in missing information on the receiving homeserver.
For federation, these problems can be resolved by sending the
``m.room.member`` event as they are in v1 (with ``displayname`` and
@ -457,7 +457,7 @@ they cannot be in the ``unsigned`` part of the event. The receiving home
server will then extract these keys and create a server-generated
``m.room.member.profile`` event. To avoid confusion with duplicate
information, the ``avatar_url`` and ``displayname`` keys should be
removed from the ``m.room.member`` event by the receiving home server.
removed from the ``m.room.member`` event by the receiving homeserver.
When a client requests these events (either from the event stream
or from an initial sync), the server will send the generated
``m.room.member.profile`` event under the ``unsigned.profile`` key of the
@ -840,17 +840,17 @@ information per device to all other users just redirects the union problem to
the client, which will commonly be presenting this information as an icon
alongside the user.
When a client hits the event stream, the home server can treat the user as
When a client hits the event stream, the homeserver can treat the user as
"online". This behaviour should be able to be overridden to avoid flicker
during connection losses when the client is appear offline (e.g. device is
appear offline > goes into a tunnel > server times out > device regains
connection and hits the event stream forcing the device online before the
"appear offline" state can be set). When the client has not hit the event
stream for a certain period of time, the home server can treat the user as
stream for a certain period of time, the homeserver can treat the user as
"offline". The user can also set a global *per-user* appear offline flag.
The user should also be able to set their presence state via a direct API,
without having to hit the event stream. The home server will set a timer when
without having to hit the event stream. The homeserver will set a timer when
the connection ends, after which it will set that device to offline.
As the idle flag and online state is determined per device, there needs to be a
@ -970,12 +970,12 @@ the hashes the same is the best as that means clients do not need to request
the capabilities for the given hash.
On first signup, the client will attempt to send the hash and be most likely
refused by the home server as it does not know the full capability set for that
refused by the homeserver as it does not know the full capability set for that
hash. The client will then have to upload the full capability set to the home
server. The client will then be able to send the hash as normal.
When a client receives a hash, the client will either recognise the hash or
will have to request the capability set from their home server:
will have to request the capability set from their homeserver:
Inputs:
- Hash
@ -1070,7 +1070,7 @@ Main use cases for ``updates``:
- Call signalling (child events are ICE candidates, answer to the offer, and
termination)
- *Local* Delivery/Read receipts : "Local" means they are not shared with other
users on the same home server or via federation but *are* shared between
users on the same homeserver or via federation but *are* shared between
clients for the same user; useful for push notifications, read count markers,
etc. This is done to avoid the ``n^2`` problem for sending receipts, where
the vast majority of traffic tends towards sending more receipts.
@ -1168,11 +1168,11 @@ Events (breaking changes; event version 2) ``[Draft]``
when dealing with custom event types. E.g. ``_custom.event`` would allow
anything in the state key, ``_@custom.event`` would only allow user IDs in
the state key, etc.
- s/user_id/sender/g given that home servers can send events, not just users.
- s/user_id/sender/g given that homeservers can send events, not just users.
Server-generated events ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Home servers may want to send events to their local clients or to other home
Homeservers may want to send events to their local clients or to other home
servers e.g. for server status notifications.
These events look like regular events but have a server domain name as the

14
drafts/human-id-rules.rst
View file

@ -13,9 +13,9 @@ phishing/spoofing of IDs, commonly known as a homograph attack.
Web browers encountered this problem when International Domain Names were
introduced. A variety of checks were put in place in order to protect users. If
an address failed the check, the raw punycode would be displayed to
disambiguate the address. Similar checks are performed by home servers in
disambiguate the address. Similar checks are performed by homeservers in
Matrix. However, Matrix does not use punycode representations, and so does not
show raw punycode on a failed check. Instead, home servers must outright reject
show raw punycode on a failed check. Instead, homeservers must outright reject
these misleading IDs.
Types of human-readable IDs
@ -48,12 +48,12 @@ Checks
Rejecting
---------
- Home servers MUST reject room aliases which do not pass the check, both on
- Homeservers MUST reject room aliases which do not pass the check, both on
GETs and PUTs.
- Home servers MUST reject user ID localparts which do not pass the check, both
- Homeservers MUST reject user ID localparts which do not pass the check, both
on creation and on events.
- Any home server whose domain does not pass this check, MUST use their punycode
domain name instead of the IDN, to prevent other home servers rejecting you.
- Any homeserver whose domain does not pass this check, MUST use their punycode
domain name instead of the IDN, to prevent other homeservers rejecting you.
- Error code is ``M_FAILED_HUMAN_ID_CHECK``. (generic enough for both failing
due to homograph attacks, and failing due to including ``:`` s, etc)
- Error message MAY go into further information about which characters were
@ -74,7 +74,7 @@ Other considerations
- High security: Outright rejection of the ID at the point of creation /
receiving event. Point of creation rejection is preferable to avoid the ID
entering the system in the first place. However, malicious HSes can just
allow the ID. Hence, other home servers must reject them if they see them in
allow the ID. Hence, other homeservers must reject them if they see them in
events. Client never sees the problem ID, provided the HS is correctly
implemented.
- High security decided; client doesn't need to worry about it, no additional

146
drafts/markjh_end_to_end.rst
View file

@ -1,146 +0,0 @@
Goals of Key-Distribution in Matrix
===================================
* No Central Authority: Users should not need to trust a central authority
when determining the authenticity of keys.
* Easy to Add New Devices: It should be easy for a user to start using a
new device.
* Possible to discover MITM: It should be possible for a user to determine if
they are being MITM.
* Lost Devices: It should be possible for a user to recover if they lose all
their devices.
* No Copying Keys: Keys should be per device and shouldn't leave the device
they were created on.
A Possible Mechanism for Key Distribution
=========================================
Basic API for setting up keys on a server:
https://github.com/matrix-org/matrix-doc/pull/24
Client shouldn't trust the keys unless they have been verified, e.g by
comparing fingerprints.
If a user adds a new device it should some yet to be specified protocol
communicate with an old device and obtain a cross-signature from the old
device for its public key.
The new device can then present the cross-signed key to all the devices
that the user is in conversations with. Those devices should then include
the new device into those conversations.
If the user cannot cross-sign the new key, e.g. because their old device
is lost or stolen. Then they will need to reauthenticate their conversations
out of band, e.g by comparing fingerprints.
Goals of End-to-end encryption in Matrix
========================================
* Access to Chat History: Users should be able to see the history of a
conversation on a new device. User should be able to control who can
see their chat history and how much of the chat history they can see.
* Forward Secrecy of Discarded Chat History: Users should be able to discard
history from their device, once they have discarded the history it should be
impossible for an adversary to recover that history.
* Forward Secrecy of Future Messages: Users should be able to recover from
disclosure of the chat history on their device.
* Deniablity of Chat History: It should not be possible to prove to a third
party that a given user sent a message.
* Authenticity of Chat History: It should be possible to prove amoungst
the members of a chat that a message sent by a user was authored by that
user.
Bonus Goals:
* Traffic Analysis: It would be nice if the protocol was resilient to traffic
or metadata analysis. However it's not something we want to persue if it
harms the usability of the protocol. It might be cool if there was a
way for the user to could specify the trade off between performance and
resilience to traffic analysis that they wanted.
A Possible Design for Group Chat using Olm
==========================================
Protecting the secrecy of history
---------------------------------
Each message sent by a client has a 32-bit counter. This counter increments
by one for each message sent by the client. This counter is used to advance a
ratchet. The ratchet is split into a vector four 256-bit values,
:math:`R_{n,j}` for :math:`j \in {0,1,2,3}`. The ratchet can be advanced as
follows:
.. math::
\begin{align}
R_{2^24n,0} &= H_0\left(R_{2^24(i-1),0}\right) \\
R_{2^24n,1} &= H_1\left(R_{2^24(i-1),0}\right) \\
R_{2^24n,2} &= H_2\left(R_{2^24(i-1),0}\right) \\
R_{2^24n,3} &= H_3\left(R_{2^24(i-1),0}\right) \\
R_{2^16n,1} &= H_1\left(R_{2^16(i-1),1}\right) \\
R_{2^16n,2} &= H_2\left(R_{2^16(i-1),1}\right) \\
R_{2^16n,3} &= H_3\left(R_{2^16(i-1),1}\right) \\
R_{2^8i,2} &= H_2\left(R_{2^8(i-1),2}\right) \\
R_{2^8i,3} &= H_3\left(R_{2^8(i-1),2}\right) \\
R_{i,3} &= H_3\left(R_{(i-1),3}\right)
\end{align}
Where :math:`H_0`, :math:`H_1`, :math:`H_2`, and :math:`H_3`
are different hash functions. For example
:math:`H_0` could be :math:`HMAC\left(X,\text{"\textbackslash x00"}\right)` and
:math:`H_1` could be :math:`HMAC\left(X,\text{"\textbackslash x01"}\right)`.
So every :math:`2^24` iterations :math:`R_{n,1}` is reseeded from :math:`R_{n,0}`.
Every :math:`2^16` iterations :math:`R_{n,2}` is reseeded from :math:`R_{n,1}`.
Every :math:`2^8` iterations :math:`R_{n,3}` is reseeded from :math:`R_{n,2}`.
This scheme allows the ratchet to be advanced an arbitrary amount forwards
while needing only 1024 hash computations.
This the value of the ratchet is hashed to generate the keys used to encrypt
each mesage.
A client can decrypt chat history onwards from the earliest value of the
ratchet it is aware of. But cannot decrypt history from before that point
without reversing the hash function.
This allows a client to share its ability to decrypt chat history with another
from a point in the conversation onwards by giving a copy of the ratchet at
that point in the conversation.
A client can discard history by advancing a ratchet to beyond the last message
they want to discard and then forgetting all previous values of the ratchet.
Proving and denying the authenticity of history
-----------------------------------------------
Client sign the messages they send using a Ed25519 key generated per
conversation. That key, along with the ratchet key, is distributed
to other clients using 1:1 olm ratchets. Those 1:1 ratchets are started using
Triple Diffie-Hellman which provides authenticity of the messages to the
participants and deniability of the messages to third parties. Therefore
any keys shared over those keys inherit the same levels of deniability and
authenticity.
Protecting the secrecy of future messages
-----------------------------------------
A client would need to generate new keys if it wanted to prevent access to
messages beyond a given point in the conversation. It must generate new keys
whenever someone leaves the room. It should generate new keys periodically
anyway.
The frequency of key generation in a large room may need to be restricted to
keep the frequency of messages broadcast over the individual 1:1 channels
low.

12
drafts/model/presence.rst
View file

@ -5,14 +5,14 @@ A simple implementation of presence messaging has the ability to cause a large
amount of Internet traffic relating to presence updates. In order to minimise
the impact of such a feature, the following observations can be made:
* There is no point in a Home Server polling status for peers in a user's
* There is no point in a homeserver polling status for peers in a user's
presence list if the user has no clients connected that care about it.
* It is highly likely that most presence subscriptions will be symmetric - a
given user watching another is likely to in turn be watched by that user.
* It is likely that most subscription pairings will be between users who share
at least one Room in common, and so their Home Servers are actively
at least one Room in common, and so their homeservers are actively
exchanging message PDUs or transactions relating to that Room.
* Presence update messages do not need realtime guarantees. It is acceptable to
@ -25,7 +25,7 @@ promise to send them when required. Rather than actively polling for the
current state all the time, HSes can rely on their relative stability to only
push updates when required.
A Home Server should not rely on the longterm validity of this presence
A homeserver should not rely on the longterm validity of this presence
information, however, as this would not cover such cases as a user's server
crashing and thus failing to inform their peers that users it used to host are
no longer available online. Therefore, each promise of future updates should
@ -33,7 +33,7 @@ carry with a timeout value (whether explicit in the message, or implicit as some
defined default in the protocol), after which the receiving HS should consider
the information potentially stale and request it again.
However, because of the likelihood that two home servers are exchanging messages
However, because of the likelihood that two homeservers are exchanging messages
relating to chat traffic in a room common to both of them, the ongoing receipt
of these messages can be taken by each server as an implicit notification that
the sending server is still up and running, and therefore that no status changes
@ -98,7 +98,7 @@ The data model presented here puts the following requirements on the APIs:
Client-Server
-------------
Requests that a client can make to its Home Server
Requests that a client can make to its homeserver
* get/set current presence state
Basic enumeration + ability to set a custom piece of text
@ -128,7 +128,7 @@ Requests that a client can make to its Home Server
Server-Server
-------------
Requests that Home Servers make to others
Requests that homeservers make to others
* request permission to add a user to presence list

16
drafts/model/profiles.rst
View file

@ -9,7 +9,7 @@ Overview
========
Internally within Synapse users are referred to by an opaque ID, which consists
of some opaque localpart combined with the domain name of their home server.
of some opaque localpart combined with the domain name of their homeserver.
Obviously this does not yield a very nice user experience; users would like to
see readable names for other users that are in some way meaningful to them.
Additionally, users like to be able to publish "profile" details to inform other
@ -59,7 +59,7 @@ servers should be accounted for here.]]
Visibility Permissions
======================
A home server implementation could offer the ability to set permissions on
A homeserver implementation could offer the ability to set permissions on
limited visibility of those fields. When another user requests access to the
target user's profile, their own identity should form part of that request. The
HS implementation can then decide which fields to make available to the
@ -130,12 +130,12 @@ namespace to allocate names into.
It would also be nice from a user experience perspective if the profile that a
given name links to can also declare that name as part of its metadata.
Furthermore as a security and consistency perspective it would be nice if each
end (the directory server and the user's home server) check the validity of the
end (the directory server and the user's homeserver) check the validity of the
mapping in some way. This needs investigation from a security perspective to
ensure against spoofing.
One such model may be that the user starts by declaring their intent to use a
given user name link to their home server, which then contacts the directory
given user name link to their homeserver, which then contacts the directory
service. At some point later (maybe immediately for "public open FCFS servers",
maybe after some kind of human intervention for verification) the DS decides to
honour this link, and includes it in its served output. It should also tell the
@ -170,7 +170,7 @@ balancing choice on behalf of the user who would choose, or not, to make use of
such a feature to publish their information.
Additionally, unless some form of strong end-to-end user-based encryption is
used, a user of ACLs for information privacy has to trust other home servers not
used, a user of ACLs for information privacy has to trust other homeservers not
to lie about the identify of the user requesting access to the Profile.
@ -182,7 +182,7 @@ The data model presented here puts the following requirements on the APIs:
Client-Server
-------------
Requests that a client can make to its Home Server
Requests that a client can make to its homeserver
* get/set my Display Name
This should return/take a simple "text/plain" field
@ -207,7 +207,7 @@ TODO(paul): At some later stage we should consider the API for:
Server-Server
-------------
Requests that Home Servers make to others
Requests that homeservers make to others
* get a user's Display Name / Avatar
@ -221,7 +221,7 @@ Requests that Home Servers make to others
Room Event PDU Types
--------------------
Events that are pushed from Home Servers to other Home Servers or clients.
Events that are pushed from homeservers to other homeservers or clients.
* user Display Name change

12
drafts/model/room-join-workflow.rst
View file

@ -8,7 +8,7 @@ Discovery
=========
To join a room, a user has to discover the room by some mechanism in order to
obtain the (opaque) Room ID and a candidate list of likely home servers that
obtain the (opaque) Room ID and a candidate list of likely homeservers that
contain it.
Sending an Invitation
@ -21,7 +21,7 @@ The inviter's HS sets the membership status of the invitee to "invited" in the
"m.members" state key by sending a state update PDU. The HS then broadcasts this
PDU among the existing members in the usual way. An invitation message is also
sent to the invited user, containing the Room ID and the PDU ID of this
invitation state change and potentially a list of some other home servers to use
invitation state change and potentially a list of some other homeservers to use
to accept the invite. The user's client can then choose to display it in some
way to alert the user.
@ -34,7 +34,7 @@ Directory Service
Alternatively, the user may discover the channel via a directory service; either
by performing a name lookup, or some kind of browse or search acitivty. However
this is performed, the end result is that the user's home server requests the
this is performed, the end result is that the user's homeserver requests the
Room ID and candidate list from the directory service.
[[TODO(paul): At present, no API has been designed or described for this
@ -44,14 +44,14 @@ directory service]]
Joining
=======
Once the ID and home servers are obtained, the user can then actually join the
Once the ID and homeservers are obtained, the user can then actually join the
room.
Accepting an Invite
-------------------
If a user has received and accepted an invitation to join a room, the invitee's
home server can now send an invite acceptance message to a chosen candidate
homeserver can now send an invite acceptance message to a chosen candidate
server from the list given in the invitation, citing also the PDU ID of the
invitation as "proof" of their invite. (This is required as due to late message
propagation it could be the case that the acceptance is received before the
@ -85,7 +85,7 @@ can instead post a "knock" message, which informs other members of the room that
the would-be joiner wishes to become a member and sets their membership value to
"knocked". If any of them wish to accept this, they can then send an invitation
in the usual way described above. Knowing that the user has already knocked and
expressed an interest in joining, the invited user's home server should
expressed an interest in joining, the invited user's homeserver should
immediately accept that invitation on the user's behalf, and go on to join the
room in the usual way.

20
drafts/model/rooms.rst
View file

@ -18,19 +18,19 @@ users, and other management and miscellaneous metadata), and a message history.
Room Identity and Naming
========================
Rooms can be arbitrarily created by any user on any home server; at which point
the home server will sign the message that creates the channel, and the
Rooms can be arbitrarily created by any user on any homeserver; at which point
the homeserver will sign the message that creates the channel, and the
fingerprint of this signature becomes the strong persistent identify of the
room. This now identifies the room to any home server in the network regardless
room. This now identifies the room to any homeserver in the network regardless
of its original origin. This allows the identify of the room to outlive any
particular server. Subject to appropriate permissions [to be discussed later],
any current member of a room can invite others to join it, can post messages
that become part of its history, and can change the persistent state of the room
(including its current set of permissions).
Home servers can provide a directory service, allowing a lookup from a
Homeservers can provide a directory service, allowing a lookup from a
convenient human-readable form of room label to a room ID. This mapping is
scoped to the particular home server domain and so simply represents that server
scoped to the particular homeserver domain and so simply represents that server
administrator's opinion of what room should take that label; it does not have to
be globally replicated and does not form part of the stored state of that room.
@ -156,7 +156,7 @@ m.public_history
to be a member of the room.
m.archive_servers
For "public" rooms with public history, gives a list of home servers that
For "public" rooms with public history, gives a list of homeservers that
should be included in message distribution to the room, even if no users on
that server are present. These ensure that a public room can still persist
even if no users are currently members of it. This list should be consulted by
@ -179,7 +179,7 @@ m.topic
Room Creation Templates
=======================
A client (or maybe home server?) could offer a few templates for the creation of
A client (or maybe homeserver?) could offer a few templates for the creation of
new rooms. For example, for a simple private one-to-one chat the channel could
assign the creator a power-level of 1, requiring a level of 1 to invite, and
needing an invite before members can join. An invite is then sent to the other
@ -215,7 +215,7 @@ permissions to allow this direct messaging.
Between any given pair of user IDs that wish to exchange private messages, there
will exist a single shared Room, created lazily by either side. These rooms will
need a certain amount of special handling in both home servers and display on
need a certain amount of special handling in both homeservers and display on
clients, but as much as possible should be treated by the lower layers of code
the same as other rooms.
@ -226,7 +226,7 @@ clients should display these in a special way too as the room name is not
important; instead it should distinguish them on the Display Name of the other
party.
Home Servers will need a client-API option to request setting up a new user-user
Homeservers will need a client-API option to request setting up a new user-user
chat room, which will then need special handling within the server. It will
create a new room with the following
@ -260,7 +260,7 @@ history with each other simultaneously create a room and invite the other to it.
This is called a "glare" situation. There are two possible ideas for how to
resolve this:
* Each Home Server should persist the mapping of (user ID pair) to room ID, so
* Each homeserver should persist the mapping of (user ID pair) to room ID, so
that duplicate requests can be suppressed. On receipt of a room creation
request that the HS thinks there already exists a room for, the invitation to
join can be rejected if:

2
drafts/model/third-party-id.rst
View file

@ -66,7 +66,7 @@ Privacy
A User may publish the association between their phone number and Matrix User ID
on the Identity Server without publishing the number in their Profile hosted on
their Home Server.
their homeserver.
Identity Servers should refrain from publishing reverse mappings and should
take steps, such as rate limiting, to prevent attackers enumerating the space of

16
event-schemas/check_examples.py
View file

@ -38,13 +38,12 @@ def check_example_file(examplepath, schemapath):
schema = yaml.load(f)
fileurl = "file://" + os.path.abspath(schemapath)
schema["id"] = fileurl
resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_yaml})
print ("Checking schema for: %r %r" % (examplepath, schemapath))
# Setting the 'id' tells jsonschema where the file is so that it
# can correctly resolve relative $ref references in the schema
schema['id'] = fileurl
try:
jsonschema.validate(example, schema)
jsonschema.validate(example, schema, resolver=resolver)
except Exception as e:
raise ValueError("Error validating JSON schema for %r %r" % (
examplepath, schemapath
@ -71,6 +70,15 @@ def check_example_dir(exampledir, schemadir):
if errors:
raise ValueError("Error validating examples")
def load_yaml(path):
if not path.startswith("file:///"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
return yaml.load(f)
if __name__ == '__main__':
try:
check_example_dir("examples", "schema")

2
event-schemas/examples/m.call.answer
View file

@ -13,5 +13,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.answer",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.call.candidates
View file

@ -15,5 +15,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.candidates",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.call.hangup
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.hangup",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.call.invite
View file

@ -13,5 +13,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.invite",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.aliases
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.aliases",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.avatar
View file

@ -14,5 +14,5 @@
"type": "m.room.avatar",
"state_key": "",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.canonical_alias
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.canonical_alias",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.create
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.create",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.guest_access
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEG:localhost",
"type": "m.room.guest_access",
"room_id": "!Cuyf34gef24u:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.history_visibility
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.history_visibility",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.join_rules
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.join_rules",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.member
View file

@ -26,5 +26,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.member#invite_room_state
View file

@ -26,5 +26,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

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

@ -21,5 +21,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

4
event-schemas/examples/m.room.message#m.audio
View file

@ -14,5 +14,5 @@
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"user_id": "@example:localhost"
}
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.message#m.emote
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

4
event-schemas/examples/m.room.message#m.file
View file

@ -14,5 +14,5 @@
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"user_id": "@example:localhost"
}
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.message#m.image
View file

@ -15,5 +15,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.message#m.location
View file

@ -16,5 +16,5 @@
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.message#m.notice
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.message#m.text
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

4
event-schemas/examples/m.room.message#m.video
View file

@ -23,5 +23,5 @@
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"user_id": "@example:localhost"
}
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.message.feedback
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message.feedback",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.name
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.name",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.power_levels
View file

@ -20,5 +20,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.power_levels",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.redaction
View file

@ -8,5 +8,5 @@
"type": "m.room.redaction",
"room_id": "!Cuyf34gef24t:localhost",
"redacts": "!fukweghifu23:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.room.topic
View file

@ -8,5 +8,5 @@
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.topic",
"room_id": "!Cuyf34gef24t:localhost",
"user_id": "@example:localhost"
"sender": "@example:localhost"
}

2
event-schemas/examples/m.typing
View file

@ -4,4 +4,4 @@
"content": {
"user_ids": ["@alice:matrix.org", "@bob:example.com"]
}
}
}

16
event-schemas/schema/core-event-schema/event.json
View file

@ -1,16 +0,0 @@
{
"type": "object",
"title": "Event",
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"type": "object",
"title": "EventContent",
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body."
},
"type": {
"type": "string",
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'"
}
}
}

13
event-schemas/schema/core-event-schema/event.yaml Normal file
View file

@ -0,0 +1,13 @@
description: The basic set of fields all events must have.
properties:
content:
description: The fields in this object will vary depending on the type of event.
When interacting with the REST API, this is the HTTP body.
title: EventContent
type: object
type:
description: The type of event. This SHOULD be namespaced similar to Java package
naming conventions e.g. 'com.example.subdomain.event.type'
type: string
title: Event
type: object

23
event-schemas/schema/core-event-schema/msgtype_infos/image_info.json
View file

@ -1,23 +0,0 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "ImageInfo",
"description": "Metadata about an image.",
"properties": {
"size": {
"type": "integer",
"description": "Size of the image in bytes."
},
"w": {
"type": "integer",
"description": "The width of the image in pixels."
},
"h": {
"type": "integer",
"description": "The height of the image in pixels."
},
"mimetype": {
"type": "string",
"description": "The mimetype of the image, e.g. ``image/jpeg``."
}
}
}

16
event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml Normal file
View file

@ -0,0 +1,16 @@
$schema: http://json-schema.org/draft-04/schema#
description: Metadata about an image.
properties:
h:
description: The height of the image in pixels.
type: integer
mimetype:
description: The mimetype of the image, e.g. ``image/jpeg``.
type: string
size:
description: Size of the image in bytes.
type: integer
w:
description: The width of the image in pixels.
type: integer
title: ImageInfo

Some files were not shown because too many files have changed in this diff Show more