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

Merge branch 'master' into anoa/document_as_options

Browse source
This commit is contained in:
Travis Ralston 2018-08-21 09:42:44 -06:00
commit 06157c6336
13 changed files with 324 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

10
README.rst
View file

@ -68,10 +68,10 @@ Windows users
~~~~~~~~~~~~~
If you're on Windows Vista or higher, be sure that the "Symbolic Links"
option was selected when installing Git prior to cloning this repository. If
you're still seeing errors about files not being found it is likely because
the symlink at ``api/client-server/definitions/event-schemas`` looks like a
file. To correct the problem, open an Administrative/Elevated shell in your
option was selected when installing Git prior to cloning this repository. If
you're still seeing errors about files not being found it is likely because
the symlink at ``api/client-server/definitions/event-schemas`` looks like a
file. To correct the problem, open an Administrative/Elevated shell in your
cloned matrix-doc directory and run the following::
cd api\client-server\definitions
@ -121,7 +121,7 @@ changes.
It is written in Go, so you will need the ``go`` compiler installed on your
computer. You will also need to install fsnotify by running::
go get gopkg.in/fsnotify.v1
go get gopkg.in/fsnotify/fsnotify.v1
Then, create a virtualenv as described above under `Preparation`_,
and::

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

@ -95,6 +95,15 @@ paths:
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
- in: query
type: boolean
name: allow_remote
x-example: false
required: false
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
description: "The content that was previously uploaded."
@ -140,6 +149,15 @@ paths:
required: true
description: |
The filename to give in the Content-Disposition
- in: query
type: boolean
name: allow_remote
x-example: false
required: false
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
description: "The content that was previously uploaded."
@ -198,6 +216,15 @@ paths:
name: method
x-example: "scale"
description: The desired resizing method.
- in: query
type: boolean
name: allow_remote
x-example: false
required: false
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
description: "A thumbnail of the requested content."

23
api/client-server/logout.yaml
View file

@ -44,3 +44,26 @@ paths:
properties: {}
tags:
- Session management
"/logout/all":
post:
summary: Invalidates all access tokens for a user
description: |-
Invalidates all access tokens for a user, so that they can no longer be used for
authorization. This includes the access token that made this request.
This endpoint does not require UI authorization because UI authorization is
designed to protect against attacks where the someone gets hold of a single access
token then takes over the account. This endpoint invalidates all access tokens for
the user, including the token used in the request, and therefore the attacker is
unable to take over the account in this way.
operationId: logout_all
security:
- accessToken: []
responses:
200:
description: The user's access tokens were succesfully invalidated.
schema:
type: object
properties: {}
tags:
- Session management

78
api/client-server/report_content.yaml Normal file
View file

@ -0,0 +1,78 @@
# Copyright 2018 Travis Ralston
#
# 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.
swagger: '2.0'
info:
title: "Matrix Client-Server Report Content API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/rooms/{roomId}/report/{eventId}":
post:
summary: Reports an event as inappropriate.
description: |-
Reports an event as inappropriate to the server, which may then notify
the appropriate people.
operationId: reportContent
parameters:
- in: path
type: string
name: roomId
description: The room in which the event being reported is located.
required: true
x-example: "!637q39766251:example.com"
- in: path
type: string
name: eventId
description: The event to report.
required: true
x-example: "$something:domain.com"
- in: body
name: body
schema:
type: object
example: {
"score": -100,
"reason": "this makes me sad"
}
required: ['score', 'reason']
properties:
score:
type: integer
description: |-
The score to rate this content as where -100 is most offensive
and 0 is inoffensive.
reason:
type: string
description: The reason the content is being reported. May be blank.
security:
- accessToken: []
responses:
200:
description: The event has been reported successfully.
schema:
type: object
examples:
application/json: {}
tags:
- Reporting content

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

@ -53,16 +53,16 @@ paths:
"keys": [
"content.body"
],
"search_term": "martians and men"
}
},
"order_by": "recent",
"groupings": {
"group_by": [
{
"key": "room_id"
"search_term": "martians and men",
"order_by": "recent",
"groupings": {
"group_by": [
{
"key": "room_id"
}
]
}
]
}
}
}
properties:
@ -181,6 +181,12 @@ paths:
count:
type: number
description: An approximate count of the total number of results found.
highlights:
type: array
title: Highlights
description: List of words which should be highlighted, useful for stemming which may change the query terms.
items:
type: string
results:
type: array
title: Results
@ -318,6 +324,10 @@ paths:
}
}
},
"highlights": [
"martians",
"men"
],
"next_batch": "5FdgFsd234dfgsdfFD",
"count": 1224,
"results": [

8
changelogs/client_server.rst
View file

@ -48,6 +48,14 @@ Unreleased changes
(`#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>`_).
r0.3.0
======

6
scripts/continuserv/README
View file

@ -1,6 +0,0 @@
continuserv proactively re-generates the spec on filesystem changes, and serves it over HTTP.
To run it, you must install the `go` tool. You will also need to install fsnotify by running:
`go get gopkg.in/fsnotify/fsnotify.v1`
You can then run continuserv by running:
`go run main.go`

3
scripts/continuserv/README.md Normal file
View file

@ -0,0 +1,3 @@
continuserv proactively re-generates the spec on filesystem changes, and serves
it over HTTP. For notes on using it, see [the main
readme](../../README.rst#continuserv).

6
scripts/proposals.py Normal file → Executable file
View file

@ -1,3 +1,5 @@
#! /usr/bin/env python
# proposals.py: generate an RST file (proposals.rst) from queries to github.com/matrix.org/matrix-doc/issues.
# v0.0.1
@ -22,7 +24,7 @@ def getpage(url, page):
def getbylabel(label):
pagecount = 1
json = list()
urlbase = 'https://api.github.com/repos/matrix-org/matrix-doc/issues?state=open&labels=' + label + '&page='
urlbase = 'https://api.github.com/repos/matrix-org/matrix-doc/issues?state=all&labels=' + label + '&page='
print(urlbase)
json.extend(getpage(urlbase, 1))
for page in range(2, int(pagecount) + 1):
@ -100,7 +102,7 @@ for label in labels:
text_file.write(" - " + updated.strftime('%Y-%m-%d') + "\n")
# list of document links (urls comma-separated)
maindoc = re.search('^Documentation: (.+?)\n', str(item['body']))
maindoc = re.search('^Documentation: (.+?)$', str(item['body']), flags=re.MULTILINE)
if maindoc is not None:
maindoc = maindoc.group(1)
doc_list_formatted = ["`" + str(item['number']) + "-" + str(i) + " <" + x.strip() + ">`_" for i, x in enumerate(maindoc.split(','),1)]

35
specification/modules/report_content.rst Normal file
View file

@ -0,0 +1,35 @@
.. Copyright 2018 Travis Ralston
..
.. 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.
Reporting Content
=================
.. _module:report_content:
Users may encounter content which they find inappropriate and should be able
to report it to the server administrators or room moderators for review. This
module defines a way for users to report content.
Content is reported based upon a negative score, where -100 is "most offensive"
and 0 is "inoffensive".
Client behaviour
----------------
{{report_content_cs_http_api}}
Server behaviour
----------------
Servers are free to handle the reported content however they desire. This may
be a dedicated room to alert server administrators to the reported content or
some other mechanism for notifying the appropriate people.

162
specification/proposals.rst
View file

@ -49,6 +49,14 @@ proposal-wip
- `@leonerd`_
- None
-
* - `MSC1148 <https://github.com/matrix-org/matrix-doc/issues/1148>`_
- Support for websockets
- 2015-11-16
- 2018-06-04
- `1148-1 <https://github.com/matrix-org/matrix-doc/blob/master/drafts/websockets.rst>`_, `1148-2 <https://docs.google.com/document/d/104ClehFBgqLQbf4s-AKX2ijr8sOAxcizfcRs_atsB0g/edit>`_
- `@richvdh`_, `@krombel`_
- None
-
* - `MSC1238 <https://github.com/matrix-org/matrix-doc/issues/1238>`_
- Push to Talk
- 2016-04-13
@ -68,7 +76,7 @@ proposal-wip
* - `MSC1207 <https://github.com/matrix-org/matrix-doc/issues/1207>`_
- Publishing Room Lists for 3rd party networks
- 2016-10-21
- 2018-05-15
- 2018-05-31
- `1207-1 <https://docs.google.com/document/d/12mVuOT7Qoa49L_PQAPjavoK9c2nalYEFOHxJOmH5j-w/edit>`_
- `@erikjohnston`_
- None
@ -140,7 +148,7 @@ proposal-wip
* - `MSC1222 <https://github.com/matrix-org/matrix-doc/issues/1222>`_
- Pushing updates about Groups (Communities) to clients
- 2018-01-02
- 2018-05-15
- 2018-05-24
- `1222-1 <https://drive.google.com/open?id=1GzwhGdnWWMENYOaXMFP8CD-M9ny1vznxHnNqT3I3NZI>`_
- `@ara4n`_
- None
@ -156,7 +164,7 @@ proposal-wip
* - `MSC1227 <https://github.com/matrix-org/matrix-doc/issues/1227>`_
- Proposal for lazy-loading room members to improve initial sync speed and client RAM usage
- 2018-03-05
- 2018-05-15
- 2018-05-28
- `1227-1 <https://docs.google.com/document/d/11yn-mAkYll10RJpN0mkYEVqraTbU3U4eQx9MNrzqX1U/edit>`_
- `@ara4n`_
- None
@ -185,6 +193,22 @@ proposal-wip
- `@neilisfragile`_
- None
-
* - `MSC1267 <https://github.com/matrix-org/matrix-doc/issues/1267>`_
- Interactive Key Verification
- 2018-05-28
- 2018-05-28
- `1267-1 <https://docs.google.com/document/d/1SXmyjyNqClJ5bTHtwvp8tT1Db4pjlGVxfPQNdlQILqU/edit#>`_
- `@uhoreg`_
- None
-
* - `MSC1280 <https://github.com/matrix-org/matrix-doc/issues/1280>`_
- Mechanisms for communicating erasure requests to bots and federated homeservers
- 2018-06-05
- 2018-06-05
- `1280-1 <https://docs.google.com/document/d/17ssplT4pX80ebmyaFIYcXtINV88lBT83ddW9ZhjsDnI>`_
- `@richvdh`_
- None
-
@ -204,18 +228,10 @@ proposal-ready-for-review
- Author
- Shepherd
- PRs
* - `MSC1183 <https://github.com/matrix-org/matrix-doc/issues/1183>`_
- Document key-share requests
- 2018-04-30
- 2018-05-15
- `1183-1 <https://docs.google.com/document/d/1m4gQkcnJkxNuBmb5NoFCIadIY-DyqqNAS3lloE73BlQ>`_
- `@richvdh`_
- None
-
* - `MSC1232 <https://github.com/matrix-org/matrix-doc/issues/1232>`_
- Media limits API
- 2018-05-04
- 2018-05-15
- 2018-06-05
- `1232-1 <https://docs.google.com/document/d/1fI4ZqQcyAyBEPMtS1MCZWpN84kEPdm9SDw6SVZsJvYY/edit>`_
- `@Half-Shot`_
- None
@ -228,6 +244,14 @@ proposal-ready-for-review
- `@turt2live`_
- None
-
* - `MSC1270 <https://github.com/matrix-org/matrix-doc/issues/1270>`_
- Add /_matrix/media/v1/resolve_url to Client-Server API: download and preview urls in the clients despite CORS
- 2018-05-31
- 2018-06-05
- `1270-1 <https://docs.google.com/document/d/1bbX1yxNETmMa-AxBGjIpb4lNoTuc3vjGXmbZWrNBlzM/edit?usp=sharing>`_
- `@oivoodoo`_
- None
-
@ -325,6 +349,14 @@ spec-pr-missing
- Author
- Shepherd
- PRs
* - `MSC1200 <https://github.com/matrix-org/matrix-doc/issues/1200>`_
- Configuration of E2E encryption in a room
- 2016-06-16
- 2018-05-31
- `1200-1 <https://docs.google.com/document/d/1SEPMhNh6ztcrrbkGRSayVQ23bd3cfMPkTgGL4kBS9Ps/edit#heading=h.e7hfigo2zcsj>`_
- `@richvdh`_
- None
-
* - `MSC1201 <https://github.com/matrix-org/matrix-doc/issues/1201>`_
- Device Management API
- 2016-07-14
@ -360,7 +392,7 @@ spec-pr-missing
* - `MSC739 <https://github.com/matrix-org/matrix-doc/issues/739>`_
- Reporting inappropriate content in Matrix
- 2016-11-21
- 2018-05-15
- 2018-05-31
- `739-1 <https://docs.google.com/document/d/15cUuF0VyBMtNIcyFqXvEmXsMURLgXzMOIW33qHoi89A/edit>`_
- `@ara4n`_
- None
@ -421,14 +453,22 @@ spec-pr-missing
- `@lukebarnard1`_
- None
-
* - `MSC1216 <https://github.com/matrix-org/matrix-doc/issues/1216>`_
- @room notification proposal
* - `MSC1033 <https://github.com/matrix-org/matrix-doc/issues/1033>`_
- Doc @room notifications
- 2017-10-23
- 2018-05-15
- `1216-1 <https://docs.google.com/document/d/1qRdlg94cr9YXxPCwhW4HgI2oDrqQOUKX5HptZFBGf6o/edit>`_
- 2018-05-31
-
- `@dbkr`_
- None
- `PR#1176`_
-
* - `MSC1183 <https://github.com/matrix-org/matrix-doc/issues/1183>`_
- Document key-share requests
- 2018-04-30
- 2018-05-31
- `1183-1 <https://docs.google.com/document/d/1m4gQkcnJkxNuBmb5NoFCIadIY-DyqqNAS3lloE73BlQ>`_
- `@richvdh`_
- None
-
* - `MSC1230 <https://github.com/matrix-org/matrix-doc/issues/1230>`_
- Temporary mitigation for depth parameter abuse
- 2018-05-01
@ -464,6 +504,14 @@ merged
- Author
- Shepherd
- PRs
* - `MSC1197 <https://github.com/matrix-org/matrix-doc/issues/1197>`_
- Ignoring Users
- 2016-05-03
- 2018-05-18
- `1197-1 <https://docs.google.com/document/d/1Jex7lDAwmv0KcgyL9oeGfUCsjw0CWSqedPKZ1ViSVis/edit>`_
- `@erikjohnston`_
- None
- `PR#1142`_
* - `MSC1199 <https://github.com/matrix-org/matrix-doc/issues/1199>`_
- Notifications API
- 2016-05-23
@ -472,14 +520,6 @@ merged
- `@dbkr`_
- None
-
* - `MSC1200 <https://github.com/matrix-org/matrix-doc/issues/1200>`_
- Configuration of E2E encryption in a room
- 2016-06-16
- 2018-05-15
- `1200-1 <https://docs.google.com/document/d/1SEPMhNh6ztcrrbkGRSayVQ23bd3cfMPkTgGL4kBS9Ps/edit#heading=h.e7hfigo2zcsj>`_
- `@richvdh`_
- None
-
* - `MSC1204 <https://github.com/matrix-org/matrix-doc/issues/1204>`_
- Access Token Semantics (refresh and macaroons) - aka Auth Sept 2016 Edition
- 2016-09-29
@ -488,6 +528,14 @@ merged
- `@richvdh`_
- None
-
* - `MSC953 <https://github.com/matrix-org/matrix-doc/issues/953>`_
- Add /user_directory/search API
- 2017-05-31
- 2018-05-10
- `953-1 <https://docs.google.com/document/d/1Xc9lAM-FiIC66Z5pnaI4D5zqAqcFcZ5uHr3bYT-DWVk/edit>`_
- `@erikjohnston`_
- None
-
* - `MSC1233 <https://github.com/matrix-org/matrix-doc/issues/1233>`_
- A proposal for organising spec proposals
- 2018-05-10
@ -566,6 +614,22 @@ obsolete
- Author
- Shepherd
- PRs
* - `MSC1223 <https://github.com/matrix-org/matrix-doc/issues/1223>`_
- Replies event format
- 2018-02-01
- 2018-05-15
- `1223-1 <https://docs.google.com/document/d/1KLdKtuZBbFoWDSfN4KM3p7LnIvFBQfSORICBo8zRHaE/edit>`_
- `@t3chguy`_
- None
-
* - `MSC1224 <https://github.com/matrix-org/matrix-doc/issues/1224>`_
- Replies - next steps
- 2018-02-03
- 2018-05-15
- `1224-1 <https://docs.google.com/document/d/1FZsvodn2C0iKJDtn-8y8IPwOa96ixoJejK3gMLVOXHM/edit>`_
- `@t3chguy`_
- None
-
* - `MSC1235 <https://github.com/matrix-org/matrix-doc/issues/1235>`_
- Proposal for Calendar Events
- 2018-02-06
@ -574,34 +638,44 @@ obsolete
- `@Half-Shot`_
- None
-
* - `MSC1220 <https://github.com/matrix-org/matrix-doc/issues/1220>`_
- Rich quoting proposal
- 2018-05-10
- 2018-05-15
- `1220-1 <https://docs.google.com/document/d/146zJr4h6odczMeGUH99dxDZk0i_iVtDiVMy510G25jI/edit>`_
- `@t3chguy`_
- None
-
.. _@t3chguy: https://github.com/t3chguy
.. _@KitsuneRal: https://github.com/KitsuneRal
.. _@pik: https://github.com/pik
.. _@leonerd: https://github.com/leonerd
.. _@rxl881: https://github.com/rxl881
.. _@turt2live: https://github.com/turt2live
.. _@erikjohnston: https://github.com/erikjohnston
.. _@neilisfragile: https://github.com/neilisfragile
.. _@psaavedra: https://github.com/psaavedra
.. _@richvdh: https://github.com/richvdh
.. _@NegativeMjark: https://github.com/NegativeMjark
.. _@ara4n: https://github.com/ara4n
.. _@lukebarnard1: https://github.com/lukebarnard1
.. _@lampholder: https://github.com/lampholder
.. _@dbkr: https://github.com/dbkr
.. _@maxidor: https://github.com/maxidor
.. _others: https://github.com/thers
.. _@rxl881: https://github.com/rxl881
.. _@uhoreg: https://github.com/uhoreg
.. _@t3chguy: https://github.com/t3chguy
.. _@Kegsay: https://github.com/Kegsay
.. _@KitsuneRal: https://github.com/KitsuneRal
.. _@leonerd: https://github.com/leonerd
.. _@psaavedra: https://github.com/psaavedra
.. _@ara4n: https://github.com/ara4n
.. _@krombel: https://github.com/krombel
.. _@maxidor: https://github.com/maxidor
.. _@uhoreg: https://github.com/uhoreg
.. _@pik: https://github.com/pik
.. _@neilisfragile: https://github.com/neilisfragile
.. _@lukebarnard1: https://github.com/lukebarnard1
.. _others: https://github.com/thers
.. _@Half-Shot: https://github.com/Half-Shot
.. _@aviraldg: https://github.com/aviraldg
.. _@oivoodoo: https://github.com/oivoodoo
.. _@richvdh: https://github.com/richvdh
.. _@NegativeMjark: https://github.com/NegativeMjark
.. _@lampholder: https://github.com/lampholder
.. _@dbkr: https://github.com/dbkr
.. _PR#310: https://github.com/matrix-org/matrix-doc/pull/310
.. _PR#1142: https://github.com/matrix-org/matrix-doc/pull/1142
.. _PR#1240: https://github.com/matrix-org/matrix-doc/pull/1240
.. _PR#1189: https://github.com/matrix-org/matrix-doc/pull/1189
.. _PR#919: https://github.com/matrix-org/matrix-doc/pull/919
.. _PR#1176: https://github.com/matrix-org/matrix-doc/pull/1176
.. _PR#919: https://github.com/matrix-org/matrix-doc/pull/919

5
specification/server_server_api.rst
View file

@ -18,7 +18,8 @@ Federation API
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 request historic messages from each other, and to
each other in real-time, to
historic messages from each other, and to
query profile and presence information about users on each other's servers.
The APIs are implemented using HTTPS GETs and PUTs between each of the
@ -1173,7 +1174,7 @@ Step 1 sign JSON:
"method": "GET",
"uri": "/target",
"origin": "origin.hs.example.com",
"destintation": "destination.hs.example.com",
"destination": "destination.hs.example.com",
"content": <request body>,
"signatures": {
"origin.hs.example.com": {

1
specification/targets.yaml
View file

@ -67,6 +67,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
- modules/dm.rst
- modules/ignore_users.rst
- modules/stickers.rst
- modules/report_content.rst
title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]