Skip to content

Commit a2a1694

Browse files
turt2liveturt2live
committed
Spec v2 send_join and send_leave endpoints
MSC: #1802 Fixes #2541 This also adds the v2 invite endpoint to the ACL protected list as that appears to be an omission.
1 parent 7eafe5a commit a2a1694

File tree

6 files changed

+338
-4
lines changed

6 files changed

+338
-4
lines changed

‎api/server-server/joins.yaml‎ renamed to ‎api/server-server/joins-v1.yaml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Copyright 2018 New Vector Ltd
2+
# Copyright 2020 The Matrix.org Foundation C.I.C.
23
#
34
# Licensed under the Apache License, Version 2.0 (the "License");
45
# you may not use this file except in compliance with the License.
@@ -165,14 +166,18 @@ paths:
165166
put:
166167
summary: Submit a signed join event to a resident server
167168
description: |-
169+
.. Note::
170+
Servers should instead prefer to use the v2 ``/send_join``
171+
endpoint.
172+
168173
Submits a signed join event to the resident server for it
169174
to accept it into the room's graph. Note that events have
170175
a different format depending on the room version - check
171176
the `room version specification`_ for precise event formats.
172177
**The request and response body here describes the common
173178
event fields in more detail and may be missing other required
174179
fields for a PDU.**
175-
operationId: sendJoin
180+
operationId: sendJoinV1
176181
security:
177182
- signedRequest: []
178183
parameters:

‎api/server-server/joins-v2.yaml‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Copyright 2018 New Vector Ltd
2+
# Copyright 2020 The Matrix.org Foundation C.I.C.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
swagger: '2.0'
17+
info:
18+
title: "Matrix Federation Join Room API"
19+
version: "1.0.0"
20+
host: localhost:8448
21+
schemes:
22+
- https
23+
basePath: /_matrix/federation/v2
24+
consumes:
25+
- application/json
26+
produces:
27+
- application/json
28+
securityDefinitions:
29+
$ref: definitions/security.yaml
30+
paths:
31+
# Note: there is no v2 of make_join (yet)
32+
"/send_join/{roomId}/{eventId}":
33+
put:
34+
summary: Submit a signed join event to a resident server
35+
description: |-
36+
.. Note::
37+
This API is nearly identical to the v1 API with the
38+
exception of the response format being fixed.
39+
40+
This endpoint is preferred over the v1 API as it provides
41+
a more standarised response format. Senders which receive
42+
a 400, 404, or other status code which indicates this endpoint
43+
is not available should retry using the v1 API instead.
44+
45+
Submits a signed join event to the resident server for it
46+
to accept it into the room's graph. Note that events have
47+
a different format depending on the room version - check
48+
the `room version specification`_ for precise event formats.
49+
**The request and response body here describes the common
50+
event fields in more detail and may be missing other required
51+
fields for a PDU.**
52+
operationId: sendJoinV2
53+
security:
54+
- signedRequest: []
55+
parameters:
56+
- in: path
57+
name: roomId
58+
type: string
59+
description: The room ID that is about to be joined.
60+
required: true
61+
x-example: "!abc123:matrix.org"
62+
- in: path
63+
name: eventId
64+
type: string
65+
description: The event ID for the join event.
66+
required: true
67+
x-example: "$abc123:example.org"
68+
- in: body
69+
name: body
70+
type: object
71+
required: true
72+
schema:
73+
type: object
74+
properties:
75+
sender:
76+
type: string
77+
description: The user ID of the joining member.
78+
example: "@someone:example.org"
79+
origin:
80+
type: string
81+
description: The name of the joining homeserver.
82+
example: "matrix.org"
83+
origin_server_ts:
84+
type: integer
85+
format: int64
86+
description: A timestamp added by the joining homeserver.
87+
example: 1234567890
88+
type:
89+
type: string
90+
description: The value ``m.room.member``.
91+
example: "m.room.member"
92+
state_key:
93+
type: string
94+
description: The user ID of the joining member.
95+
example: "@someone:example.org"
96+
content:
97+
type: object
98+
title: Membership Event Content
99+
description: The content of the event.
100+
example: {"membership": "join"}
101+
properties:
102+
membership:
103+
type: string
104+
description: The value ``join``.
105+
example: "join"
106+
required: ['membership']
107+
required:
108+
- state_key
109+
- sender
110+
- origin
111+
- origin_server_ts
112+
- type
113+
- content
114+
example: {
115+
"$ref": "examples/minimal_pdu.json",
116+
"type": "m.room.member",
117+
"state_key": "@someone:example.org",
118+
"origin": "example.org",
119+
"origin_server_ts": 1549041175876,
120+
"sender": "@someone:example.org",
121+
"content": {
122+
"membership": "join"
123+
}
124+
}
125+
responses:
126+
200:
127+
description: |-
128+
The full state for the room, having accepted the join event.
129+
schema:
130+
type: object
131+
title: Room State
132+
description: The state for the room.
133+
properties:
134+
origin:
135+
type: string
136+
description: The resident server's DNS name.
137+
auth_chain:
138+
type: array
139+
description: |-
140+
The auth chain. Note that events have a different format depending on
141+
the room version - check the `room version specification`_ for precise
142+
event formats.
143+
items:
144+
type: object
145+
title: PDU
146+
description: |-
147+
The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending
148+
on the room version - check the `room version specification`_ for precise event formats.
149+
schema:
150+
type: object
151+
properties: []
152+
example:
153+
$ref: "examples/minimal_pdu.json"
154+
state:
155+
type: array
156+
description: |-
157+
The room state. The event format varies depending on the room version -
158+
check the `room version specification`_ for precise event formats.
159+
items:
160+
type: object
161+
title: PDU
162+
description: |-
163+
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
164+
on the room version - check the `room version specification`_ for precise event formats.
165+
schema:
166+
type: object
167+
properties: []
168+
example:
169+
$ref: "examples/minimal_pdu.json"
170+
required: ["auth_chain", "state", "origin"]
171+
examples:
172+
application/json: {
173+
"origin": "matrix.org",
174+
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
175+
"state": [{"$ref": "examples/minimal_pdu.json"}]
176+
}

‎api/server-server/leaving.yaml‎ renamed to ‎api/server-server/leaving-v1.yaml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Copyright 2018 New Vector Ltd
2+
# Copyright 2020 The Matrix.org Foundation C.I.C.
23
#
34
# Licensed under the Apache License, Version 2.0 (the "License");
45
# you may not use this file except in compliance with the License.
@@ -142,14 +143,18 @@ paths:
142143
put:
143144
summary: Submit a signed leave event to a resident server
144145
description: |-
146+
.. Note::
147+
Servers should instead prefer to use the v2 ``/send_leave``
148+
endpoint.
149+
145150
Submits a signed leave event to the resident server for it
146151
to accept it into the room's graph. Note that events have
147152
a different format depending on the room version - check
148153
the `room version specification`_ for precise event formats.
149154
**The request and response body here describes the common
150155
event fields in more detail and may be missing other required
151156
fields for a PDU.**
152-
operationId: sendLeave
157+
operationId: sendLeaveV1
153158
security:
154159
- signedRequest: []
155160
parameters:

‎api/server-server/leaving-v2.yaml‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Copyright 2018 New Vector Ltd
2+
# Copyright 2020 The Matrix.org Foundation C.I.C.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
swagger: '2.0'
17+
info:
18+
title: "Matrix Federation Leave Room API"
19+
version: "1.0.0"
20+
host: localhost:8448
21+
schemes:
22+
- https
23+
basePath: /_matrix/federation/v2
24+
consumes:
25+
- application/json
26+
produces:
27+
- application/json
28+
securityDefinitions:
29+
$ref: definitions/security.yaml
30+
paths:
31+
# Note: there is no v2 of make_leave (yet)
32+
"/send_leave/{roomId}/{eventId}":
33+
put:
34+
summary: Submit a signed leave event to a resident server
35+
description: |-
36+
.. Note::
37+
This API is nearly identical to the v1 API with the
38+
exception of the response format being fixed.
39+
40+
This endpoint is preferred over the v1 API as it provides
41+
a more standarised response format. Senders which receive
42+
a 400, 404, or other status code which indicates this endpoint
43+
is not available should retry using the v1 API instead.
44+
45+
Submits a signed leave event to the resident server for it
46+
to accept it into the room's graph. Note that events have
47+
a different format depending on the room version - check
48+
the `room version specification`_ for precise event formats.
49+
**The request and response body here describes the common
50+
event fields in more detail and may be missing other required
51+
fields for a PDU.**
52+
operationId: sendLeaveV2
53+
security:
54+
- signedRequest: []
55+
parameters:
56+
- in: path
57+
name: roomId
58+
type: string
59+
description: The room ID that is about to be left.
60+
required: true
61+
x-example: "!abc123:matrix.org"
62+
- in: path
63+
name: eventId
64+
type: string
65+
description: The event ID for the leave event.
66+
required: true
67+
x-example: "$abc123:example.org"
68+
- in: body
69+
name: body
70+
type: object
71+
required: true
72+
schema:
73+
type: object
74+
properties:
75+
sender:
76+
type: string
77+
description: The user ID of the leaving member.
78+
example: "@someone:example.org"
79+
origin:
80+
type: string
81+
description: The name of the leaving homeserver.
82+
example: "matrix.org"
83+
origin_server_ts:
84+
type: integer
85+
format: int64
86+
description: A timestamp added by the leaving homeserver.
87+
example: 1234567890
88+
type:
89+
type: string
90+
description: The value ``m.room.member``.
91+
example: "m.room.member"
92+
state_key:
93+
type: string
94+
description: The user ID of the leaving member.
95+
example: "@someone:example.org"
96+
content:
97+
type: object
98+
title: Membership Event Content
99+
description: The content of the event.
100+
example: {"membership": "leave"}
101+
properties:
102+
membership:
103+
type: string
104+
description: The value ``leave``.
105+
example: "leave"
106+
required: ['membership']
107+
depth:
108+
type: integer
109+
description: This field must be present but is ignored; it may be 0.
110+
example: 12
111+
required:
112+
- state_key
113+
- sender
114+
- origin
115+
- origin_server_ts
116+
- type
117+
- depth
118+
- content
119+
example: {
120+
"$ref": "examples/minimal_pdu.json",
121+
"type": "m.room.member",
122+
"state_key": "@someone:example.org",
123+
"origin": "example.org",
124+
"origin_server_ts": 1549041175876,
125+
"sender": "@someone:example.org",
126+
"content": {
127+
"membership": "leave"
128+
}
129+
}
130+
responses:
131+
200:
132+
description: |-
133+
An empty response to indicate the event was accepted into the graph by
134+
the receiving homeserver.
135+
schema:
136+
type: object
137+
title: Empty Object
138+
description: An empty object.
139+
examples:
140+
application/json: {}

‎changelogs/server_server/newsfragments/2547.new‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Add new v2 ``/send_join`` and ``/send_leave`` endpoints per `MSC1802 <https://github.com/matrix-org/matrix-doc/pull/1802>`_.

0 commit comments

Comments
 (0)