From 114bcf1a2e1d612c15a735612e8a8f0ab9fb3b4f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 6 Jul 2018 10:28:57 +0100 Subject: [PATCH] Use $ref, clean up, fix errors, AS is now a C-S module. --- .../application_service.yaml | 192 +---- .../definitions/schema/location.yaml | 30 + .../definitions/schema/location_batch.yaml | 17 + .../definitions/schema/protocol.yaml | 79 ++ .../definitions/schema/protocol_metadata.yaml | 66 ++ .../definitions/schema/user.yaml | 31 + .../definitions/schema/user_batch.yaml | 17 + api/client-server/third_party_lookup.yaml | 209 +---- specification/feature_profiles.rst | 2 + .../application_services.rst} | 2 + specification/proposals.rst | 770 +----------------- specification/targets.yaml | 2 +- 12 files changed, 323 insertions(+), 1094 deletions(-) create mode 100644 api/application-service/definitions/schema/location.yaml create mode 100644 api/application-service/definitions/schema/location_batch.yaml create mode 100644 api/application-service/definitions/schema/protocol.yaml create mode 100644 api/application-service/definitions/schema/protocol_metadata.yaml create mode 100644 api/application-service/definitions/schema/user.yaml create mode 100644 api/application-service/definitions/schema/user_batch.yaml rename specification/{third_party_lookup.rst => modules/application_services.rst} (94%) diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml index 86411ffa..b68cbe18 100644 --- a/api/application-service/application_service.yaml +++ b/api/application-service/application_service.yaml @@ -131,7 +131,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. @@ -140,7 +140,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 404: description: |- The application service indicates that this room alias does not exist. @@ -150,7 +150,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - type: object + $ref: ../client-server/definitions/error.yaml "/users/{userId}": get: summary: Query if a user should exist on the application service. @@ -187,7 +187,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. @@ -196,7 +196,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 404: description: |- The application service indicates that this user does not exist. @@ -206,7 +206,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - type: object + $ref: ../client-server/definitions/error.yaml "/_matrix/app/unstable/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the application service supports. @@ -219,44 +219,14 @@ paths: - in: path name: protocol type: string - description: |- - The name of the protocol. + description: The protocol ID. required: true x-example: "irc" responses: 200: description: The protocol was found and metadata returned. - examples: - application/json: { - "user_fields": ["network", "nickname"], - "location_fields": ["network", "channel"], - "icon": "mxc://example.org/aBcDeFgH", - "field_types": { - "network": { - "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", - "placeholder": "irc.example.org" - }, - "nickname": { - "regexp": "[^\\s]+", - "placeholder": "username" - }, - "channel": { - "regexp": "#[^\\s]+", - "placeholder": "#foobar" - } - }, - "instances": [ - { - "desc": "Freenode", - "icon": "mxc://example.org/JkLmNoPq", - "fields": { - "network": "freenode.net", - } - } - ] - } schema: - type: object + $ref: definitions/schema/protocol_metadata.yaml 401: description: |- The homeserver has not supplied credentials to the application service. @@ -266,7 +236,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. @@ -275,7 +245,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 404: description: No protocol was found with the given path. examples: @@ -283,20 +253,20 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - type: object + $ref: ../client-server/definitions/error.yaml "/_matrix/app/unstable/thirdparty/user/{protocol}": get: - summary: Retrieve the Matrix ID of a corresponding third party user. + summary: Retrieve the Matrix User ID of a corresponding third party user. description: |- - This API is called by the homeserver in order to retrieve a Matrix ID linked - to a user on the external service, given a set of user parameters. + This API is called by the homeserver in order to retrieve a Matrix + User ID linked to a user on the third party network, given a set of + user parameters. operationId: queryUserByProtocol parameters: - in: path name: protocol type: string - description: |- - The name of the protocol. + description: The protocol ID. required: true x-example: irc - in: query @@ -307,35 +277,9 @@ paths: service to help identify the user. responses: 200: - description: The Matrix IDs found with the given parameters. - examples: - application/json: [{ - "userid": "@_gitter_jim:matrix.org", - "protocol": "gitter", - "fields": { - "user": "jim" - } - }] + description: The Matrix User IDs found with the given parameters. schema: - type: array - description: Matched users. - items: - type: object - title: User - schema: - userid: - type: string - description: The Matrix ID of the matched user. - protocol: - type: string - description: The third party protocol. - fields: - type: object - description: The third party network fields used to identify this user. - properties: - user: - type: string - description: An example field, in this case the username for a Gitter user. + $ref: definitions/schema/user_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. @@ -345,7 +289,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. @@ -354,7 +298,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 404: description: No users were found with the given parameters. examples: @@ -362,27 +306,20 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - type: object + $ref: ../client-server/definitions/error.yaml "/_matrix/app/unstable/thirdparty/location/{protocol}": get: summary: Retreive Matrix-side portal rooms leading to a third party location. description: |- - Requesting this endpoint with a valid protocol name results in a list - of successful mapping results in a JSON array. Each result contains - objects to represent the Matrix room or rooms that represent a portal - to this third party network. Each has the Matrix room alias string, - an identifier for the particular third party network protocol, and an - object containing the network-specific fields that comprise this - identifier. It should attempt to canonicalise the identifier as much - as reasonably possible given the network type. + Retrieve a list of Matrix portal rooms that lead to the matched third party location. operationId: queryLocationByProtocol parameters: - in: path name: protocol type: string - description: The protocol used to communicate to the third party network. + description: The protocol ID. required: true - x-example: "irc" + x-example: irc - in: query name: field1, field2... type: string @@ -392,23 +329,8 @@ paths: responses: 200: description: At least one portal room was found. - examples: - application/json: [{ - "alias": "#freenode_#matrix:matrix.org", - "protocol": "irc", - "fields": { - "network": "freenode", - "channel": "#matrix" - } - }] schema: - type: array - description: |- - Array of portal rooms leading to the requested third party - location. - items: - type: object - title: Portal Room + $ref: definitions/schema/location_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. @@ -418,7 +340,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. @@ -427,7 +349,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 404: description: No mappings were found with the given parameters. examples: @@ -435,7 +357,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - type: object + $ref: ../client-server/definitions/error.yaml "/_matrix/app/unstable/thirdparty/location": get: summary: Reverse-lookup third party locations given a Matrix room alias. @@ -444,30 +366,16 @@ paths: alias. operationId: queryLocationByAlias parameters: - - in: query - name: alias - type: string - description: The Matrix room alias to look up. + - in: query + name: alias + type: string + description: The Matrix room alias to look up. responses: 200: description: |- - All found third party locations. Same response format as the - forward lookup response. - examples: - application/json: [{ - "alias": "#freenode_#matrix:matrix.org", - "protocol": "irc", - "fields": { - "network": "freenode", - "channel": "#matrix" - } - }] + All found third party locations. schema: - type: array - description: Matched third party locations. - items: - type: object - title: Location + $ref: definitions/schema/location_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. @@ -477,7 +385,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. @@ -486,7 +394,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 404: description: No mappings were found with the given parameters. examples: @@ -494,36 +402,24 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - type: object + $ref: ../client-server/definitions/error.yaml "/_matrix/app/unstable/thirdparty/user": get: - summary: Reverse-lookup third party users given a Matrix ID. + summary: Reverse-lookup third party users given a Matrix User ID. description: |- - Retreive an array of third party users from a Matrix ID. + Retreive an array of third party users from a Matrix User ID. operationId: queryUserByID parameters: - in: query name: userid type: string - description: The Matrix ID to look up. + description: The Matrix User ID to look up. responses: 200: description: |- An array of third party users. - examples: - application/json: [{ - "userid": "@_gitter_jim:matrix.org", - "protocol": "gitter", - "fields": { - "user": "jim" - } - }] schema: - type: array - description: Matched third party users - items: - type: object - title: User + $ref: definitions/schema/user_batch.yaml 401: description: |- The homeserver has not supplied credentials to the application service. @@ -533,7 +429,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 403: description: |- The credentials supplied by the homeserver were rejected. @@ -542,7 +438,7 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" } schema: - type: object + $ref: ../client-server/definitions/error.yaml 404: description: No mappings were found with the given parameters. examples: @@ -550,4 +446,4 @@ paths: "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" } schema: - type: object \ No newline at end of file + $ref: ../client-server/definitions/error.yaml \ No newline at end of file diff --git a/api/application-service/definitions/schema/location.yaml b/api/application-service/definitions/schema/location.yaml new file mode 100644 index 00000000..4967ef61 --- /dev/null +++ b/api/application-service/definitions/schema/location.yaml @@ -0,0 +1,30 @@ +# Copyright 2018 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. +# 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. +properties: + alias: + description: An alias for a matrix room. + type: string + example: "#freenode_#matrix:matrix.org" + protocol: + description: The protocol ID that the third party location is a part of. + type: string + example: irc + fields: + description: Information used to identify this third party location. + type: object + example: + "network": "freenode" + "channel": "#matrix" +title: Location +type: object \ No newline at end of file diff --git a/api/application-service/definitions/schema/location_batch.yaml b/api/application-service/definitions/schema/location_batch.yaml new file mode 100644 index 00000000..3f6de9df --- /dev/null +++ b/api/application-service/definitions/schema/location_batch.yaml @@ -0,0 +1,17 @@ +# Copyright 2018 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. +# 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. +type: array +description: List of matched third party locations. +items: + $ref: location.yaml diff --git a/api/application-service/definitions/schema/protocol.yaml b/api/application-service/definitions/schema/protocol.yaml new file mode 100644 index 00000000..231e8288 --- /dev/null +++ b/api/application-service/definitions/schema/protocol.yaml @@ -0,0 +1,79 @@ +# Copyright 2018 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. +# 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. +properties: + user_fields: + description: Fields used to identify a third party user. + type: array + items: + type: string + description: Field used to identify a third party user. + example: ["network", "nickname"] + location_fields: + description: Fields used to identify a third party location. + type: array + items: + type: string + description: Field used to identify a third party location. + example: ["network", "channel"] + icon: + description: An icon representing the third party protocol. + type: string + example: "mxc://example.org/aBcDeFgH" + field_types: + title: Field Types + description: All location or user fields should have an entry here. + type: object + properties: + fieldname: + title: Field Type + description: Definition of valid values for a field. + type: object + properties: + regexp: + description: A regular expression for validation of a field's value. + type: string + placeholder: + description: An placeholder serving as a valid example of the field value. + type: string + example: { + "network": { + "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", + "placeholder": "irc.example.org" + }, + "nickname": { + "regexp": "[^\\s#]+", + "placeholder": "username" + }, + "channel": { + "regexp": "#[^\\s]+", + "placeholder": "#foobar" + } + } + instances: + description: |- + A list of objects representing independent instances of configuration. + For instance multiple networks on IRC if multiple are bridged by the + same bridge. + type: array + items: + type: object + example: { + "desc": "Freenode", + "icon": "mxc://example.org/JkLmNoPq", + "fields": { + "network": "freenode.net", + } + } +title: Protocol +type: object \ No newline at end of file diff --git a/api/application-service/definitions/schema/protocol_metadata.yaml b/api/application-service/definitions/schema/protocol_metadata.yaml new file mode 100644 index 00000000..72264060 --- /dev/null +++ b/api/application-service/definitions/schema/protocol_metadata.yaml @@ -0,0 +1,66 @@ +# Copyright 2018 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. +# 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. +type: object +description: Dictionary of supported third party protocols. +example: { + "irc": { + "user_fields": ["network", "nickname"], + "location_fields": ["network", "channel"], + "icon": "mxc://example.org/aBcDeFgH", + "field_types": { + "network": { + "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", + "placeholder": "irc.example.org" + }, + "nickname": { + "regexp": "[^\\s]+", + "placeholder": "username" + }, + "channel": { + "regexp": "#[^\\s]+", + "placeholder": "#foobar" + } + }, + "instances": [ + { + "desc": "Freenode", + "icon": "mxc://example.org/JkLmNoPq", + "fields": { + "network": "freenode.net", + } + } + ] + }, + "gitter": { + "user_fields": ["username"], + "location_fields": ["room"], + "field_types": { + "username": { + "regexp": "@[^\\s]+", + "placeholder": "@username" + }, + "room": { + "regexp": "[^\\s]+\\/[^\\s]+", + "placeholder": "matrix-org/matrix-doc" + } + }, + "instances": [ + { + "desc": "Gitter", + "icon": "mxc://example.org/zXyWvUt", + "fields": {} + } + ] + } +} \ No newline at end of file diff --git a/api/application-service/definitions/schema/user.yaml b/api/application-service/definitions/schema/user.yaml new file mode 100644 index 00000000..5f8d0460 --- /dev/null +++ b/api/application-service/definitions/schema/user.yaml @@ -0,0 +1,31 @@ +# Copyright 2018 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. +# 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. + +# TODO: Change userid to user_id as a breaking change +properties: + userid: + description: A Matrix User ID represting a third party user. + type: string + example: "@_gitter_jim:matrix.org" + protocol: + description: The protocol ID that the third party location is a part of. + type: string + example: gitter + fields: + description: Information used to identify this third party location. + type: object + example: + "user": "jim" +title: Location +type: object \ No newline at end of file diff --git a/api/application-service/definitions/schema/user_batch.yaml b/api/application-service/definitions/schema/user_batch.yaml new file mode 100644 index 00000000..3653feb4 --- /dev/null +++ b/api/application-service/definitions/schema/user_batch.yaml @@ -0,0 +1,17 @@ +# Copyright 2018 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. +# 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. +type: array +description: List of matched third party users. +items: + $ref: user.yaml diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml index 343cf2b7..86389603 100644 --- a/api/client-server/third_party_lookup.yaml +++ b/api/client-server/third_party_lookup.yaml @@ -24,6 +24,8 @@ consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/thirdparty/protocols": get: @@ -36,60 +38,8 @@ paths: responses: 200: description: The protocols supported by the homeserver. - examples: - application/json: { - "irc": { - "user_fields": ["network", "nickname"], - "location_fields": ["network", "channel"], - "icon": "mxc://example.org/aBcDeFgH", - "field_types": { - "network": { - "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", - "placeholder": "irc.example.org" - }, - "nickname": { - "regexp": "[^\\s]+", - "placeholder": "username" - }, - "channel": { - "regexp": "#[^\\s]+", - "placeholder": "#foobar" - } - }, - "instances": [ - { - "desc": "Freenode", - "icon": "mxc://example.org/JkLmNoPq", - "fields": { - "network": "freenode.net", - } - } - ] - }, - "gitter": { - "user_fields": ["username"], - "location_fields": ["room"], - "field_types": { - "username": { - "regexp": "@[^\\s]+", - "placeholder": "@username" - }, - "room": { - "regexp": "[^\\s]+\\/[^\\s]+", - "placeholder": "matrix-org/matrix-doc" - } - }, - "instances": [ - { - "desc": "Gitter", - "icon": "mxc://example.org/zXyWvUt", - "fields": {} - } - ] - } - } schema: - type: object + $ref: ../application-service/definitions/schema/protocol_metadata.yaml "/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the homeserver supports. @@ -107,45 +57,16 @@ paths: responses: 200: description: The protocol was found and metadata returned. - examples: - application/json: { - "user_fields": ["network", "nickname"], - "location_fields": ["network", "channel"], - "icon": "mxc://example.org/aBcDeFgH", - "field_types": { - "network": { - "regexp": "([a-z0-9]+\\.)*[a-z0-9]+", - "placeholder": "irc.example.org" - }, - "nickname": { - "regexp": "[^\\s#]+", - "placeholder": "username" - }, - "channel": { - "regexp": "#[^\\s]+", - "placeholder": "#foobar" - } - }, - "instances": [ - { - "desc": "Freenode", - "icon": "mxc://example.org/JkLmNoPq", - "fields": { - "network": "freenode.net", - } - } - ] - } schema: - type: object + $ref: ../application-service/definitions/schema/protocol.yaml 404: - description: The protocol is unknown + description: The protocol is unknown. examples: application/json: { "errcode": "M_NOT_FOUND" } schema: - type: object + $ref: definitions/error.yaml "/thirdparty/location/{protocol}": get: summary: Retreive Matrix-side portals rooms leading to a third party location. @@ -165,9 +86,9 @@ paths: type: string description: The protocol used to communicate to the third party network. required: true - x-example: "irc" + x-example: irc - in: query - name: field1, field2... + name: searchFields type: string description: |- One or more custom fields to help identify the third party @@ -175,36 +96,21 @@ paths: responses: 200: description: At least one portal room was found. - examples: - application/json: [{ - "alias": "#freenode_#matrix:matrix.org", - "protocol": "irc", - "fields": { - "network": "freenode", - "channel": "#matrix" - } - }] schema: - type: array - description: |- - Array of portal rooms leading to the requested third party - location. - items: - type: object - title: Portal Room + $ref: ../application-service/definitions/schema/location_batch.yaml 404: - description: The Matrix room alias was not found + description: No portal rooms were found. examples: application/json: { "errcode": "M_NOT_FOUND" } schema: - type: object + $ref: definitions/error.yaml "/thirdparty/user/{protocol}": get: - summary: Retrieve the Matrix ID of a corresponding third party user. + summary: Retrieve the Matrix User ID of a corresponding third party user. description: |- - Retrieve a Matrix ID linked to a user on the third party service, given + Retrieve a Matrix User ID linked to a user on the third party service, given a set of user parameters. operationId: queryUserByProtocol parameters: @@ -222,43 +128,16 @@ paths: One or more custom fields that are passed to the AS to help identify the user. responses: 200: - description: The Matrix IDs found with the given parameters. - examples: - application/json: [{ - "userid": "@_gitter_jim:matrix.org", - "protocol": "gitter", - "fields": { - "user": "jim" - } - }] - schema: - type: array - description: Matched users. - items: - type: object - title: User - schema: - userid: - type: string - description: The Matrix ID of the matched user. - protocol: - type: string - description: The third party protocol. - fields: - type: object - description: The third party network fields used to identify this user. - properties: - user: - type: string - description: An example field, in this case the username for a Gitter user. + description: The Matrix User IDs found with the given parameters. + $ref: ../application-service/definitions/schema/user_batch.yaml 404: - description: The Matrix ID was not found + description: The Matrix User ID was not found examples: application/json: { "errcode": "M_NOT_FOUND" } schema: - type: object + $ref: definitions/error.yaml "/thirdparty/location": get: summary: Reverse-lookup third party locations given a Matrix room alias. @@ -267,30 +146,17 @@ paths: alias. operationId: queryLocationByAlias parameters: - - in: path - name: alias - type: string - description: The Matrix room alias to look up. + - in: path + name: alias + type: string + description: The Matrix room alias to look up. + required: true responses: 200: description: |- - All found third party locations. Same response format as the - forward lookup response. - examples: - application/json: [{ - "alias": "#freenode_#matrix:matrix.org", - "protocol": "irc", - "fields": { - "network": "freenode", - "channel": "#matrix" - } - }] + All found third party locations. schema: - type: array - description: Matched third party locations. - items: - type: object - title: Location + $ref: ../application-service/definitions/schema/location_batch.yaml 404: description: The Matrix room alias was not found examples: @@ -298,41 +164,30 @@ paths: "errcode": "M_NOT_FOUND" } schema: - type: object + $ref: definitions/error.yaml "/thirdparty/user": get: - summary: Reverse-lookup third party users given a Matrix ID. + summary: Reverse-lookup third party users given a Matrix User ID. description: |- - Retreive an array of third party users from a Matrix ID. + Retreive an array of third party users from a Matrix User ID. operationId: queryUserByID parameters: - in: path name: userid type: string - description: The Matrix ID to look up. + description: The Matrix User ID to look up. + required: true responses: 200: description: |- An array of third party users. - examples: - application/json: [{ - "userid": "@_gitter_jim:matrix.org", - "protocol": "gitter", - "fields": { - "user": "jim" - } - }] schema: - type: array - description: Matched third party users - items: - type: object - title: User + $ref: ../application-service/definitions/schema/user_batch.yaml 404: - description: The Matrix ID was not found + description: The Matrix User ID was not found examples: application/json: { "errcode": "M_NOT_FOUND" } schema: - type: object \ No newline at end of file + $ref: definitions/error.yaml \ No newline at end of file diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst index 7fc9696d..97d0de0e 100644 --- a/specification/feature_profiles.rst +++ b/specification/feature_profiles.rst @@ -42,6 +42,7 @@ Summary `Server Side Search`_ Optional Optional Optional Optional Optional `Server Administration`_ Optional Optional Optional Optional Optional `Event Context`_ Optional Optional Optional Optional Optional + `Application Services`_ Optional Optional Optional Optional Optional ===================================== ========== ========== ========== ========== ========== *Please see each module for more details on what clients need to implement.* @@ -57,6 +58,7 @@ Summary .. _Server Side Search: `module:search`_ .. _Server Administration: `module:admin`_ .. _Event Context: `module:event-context`_ +.. _Application Services: `module:application-services`_ Clients ------- diff --git a/specification/third_party_lookup.rst b/specification/modules/application_services.rst similarity index 94% rename from specification/third_party_lookup.rst rename to specification/modules/application_services.rst index 6325dca0..52e35dc8 100644 --- a/specification/third_party_lookup.rst +++ b/specification/modules/application_services.rst @@ -1,6 +1,8 @@ Application Services ==================== +.. _module:application-services: + An application service is a separate program that interacts with a homeserver and provides various bits of functionality that would otherwise not make sense to include directly in the homeserver. This ranges from bots, which can diff --git a/specification/proposals.rst b/specification/proposals.rst index d04edfa8..371850ab 100644 --- a/specification/proposals.rst +++ b/specification/proposals.rst @@ -1,772 +1,6 @@ Tables of Tracked Proposals --------------------------- -proposal-wip -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This file is autogenerated by a jenkins build process -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - Author - - Shepherd - - PRs - * - `MSC455 `_ - - Do we want to specify a matrix:// URI scheme for rooms? (SPEC-5) - - 2014-09-15 - - 2018-05-15 - - `455-1 `_ - - `@KitsuneRal`_ - - None - - - * - `MSC586 `_ - - Federation API for canonicalising MXIDs - - 2014-10-27 - - 2018-05-15 - - `586-1 `_ - - `@ara4n`_ - - None - - - * - `MSC489 `_ - - Extensible Profiles. (SPEC-93) - - 2015-01-19 - - 2018-05-15 - - `489-1 `_ - - `@erikjohnston`_ - - None - - - * - `MSC1196 `_ - - Matrix Escape Hatch (Versioned Rooms) - - 2015-10-22 - - 2018-05-15 - - `1196-1 `_ - - `@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 - - 2018-05-15 - - `1238-1 `_ - - `@aviraldg`_ - - None - - `PR#310`_ - * - `MSC1198 `_ - - Threading API - - 2016-05-23 - - 2018-05-15 - - `1198-1 `_ - - `@Half-Shot`_ - - None - - - * - `MSC1207 `_ - - Publishing Room Lists for 3rd party networks - - 2016-10-21 - - 2018-05-31 - - `1207-1 `_ - - `@erikjohnston`_ - - None - - - * - `MSC441 `_ - - Support for Reactions / Aggregations - - 2016-12-25 - - 2018-05-15 - - `441-1 `_ - - `@pik`_ - - `@ara4n`_ - - - * - `MSC1237 `_ - - Improving m.location with GeoJSON and accuracy - - 2017-05-19 - - 2018-05-15 - - `1237-1 `_ - - `@Half-Shot`_ - - None - - `PR#919`_ - * - `MSC971 `_ - - Add groups stuff to spec - - 2017-08-10 - - 2018-05-20 - - `971-1 `_, `971-2 `_, `971-3 `_ - - `@erikjohnston`_ - - None - - - * - `MSC1215 `_ - - Groups as Rooms - - 2017-10-17 - - 2018-05-15 - - `1215-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1217 `_ - - Visibility of groups to group members and their non-members - - 2017-10-30 - - 2018-05-15 - - `1217-1 `_ - - `@lampholder`_ - - None - - - * - `MSC1218 `_ - - Bridging group membership with 3rd party group sources - - 2017-11-15 - - 2018-05-15 - - `1218-1 `_ - - `@lukebarnard1`_ - - None - - - * - `MSC1219 `_ - - Proposal for storing megolm keys serverside - - 2017-11-23 - - 2018-05-15 - - `1219-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1221 `_ - - Improving Presence - - 2017-12-26 - - 2018-05-24 - - `1221-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1222 `_ - - Pushing updates about Groups (Communities) to clients - - 2018-01-02 - - 2018-05-24 - - `1222-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1225 `_ - - Extensible event types & fallback in Matrix - - 2018-02-18 - - 2018-05-15 - - `1225-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1206 `_ - - Proposal for improved bot support - - 2018-03-14 - - 2018-06-08 - - `1206-1 `_ - - `@turt2live`_ - - None - - - * - `MSC1228 `_ - - Removing MXIDs from events - - 2018-04-19 - - 2018-05-15 - - `1228-1 `_ - - `@richvdh`_ - - None - - - * - `MSC1231 `_ - - Handling Consent for Privacy Policy - - 2018-05-02 - - 2018-05-15 - - `1231-1 `_ - - `@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 - - - * - `MSC688 `_ - - Calculate room names server-side - - 2018-06-10 - - 2018-06-15 - - `688-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1324 `_ - - Custom protocol definitions for application services - - 2018-06-20 - - 2018-06-20 - - `1324-1 `_ - - `@anoadragon453`_ - - None - - - * - `MSC1323 `_ - - AS traffic rate-limiting - - 2018-06-20 - - 2018-07-03 - - `1323-1 `_ - - `@anoadragon453`_ - - None - - - * - `MSC1322 `_ - - Mechanism to communicate 3PID binding updates or deletions to homeservers - - 2018-06-20 - - 2018-06-20 - - `1322-1 `_ - - `@babolivier`_ - - None - - - - - -proposal-ready-for-review -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - Author - - Shepherd - - PRs - * - `MSC1227 `_ - - Proposal for lazy-loading room members to improve initial sync speed and client RAM usage - - 2018-03-05 - - 2018-06-10 - - `1227-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1206 `_ - - Proposal for improved bot support - - 2018-03-14 - - 2018-06-08 - - `1206-1 `_ - - `@turt2live`_ - - None - - - * - `MSC1256 `_ - - Custom emoji and sticker packs in matrix - - 2018-05-23 - - 2018-05-24 - - `1256-1 `_ - - `@turt2live`_ - - None - - - * - `MSC1270 `_ - - Proposal Add /_matrix/media/v1/resolve_url to Client-Server API: download and preview urls in the clients despite CORS - - 2018-05-31 - - 2018-06-19 - - `1270-1 `_ - - `@oivoodoo`_ - - None - - - * - `MSC701 `_ - - Auth for content repo (and enforcing GDPR erasure) - - 2018-06-04 - - 2018-06-07 - - `701-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1304 `_ - - Proposal to simplify the auth rules of m.room.power_level events. - - 2018-06-13 - - 2018-06-14 - - `1304-1 `_ - - `@richvdh`_, `@ara4n`_ - - None - - - * - `MSC1301 `_ - - Proposal for improving authorization for the matrix profile API - - 2018-06-13 - - 2018-06-13 - - `1301-1 `_ - - `@turt2live`_ - - None - - - * - `MSC1309 `_ - - Proposal for an application service management API - - 2018-06-14 - - 2018-06-15 - - `1309-1 `_ - - `@turt2live`_ - - None - - - * - `MSC1308 `_ - - Proposal for speeding up review of simple spec changes - - 2018-06-14 - - 2018-06-24 - - - - `@ara4n`_ - - None - - - * - `MSC1306 `_ - - Proposal to filter out traffic to Appservices based on filters - - 2018-06-14 - - 2018-06-14 - - `1306-1 `_ - - `@Half-Shot`_ - - None - - - - - -proposal-in-review -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - Author - - Shepherd - - PRs - * - `MSC1194 `_ - - A way for HSes to remove bindings from ISes (aka unbind) - - 2018-05-09 - - 2018-06-05 - - `1194-1 `_ - - `@dbkr`_ - - None - - - - - -proposal-passed-review -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - Author - - Shepherd - - PRs - * - `MSC433 `_ - - Support for discovering API endpoints via .well-known URIs (SPEC-121) - - 2015-03-08 - - 2018-07-01 - - `433-1 `_, `433-2 `_ - - `@maxidor`_, `others`_ - - `@uhoreg`_ - - - * - `MSC1226 `_ - - State Reset mitigation proposal - - 2018-02-20 - - 2018-05-15 - - `1226-1 `_ - - `@richvdh`_ - - None - - - * - `MSC1229 `_ - - Mitigating abuse of the event depth parameter over federation - - 2018-04-30 - - 2018-05-15 - - `1229-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1232 `_ - - Media limits API - - 2018-05-04 - - 2018-06-21 - - `1232-1 `_ - - `@Half-Shot`_ - - None - - `PR#1189`_ - * - `MSC1236 `_ - - Matrix Widget API v2 - - 2018-05-13 - - 2018-05-15 - - `1236-1 `_ - - `@rxl881`_ - - None - - - - - -spec-pr-missing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - 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 - - 2018-05-15 - - `1201-1 `_ - - `@richvdh`_ - - None - - - * - `MSC1203 `_ - - 3rd Party Entity lookup API - - 2016-07-21 - - 2018-07-02 - - `1203-1 `_ - - `@leonerd`_ - - None - - - * - `MSC1208 `_ - - Encrypted attachment format - - 2016-10-26 - - 2018-05-15 - - `1208-1 `_ - - `@NegativeMjark`_ - - None - - - * - `MSC739 `_ - - Reporting inappropriate content in Matrix - - 2016-11-21 - - 2018-05-31 - - `739-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1211 `_ - - Megolm session export format - - 2017-01-03 - - 2018-05-15 - - `1211-1 `_ - - `@richvdh`_ - - None - - - * - `MSC1212 `_ - - Device List Update Stream - - 2017-01-18 - - 2018-05-15 - - `1212-1 `_ - - `@richvdh`_ - - None - - - * - `MSC829 `_ - - Need to spec msisdn login API - - 2017-03-08 - - 2018-05-15 - - `829-1 `_ - - `@dbkr`_ - - None - - - * - `MSC855 `_ - - spec m.login.msisdn UI auth type - - 2017-03-24 - - 2018-05-15 - - `855-1 `_ - - `@dbkr`_ - - None - - - * - `MSC910 `_ - - Add new Read Marker API to docs - - 2017-05-08 - - 2018-05-15 - - - - `@lukebarnard1`_ - - None - - - * - `MSC1067 `_ - - Spec @mentions - - 2017-07-14 - - 2018-05-15 - - `1067-1 `_ - - `@lukebarnard1`_ - - None - - - * - `MSC1214 `_ - - Related Groups (i.e. flair) - - 2017-10-03 - - 2018-05-15 - - `1214-1 `_ - - `@lukebarnard1`_ - - None - - - * - `MSC1033 `_ - - Doc @room notifications - - 2017-10-23 - - 2018-05-31 - - - - `@dbkr`_ - - None - - - * - `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 - - 2018-05-15 - - `1230-1 `_ - - `@ara4n`_ - - None - - - * - `MSC1234 `_ - - Rich Replies format - - 2018-05-12 - - 2018-05-18 - - `1234-1 `_ - - `@t3chguy`_ - - None - - - - - -merged -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - Author - - Shepherd - - PRs - * - `MSC1197 `_ - - Ignoring Users - - 2016-05-03 - - 2018-05-18 - - `1197-1 `_ - - `@erikjohnston`_ - - None - - `PR#1142`_ - * - `MSC1199 `_ - - Notifications API - - 2016-05-23 - - 2018-06-25 - - `1199-1 `_ - - `@dbkr`_ - - None - - - * - `MSC1204 `_ - - Access Token Semantics (refresh and macaroons) - aka Auth Sept 2016 Edition - - 2016-09-29 - - 2018-06-25 - - `1204-1 `_ - - `@richvdh`_ - - None - - - * - `MSC1205 `_ - - Proposal for multi-device deletion API - - 2016-10-12 - - 2018-06-25 - - `1205-1 `_ - - `@richvdh`_ - - None - - `PR#1239`_ - * - `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 - - 2018-06-25 - - `1233-1 `_ - - `@ara4n`_ - - None - - `PR#1240`_ - - - -abandoned -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - Author - - Shepherd - - PRs - * - `MSC531 `_ - - Homeservers as OAuth authorization endpoints (resource owners) (SPEC-206) - - 2015-07-25 - - 2018-05-15 - - `531-1 `_ - - `@Kegsay`_ - - None - - - * - `MSC1202 `_ - - Profile Personae - - 2016-07-15 - - 2018-05-15 - - `1202-1 `_ - - `@erikjohnston`_ - - None - - - * - `MSC1209 `_ - - Server Side Profile API - - 2016-11-01 - - 2018-05-15 - - `1209-1 `_ - - `@erikjohnston`_ - - None - - - * - `MSC1213 `_ - - Set defaults for m.federate - - 2017-04-10 - - 2018-05-18 - - `1213-1 `_ - - `@psaavedra`_ - - None - - - - - -obsolete -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: auto - :stub-columns: 1 - - * - MSC - - Proposal Title - - Creation Date - - Update Date - - Documentation - - 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 - - 2018-05-15 - - `1235-1 `_ - - `@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 -.. _@anoadragon453: https://github.com/anoadragon453 -.. _@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 -.. _@babolivier: https://github.com/babolivier -.. _@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#1189: https://github.com/matrix-org/matrix-doc/pull/1189 -.. _PR#310: https://github.com/matrix-org/matrix-doc/pull/310 -.. _PR#1142: https://github.com/matrix-org/matrix-doc/pull/1142 -.. _PR#1239: https://github.com/matrix-org/matrix-doc/pull/1239 -.. _PR#1240: https://github.com/matrix-org/matrix-doc/pull/1240 -.. _PR#919: https://github.com/matrix-org/matrix-doc/pull/919 \ No newline at end of file +View the current live version `at https://matrix.org/docs/spec/proposals `_ diff --git a/specification/targets.yaml b/specification/targets.yaml index 96199d29..ba3e3299 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -12,7 +12,6 @@ targets: - { 1: modules.rst } - { 2: feature_profiles.rst } - { 2: "group:modules" } # reference a group of files - - { 1: third_party_lookup.rst } version_label: "%CLIENT_RELEASE_LABEL%" application_service: files: @@ -69,6 +68,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/ignore_users.rst - modules/stickers.rst - modules/report_content.rst + - modules/application_services.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]