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

Merge remote-tracking branch 'matrix-org/master' into travis/preset-guests

Browse source
This commit is contained in:
Travis Ralston 2018-07-12 09:48:52 -06:00
commit 6e3993effe
18 changed files with 178 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -61,7 +61,8 @@ paths:
description: The fully qualified user ID of the user being banned.
reason:
type: string
description: The reason the user has been banned.
description: The reason the user has been banned. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:

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

@ -299,3 +299,44 @@ paths:
"$ref": "definitions/error.yaml"
tags:
- Media
"/config":
get:
summary: Get the configuration for the content repository.
description: |-
This endpoint allows clients to retrieve the configuration of the content
repository, such as upload limitations.
Clients SHOULD use this as a guide when using content repository endpoints.
All values are intentionally left optional. Clients SHOULD follow
the advice given in the field description when the field is not available.
**NOTE:** Both clients and server administrators should be aware that proxies
between the client and the server may affect the apparent behaviour of content
repository APIs, for example, proxies may enforce a lower upload size limit
than is advertised by the server on this endpoint.
operationId: getConfig
produces: ["application/json"]
security:
- accessToken: []
responses:
200:
description: The public content repository configuration for the matrix server.
schema:
type: object
properties:
m.upload.size:
type: number
description: |-
The maximum size an upload can be in bytes.
Clients SHOULD use this as a guide when uploading content.
If not listed or null, the size limit should be treated as unknown.
examples:
application/json: {
"m.upload.size": 50000000
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Media

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

@ -143,6 +143,15 @@ paths:
description: The room identifier or alias to join.
required: true
x-example: "#monkeys:matrix.org"
- in: query
type: array
items:
type: string
name: server_name
description: |-
The servers to attempt to join the room through. One of the servers
must be participating in the room.
x-example: ["matrix.org", "elsewhere.ca"]
- in: body
name: third_party_signed
schema:

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

@ -34,6 +34,10 @@ paths:
Kick a user from the room.
The caller must have the required power level in order to perform this operation.
Kicking a user adjusts the target member's membership state to be ``leave`` with an
optional ``reason``. Like with other membership changes, a user can directly adjust
the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
operationId: kick
security:
- accessToken: []
@ -59,7 +63,9 @@ paths:
description: The fully qualified user ID of the user being kicked.
reason:
type: string
description: The reason the user has been kicked.
description: |-
The reason the user has been kicked. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:

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

@ -78,8 +78,8 @@ paths:
for this room. If all users on a homeserver forget a room, the room is
eligible for deletion from that homeserver.
If the user is currently joined to the room, they will implicitly leave
the room as part of this API call.
If the user is currently joined to the room, they must leave the room
before calling this API.
operationId: forgetRoom
security:
- accessToken: []
@ -99,6 +99,15 @@ paths:
}
schema:
type: object
400:
description: The user has not left the room
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
}
schema:
"$ref": "definitions/error.yaml"
429:
description: This request was rate-limited.
schema:

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

@ -107,6 +107,7 @@ paths:
items:
type: object
title: RoomEvent
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
examples:
application/json: {
"start": "t47429-4392820_219380_26003_2265",

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

@ -83,6 +83,8 @@ paths:
description: |-
Get the given user's presence state.
operationId: getPresence
security:
- accessToken: []
parameters:
- in: path
type: string
@ -121,6 +123,15 @@ paths:
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
403:
description: You are not allowed to see this user's presence status.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to see their presence"
}
schema:
"$ref": "definitions/error.yaml"
tags:
- Presence
"/presence/list/{userId}":

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

@ -74,7 +74,7 @@ paths:
properties:
room_events:
type: object
title: "Room Events"
title: Room Events Criteria
description: Mapping of category name to search criteria.
properties:
search_term:
@ -103,7 +103,7 @@ paths:
The order in which to search for results.
By default, this is ``"rank"``.
event_context:
title: "Event Context"
title: Include Event Context
type: object
description: |-
Configures whether any context for the events
@ -169,13 +169,13 @@ paths:
properties:
search_categories:
type: object
title: Categories
title: Result Categories
description: Describes which categories to search in and
their criteria.
properties:
room_events:
type: object
title: Room Event Results
title: Result Room Events
description: Mapping of category name to search criteria.
properties:
count:

49
changelogs/client_server.rst
View file

@ -15,10 +15,30 @@ Unreleased changes
- Sticker messages:
- Add sticker message event definition.
(`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
- Document the ``server_name`` parameter on ``/join/{roomIdOrAlias}``
(`#1364 <https://github.com/matrix-org/matrix-doc/pull/1364>`_).
- Add 'token' parameter to /keys/query endpoint
(`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
- Add the room visibility options for the room directory
(`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
- Add spec for ignoring users
(`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
- Add the ``/register/available`` endpoint for username availability
(`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
- Add ``allow_remote`` to the content repo to avoid routing loops
(`#1265 <https://github.com/matrix-org/matrix-doc/pull/1265>`_).
- Add report content API
(`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
- Document ``/logout/all`` endpoint
(`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
- Document `highlights` field in /search response
(`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
- Document the GET version of ``/login``
(`#1361 <https://github.com/matrix-org/matrix-doc/pull/1361>`_).
- Document guest access in ``/createRoom`` presets
(`#1379 <https://github.com/matrix-org/matrix-doc/pull/1379>`_).
- Document the CORS/preflight headers
(`#1365 <https://github.com/matrix-org/matrix-doc/pull/1365>`_).
- Spec clarifications:
@ -41,27 +61,18 @@ Unreleased changes
(`#1152 <https://github.com/matrix-org/matrix-doc/pull/1152>`_).
- Mark ``GET /rooms/{roomId}/members`` as requiring authentication
(`#1245 <https://github.com/matrix-org/matrix-doc/pull/1244>`_).
- Define what a ``RoomEvent`` is on ``/rooms/{roomId}/messages``
(`#1380 <https://github.com/matrix-org/matrix-doc/pull/1380>`_).
- Mark ``GET /presence/{userId}/status`` as requiring authentication
(`#1371 <https://github.com/matrix-org/matrix-doc/pull/1371>`_).
- Describe ``StateEvent`` for ``/createRoom``
(`#1329 <https://github.com/matrix-org/matrix-doc/pull/1329>`_).
- Changes to the API which will be backwards-compatible for clients:
- Add 'token' parameter to /keys/query endpoint
(`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
- Add the room visibility options for the room directory
(`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
- Add spec for ignoring users
(`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
- Add the ``/register/available`` endpoint for username availability
(`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
- Add ``allow_remote`` to the content repo to avoid routing loops
(`#1265 <https://github.com/matrix-org/matrix-doc/pull/1265>`_).
- Add report content API
(`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
- Document ``/logout/all`` endpoint
(`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
- Document `highlights` field in /search response
(`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
- Describe how the ``reason`` is handled for kicks/bans
(`#1362 <https://github.com/matrix-org/matrix-doc/pull/1362>`_).
- Clarify that clients must leave rooms before forgetting them
(`#1378 <https://github.com/matrix-org/matrix-doc/pull/1378>`_).
- Clarify the request and result types on ``/search``
(`#1381 <https://github.com/matrix-org/matrix-doc/pull/1381>`_).
r0.3.0
======

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

@ -0,0 +1 @@
Document message formats on ``m.text`` and ``m.emote`` messages

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

@ -2,7 +2,9 @@
"age": 242352,
"content": {
"body": "thinks this is an example emote",
"msgtype": "m.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",

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

@ -2,7 +2,9 @@
"age": 242352,
"content": {
"body": "This is an example text message",
"msgtype": "m.text"
"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",

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

@ -12,6 +12,16 @@ properties:
enum:
- m.emote
type: string
format:
description: |-
The format used in the ``formatted_body``. Currently only
``org.matrix.custom.html`` is supported.
type: string
formatted_body:
description: |-
The formatted version of the ``body``. This is required if ``format``
is specified.
type: string
required:
- msgtype
- body

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

@ -12,6 +12,16 @@ properties:
enum:
- m.text
type: string
format:
description: |-
The format used in the ``formatted_body``. Currently only
``org.matrix.custom.html`` is supported.
type: string
formatted_body:
description: |-
The formatted version of the ``body``. This is required if ``format``
is specified.
type: string
required:
- msgtype
- body

9
scripts/speculator/main.go
View file

@ -701,8 +701,8 @@ func ignoreExitCodeOne(err error) error {
func main() {
flag.Parse()
// It would be great to read this from github, but there's no convenient way to do so.
// Most of these memberships are "private", so would require some kind of auth.
// It would be great to read this from github
// cf https://github.com/matrix-org/matrix-doc/issues/1384
allowedMembers = map[string]bool{
"dbkr": true,
"erikjohnston": true,
@ -715,6 +715,11 @@ func main() {
"rxl881": true,
"uhoreg": true,
"turt2live": true,
"Half-Shot": true,
"anoadragon453": true,
"mujx": true,
"benparsons": true,
"KitsuneRal": true,
}
if err := initCache(); err != nil {
log.Fatal(err)

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

@ -502,6 +502,11 @@ class MatrixUnits(Units):
# assign value expected for this param
val_type = param.get("type") # integer/string
if val_type == "array":
items = param.get("items")
if items:
val_type = "[%s]" % items.get("type")
if param.get("enum"):
val_type = "enum"
desc += (

19
specification/client_server_api.rst
View file

@ -164,6 +164,25 @@ recommended.
{{versions_cs_http_api}}
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 homeserver 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:
.. code::
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
Client Authentication
---------------------

4
specification/server_server_api.rst
View file

@ -16,6 +16,10 @@
Federation API
==============
.. WARNING::
This API is unstable and will change without warning or discussion while
we work towards a r0 release (scheduled for August 2018).
Matrix homeservers use the Federation APIs (also known as server-server APIs)
to communicate with each other. Homeservers use these APIs to push messages to
each other in real-time, to