Merge branch 'master' into anoa/document_as_options

README.rst

@@ -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::

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."

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

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

api/client-server/search.yaml

@@ -53,9 +53,7 @@ paths:
                     "keys": [
                       "content.body"
                     ],
-                    "search_term": "martians and men"
+                    "search_term": "martians and men",
-                  }
-                },
                     "order_by": "recent",
                     "groupings": {
                       "group_by": [
@@ -65,6 +63,8 @@ paths:
                       ]
                     }
                   }
+                }
+              }
             properties:
               search_categories:
                 type: object
@@ -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": [

changelogs/client_server.rst

@@ -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
 ======

scripts/continuserv/README

@@ -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`

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).

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)]

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.

specification/proposals.rst

@@ -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>`_
+   * - `MSC1033 <https://github.com/matrix-org/matrix-doc/issues/1033>`_
-     - @room notification proposal
+     - Doc @room notifications
      - 2017-10-23
-     - 2018-05-15
+     - 2018-05-31
-     - `1216-1 <https://docs.google.com/document/d/1qRdlg94cr9YXxPCwhW4HgI2oDrqQOUKX5HptZFBGf6o/edit>`_
+     - 
      - `@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
+     - 
 
 
 
 
 
+.. _@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
+.. _@krombel: https://github.com/krombel
-.. _@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
-.. _@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

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": <request body>,
         "signatures": {
             "origin.hs.example.com": {

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: ["=", "-", "~", "+", "^", "`", "@", ":"]