Add spec for MSC2659: application service ping endpoint (#1516)
Tulir Asokan
12 months ago
committed by
GitHub
parent
f564c07e60
commit
9dd9639dd7
@ -0,0 +1 @@
|
||||
Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper.
|
||||
@ -0,0 +1 @@
|
||||
Add `POST /_matrix/app/v1/ping` and `POST /_matrix/client/v1/appservice/{appserviceId}/ping` endpoints as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659).
|
||||
@ -0,0 +1,63 @@
|
||||
# Copyright 2023 Tulir Asokan
|
||||
#
|
||||
# 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 Application Service API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/app/v1
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/ping":
|
||||
post:
|
||||
x-addedInMatrixVersion: "1.7"
|
||||
summary: Ping the application service
|
||||
description: |-
|
||||
This API is called by the homeserver to ensure that the connection works
|
||||
and the `hs_token` the homeserver has is correct.
|
||||
|
||||
Currently this is only called by the homeserver as a direct result of
|
||||
the application service calling
|
||||
[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping).
|
||||
operationId: ping
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
description: Ping body with optional transaction ID.
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"transaction_id": "mautrix-go_1683636478256400935_123"
|
||||
}
|
||||
properties:
|
||||
transaction_id:
|
||||
type: string
|
||||
description: |-
|
||||
A transaction ID for the ping, copied directly from the
|
||||
`POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
|
||||
responses:
|
||||
200:
|
||||
description: The provided `hs_token` is valid and the ping request was successful.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
@ -0,0 +1,150 @@
|
||||
# Copyright 2023 Tulir Asokan
|
||||
#
|
||||
# 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 Application Service Ping API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
# Note: this is the same access_token definition used elsewhere in the client
|
||||
# server API, however this expects an access token for an application service.
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/appservice/{appserviceId}/ping":
|
||||
post:
|
||||
x-addedInMatrixVersion: "1.7"
|
||||
summary: |-
|
||||
Ask the homeserver to ping the application service to ensure the connection works.
|
||||
description: |-
|
||||
This API asks the homeserver to call the
|
||||
[`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
|
||||
application service to ensure that the homeserver can communicate
|
||||
with the application service.
|
||||
|
||||
This API requires the use of an application service access token (`as_token`)
|
||||
instead of a typical client's access token. This API cannot be invoked by
|
||||
users who are not identified as application services. Additionally, the
|
||||
appservice ID in the path must be the same as the appservice whose `as_token`
|
||||
is being used.
|
||||
operationId: pingAppservice
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: appserviceId
|
||||
description: |-
|
||||
The appservice ID of the appservice to ping. This must be the same
|
||||
as the appservice whose `as_token` is being used to authenticate the
|
||||
request.
|
||||
required: true
|
||||
x-example: "telegram"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
transaction_id:
|
||||
type: string
|
||||
description: |-
|
||||
An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call.
|
||||
example: "mautrix-go_1683636478256400935_123"
|
||||
security:
|
||||
# again, this is the appservice's token - not a typical client's
|
||||
- accessToken: []
|
||||
responses:
|
||||
200:
|
||||
description: The ping was successful.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
duration_ms:
|
||||
type: integer
|
||||
description: |-
|
||||
The duration in milliseconds that the
|
||||
[`/_matrix/app/v1/ping`](#post_matrixappv1ping)
|
||||
request took from the homeserver's point of view.
|
||||
examples:
|
||||
application/json: {"duration_ms": 123}
|
||||
400:
|
||||
description: The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_URL_NOT_SET",
|
||||
"error": "Application service doesn't have a URL configured"
|
||||
}
|
||||
403:
|
||||
description: The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Provided access token is not the appservice's as_token"
|
||||
}
|
||||
502:
|
||||
description: |-
|
||||
The application service returned a bad status, or the connection failed.
|
||||
The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
|
||||
|
||||
For bad statuses, the response may include `status` and `body`
|
||||
fields containing the HTTP status code and response body text
|
||||
respectively to aid with debugging.
|
||||
schema:
|
||||
type: object
|
||||
title: Error
|
||||
description: A Matrix-level Error
|
||||
properties:
|
||||
errcode:
|
||||
type: string
|
||||
description: An error code.
|
||||
enum: [M_BAD_STATUS, M_CONNECTION_FAILED]
|
||||
error:
|
||||
type: string
|
||||
description: A human-readable error message.
|
||||
example: Ping returned status 401
|
||||
status:
|
||||
type: integer
|
||||
description: The HTTP status code returned by the appservice.
|
||||
example: 401
|
||||
body:
|
||||
type: string
|
||||
description: The HTTP response body returned by the appservice.
|
||||
example: "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
|
||||
required: ["errcode"]
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_BAD_STATUS",
|
||||
"error": "Ping returned status 401",
|
||||
"status": 401,
|
||||
"body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
|
||||
}
|
||||
504:
|
||||
description: The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_CONNECTION_TIMEOUT",
|
||||
"error": "Connection to application service timed out"
|
||||
}
|
||||
Loading…
Reference in New Issue