Merge pull request #1450 from turt2live/travis/s2s/inviting-rooms

Improve documentation for how non-third party invites work
pull/977/head
Travis Ralston 6 years ago committed by GitHub
commit a77975ba68
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -47,7 +47,7 @@ allOf:
title: Membership Event Content title: Membership Event Content
description: |- description: |-
The content of the event, matching what is available in the The content of the event, matching what is available in the
`Client-Server API`_. `Client-Server API`_. Must include a ``membership`` of ``invite``.
example: {"membership": "invite"} example: {"membership": "invite"}
properties: properties:
membership: membership:
@ -85,4 +85,3 @@ allOf:
required: required:
# Every other field is already flagged as required by the $ref # Every other field is already flagged as required by the $ref
- state_key - state_key
- unsigned # TODO: apparently this is required? Verify.

@ -36,7 +36,7 @@ allOf:
signatures: signatures:
type: object type: object
description: |- description: |-
Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_. Signatures for the PDU, following the algorithm specified in `Signing Events`_.
example: { example: {
"example.com": { "example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"

@ -20,16 +20,18 @@ host: localhost:8448
schemes: schemes:
- https - https
basePath: /_matrix/federation/v1 basePath: /_matrix/federation/v1
consumes:
- application/json
produces: produces:
- application/json - application/json
paths: paths:
"/invite/{roomId}/{eventId}": "/invite/{roomId}/{eventId}":
put: put:
summary: Invites a user to a room summary: Invites a remote user to a room
description: |- description: |-
Invites a remote user to a room. Once the event has been Invites a remote user to a room. Once the event has been signed by both the inviting
signed by both the inviting homeserver and the invited homeserver and the invited homeserver, it can be sent to all of the servers in the
homeserver, it can be sent to all of the users in the room. room by the inviting homeserver.
operationId: sendInvite operationId: sendInvite
parameters: parameters:
- in: path - in: path
@ -41,7 +43,7 @@ paths:
- in: path - in: path
name: eventId name: eventId
type: string type: string
description: The event ID for the invite event. description: The event ID for the invite event, generated by the inviting server.
required: true required: true
x-example: "$abc123:example.org" x-example: "$abc123:example.org"
- in: body - in: body
@ -49,15 +51,85 @@ paths:
type: object type: object
required: true required: true
schema: schema:
$ref: "definitions/invite_event.yaml" allOf:
- $ref: "definitions/invite_event.yaml"
- type: object
properties:
unsigned:
type: object
title: Unsigned Event Content
description: |-
Information included alongside the event that is not signed. May include more
than what is listed here.
properties:
invite_room_state:
type: array
description: |-
An optional list of simplified events to help the receiver of the invite
identify the room. The recommended events to include are the join rules,
canonical alias, avatar, and name of the room.
items:
type: object
title: Invite Room State Event
properties:
type:
type: string
description: The type of event.
example: "m.room.join_rules"
state_key:
type: string
description: The state key for the event. May be an empty string.
example: ""
content:
type: object
description: The content for the event.
sender:
type: string
description: The sender of the event.
example: "@someone:matrix.org"
required: ['type', 'state_key', 'content', 'sender']
example: [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
}
]
example: { example: {
"$ref": "examples/pdu.json", "$ref": "examples/pdu.json",
"type": "m.room.member", "type": "m.room.member",
"state_key": "@someone:example.org", "state_key": "@joe:elsewhere.com",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
},
"content": { "content": {
"membership": "invite" "membership": "invite"
}, },
"unsigned": {} "signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
}
} }
responses: responses:
200: 200:
@ -72,17 +144,66 @@ paths:
- type: integer - type: integer
description: The value ``200``. description: The value ``200``.
example: 200 example: 200
- $ref: "definitions/invite_event.yaml" - type: object
description: An object containing the signed invite event.
title: Event Container
properties:
event:
$ref: "definitions/invite_event.yaml"
required: ['event']
examples: examples:
application/json: [ application/json: [
200, 200,
{ {
"$ref": "examples/pdu.json", "event": {
"type": "m.room.member", "$ref": "examples/pdu.json",
"state_key": "@someone:example.org", "type": "m.room.member",
"content": { "state_key": "@someone:example.org",
"membership": "invite" "unsigned": {
}, "invite_room_state": [
"unsigned": {} {
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
},
"content": {
"membership": "invite"
},
"signatures": {
"example.com": {
"ed25519:key_version": "SomeSignatureHere"
},
"elsewhere.com": {
"ed25519:k3y_versi0n": "SomeOtherSignatureHere"
}
}
}
} }
] ]
403:
description: |-
The invite is not allowed. This could be for a number of reasons, including:
* The sender is not allowed to send invites to the target user/homeserver.
* The homeserver does not permit anyone to invite its users.
* The homeserver refuses to participate in the room.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "User cannot invite the target user."
}

@ -633,6 +633,11 @@ point in the timeline.
Inviting to a room Inviting to a room
------------------ ------------------
When a user on a given homeserver invites another user on the same homeserver,
the homeserver may sign the membership event itself and skip the process defined
here. However, when a user invites another user on a different homeserver, a request
to that homeserver to have the event signed and verified must be made.
{{invites_ss_http_api}} {{invites_ss_http_api}}
Leaving Rooms (Rejecting Invites) Leaving Rooms (Rejecting Invites)

Loading…
Cancel
Save