diff --git a/README.rst b/README.rst index 76f4ad55..6c87201c 100644 --- a/README.rst +++ b/README.rst @@ -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:: diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 03a25fd9..f76b2fb9 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -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." diff --git a/api/client-server/logout.yaml b/api/client-server/logout.yaml index 3a2f71e9..2dfd6d97 100644 --- a/api/client-server/logout.yaml +++ b/api/client-server/logout.yaml @@ -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 diff --git a/api/client-server/report_content.yaml b/api/client-server/report_content.yaml new file mode 100644 index 00000000..f702151d --- /dev/null +++ b/api/client-server/report_content.yaml @@ -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 diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index c4f38fa1..e5f6a872 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -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": [ diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 3c4fbffa..24344116 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -48,6 +48,14 @@ Unreleased changes (`#1142 `_). - Add the ``/register/available`` endpoint for username availability (`#1151 `_). + - Add ``allow_remote`` to the content repo to avoid routing loops + (`#1265 `_). + - Add report content API + (`#1264 `_). + - Document ``/logout/all`` endpoint + (`#1263 `_). + - Document `highlights` field in /search response + (`#1274 `_). r0.3.0 ====== diff --git a/scripts/continuserv/README b/scripts/continuserv/README deleted file mode 100644 index edb9aef4..00000000 --- a/scripts/continuserv/README +++ /dev/null @@ -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` diff --git a/scripts/continuserv/README.md b/scripts/continuserv/README.md new file mode 100644 index 00000000..40321bb6 --- /dev/null +++ b/scripts/continuserv/README.md @@ -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). diff --git a/scripts/proposals.py b/scripts/proposals.py old mode 100644 new mode 100755 index a84804a7..aa2252bc --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -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)] diff --git a/specification/modules/report_content.rst b/specification/modules/report_content.rst new file mode 100644 index 00000000..5eca69cd --- /dev/null +++ b/specification/modules/report_content.rst @@ -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. diff --git a/specification/proposals.rst b/specification/proposals.rst index 80d1ce0f..6c41a0ac 100644 --- a/specification/proposals.rst +++ b/specification/proposals.rst @@ -49,6 +49,14 @@ proposal-wip - `@leonerd`_ - None - + * - `MSC1148 `_ + - Support for websockets + - 2015-11-16 + - 2018-06-04 + - `1148-1 `_, `1148-2 `_ + - `@richvdh`_, `@krombel`_ + - None + - * - `MSC1238 `_ - Push to Talk - 2016-04-13 @@ -68,7 +76,7 @@ proposal-wip * - `MSC1207 `_ - Publishing Room Lists for 3rd party networks - 2016-10-21 - - 2018-05-15 + - 2018-05-31 - `1207-1 `_ - `@erikjohnston`_ - None @@ -140,7 +148,7 @@ proposal-wip * - `MSC1222 `_ - Pushing updates about Groups (Communities) to clients - 2018-01-02 - - 2018-05-15 + - 2018-05-24 - `1222-1 `_ - `@ara4n`_ - None @@ -156,7 +164,7 @@ proposal-wip * - `MSC1227 `_ - 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 `_ - `@ara4n`_ - None @@ -185,6 +193,22 @@ proposal-wip - `@neilisfragile`_ - None - + * - `MSC1267 `_ + - Interactive Key Verification + - 2018-05-28 + - 2018-05-28 + - `1267-1 `_ + - `@uhoreg`_ + - None + - + * - `MSC1280 `_ + - Mechanisms for communicating erasure requests to bots and federated homeservers + - 2018-06-05 + - 2018-06-05 + - `1280-1 `_ + - `@richvdh`_ + - None + - @@ -204,18 +228,10 @@ proposal-ready-for-review - Author - Shepherd - PRs - * - `MSC1183 `_ - - Document key-share requests - - 2018-04-30 - - 2018-05-15 - - `1183-1 `_ - - `@richvdh`_ - - None - - * - `MSC1232 `_ - Media limits API - 2018-05-04 - - 2018-05-15 + - 2018-06-05 - `1232-1 `_ - `@Half-Shot`_ - None @@ -228,6 +244,14 @@ proposal-ready-for-review - `@turt2live`_ - None - + * - `MSC1270 `_ + - 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 `_ + - `@oivoodoo`_ + - None + - @@ -325,6 +349,14 @@ spec-pr-missing - Author - Shepherd - PRs + * - `MSC1200 `_ + - Configuration of E2E encryption in a room + - 2016-06-16 + - 2018-05-31 + - `1200-1 `_ + - `@richvdh`_ + - None + - * - `MSC1201 `_ - Device Management API - 2016-07-14 @@ -360,7 +392,7 @@ spec-pr-missing * - `MSC739 `_ - Reporting inappropriate content in Matrix - 2016-11-21 - - 2018-05-15 + - 2018-05-31 - `739-1 `_ - `@ara4n`_ - None @@ -421,14 +453,22 @@ spec-pr-missing - `@lukebarnard1`_ - None - - * - `MSC1216 `_ - - @room notification proposal + * - `MSC1033 `_ + - Doc @room notifications - 2017-10-23 - - 2018-05-15 - - `1216-1 `_ + - 2018-05-31 + - - `@dbkr`_ - None - - `PR#1176`_ + - + * - `MSC1183 `_ + - Document key-share requests + - 2018-04-30 + - 2018-05-31 + - `1183-1 `_ + - `@richvdh`_ + - None + - * - `MSC1230 `_ - Temporary mitigation for depth parameter abuse - 2018-05-01 @@ -464,6 +504,14 @@ merged - Author - Shepherd - PRs + * - `MSC1197 `_ + - Ignoring Users + - 2016-05-03 + - 2018-05-18 + - `1197-1 `_ + - `@erikjohnston`_ + - None + - `PR#1142`_ * - `MSC1199 `_ - Notifications API - 2016-05-23 @@ -472,14 +520,6 @@ merged - `@dbkr`_ - None - - * - `MSC1200 `_ - - Configuration of E2E encryption in a room - - 2016-06-16 - - 2018-05-15 - - `1200-1 `_ - - `@richvdh`_ - - None - - * - `MSC1204 `_ - Access Token Semantics (refresh and macaroons) - aka Auth Sept 2016 Edition - 2016-09-29 @@ -488,6 +528,14 @@ merged - `@richvdh`_ - None - + * - `MSC953 `_ + - Add /user_directory/search API + - 2017-05-31 + - 2018-05-10 + - `953-1 `_ + - `@erikjohnston`_ + - None + - * - `MSC1233 `_ - A proposal for organising spec proposals - 2018-05-10 @@ -566,6 +614,22 @@ obsolete - Author - Shepherd - PRs + * - `MSC1223 `_ + - Replies event format + - 2018-02-01 + - 2018-05-15 + - `1223-1 `_ + - `@t3chguy`_ + - None + - + * - `MSC1224 `_ + - Replies - next steps + - 2018-02-03 + - 2018-05-15 + - `1224-1 `_ + - `@t3chguy`_ + - None + - * - `MSC1235 `_ - Proposal for Calendar Events - 2018-02-06 @@ -574,34 +638,44 @@ obsolete - `@Half-Shot`_ - None - + * - `MSC1220 `_ + - Rich quoting proposal + - 2018-05-10 + - 2018-05-15 + - `1220-1 `_ + - `@t3chguy`_ + - None + - +.. _@rxl881: https://github.com/rxl881 +.. _@turt2live: https://github.com/turt2live +.. _@erikjohnston: https://github.com/erikjohnston .. _@t3chguy: https://github.com/t3chguy +.. _@Kegsay: https://github.com/Kegsay .. _@KitsuneRal: https://github.com/KitsuneRal -.. _@pik: https://github.com/pik .. _@leonerd: https://github.com/leonerd -.. _@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 +.. _@krombel: https://github.com/krombel .. _@maxidor: https://github.com/maxidor -.. _others: https://github.com/thers -.. _@rxl881: https://github.com/rxl881 .. _@uhoreg: https://github.com/uhoreg -.. _@Kegsay: https://github.com/Kegsay +.. _@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 \ No newline at end of file +.. _PR#919: https://github.com/matrix-org/matrix-doc/pull/919 \ No newline at end of file diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e9885311..9ad04d10 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -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": , "signatures": { "origin.hs.example.com": { diff --git a/specification/targets.yaml b/specification/targets.yaml index 8ca5ce30..bc9d94c8 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -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: ["=", "-", "~", "+", "^", "`", "@", ":"]