From b1801ea6db61ac003054c42d17b9f55a06f1ec21 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 12 Nov 2017 23:49:40 -0700 Subject: [PATCH 01/24] Spec /account/whoami Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 54 +++++++++++++++++++++++++++++ specification/client_server_api.rst | 5 +++ 2 files changed, 59 insertions(+) create mode 100644 api/client-server/whoami.yaml diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml new file mode 100644 index 00000000..5b622f5c --- /dev/null +++ b/api/client-server/whoami.yaml @@ -0,0 +1,54 @@ +# Copyright 2017 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 Client Config 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: + "/account/whoami": + get: + summary: Gets information about the owner of an access token. + description: |- + Gets information about the owner of a given access token. Currently this + only supports returning the user id that owns the token. + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: + The account_data was successfully added. + examples: + application/json: { + "user_id": "@joe:example.org" + } + schema: + type: object + properties: + user_id: + type: string + description: The user id that owns the access token. + tags: + - User data diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 87e90150..09f73bb9 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -786,6 +786,11 @@ This is independent of any information kept by any Identity Servers. {{administrative_contact_cs_http_api}} +Current account information +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +{{whoami_cs_http_api}} + Pagination ---------- From 2b3c84503c51fd703e4991d26910c9ab51d1d77b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 12 Nov 2017 23:54:47 -0700 Subject: [PATCH 02/24] Add /account/whoami to changelog Signed-off-by: Travis Ralston --- changelogs/client_server.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index c24f9ef4..10387c56 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -60,6 +60,9 @@ - ``GET /rooms/{roomId}/joined_members`` (`#999 `_). + - ``GET /account/whoami`` + (`#1063 `_). + - Spec clarifications: - Add endpoints and logic for invites and third-party invites to the federation From 9cf2b59f4e521f88d4a50dee1eae478766eb0994 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 12 Nov 2017 23:56:28 -0700 Subject: [PATCH 03/24] Make it less obvious where this was copy/pasted from Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index 5b622f5c..2ac2c62c 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -39,7 +39,7 @@ paths: responses: 200: description: - The account_data was successfully added. + The token belongs to a known user. examples: application/json: { "user_id": "@joe:example.org" From 41db12713d573694360d191a253a25fd13a0f22a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 13 Nov 2017 14:22:20 -0700 Subject: [PATCH 04/24] Update whoami endpoint Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index 2ac2c62c..7374ab5a 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -13,15 +13,13 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server Client Config API" + title: "Matrix Client-Server Account Identification API" version: "1.0.0" host: localhost:8008 schemes: - https - http basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% -consumes: - - application/json produces: - application/json securityDefinitions: @@ -31,8 +29,7 @@ paths: get: summary: Gets information about the owner of an access token. description: |- - Gets information about the owner of a given access token. Currently this - only supports returning the user id that owns the token. + Gets information about the owner of a given access token. security: - accessToken: [] parameters: [] From 2468c38482fc53bd3736f4c70526ec94fd393878 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 13 Nov 2017 18:47:38 -0700 Subject: [PATCH 05/24] Add required property to whoami Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index 7374ab5a..4d9d6ceb 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -43,6 +43,7 @@ paths: } schema: type: object + required: ["user_id"] properties: user_id: type: string From 0cbf533625b5c21b11a83134338c5b0a393976f7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 14 Nov 2017 13:02:43 +0000 Subject: [PATCH 06/24] Use petstore for continuserv swagger docs Matrix.org's swagger browser is behind https, which means it can't read the swagger from a continuserv on http. Use the petstore instead. --- scripts/continuserv/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/continuserv/index.html b/scripts/continuserv/index.html index f698c5b3..24ed7ecb 100644 --- a/scripts/continuserv/index.html +++ b/scripts/continuserv/index.html @@ -3,7 +3,7 @@ window.onload = function() { var url = new URL(window.location); url.pathname += "api-docs.json"; - var newLoc = "http://matrix.org/docs/api/client-server/?url=" + encodeURIComponent(url); + var newLoc = "http://petstore.swagger.io/?url=" + encodeURIComponent(url); document.getElementById("apidocs").href = newLoc; }; From 202a265d853460baaeb6431feb10ac6ea0a20247 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 14 Nov 2017 13:12:38 +0000 Subject: [PATCH 07/24] Config for travis-ci --- .travis.yml | 8 ++++++++ scripts/travis.sh | 27 +++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 .travis.yml create mode 100755 scripts/travis.sh diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..26a2f67b --- /dev/null +++ b/.travis.yml @@ -0,0 +1,8 @@ +language: go +go: + - 1.8 + +sudo: false + +script: + - ./scripts/travis.sh diff --git a/scripts/travis.sh b/scripts/travis.sh new file mode 100755 index 00000000..9fe49856 --- /dev/null +++ b/scripts/travis.sh @@ -0,0 +1,27 @@ +#! /bin/bash + +set -ex + +virtualenv env +. env/bin/activate +pip install -r scripts/requirements.txt + +# do sanity checks on the examples and swagger +(cd event-schemas/ && ./check_examples.py) +(cd api && ./check_examples.py) +(cd api && npm install && node validator.js -s "client-server") + +: ${GOPATH:=${WORKSPACE}/.gopath} +mkdir -p "${GOPATH}" +export GOPATH +go get github.com/hashicorp/golang-lru +go get gopkg.in/fsnotify.v1 + +# make sure that the scripts build +(cd scripts/continuserv && go build) +(cd scripts/speculator && go build) + +# build the spec and collect the supporting docs for matrix.org. (we aren't +# actually going to use them, since we're on travis, but we may as well check +# that the build works correctly). +./scripts/generate-matrix-org-assets From 6edb90a08e50c75536fa51f7075e42f4703db6e6 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 14:36:38 +0000 Subject: [PATCH 08/24] Document threepids Adds the /msisdn' 3pid type and generally fleshes out what a 3pid is and how they work. This merges most of the work from Max Dor in https://github.com/matrix-org/matrix-doc/pull/1039 with some tweaks and additions. --- api/identity/lookup.yaml | 8 +++-- specification/appendices/threepids.rst | 48 ++++++++++++++++++++++++++ specification/identity_service_api.rst | 5 +++ specification/targets.yaml | 1 + 4 files changed, 59 insertions(+), 3 deletions(-) create mode 100644 specification/appendices/threepids.rst diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 18e5e77d..bd3635b4 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -1,4 +1,6 @@ # Copyright 2016 OpenMarket Ltd +# Copyright 2017 Kamax.io +# Copyright 2017 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. @@ -32,13 +34,13 @@ paths: type: string name: medium required: true - description: The literal string "email". + description: The medium type of the 3pid. See `Appendices`_. x-example: "email" - in: query type: string name: address required: true - description: The email address being looked up. + description: The address of the 3pid being looked up. See `Appendices`_. x-example: "louise@bobs.burgers" responses: 200: @@ -82,4 +84,4 @@ paths: description: The unix timestamp at which the association was verified. signatures: type: object - description: The signatures of the verifying identity service which show that the association should be trusted, if you trust the verifying identity service. + description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst new file mode 100644 index 00000000..2f8147a8 --- /dev/null +++ b/specification/appendices/threepids.rst @@ -0,0 +1,48 @@ +.. Copyright 2017 Kamax.io +.. +.. 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. + +3PID Types +---------- +3PIDs represent identifiers on other namespaces that might be associated with a +particular person. They comprise a tuple of `medium` which is a string that +identifies the namespace in which the identifier exists and an `address`: a +string representing the identifier in that namespace. This must be a canonical +form of the identifier, ie. if multiple strings could represent the same +identifier, only one of these strings must be used in a 3PID address, in a +well-defined manner. + +For example, for e-mail, the `medium` is 'email' and the `address` would be the +email address, eg. the string 'bob@example.com'. Since domain resolution is +case-insensitive, the email address 'bob@Example.com' also has a 3PID address +of 'bob@example.com' and not 'bob@Example.com'. + +The namespaces defined by this specification are listed below. More namespaces +may be defined in future versions of this specification. + +E-Mail +~~~~~~ +Medium: `email` + +Represents E-Mail addresses. The `address` is the raw email address in +user@domain form with the domain in lowercase. It must not contain other text +such as real name, angle brackets or a mailto: prefix. + +PSTN Phone numbers +~~~~~~~~~~~~~~~~~~ +Medium: `msisdn` + +Represents telephone numbers on the public switched telephone network. The +`address` is the telephone number represented as a MSISDN (Mobile Station +International Subscriber Directory Number) as defined by the E.164 numbering +plan. Note that MSISDNs do not include a leading '+'. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index fa03e162..90b20d23 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -1,4 +1,6 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2017 Kamax.io +.. Copyright 2017 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. @@ -52,6 +54,8 @@ necessarily provide evidence that they have validated associations, but claim to have done so. Establishing the trustworthiness of an individual identity service is left as an exercise for the client. +3PID types are described in the `Appendices`_. + Privacy ------- @@ -291,3 +295,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe } .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`Appendices`: ../appendices.html#threepids diff --git a/specification/targets.yaml b/specification/targets.yaml index fb68e13d..6a52fd84 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -33,6 +33,7 @@ targets: files: - appendices.rst - appendices/base64.rst + - appendices/threepids.rst - appendices/signing_json.rst - appendices/identifier_grammar.rst - appendices/threat_model.rst From 0f5a4efce6affc1dc002097d16028aa8598e0582 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 14 Nov 2017 07:52:51 -0700 Subject: [PATCH 09/24] Spec URL previews (#1064) * Spec URL previews * Require authentication on /upload and /preview_url --- api/client-server/content-repo.yaml | 78 +++++++++++++++++++++++++++++ changelogs/client_server.rst | 5 ++ 2 files changed, 83 insertions(+) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index ebb63ba4..e8f23c12 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -18,15 +18,23 @@ info: host: localhost:8008 schemes: - https + - http basePath: /_matrix/media/%CLIENT_MAJOR_VERSION% +consumes: + - application/json + - "*/*" produces: - application/json - "*/*" +securityDefinitions: + $ref: definitions/security.yaml paths: "/upload": post: summary: Upload some content to the content repository. produces: ["application/json"] + security: + - accessToken: [] parameters: - in: header name: Content-Type @@ -60,6 +68,10 @@ paths: application/json: { "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media "/download/{serverName}/{mediaId}": @@ -93,6 +105,10 @@ paths: type: "string" schema: type: file + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media "/download/{serverName}/{mediaId}/{fileName}": @@ -133,6 +149,10 @@ paths: type: "string" schema: type: file + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media "/thumbnail/{serverName}/{mediaId}": @@ -184,5 +204,63 @@ paths: enum: ["image/jpeg", "image/png"] schema: type: file + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + tags: + - Media + "/preview_url": + get: + summary: "Get information about a URL for a client" + produces: ["application/json"] + security: + - accessToken: [] + parameters: + - in: query + type: string + x-example: "https://matrix.org" + name: url + description: "The URL to get a preview of" + required: true + - in: query + type: number + x-example: 1510610716656 + name: ts + description: |- + The preferred point in time to return a preview for. The server may + return a newer version if it does not have the requested version + available. + responses: + 200: + description: |- + The OpenGraph data for the URL, which may be empty. Some values are + replaced with matrix equivalents if they are provided in the response. + The differences from the OpenGraph protocol are described here. + schema: + type: object + properties: + "matrix:image:size": + type: number + description: |- + The byte-size of the image. Omitted if there is no image attached. + "og:image": + type: string + description: |- + An MXC URI to the image. Ommitted if there is no image. + examples: + application/json: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - Media diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 10387c56..e428605e 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -63,6 +63,9 @@ - ``GET /account/whoami`` (`#1063 `_). + - ``GET /media/{version}/preview_url`` + (`#1064 `_). + - Spec clarifications: - Add endpoints and logic for invites and third-party invites to the federation @@ -99,6 +102,8 @@ - Clarify the relationship between ``username`` and ``user_id`` in the ``/register`` API (`#1032 `_). + - Clarify rate limiting and security for content repository. + (`#1064 `_). r0.2.0 ====== From cdfff6787890124f393c8ca8f9f146482a63f53d Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Thu, 26 Oct 2017 03:04:43 +0200 Subject: [PATCH 10/24] Create spec for IS bulk lookup --- api/identity/lookup.yaml | 55 +++++++++++++++++++++++++- specification/identity_service_api.rst | 1 + 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 18e5e77d..4d5ab5b7 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -82,4 +82,57 @@ paths: description: The unix timestamp at which the association was verified. signatures: type: object - description: The signatures of the verifying identity service which show that the association should be trusted, if you trust the verifying identity service. + description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + "/bulk_lookup": + post: + summary: Lookup Matrix user IDs for a list of 3pid. + description: Lookup Matrix user IDs for a list of 3pid. + parameters: + - in: body + name: body + schema: + type: object + example: { + "threepids": + [ + ["email","user@example.org"], + ["msisdn", "123456789"], + ["email","user2@example.org"] + ] + } + properties: + threepids: + type: array + items: + type: array + title: 3PID mappings + items: + type: string + title: 3PID medium or address + description: an array of array containing the `3PID Medium type`_ in first position and the 3PID Address in second position. + required: + - "threepids" + responses: + 200: + description: A list of known 3PID mappings for the supplied 3PIDs. + examples: + application/json: { + "threepids": [ + ["email","user@example.org", "@bla:example.org"], + ["msisdn", "123456789", "@blah2:example.com"] + ] + } + schema: + type: object + properties: + threepids: + type: array + items: + type: array + title: 3PID mappings + items: + type: string + title: 3PID medium or address or the Matrix ID + description: an array of array containing the `3PID Medium type`_ in first position, the 3PID Address in second position and Matrix ID is in third position. + required: + - "threepids" diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index fa03e162..85b9789f 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -291,3 +291,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe } .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`3PID Types`: ../appendices.html#pid-medium-types From b789f615229b445d5399350c35bfc1314516002a Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 14:58:30 +0000 Subject: [PATCH 11/24] Make link more specific --- specification/identity_service_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 90b20d23..19275593 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -54,7 +54,7 @@ necessarily provide evidence that they have validated associations, but claim to have done so. Establishing the trustworthiness of an individual identity service is left as an exercise for the client. -3PID types are described in the `Appendices`_. +3PID types are described in `3PID Types`_ Appendix. Privacy ------- @@ -295,4 +295,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe } .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 -.. _`Appendices`: ../appendices.html#threepids +.. _`3PID Types`: ../appendices.html#pid-types From 493b9362096d7d7463570d120d06a4881b13b49c Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:01:58 +0000 Subject: [PATCH 12/24] Make these links more specific too --- api/identity/lookup.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index bd3635b4..ed16e4bf 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -34,13 +34,13 @@ paths: type: string name: medium required: true - description: The medium type of the 3pid. See `Appendices`_. + description: The medium type of the 3pid. See the `3PID Types`_ Appendix. x-example: "email" - in: query type: string name: address required: true - description: The address of the 3pid being looked up. See `Appendices`_. + description: The address of the 3pid being looked up. See the `3PID Types`_ Appendix. x-example: "louise@bobs.burgers" responses: 200: @@ -85,3 +85,5 @@ paths: 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. + +.. _`3PID Types`: ../appendices.html#pid-types From e80675c9e9135050f3b7334a40c680dcf2485b00 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:03:51 +0000 Subject: [PATCH 13/24] Link in markdown, not swagger --- api/identity/lookup.yaml | 2 -- specification/client_server_api.rst | 1 + 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index ed16e4bf..d039f2b5 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -85,5 +85,3 @@ paths: 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. - -.. _`3PID Types`: ../appendices.html#pid-types diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 09f73bb9..7cd79479 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1446,3 +1446,4 @@ have to wait in milliseconds before they can try again. .. _/user//account_data/: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`3PID Types`: ../appendices.html#pid-types From 8d557ec9dc0a78352f379f1308daf78a7acee382 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:05:58 +0000 Subject: [PATCH 14/24] Actually this isn't necessary in this section --- specification/client_server_api.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 7cd79479..09f73bb9 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1446,4 +1446,3 @@ have to wait in milliseconds before they can try again. .. _/user//account_data/: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 -.. _`3PID Types`: ../appendices.html#pid-types From ff85ec055ec51922ae94d1e8a4b8b938e5fe9a28 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:07:22 +0000 Subject: [PATCH 15/24] Move 3pid types down --- specification/targets.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/targets.yaml b/specification/targets.yaml index 6a52fd84..62799afe 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -33,9 +33,9 @@ targets: files: - appendices.rst - appendices/base64.rst - - appendices/threepids.rst - appendices/signing_json.rst - appendices/identifier_grammar.rst + - appendices/threepids.rst - appendices/threat_model.rst - appendices/test_vectors.rst groups: # reusable blobs of files when prefixed with 'group:' From 3487f5d75a20790a8c9eff2d3734a48891b4ae61 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:08:56 +0000 Subject: [PATCH 16/24] Spell out what we mean by a 3pid (and consequently rejig all the fixed-width formatting) --- specification/appendices/threepids.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst index 2f8147a8..e578a559 100644 --- a/specification/appendices/threepids.rst +++ b/specification/appendices/threepids.rst @@ -14,13 +14,13 @@ 3PID Types ---------- -3PIDs represent identifiers on other namespaces that might be associated with a -particular person. They comprise a tuple of `medium` which is a string that -identifies the namespace in which the identifier exists and an `address`: a -string representing the identifier in that namespace. This must be a canonical -form of the identifier, ie. if multiple strings could represent the same -identifier, only one of these strings must be used in a 3PID address, in a -well-defined manner. +Third Party Identifiers (3PIDs) represent identifiers on other namespaces that +might be associated with a particular person. They comprise a tuple of `medium` +which is a string that identifies the namespace in which the identifier exists +and an `address`: a string representing the identifier in that namespace. This +must be a canonical form of the identifier, ie. if multiple strings could +represent the same identifier, only one of these strings must be used in a 3PID +address, in a well-defined manner. For example, for e-mail, the `medium` is 'email' and the `address` would be the email address, eg. the string 'bob@example.com'. Since domain resolution is From 1e4cba6b5577fb59892fe63ea2442b436955b1ee Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:10:11 +0000 Subject: [PATCH 17/24] Don't linkify email addresses in examples --- specification/appendices/threepids.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst index e578a559..64dfa4b1 100644 --- a/specification/appendices/threepids.rst +++ b/specification/appendices/threepids.rst @@ -23,9 +23,9 @@ represent the same identifier, only one of these strings must be used in a 3PID address, in a well-defined manner. For example, for e-mail, the `medium` is 'email' and the `address` would be the -email address, eg. the string 'bob@example.com'. Since domain resolution is -case-insensitive, the email address 'bob@Example.com' also has a 3PID address -of 'bob@example.com' and not 'bob@Example.com'. +email address, eg. the string ``bob@example.com``. Since domain resolution is +case-insensitive, the email address ``bob@Example.com`` also has a 3PID address +of ``bob@example.com`` and not ``bob@Example.com``. The namespaces defined by this specification are listed below. More namespaces may be defined in future versions of this specification. From 4526ff2ea69d85bd13071baa8b6fd65bbe493c68 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:11:30 +0000 Subject: [PATCH 18/24] Double backticks in rst :/ --- specification/appendices/threepids.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst index 64dfa4b1..a275143f 100644 --- a/specification/appendices/threepids.rst +++ b/specification/appendices/threepids.rst @@ -15,14 +15,14 @@ 3PID Types ---------- Third Party Identifiers (3PIDs) represent identifiers on other namespaces that -might be associated with a particular person. They comprise a tuple of `medium` +might be associated with a particular person. They comprise a tuple of ``medium`` which is a string that identifies the namespace in which the identifier exists -and an `address`: a string representing the identifier in that namespace. This +and an ``address``: a string representing the identifier in that namespace. This must be a canonical form of the identifier, ie. if multiple strings could represent the same identifier, only one of these strings must be used in a 3PID address, in a well-defined manner. -For example, for e-mail, the `medium` is 'email' and the `address` would be the +For example, for e-mail, the ``medium`` is 'email' and the ``address`` would be the email address, eg. the string ``bob@example.com``. Since domain resolution is case-insensitive, the email address ``bob@Example.com`` also has a 3PID address of ``bob@example.com`` and not ``bob@Example.com``. @@ -32,17 +32,17 @@ may be defined in future versions of this specification. E-Mail ~~~~~~ -Medium: `email` +Medium: ``email`` -Represents E-Mail addresses. The `address` is the raw email address in +Represents E-Mail addresses. The ``address`` is the raw email address in user@domain form with the domain in lowercase. It must not contain other text such as real name, angle brackets or a mailto: prefix. PSTN Phone numbers ~~~~~~~~~~~~~~~~~~ -Medium: `msisdn` +Medium: ``msisdn`` Represents telephone numbers on the public switched telephone network. The -`address` is the telephone number represented as a MSISDN (Mobile Station +``address`` is the telephone number represented as a MSISDN (Mobile Station International Subscriber Directory Number) as defined by the E.164 numbering plan. Note that MSISDNs do not include a leading '+'. From e12c0b54ff8c93a77702faed74232abb7eec0ea8 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:12:30 +0000 Subject: [PATCH 19/24] Formatting & grammar --- specification/appendices/threepids.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst index a275143f..cd312710 100644 --- a/specification/appendices/threepids.rst +++ b/specification/appendices/threepids.rst @@ -16,9 +16,9 @@ ---------- Third Party Identifiers (3PIDs) represent identifiers on other namespaces that might be associated with a particular person. They comprise a tuple of ``medium`` -which is a string that identifies the namespace in which the identifier exists +which is a string that identifies the namespace in which the identifier exists, and an ``address``: a string representing the identifier in that namespace. This -must be a canonical form of the identifier, ie. if multiple strings could +must be a canonical form of the identifier, *ie.* if multiple strings could represent the same identifier, only one of these strings must be used in a 3PID address, in a well-defined manner. From 836e6c81d1dc81b177e244b91af418d6aee2aa94 Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Thu, 26 Oct 2017 12:37:25 +0200 Subject: [PATCH 20/24] Fix spelling --- api/identity/lookup.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 4d5ab5b7..385e8a60 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -85,8 +85,8 @@ paths: description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. "/bulk_lookup": post: - summary: Lookup Matrix user IDs for a list of 3pid. - description: Lookup Matrix user IDs for a list of 3pid. + summary: Lookup Matrix user IDs for a list of 3pids. + description: Lookup Matrix user IDs for a list of 3pids. parameters: - in: body name: body @@ -109,7 +109,7 @@ paths: items: type: string title: 3PID medium or address - description: an array of array containing the `3PID Medium type`_ in first position and the 3PID Address in second position. + description: an array of arrays containing the `3PID Medium type`_ in first position and the 3PID Address in second position. required: - "threepids" responses: From 9c5972ffe34039f965cb184ac24dfb64c2d6601d Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:31:02 +0000 Subject: [PATCH 21/24] More formatting / grammar --- specification/appendices/threepids.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst index cd312710..652ec4c7 100644 --- a/specification/appendices/threepids.rst +++ b/specification/appendices/threepids.rst @@ -18,12 +18,12 @@ Third Party Identifiers (3PIDs) represent identifiers on other namespaces that might be associated with a particular person. They comprise a tuple of ``medium`` which is a string that identifies the namespace in which the identifier exists, and an ``address``: a string representing the identifier in that namespace. This -must be a canonical form of the identifier, *ie.* if multiple strings could +must be a canonical form of the identifier, *i.e.* if multiple strings could represent the same identifier, only one of these strings must be used in a 3PID address, in a well-defined manner. For example, for e-mail, the ``medium`` is 'email' and the ``address`` would be the -email address, eg. the string ``bob@example.com``. Since domain resolution is +email address, *e.g.* the string ``bob@example.com``. Since domain resolution is case-insensitive, the email address ``bob@Example.com`` also has a 3PID address of ``bob@example.com`` and not ``bob@Example.com``. @@ -35,7 +35,7 @@ E-Mail Medium: ``email`` Represents E-Mail addresses. The ``address`` is the raw email address in -user@domain form with the domain in lowercase. It must not contain other text +``user@domain`` form with the domain in lowercase. It must not contain other text such as real name, angle brackets or a mailto: prefix. PSTN Phone numbers From 14df31458b86a4c1be022d842cf15cda63a28dde Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 15:39:25 +0000 Subject: [PATCH 22/24] Attempt to clarify example a little --- specification/appendices/threepids.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst index 652ec4c7..84860740 100644 --- a/specification/appendices/threepids.rst +++ b/specification/appendices/threepids.rst @@ -24,8 +24,8 @@ address, in a well-defined manner. For example, for e-mail, the ``medium`` is 'email' and the ``address`` would be the email address, *e.g.* the string ``bob@example.com``. Since domain resolution is -case-insensitive, the email address ``bob@Example.com`` also has a 3PID address -of ``bob@example.com`` and not ``bob@Example.com``. +case-insensitive, the email address ``bob@Example.com`` is also has the 3PID address +of ``bob@example.com`` (without the capital 'e') rather than ``bob@Example.com``. The namespaces defined by this specification are listed below. More namespaces may be defined in future versions of this specification. From 5147a3b975d258699831fbe49358274b68a8cba5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 17:14:56 +0000 Subject: [PATCH 23/24] Fix broken links & grammar --- api/identity/lookup.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 285844c0..7cd7fded 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -111,7 +111,7 @@ paths: items: type: string title: 3PID medium or address - description: an array of arrays containing the `3PID Medium type`_ in first position and the 3PID 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: @@ -135,6 +135,6 @@ paths: items: type: string title: 3PID medium or address or the Matrix ID - description: an array of array containing the `3PID Medium type`_ in first position, the 3PID Address in second position and Matrix ID is 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 ID in third position. required: - "threepids" From 427e0bb83bb94e56ef8bb4268c423d35ce251a61 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 14 Nov 2017 19:18:58 +0000 Subject: [PATCH 24/24] make jenkins and travis use a common script --- .travis.yml | 2 +- jenkins.sh | 26 ++---------------------- scripts/{travis.sh => test-and-build.sh} | 8 +++++--- 3 files changed, 8 insertions(+), 28 deletions(-) rename scripts/{travis.sh => test-and-build.sh} (74%) diff --git a/.travis.yml b/.travis.yml index 26a2f67b..03ef6513 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,4 +5,4 @@ go: sudo: false script: - - ./scripts/travis.sh + - ./scripts/test-and-build.sh diff --git a/jenkins.sh b/jenkins.sh index d8950ade..79b77acb 100755 --- a/jenkins.sh +++ b/jenkins.sh @@ -1,25 +1,3 @@ -#! /bin/bash +#!/bin/sh -set -ex - -virtualenv env -. env/bin/activate -pip install -r scripts/requirements.txt - -# do sanity checks on the examples and swagger -(cd event-schemas/ && ./check_examples.py) -(cd api && ./check_examples.py) -(cd api && npm install && node validator.js -s "client-server") - -: ${GOPATH:=${WORKSPACE}/.gopath} -mkdir -p "${GOPATH}" -export GOPATH -go get github.com/hashicorp/golang-lru -go get gopkg.in/fsnotify.v1 - -# make sure that the scripts build -(cd scripts/continuserv && go build) -(cd scripts/speculator && go build) - -# build the spec and collect the supporting docs for matrix.org -./scripts/generate-matrix-org-assets +exec ./scripts/test-and-build.sh diff --git a/scripts/travis.sh b/scripts/test-and-build.sh similarity index 74% rename from scripts/travis.sh rename to scripts/test-and-build.sh index 9fe49856..cd25ded2 100755 --- a/scripts/travis.sh +++ b/scripts/test-and-build.sh @@ -2,6 +2,8 @@ set -ex +cd `dirname $0`/.. + virtualenv env . env/bin/activate pip install -r scripts/requirements.txt @@ -21,7 +23,7 @@ go get gopkg.in/fsnotify.v1 (cd scripts/continuserv && go build) (cd scripts/speculator && go build) -# build the spec and collect the supporting docs for matrix.org. (we aren't -# actually going to use them, since we're on travis, but we may as well check -# that the build works correctly). +# build the spec for matrix.org. +# (we don't actually use it on travis, but it's still useful to check we +# can build it. On Jenkins, this is then used to deploy to matrix.org). ./scripts/generate-matrix-org-assets