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

Merge branch 'master' into rav/clarify_event_signing

Browse source
This commit is contained in:
Richard van der Hoff 2018-08-30 22:48:56 +01:00 • committed by GitHub
commit 0f84c69805
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
84 changed files with 667 additions and 451 deletions
Download patch file Download diff file Expand all files Collapse all files

18
api/application-service/definitions/security.yaml Normal file
View file

@ -0,0 +1,18 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
homeserverAccessToken:
type: apiKey
description: The ``hs_token`` provided by the application service's registration.
name: access_token
in: query

24
api/application-service/protocols.yaml
View file

@ -19,13 +19,15 @@ host: localhost:8008
schemes:
- https
- http
basePath: "/"
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
description: |-
@ -33,6 +35,8 @@ paths:
with specific information about the various third party networks that
an application service supports.
operationId: getProtocolMetadata
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
@ -72,7 +76,7 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user/{protocol}":
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |-
@ -80,6 +84,8 @@ paths:
User ID linked to a user on the third party network, given a set of
user parameters.
operationId: queryUserByProtocol
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
@ -125,12 +131,14 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location/{protocol}":
"/thirdparty/location/{protocol}":
get:
summary: Retrieve Matrix-side portal rooms leading to a third party location.
description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
operationId: queryLocationByProtocol
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
@ -176,13 +184,15 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location":
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retrieve an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
security:
- homeserverAccessToken: []
parameters:
- in: query
name: alias
@ -221,12 +231,14 @@ paths:
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user":
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retrieve an array of third party users from a Matrix User ID.
operationId: queryUserByID
security:
- homeserverAccessToken: []
parameters:
- in: query
name: userid

6
api/application-service/query_room.yaml
View file

@ -20,11 +20,13 @@ host: localhost:8008
schemes:
- https
- http
basePath: "/"
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/rooms/{roomAlias}":
get:
@ -36,6 +38,8 @@ paths:
homeserver will send this request when it receives a request to join a
room alias within the application service's namespace.
operationId: queryRoomByAlias
security:
- homeserverAccessToken: []
parameters:
- in: path
name: roomAlias

6
api/application-service/query_user.yaml
View file

@ -20,11 +20,13 @@ host: localhost:8008
schemes:
- https
- http
basePath: "/"
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/users/{userId}":
get:
@ -36,6 +38,8 @@ paths:
send this request when it receives an event for an unknown user ID in
the application service's namespace, such as a room invite.
operationId: queryUserById
security:
- homeserverAccessToken: []
parameters:
- in: path
name: userId

6
api/application-service/transactions.yaml
View file

@ -20,9 +20,11 @@ host: localhost:8008
schemes:
- https
- http
basePath: "/"
basePath: /_matrix/app/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/transactions/{txnId}":
put:
@ -35,6 +37,8 @@ paths:
from message events via the presence of a ``state_key``, rather than
via the event type.
operationId: sendTransaction
security:
- homeserverAccessToken: []
parameters:
- in: path
name: txnId

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

@ -87,6 +87,16 @@ paths:
type: string
description: |-
A unique identifier for the event.
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
@ -142,5 +152,15 @@ paths:
type: string
description: |-
A unique identifier for the event.
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags:
- Room participation

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

@ -77,13 +77,14 @@ paths:
- in: query
name: set_presence
type: string
enum: ["offline"]
enum: ["offline", "online", "unavailable"]
description: |-
Controls whether the client is automatically marked as online by
polling this API. If this parameter is omitted then the client is
automatically marked as online when it uses this API. Otherwise if
the parameter is set to "offline" then the client is not marked as
being online when it uses this API.
being online when it uses this API. When set to "unavailable", the
client is marked as being idle.
x-example: "offline"
- in: query
name: timeout

20
api/identity/associations.yaml
View file

@ -18,15 +18,17 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/3pid/getValidated3pid":
get:
summary: Check whether ownership of a 3pid was validated.
description: A client can check whether ownership of a 3pid was validated
description: |-
Determines if a given 3pid has been validated by a user.
operationId: getValidated3pid
parameters:
- in: query
@ -61,7 +63,9 @@ paths:
description: The address of the 3pid being looked up.
validated_at:
type: integer
description: Timestamp indicating the time that the 3pid was validated.
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required: ['medium', 'address', 'validated_at']
400:
description: |-
@ -78,7 +82,7 @@ paths:
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found
description: The Session ID or client secret were not found.
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
@ -95,7 +99,7 @@ paths:
Future calls to ``/lookup`` for any of the session\'s 3pids will return
this association.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -132,7 +136,6 @@ paths:
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
@ -162,7 +165,10 @@ paths:
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
description: |-
The signatures of the verifying identity services which show that the
association should be trusted, if you trust the verifying identity
services.
$ref: "../../schemas/server-signatures.yaml"
required:
- address

11
api/identity/email_associations.yaml
View file

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -34,13 +35,13 @@ paths:
that that user was able to read the email for that email address, and
so we validate ownership of the email address.
Note that Home Servers offer APIs that proxy this API, adding
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
``/register/email/requestToken`` is designed specifically for use when
registering an account and therefore will inform the user if the email
address given is already registered on the server.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -58,7 +59,7 @@ paths:
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt
description: A unique string used to identify the validation attempt.
email:
type: string
description: The email address to validate.
@ -119,7 +120,7 @@ paths:
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.

11
api/identity/invitation_signing.yaml
View file

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -29,7 +30,7 @@ paths:
description: |-
Sign invitation details.
The identity server will look up ``token`` which was stored in a call
The identity service will look up ``token`` which was stored in a call
to ``store-invite``, and fetch the sender of the invite.
operationId: blindlySignStuff
parameters:
@ -48,14 +49,14 @@ paths:
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: Token from the call to ``store-invite``
description: The token from the call to ``store-invite``.
private_key:
type: string
description: The private key, encoded as `Unpadded base64`_.
required: ["mxid", "token", "private_key"]
responses:
200:
description: The signedjson of the mxid, sender, and token.
description: The signed JSON of the mxid, sender, and token.
schema:
type: object
properties:
@ -85,7 +86,7 @@ paths:
"token": "abc123"
}
404:
description: Token was not found.
description: The token was not found.
examples:
application/json: {
"errcode": "M_UNRECOGNIZED",

19
api/identity/lookup.yaml
View file

@ -1,6 +1,7 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -20,8 +21,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -46,7 +48,7 @@ paths:
responses:
200:
description:
The association for that 3pid, or the empty object if no association is known.
The association for that 3pid, or an empty object if no association is known.
examples:
application/json: {
"address": "louise@bobs.burgers",
@ -66,10 +68,10 @@ paths:
properties:
address:
type: string
description: The 3pid address of the user being looked up.
description: The 3pid address of the user being looked up, matching the address requested.
medium:
type: string
description: The literal string "email".
description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
@ -126,7 +128,9 @@ paths:
#- type: 3PID Address
- type: string
- type: string
description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
description: |-
An array of arrays containing the `3PID Types`_ with the ``medium``
in first position and the ``address`` in second position.
required:
- "threepids"
responses:
@ -157,6 +161,9 @@ paths:
- type: string
- type: string
- type: string
description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
description: |-
An array of array containing the `3PID Types`_ with the ``medium``
in first position, the ``address`` in second position and Matrix user
ID in third position.
required:
- "threepids"

11
api/identity/phone_associations.yaml
View file

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
@ -34,13 +35,13 @@ paths:
indicates that that user was able to read the SMS for that phone
number, and so we validate ownership of the phone number.
Note that Home Servers offer APIs that proxy this API, adding
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
``/register/msisdn/requestToken`` is designed specifically for use when
registering an account and therefore will inform the user if the phone
number given is already registered on the server.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
@ -106,6 +107,8 @@ paths:
- ``M_INVALID_ADDRESS``: The phone number provided was invalid.
- ``M_SEND_ERROR``: The validation SMS could not be sent.
- ``M_DESTINATION_REJECTED``: The identity service cannot deliver an
SMS to the provided country or region.
examples:
application/json: {
"errcode": "M_INVALID_ADDRESS",
@ -125,7 +128,7 @@ paths:
associate the phone number address with any Matrix user
ID. Specifically, calls to ``/lookup`` will not show a binding.
Note: for backwards compatibility with older versions of this
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.

13
api/identity/ping.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2018 Kamax Sàrl
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -14,7 +15,7 @@
swagger: "2.0"
info:
title: "Matrix Client-Identity Versions API"
title: "Matrix Identity Service Ping API"
version: "1.0.0"
host: localhost:8090
schemes:
@ -25,19 +26,19 @@ produces:
paths:
"/api/v1":
get:
summary: Checks that an Identity server is available at this API endpopint.
summary: Checks that an Identity Service is available at this API endpoint.
description: |-
Checks that an Identity server is available at this API endpopint.
Checks that an Identity Service is available at this API endpoint.
To discover that an Identity server is available at a specific URL,
To discover that an Identity Service is available at a specific URL,
this endpoint can be queried and will return an empty object.
This is primarly used for auto-discovery and health check purposes
by entities acting as a client for the Identity server.
by entities acting as a client for the Identity Service.
operationId: ping
responses:
200:
description: An Identity server is ready to serve requests.
description: An Identity Service is ready to serve requests.
examples:
application/json: {}
schema:

3
api/identity/pubkey.yaml
View file

@ -18,8 +18,9 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:

13
api/identity/store_invite.yaml
View file

@ -18,16 +18,17 @@ info:
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
consumes:
- application/json
produces:
- application/json
paths:
"/store-invite":
post:
summary: Store pending invitations to a user\'s 3pid.
summary: Store pending invitations to a user's 3pid.
description: |-
Store pending invitations to a user\'s 3pid.
Store pending invitations to a user's 3pid.
In addition to the request parameters specified below, an arbitrary
number of other parameters may also be specified. These may be used in
@ -47,6 +48,8 @@ paths:
Also, the generated ephemeral public key will be listed as valid on
requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
Currently, invites may only be issued for 3pids of the ``email`` medium.
operationId: storeInvite
parameters:
- in: body
@ -84,7 +87,7 @@ paths:
description: The generated token.
public_keys:
type: array
description: A list of [server\'s long-term public key, generated ephemeral public key].
description: A list of [server's long-term public key, generated ephemeral public key].
items:
type: string
display_name:
@ -111,7 +114,7 @@ paths:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": mxid
"mxid": "@alice:example.com"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

6
api/server-server/events.yaml
View file

@ -49,7 +49,8 @@ paths:
responses:
200:
description: |-
The fully resolved state for the room, including the authorization
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
schema:
type: object
@ -96,7 +97,8 @@ paths:
responses:
200:
description: |-
The fully resolved state for the room, including the authorization
The fully resolved state for the room, prior to considering any state
changes induced by the requested event. Includes the authorization
chain for the events.
schema:
type: object

0
changelogs/application_service.rst Normal file
View file

1
changelogs/application_service/newsfragments/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
!.gitignore

30
changelogs/application_service/pyproject.toml Normal file
View file

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../application_service.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

1
changelogs/client_server/newsfragments/1558.clarification Normal file
View file

@ -0,0 +1 @@
Update all event examples to be accurate representations of their associated events.

1
changelogs/client_server/newsfragments/1590.clarification Normal file
View file

@ -0,0 +1 @@
Document the 403 error for sending state events.

1
changelogs/client_server/newsfragments/780.feature Normal file
View file

@ -0,0 +1 @@
Add more presence options to the ``set_presence`` parameter of ``/sync``. (Thanks @mujx!)

0
changelogs/identity_service.rst Normal file
View file

1
changelogs/identity_service/newsfragments/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
!.gitignore

30
changelogs/identity_service/pyproject.toml Normal file
View file

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../identity_service.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

0
changelogs/server_server.rst Normal file
View file

1
changelogs/server_server/newsfragments/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
!.gitignore

30
changelogs/server_server/pyproject.toml Normal file
View file

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../server_server.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

51
event-schemas/check_examples.py
View file

@ -44,16 +44,51 @@ except ImportError as e:
raise
def load_file(path):
print("Loading reference: %s" % path)
if not path.startswith("file://"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
if path.endswith(".json"):
return json.load(f)
else:
# We have to assume it's YAML because some of the YAML examples
# do not have file extensions.
return yaml.load(f)
def resolve_references(path, schema):
if isinstance(schema, dict):
# do $ref first
if '$ref' in schema:
value = schema['$ref']
path = os.path.abspath(os.path.join(os.path.dirname(path), value))
ref = load_file("file://" + path)
result = resolve_references(path, ref)
del schema['$ref']
else:
result = {}
for key, value in schema.items():
result[key] = resolve_references(path, value)
return result
elif isinstance(schema, list):
return [resolve_references(path, value) for value in schema]
else:
return schema
def check_example_file(examplepath, schemapath):
with open(examplepath) as f:
example = yaml.load(f)
example = resolve_references(examplepath, json.load(f))
with open(schemapath) as f:
schema = yaml.load(f)
fileurl = "file://" + os.path.abspath(schemapath)
schema["id"] = fileurl
resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_yaml})
resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_file})
print ("Checking schema for: %r %r" % (examplepath, schemapath))
try:
@ -71,6 +106,10 @@ def check_example_dir(exampledir, schemadir):
if filename.startswith("."):
# Skip over any vim .swp files.
continue
cwd = os.path.basename(os.path.dirname(os.path.join(root, filename)))
if cwd == "core":
# Skip checking the underlying definitions
continue
examplepath = os.path.join(root, filename)
schemapath = examplepath.replace(exampledir, schemadir)
if schemapath.find("#") >= 0:
@ -85,14 +124,6 @@ def check_example_dir(exampledir, schemadir):
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")

6
event-schemas/examples/core/event.json Normal file
View file

@ -0,0 +1,6 @@
{
"content": {
"key": "value"
},
"type": "org.example.custom.event"
}

4
event-schemas/examples/core/room_edu.json Normal file
View file

@ -0,0 +1,4 @@
{
"$ref": "event.json",
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com"
}

10
event-schemas/examples/core/room_event.json Normal file
View file

@ -0,0 +1,10 @@
{
"$ref": "event.json",
"event_id": "$143273582443PhrSn:domain.com",
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com",
"sender": "@example:domain.com",
"origin_server_ts": 1432735824653,
"unsigned": {
"age": 1234
}
}

4
event-schemas/examples/core/state_event.json Normal file
View file

@ -0,0 +1,4 @@
{
"$ref": "room_event.json",
"state_key": "ArbitraryString"
}

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

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.answer",
"content": {
"version" : 0,
"call_id": "12345",
@ -8,10 +9,5 @@
"type" : "answer",
"sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
}
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.answer",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.candidates",
"content": {
"version" : 0,
"call_id": "12345",
@ -10,10 +11,5 @@
"candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0"
}
]
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.candidates",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.hangup",
"content": {
"version" : 0,
"call_id": "12345"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.hangup",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.call.invite",
"content": {
"version" : 0,
"call_id": "12345",
@ -8,10 +9,5 @@
"type" : "offer",
"sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
}
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.call.invite",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

1
event-schemas/examples/m.direct
View file

@ -1,4 +1,5 @@
{
"$ref": "core/event.json",
"type": "m.direct",
"content": {
"@bob:example.com": [

1
event-schemas/examples/m.ignored_user_list
View file

@ -1,4 +1,5 @@
{
"$ref": "core/event.json",
"type": "m.ignored_user_list",
"content": {
"ignored_users": {

7
event-schemas/examples/m.presence
View file

@ -1,10 +1,11 @@
{
"$ref": "core/event.json",
"sender": "@example:localhost",
"type": "m.presence",
"content": {
"avatar_url": "mxc://localhost:wefuiwegh8742w",
"last_active_ago": 2478593,
"presence": "online",
"currently_active": false
},
"sender": "@example:localhost",
"type": "m.presence"
}
}

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

@ -1,6 +1,6 @@
{
"$ref": "core/room_edu.json",
"type": "m.receipt",
"room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org",
"content": {
"$1435641916114394fHBLK:matrix.org": {
"m.read": {

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

@ -1,12 +1,8 @@
{
"age": 242352,
"content": {
"aliases": ["#somewhere:localhost", "#another:localhost"]
},
"state_key": "localhost",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"$ref": "core/state_event.json",
"state_key": "domain.com",
"type": "m.room.aliases",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
"content": {
"aliases": ["#somewhere:domain.com", "#another:domain.com"]
}
}

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

@ -1,5 +1,7 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.avatar",
"state_key": "",
"content": {
"info": {
"h": 398,
@ -7,12 +9,6 @@
"mimetype": "image/jpeg",
"size": 31037
},
"url": "mxc://localhost/JWEIFJgwEIhweiWJE"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.avatar",
"state_key": "",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
"url": "mxc://domain.com/JWEIFJgwEIhweiWJE"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.canonical_alias",
"state_key": "",
"content": {
"alias": "#somewhere:localhost"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.canonical_alias",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,12 +1,10 @@
{
"age": 242352,
"content": {
"creator": "@example:localhost"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"$ref": "core/state_event.json",
"type": "m.room.create",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
"state_key": "",
"content": {
"creator": "@example:domain.com",
"room_version": "1",
"m.federate": true
}
}

9
event-schemas/examples/m.room.encrypted#megolm
View file

@ -1,14 +1,11 @@
{
"$ref": "core/room_event.json",
"type": "m.room.encrypted",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...",
"device_id": "RJYKSTBOIE",
"sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ"
},
"event_id": "$WLGTSEFSEF:localhost",
"room_id": "!Cuyf34gef24t:localhost",
"origin_server_ts": 1476648761524,
"sender": "@example:localhost",
"type": "m.room.encrypted"
}
}

2
event-schemas/examples/m.room.encrypted#olm
View file

@ -1,6 +1,6 @@
{
"$ref": "core/room_event.json",
"type": "m.room.encrypted",
"sender": "@example:localhost",
"content": {
"algorithm": "m.olm.v1.curve25519-aes-sha2",
"sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU",

11
event-schemas/examples/m.room.encryption
View file

@ -1,13 +1,10 @@
{
"$ref": "core/state_event.json",
"type": "m.room.encryption",
"state_key": "",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"rotation_period_ms": 604800000,
"rotation_period_msgs": 100
},
"event_id": "$WLGTSEFJJKJ:localhost",
"origin_server_ts": 1476648761524,
"sender": "@example:localhost",
"room_id": "!Cuyf34gef24t:localhost",
"state_key": "",
"type": "m.room.encryption"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242353,
"$ref": "core/state_event.json",
"type": "m.room.guest_access",
"state_key": "",
"content": {
"guest_access": "can_join"
},
"state_key": "",
"origin_server_ts": 1431961217938,
"event_id": "$WLGTSEFSEG:localhost",
"type": "m.room.guest_access",
"room_id": "!Cuyf34gef24u:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.history_visibility",
"state_key": "",
"content": {
"history_visibility": "shared"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.history_visibility",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.join_rules",
"state_key": "",
"content": {
"join_rule": "public"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.join_rules",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,14 +1,10 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"state_key": "@alice:domain.com",
"type": "m.room.member",
"content": {
"membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid"
},
"state_key": "@alice:localhost",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,11 +1,12 @@
{
"age": 242352,
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid"
},
"unsigned": {
"age": 1234,
"invite_room_state": [
{
"type": "m.room.name",
@ -22,11 +23,5 @@
}
}
]
},
"state_key": "@alice:localhost",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,13 +1,13 @@
{
"age": 242352,
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid",
"third_party_invite": {
"display_name": "alice",
"signed": {
"mxid": "@alice:localhost",
"mxid": "@alice:domain.com",
"signatures": {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
@ -16,11 +16,5 @@
"token": "abc123"
}
}
},
"state_key": "@alice:localhost",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.member",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,18 +1,14 @@
{
"age": 146,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "Bee Gees - Stayin' Alive",
"url": "mxc://localhost/ffed755USFFxlgbQYZGtryd",
"url": "mxc://domain.com/ffed755USFFxlgbQYZGtryd",
"info": {
"duration": 2140786,
"size": 1563685,
"mimetype": "audio/mpeg"
},
"msgtype": "m.audio"
},
"event_id": "$143273582443PhrSn:localhost",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"sender": "@example:localhost"
}
}

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

@ -1,14 +1,10 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "thinks this is an example emote",
"msgtype": "m.emote",
"format": "org.matrix.custom.html",
"formatted_body": "thinks <b>this</b> is an example emote"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,5 +1,6 @@
{
"age": 146,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "something-important.doc",
"filename": "something-important.doc",
@ -8,11 +9,6 @@
"size": 46144
},
"msgtype": "m.file",
"url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe"
},
"event_id": "$143273582443PhrSn:localhost",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"sender": "@example:localhost"
"url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe"
}
}

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

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "filename.jpg",
"info": {
@ -8,12 +9,7 @@
"mimetype": "image/jpeg",
"size": 31037
},
"url": "mxc://localhost/JWEIFJgwEIhweiWJE",
"url": "mxc://domain.com/JWEIFJgwEIhweiWJE",
"msgtype": "m.image"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,10 +1,11 @@
{
"age": 146,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "Big Ben, London, UK",
"geo_uri": "geo:51.5008,0.1247",
"info": {
"thumbnail_url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe",
"thumbnail_url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe",
"thumbnail_info": {
"mimetype": "image/jpeg",
"size": 46144,
@ -13,10 +14,5 @@
}
},
"msgtype": "m.location"
},
"event_id": "$143273582443PhrSn:localhost",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"sender": "@example:localhost"
}
}

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

@ -1,14 +1,10 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "This is an example notice",
"msgtype": "m.notice",
"format": "org.matrix.custom.html",
"formatted_body": "This is an <strong>example</strong> notice"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,14 +1,10 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "This is an example text message",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "<b>This is an example text message</b>"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,10 +1,11 @@
{
"age": 146,
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "Gangnam Style",
"url": "mxc://localhost/a526eYUSFFxlgbQYZmo442",
"url": "mxc://domain.com/a526eYUSFFxlgbQYZmo442",
"info": {
"thumbnail_url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe",
"thumbnail_url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe",
"thumbnail_info": {
"mimetype": "image/jpeg",
"size": 46144,
@ -18,10 +19,5 @@
"mimetype": "video/mp4"
},
"msgtype": "m.video"
},
"event_id": "$143273582443PhrSn:localhost",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"sender": "@example:localhost"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.room.message.feedback",
"content": {
"type": "delivered",
"target_event_id": "$WEIGFHFW:localhost"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.message.feedback",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.name",
"state_key": "",
"content": {
"name": "The room name"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.name",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

14
event-schemas/examples/m.room.pinned_events
View file

@ -1,12 +1,8 @@
{
"age": 242352,
"content": {
"pinned": ["$someevent:localhost"]
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"$ref": "core/state_event.json",
"type": "m.room.pinned_events",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
"state_key": "",
"content": {
"pinned": ["$someevent:domain.com"]
}
}

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

@ -1,5 +1,7 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.power_levels",
"state_key": "",
"content": {
"ban": 50,
"events": {
@ -18,11 +20,5 @@
"notifications": {
"room": 20
}
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.power_levels",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,14 +1,8 @@
{
"unsigned": {
"age": 242352
},
"$ref": "core/room_event.json",
"type": "m.room.redaction",
"redacts": "$fukweghifu23:localhost",
"content": {
"reason": "Spamming"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.redaction",
"room_id": "!Cuyf34gef24t:localhost",
"redacts": "$fukweghifu23:localhost",
"sender": "@example:localhost"
}
}

12
event-schemas/examples/m.room.third_party_invite
View file

@ -1,5 +1,7 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.third_party_invite",
"state_key": "pc98",
"content": {
"display_name": "Alice Margatroid",
"key_validity_url": "https://magic.forest/verifykey",
@ -8,11 +10,5 @@
"public_key": "def456",
"key_validity_url": "https://magic.forest/verifykey"
}]
},
"state_key": "pc98",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.third_party_invite",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

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

@ -1,12 +1,8 @@
{
"age": 242352,
"$ref": "core/state_event.json",
"type": "m.room.topic",
"state_key": "",
"content": {
"topic": "A room topic"
},
"state_key": "",
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.room.topic",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

5
event-schemas/examples/m.room_key
View file

@ -1,9 +1,10 @@
{
"$ref": "core/event.json",
"type": "m.room_key",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"room_id": "!Cuyf34gef24t:localhost",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
},
"type": "m.room_key"
}
}

10
event-schemas/examples/m.sticker
View file

@ -1,5 +1,6 @@
{
"age": 242352,
"$ref": "core/room_event.json",
"type": "m.sticker",
"content": {
"body": "Landing",
"info": {
@ -16,10 +17,5 @@
"size": 73602
},
"url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",
"type": "m.sticker",
"room_id": "!Cuyf34gef24t:localhost",
"sender": "@example:localhost"
}
}

1
event-schemas/examples/m.tag
View file

@ -1,4 +1,5 @@
{
"$ref": "core/event.json",
"type": "m.tag",
"content": {
"tags": {

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

@ -1,6 +1,6 @@
{
"$ref": "core/room_edu.json",
"type": "m.typing",
"room_id": "!z0mnsuiwhifuhwwfw:matrix.org",
"content": {
"user_ids": ["@alice:matrix.org", "@bob:example.com"]
}

38
scripts/gendoc.py
View file

@ -154,7 +154,7 @@ def get_rst(file_info, title_level, title_styles, spec_dir, adjust_titles):
# string are file paths to RST blobs
if isinstance(file_info, str):
log("%s %s" % (">" * (1 + title_level), file_info))
with open(os.path.join(spec_dir, file_info), "r") as f:
with open(os.path.join(spec_dir, file_info), "r", encoding="utf-8") as f:
rst = None
if adjust_titles:
rst = load_with_adjusted_titles(
@ -186,7 +186,7 @@ def get_rst(file_info, title_level, title_styles, spec_dir, adjust_titles):
def build_spec(target, out_filename):
log("Building templated file %s" % out_filename)
with open(out_filename, "wb") as outfile:
with open(out_filename, "w", encoding="utf-8") as outfile:
for file_info in target["files"]:
section = get_rst(
file_info=file_info,
@ -195,7 +195,7 @@ def build_spec(target, out_filename):
spec_dir=spec_dir,
adjust_titles=True
)
outfile.write(section.encode('UTF-8'))
outfile.write(section)
"""
@ -223,8 +223,8 @@ def fix_relative_titles(target, filename, out_filename):
"^[" + re.escape("".join(title_styles)) + "]{3,}$"
)
current_title_style = None
with open(filename, "r") as infile:
with open(out_filename, "w") as outfile:
with open(filename, "r", encoding="utf-8") as infile:
with open(out_filename, "w", encoding="utf-8") as outfile:
for line in infile.readlines():
if not relative_title_matcher.match(line):
if title_matcher.match(line):
@ -263,8 +263,8 @@ def fix_relative_titles(target, filename, out_filename):
def rst2html(i, o, stylesheets):
log("rst2html %s -> %s" % (i, o))
with open(i, "r") as in_file:
with open(o, "w") as out_file:
with open(i, "r", encoding="utf-8") as in_file:
with open(o, "w", encoding="utf-8") as out_file:
publish_file(
source=in_file,
destination=out_file,
@ -280,16 +280,15 @@ def rst2html(i, o, stylesheets):
def addAnchors(path):
log("add anchors %s" % path)
with open(path, "rb") as f:
with open(path, "r", encoding="utf-8") as f:
lines = f.readlines()
replacement = r'<p><a class="anchor" id="\2"></a></p>\n\1'
with open(path, "wb") as f:
with open(path, "w", encoding="utf-8") as f:
for line in lines:
line = line.decode("UTF-8")
line = re.sub(r'(<h\d id="#?(.*?)">)', replacement, line.rstrip())
line = re.sub(r'(<div class="section" id="(.*?)">)', replacement, line.rstrip())
f.write((line + "\n").encode('UTF-8'))
f.write(line + "\n")
def run_through_template(input_files, set_verbose, substitutions):
@ -518,10 +517,18 @@ if __name__ == '__main__':
"--server_release", "-s", action="store", default="unstable",
help="The server-server release tag to generate, e.g. r1.2"
)
parser.add_argument(
"--appservice_release", "-a", action="store", default="unstable",
help="The appservice release tag to generate, e.g. r1.2"
)
parser.add_argument(
"--push_gateway_release", "-p", action="store", default="unstable",
help="The push gateway release tag to generate, e.g. r1.2"
)
parser.add_argument(
"--identity_release", "-i", action="store", default="unstable",
help="The identity service release tag to generate, e.g. r1.2"
)
parser.add_argument(
"--list_targets", action="store_true",
help="Do not update the specification. Instead print a list of targets.",
@ -540,12 +547,13 @@ if __name__ == '__main__':
substitutions = {
"%CLIENT_RELEASE_LABEL%": args.client_release,
# we hardcode a major version of r0. This ends up in the
# example API URLs. When we have released a new major version,
# we'll have to bump it.
# we hardcode the major versions. This ends up in the example
# API URLs. When we have released a new major version, we'll
# have to bump them.
"%CLIENT_MAJOR_VERSION%": "r0",
"%SERVER_RELEASE_LABEL%": args.server_release,
"%SERVER_MAJOR_VERSION%": extract_major(args.server_release),
"%APPSERVICE_RELEASE_LABEL%": args.appservice_release,
"%IDENTITY_RELEASE_LABEL%": args.identity_release,
"%PUSH_GATEWAY_RELEASE_LABEL%": args.push_gateway_release,
}

7
scripts/generate-matrix-org-assets
View file

@ -8,8 +8,11 @@ cd `dirname $0`/..
mkdir -p assets
# generate specification/proposals.rst
./scripts/proposals.py
if [ "$CIRCLECI" != "true" ]
then
# generate specification/proposals.rst
./scripts/proposals.py
fi
# generate the spec docs
./scripts/gendoc.py -d assets/spec

12
scripts/templating/matrix_templates/sections.py
View file

@ -37,6 +37,18 @@ class MatrixSections(Sections):
changelogs = self.units.get("changelogs")
return changelogs["push_gateway"]
def render_identity_service_changelog(self):
changelogs = self.units.get("changelogs")
return changelogs["identity_service"]
def render_server_server_changelog(self):
changelogs = self.units.get("changelogs")
return changelogs["server_server"]
def render_application_service_changelog(self):
changelogs = self.units.get("changelogs")
return changelogs["application_service"]
def _render_events(self, filterFn, sortFn):
template = self.env.get_template("events.tmpl")
examples = self.units.get("event_examples")

28
scripts/templating/matrix_templates/units.py
View file

@ -125,7 +125,7 @@ def resolve_references(path, schema):
if '$ref' in schema:
value = schema['$ref']
path = os.path.join(os.path.dirname(path), value)
with open(path) as f:
with open(path, encoding="utf-8") as f:
ref = yaml.load(f, OrderedLoader)
result = resolve_references(path, ref)
del schema['$ref']
@ -664,11 +664,11 @@ class MatrixUnits(Units):
continue
filepath = os.path.join(path, filename)
logger.info("Reading swagger API: %s" % filepath)
with open(filepath, "r") as f:
with open(filepath, "r", encoding="utf-8") as f:
# strip .yaml
group_name = filename[:-5].replace("-", "_")
group_name = "%s_%s" % (group_name, suffix)
api = yaml.load(f.read(), OrderedLoader)
api = yaml.load(f, OrderedLoader)
api = resolve_references(filepath, api)
api["__meta"] = self._load_swagger_meta(
api, group_name
@ -698,11 +698,11 @@ class MatrixUnits(Units):
continue
filepath = os.path.join(path, filename)
logger.info("Reading swagger definition: %s" % filepath)
with open(filepath, "r") as f:
with open(filepath, "r", encoding="utf-8") as f:
# strip .yaml
group_name = re.sub(r"[^a-zA-Z0-9_]", "_", filename[:-5])
group_name = "%s_%s" % (prefix, group_name)
definition = yaml.load(f.read(), OrderedLoader)
definition = yaml.load(f, OrderedLoader)
definition = resolve_references(filepath, definition)
if 'type' not in definition:
continue
@ -741,7 +741,7 @@ class MatrixUnits(Units):
event_type = filename[:-5] # strip the ".yaml"
logger.info("Reading event schema: %s" % filepath)
with open(filepath) as f:
with open(filepath, encoding="utf-8") as f:
event_schema = yaml.load(f, OrderedLoader)
schema_info = process_data_type(
@ -754,6 +754,8 @@ class MatrixUnits(Units):
def load_apis(self, substitutions):
cs_ver = substitutions.get("%CLIENT_RELEASE_LABEL%", "unstable")
fed_ver = substitutions.get("%SERVER_RELEASE_LABEL%", "unstable")
is_ver = substitutions.get("%IDENTITY_RELEASE_LABEL%", "unstable")
as_ver = substitutions.get("%APPSERVICE_RELEASE_LABEL%", "unstable")
push_gw_ver = substitutions.get("%PUSH_GATEWAY_RELEASE_LABEL%", "unstable")
# we abuse the typetable to return this info to the templates
@ -767,11 +769,11 @@ class MatrixUnits(Units):
fed_ver,
"Federation between servers",
), TypeTableRow(
"`Application Service API <application_service/unstable.html>`_",
"unstable",
"`Application Service API <application_service/"+as_ver+".html>`_",
as_ver,
"Privileged server plugins",
), TypeTableRow(
"`Identity Service API <identity_service/unstable.html>`_",
"`Identity Service API <identity_service/"+is_ver+".html>`_",
"unstable",
"Mapping of third party IDs to Matrix IDs",
), TypeTableRow(
@ -792,8 +794,8 @@ class MatrixUnits(Units):
filepath = os.path.join(path, filename)
logger.info("Reading event example: %s" % filepath)
try:
with open(filepath, "r") as f:
example = json.load(f)
with open(filepath, "r", encoding="utf-8") as f:
example = resolve_references(filepath, json.load(f))
examples[filename] = examples.get(filename, [])
examples[filename].append(example)
if filename != event_name:
@ -830,7 +832,7 @@ class MatrixUnits(Units):
def read_event_schema(self, filepath):
logger.info("Reading %s" % filepath)
with open(filepath, "r") as f:
with open(filepath, "r", encoding="utf-8") as f:
json_schema = yaml.load(f, OrderedLoader)
schema = {
@ -942,7 +944,7 @@ class MatrixUnits(Units):
title_part = None
changelog_lines = []
with open(path, "r") as f:
with open(path, "r", encoding="utf-8") as f:
lines = f.readlines()
prev_line = None
for line in (tc_lines + lines):

90
specification/application_service_api.rst
View file

@ -30,22 +30,37 @@ irrespective of the underlying homeserver implementation.
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
Changelog
---------
.. topic:: Version: unstable
{{application_service_changelog}}
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
For the full historical changelog, see
https://github.com/matrix-org/matrix-doc/blob/master/changelogs/application_service.rst
Other versions of this specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following other versions are also available, in reverse chronological order:
- `HEAD <https://matrix.org/docs/spec/application_service/unstable.html>`_: Includes all changes since the latest versioned release.
Application Services
--------------------
Application services are passive and can only observe events from a given
homeserver (HS). They can inject events into rooms they are participating in.
Application services are passive and can only observe events from homeserver.
They can inject events into rooms they are participating in.
They cannot prevent events from being sent, nor can they modify the content of
the event being sent. In order to observe events from a homeserver, the
homeserver needs to be configured to pass certain types of traffic to the
application service. This is achieved by manually configuring the homeserver
with information about the application service (AS).
with information about the application service.
Registration
~~~~~~~~~~~~
@ -169,6 +184,34 @@ An example registration file for an IRC-bridging application service is below:
Homeserver -> Application Service API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Legacy routes
+++++++++++++
Previous drafts of the application service specification had a mix of endpoints
that have been used in the wild for a significant amount of time. The application
service specification now defines a version on all endpoints to be more compatible
with the rest of the Matrix specification and the future.
Homeservers should attempt to use the specified endpoints first when communicating
with application services. However, if the application service receives an http status
code that does not indicate success (ie: 404, 500, 501, etc) then the homeserver
should fall back to the older endpoints for the application service.
The older endpoints have the exact same request body and response format, they
just belong at a different path. The equivalent path for each is as follows:
* ``/_matrix/app/v1/transactions/{txnId}`` becomes ``/transactions/{txnId}``
* ``/_matrix/app/v1/users/{userId}`` becomes ``/users/{userId}``
* ``/_matrix/app/v1/rooms/{roomAlias}`` becomes ``/rooms/{roomAlias}``
* ``/_matrix/app/v1/thirdparty/protocol/{protocol}`` becomes ``/_matrix/app/unstable/thirdparty/protocol/{protocol}``
* ``/_matrix/app/v1/thirdparty/user/{user}`` becomes ``/_matrix/app/unstable/thirdparty/user/{user}``
* ``/_matrix/app/v1/thirdparty/location/{location}`` becomes ``/_matrix/app/unstable/thirdparty/location/{location}``
* ``/_matrix/app/v1/thirdparty/user`` becomes ``/_matrix/app/unstable/thirdparty/user``
* ``/_matrix/app/v1/thirdparty/location`` becomes ``/_matrix/app/unstable/thirdparty/location``
Homeservers should periodically try again for the newer endpoints because the
application service may have been updated.
Pushing events
++++++++++++++
@ -179,24 +222,24 @@ events. Each list of events includes a transaction ID, which works as follows:
Typical
HS ---> AS : Homeserver sends events with transaction ID T.
<--- : AS sends back 200 OK.
<--- : Application Service sends back 200 OK.
AS ACK Lost
HS ---> AS : Homeserver sends events with transaction ID T.
<-/- : AS 200 OK is lost.
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 transaction ID).
<--- : Application Service 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 transaction ID).
The events sent to the application service should be linearised, as if they were
from the event stream. The homeserver MUST maintain a queue of transactions to
send to the AS. If the application service cannot be reached, the homeserver
SHOULD backoff exponentially until the application service is reachable again.
send to the application service. If the application service cannot be reached, the
homeserver SHOULD backoff exponentially until the application service is reachable again.
As application services cannot *modify* the events in any way, these requests can
be made without blocking other aspects of the homeserver. 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.
on retries, as the application service may have already processed the events.
{{transactions_as_http_api}}
@ -337,7 +380,7 @@ users needs API changes in order to:
- Have a 'passwordless' user.
This involves bypassing the registration flows entirely. This is achieved by
including the AS token on a ``/register`` request, along with a login type of
including the ``as_token`` on a ``/register`` request, along with a login type of
``m.login.application_service`` to set the desired user ID without a password.
::
@ -374,13 +417,18 @@ additional parameters on the ``/publicRooms`` client-server endpoint.
{{appservice_room_directory_cs_http_api}}
Event fields
~~~~~~~~~~~~
Referencing messages from a third party network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. TODO-TravisR: Fix this section to be a general "3rd party networks" section
Application services should include an ``external_url`` in the ``content`` of
events it emits to indicate where the message came from. This typically applies
to application services that bridge other networks into Matrix, such as IRC,
where an HTTP URL may be available to reference.
We recommend that any events that originated from a remote network should
include an ``external_url`` field in their content to provide a way for Matrix
clients to link into the 'native' client from which the event originated.
For instance, this could contain the message-ID for emails/nntp posts, or a link
to a blog comment when bridging blog comment traffic in & out of Matrix.
Clients should provide users with a way to access the ``external_url`` if it
is present. Clients should additionally ensure the URL has a scheme of ``https``
or ``http`` before making use of it.
The presence of an ``external_url`` on an event does not necessarily mean the
event was sent from an application service. Clients should be wary of the URL
contained within, as it may not be a legitimate reference to the event's source.

96
specification/identity_service_api.rst
View file

@ -1,6 +1,7 @@
.. Copyright 2016 OpenMarket Ltd
.. Copyright 2017 Kamax.io
.. Copyright 2017 New Vector Ltd
.. Copyright 2018 New Vector Ltd
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
@ -28,13 +29,27 @@ practice has only been applied specifically to email addresses and phone numbers
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
Changelog
---------
.. topic:: Version: %IDENTITY_RELEASE_LABEL%
{{identity_service_changelog}}
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
For the full historical changelog, see
https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst
Other versions of this specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following other versions are also available, in reverse chronological order:
- `HEAD <https://matrix.org/docs/spec/identity_service/unstable.html>`_: Includes all changes since the latest versioned release.
General principles
------------------
@ -56,7 +71,7 @@ is left as an exercise for the client.
3PID types are described in `3PID Types`_ Appendix.
API Standards
API standards
-------------
The mandatory baseline for identity service communication in Matrix is exchanging
@ -136,6 +151,22 @@ should allow a 3pid to be mapped to a Matrix user identity, but not in the other
direction (i.e. one should not be able to get all 3pids associated with a Matrix
user ID, or get all 3pids associated with a 3pid).
Web browser clients
-------------------
It is realistic to expect that some clients will be written to be run within a web
browser or similar environment. In these cases, the identity service should respond to
pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all
requests.
When a client approaches the server with a pre-flight (OPTIONS) request, the server
should respond with the CORS headers for that route. The recommended CORS headers
to be returned by servers on all requests are::
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Status check
------------
@ -146,25 +177,24 @@ Key management
An identity service has some long-term public-private keypairs. These are named
in a scheme ``algorithm:identifier``, e.g. ``ed25519:0``. When signing an
association, the Matrix standard JSON signing format is used, as specified in
the server-server API specification under the heading "Signing Events".
association, the standard `Signing JSON`_ algorithm applies.
In the event of key compromise, the identity service may revoke any of its keys.
An HTTP API is offered to get public keys, and check whether a particular key is
valid.
The identity server may also keep track of some short-term public-private
The identity service may also keep track of some short-term public-private
keypairs, which may have different usage and lifetime characteristics than the
service's long-term keys.
{{pubkey_is_http_api}}
Association Lookup
Association lookup
------------------
{{lookup_is_http_api}}
Establishing Associations
Establishing associations
-------------------------
The flow for creating an association is session-based.
@ -183,6 +213,12 @@ session, within a 24 hour period since its most recent modification. Any
attempts to perform these actions after the expiry will be rejected, and a new
session should be created and used instead.
To start a session, the client makes a request to the appropriate ``/requestToken``
endpoint. The user then receives a validation token which should be provided
to the client. The client then provides the token to the appropriate ``/submitToken``
endpoint, completing the session. At this point, the client should ``/bind`` the
third party identifier or leave it for another entity to bind.
Email associations
~~~~~~~~~~~~~~~~~~
@ -198,53 +234,31 @@ General
{{associations_is_http_api}}
Invitation Storage
Invitation storage
------------------
An identity service can store pending invitations to a user's 3pid, which will
be retrieved and can be either notified on or look up when the 3pid is
associated with a Matrix user ID.
At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below::
POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
Content-Type: application/json
{
"medium": "email",
"address": "foo@bar.baz",
"mxid": "@alice:example.tld",
"invites": [
{
"medium": "email",
"address": "foo@bar.baz",
"mxid": "@alice:example.tld",
"room_id": "!something:example.tld",
"sender": "@bob:example.tld",
"signed": {
"mxid": "@alice:example.tld",
"signatures": {
"vector.im": {
"ed25519:0": "somesignature"
}
},
"token": "sometoken"
}
}
]
}
Where the signature is produced using a long-term private key.
At a later point, if the owner of that particular 3pid binds it with a Matrix user
ID, the identity service will attempt to make an HTTP POST to the Matrix user's
homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a
long-term private key for the identity service.
{{store_invite_is_http_api}}
Ephemeral invitation signing
----------------------------
To aid clients who may not be able to perform crypto themselves, the identity service offers some crypto functionality to help in accepting invitations.
This is less secure than the client doing it itself, but may be useful where this isn't possible.
To aid clients who may not be able to perform crypto themselves, the identity
service offers some crypto functionality to help in accepting invitations.
This is less secure than the client doing it itself, but may be useful where
this isn't possible.
{{invitation_signing_is_http_api}}
.. _`Unpadded Base64`: ../appendices.html#unpadded-base64
.. _`3PID Types`: ../appendices.html#pid-types
.. _`Signing JSON`: ../appendices.html#signing-json
.. _`/3pid/onbind`: ../server_server/unstable.html#put-matrix-federation-v1-3pid-onbind

2
specification/modules/account_data.rst
View file

@ -31,7 +31,7 @@ The client recieves the account data as events in the ``account_data`` sections
of a ``/sync``.
These events can also be received in a ``/events`` response or in the
``account_data`` section of a room in ``/initialSync``. ``m.tag``
``account_data`` section of a room in ``/sync``. ``m.tag``
events appearing in ``/events`` will have a ``room_id`` with the room
the tags are for.

9
specification/modules/receipts.rst
View file

@ -38,11 +38,10 @@ single ``event_id``.
Client behaviour
----------------
In ``/initialSync``, receipts are listed in a separate top level ``receipts``
key. In ``/sync``, receipts are contained in the ``ephemeral`` block for a
room. New receipts that come down the event streams are deltas which update
existing mappings. Clients should replace older receipt acknowledgements based
on ``user_id`` and ``receipt_type`` pairs. For example::
In ``/sync``, receipts are listed under the ``ephemeral`` array of events
for a given room. New receipts that come down the event streams are deltas
which update existing mappings. Clients should replace older receipt acknowledgements
based on ``user_id`` and ``receipt_type`` pairs. For example::
Client receives m.receipt:
user = @alice:example.com

25
specification/server_server_api.rst
View file

@ -64,13 +64,27 @@ request.
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
Changelog
---------
.. topic:: Version: %SERVER_RELEASE_LABEL%
{{server_server_changelog}}
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
For the full historical changelog, see
https://github.com/matrix-org/matrix-doc/blob/master/changelogs/server_server.rst
Other versions of this specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following other versions are also available, in reverse chronological order:
- `HEAD <https://matrix.org/docs/spec/server_server/unstable.html>`_: Includes all changes since the latest versioned release.
Server discovery
----------------
@ -1077,12 +1091,13 @@ Example code
.. |/query/directory| replace:: ``/query/directory``
.. _/query/directory: #get-matrix-federation-v1-query-directory
.. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage
.. _`Identity Service API`: ../identity_service/unstable.html
.. _`Client-Server API`: ../client_server/unstable.html
.. _`Invitation storage`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage
.. _`Identity Service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html
.. _`Client-Server API`: ../client_server/%CLIENT_RELEASE_LABEL%.html
.. _`Inviting to a room`: #inviting-to-a-room
.. _`Canonical JSON`: ../appendices.html#canonical-json
.. _`Unpadded Base64`: ../appendices.html#unpadded-base64
.. _`Server ACLs`: ../client_server/unstable.html#module-server-acls
.. _`redaction algorithm`: ../client_server/unstable.html#redactions
.. _`Signing JSON`: ../appendices.html#signing-json
.. _`Checking for a signature`: ../appendices.html#checking-for-a-signature

2
specification/targets.yaml
View file

@ -13,7 +13,7 @@ targets:
application_service:
files:
- application_service_api.rst
version_label: unstable
version_label: "%APPSERVICE_RELEASE_LABEL%"
server_server:
files:
- server_server_api.rst