Merge pull request #1428 from turt2live/travis/s2s/joining-rooms
Improve the documentation for joining rooms
This commit is contained in:
Travis Ralston
GitHub
commit
48972addbf
2 changed files with 40 additions and 91 deletions
|
|
@ -29,7 +29,6 @@ paths:
|
||||||
description: |-
|
description: |-
|
||||||
Asks the receiving server to return information that the sending
|
Asks the receiving server to return information that the sending
|
||||||
server will need to prepare a join event to get into the room.
|
server will need to prepare a join event to get into the room.
|
||||||
This is part of the `Joining Rooms`_ handshake.
|
|
||||||
operationId: makeJoin
|
operationId: makeJoin
|
||||||
parameters:
|
parameters:
|
||||||
- in: path
|
- in: path
|
||||||
|
|
@ -95,7 +94,9 @@ paths:
|
||||||
type: array
|
type: array
|
||||||
description: |-
|
description: |-
|
||||||
An event reference list containing the authorization events that would
|
An event reference list containing the authorization events that would
|
||||||
allow the member to join the room.
|
allow the member to join the room. This should normally be the
|
||||||
|
``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
|
||||||
|
events.
|
||||||
items:
|
items:
|
||||||
type: array
|
type: array
|
||||||
maxItems: 2
|
maxItems: 2
|
||||||
|
|
@ -128,7 +129,12 @@ paths:
|
||||||
"state_key": "@someone:example.org",
|
"state_key": "@someone:example.org",
|
||||||
"content": {
|
"content": {
|
||||||
"membership": "join"
|
"membership": "join"
|
||||||
}
|
},
|
||||||
|
"auth_events": [
|
||||||
|
["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
|
||||||
|
["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
|
||||||
|
["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
|
||||||
|
]
|
||||||
}
|
}
|
||||||
"/send_join/{roomId}/{eventId}":
|
"/send_join/{roomId}/{eventId}":
|
||||||
put:
|
put:
|
||||||
|
|
@ -250,27 +256,30 @@ paths:
|
||||||
title: Room State
|
title: Room State
|
||||||
description: The state for the room.
|
description: The state for the room.
|
||||||
properties:
|
properties:
|
||||||
|
origin:
|
||||||
|
type: string
|
||||||
|
description: The resident server's DNS name.
|
||||||
auth_chain:
|
auth_chain:
|
||||||
type: array
|
type: array
|
||||||
description: The auth chain.
|
description: The auth chain.
|
||||||
items:
|
items:
|
||||||
type: object
|
type: object
|
||||||
properties: {}
|
schema:
|
||||||
# TODO: Verify schema
|
$ref: "definitions/pdu.yaml"
|
||||||
state:
|
state:
|
||||||
type: array
|
type: array
|
||||||
description: The room state.
|
description: The room state.
|
||||||
items:
|
items:
|
||||||
type: object
|
type: object
|
||||||
properties: {}
|
schema:
|
||||||
# TODO: Verify schema
|
$ref: "definitions/pdu.yaml"
|
||||||
required: ["auth_chain", "state"]
|
required: ["auth_chain", "state", "origin"]
|
||||||
examples:
|
examples:
|
||||||
application/json: [
|
application/json: [
|
||||||
200,
|
200,
|
||||||
{
|
{
|
||||||
# TODO: Use the appropriate refs (see TODOs in schema)
|
"origin": "matrix.org",
|
||||||
"auth_chain": [],
|
"auth_chain": [{"$ref": "examples/pdu.json"}],
|
||||||
"state": []
|
"state": [{"$ref": "examples/pdu.json"}]
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
|
|
|
||||||
|
|
@ -610,9 +610,6 @@ All these URLs are name-spaced within a prefix of::
|
||||||
|
|
||||||
{{query_general_ss_http_api}}
|
{{query_general_ss_http_api}}
|
||||||
|
|
||||||
|
|
||||||
{{joins_ss_http_api}}
|
|
||||||
|
|
||||||
Joining Rooms
|
Joining Rooms
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
|
|
@ -664,94 +661,34 @@ homeservers, though most in practice will use just two.
|
||||||
<---------- join response
|
<---------- join response
|
||||||
|
|
||||||
The first part of the handshake usually involves using the directory server to
|
The first part of the handshake usually involves using the directory server to
|
||||||
request the room ID and join candidates. This is covered in more detail on the
|
request the room ID and join candidates through the |/query/directory|_
|
||||||
directory server documentation, below. In the case of a new user joining a
|
API endpoint. In the case of a new user joining a room as a result of a received
|
||||||
room as a result of a received invite, the joining user's homeserver could
|
invite, the joining user's homeserver could optimise this step away by picking
|
||||||
optimise this step away by picking the origin server of that invite message as
|
the origin server of that invite message as the join candidate. However, the
|
||||||
the join candidate. However, the joining server should be aware that the origin
|
joining server should be aware that the origin server of the invite might since
|
||||||
server of the invite might since have left the room, so should be prepared to
|
have left the room, so should be prepared to fall back on the regular join flow
|
||||||
fall back on the regular join flow if this optimisation fails.
|
if this optimisation fails.
|
||||||
|
|
||||||
Once the joining server has the room ID and the join candidates, it then needs
|
Once the joining server has the room ID and the join candidates, it then needs
|
||||||
to obtain enough information about the room to fill in the required fields of
|
to obtain enough information about the room to fill in the required fields of
|
||||||
the ``m.room.member`` event. It obtains this by selecting a resident from the
|
the ``m.room.member`` event. It obtains this by selecting a resident from the
|
||||||
candidate list, and requesting the ``make_join`` endpoint using a ``GET``
|
candidate list, and using the ``GET /make_join`` endpoint. The resident server
|
||||||
request, specifying the room ID and the user ID of the new member who is
|
will then reply with enough information for the joining server to fill in the
|
||||||
attempting to join.
|
event.
|
||||||
|
|
||||||
The resident server replies to this request with a JSON-encoded object having a
|
The joining server is expected to add or replace the ``origin``, ``origin_server_ts``,
|
||||||
single key called ``event``; within this is an object whose fields contain some
|
and ``event_id`` on the templated event received by the resident server. This
|
||||||
of the information that the joining server will need. Despite its name, this
|
event is then signed by the joining server.
|
||||||
object is not a full event; notably it does not need to be hashed or signed by
|
|
||||||
the resident homeserver. The required fields are:
|
|
||||||
|
|
||||||
======================== ============ =========================================
|
|
||||||
Key Type Description
|
|
||||||
======================== ============ =========================================
|
|
||||||
``type`` String The value ``m.room.member``.
|
|
||||||
``auth_events`` List An event-reference list containing the
|
|
||||||
authorization events that would allow
|
|
||||||
this member to join.
|
|
||||||
``content`` Object The event content.
|
|
||||||
``depth`` Integer (this field must be present but is
|
|
||||||
ignored; it may be 0)
|
|
||||||
``origin`` String The name of the resident homeserver.
|
|
||||||
``origin_server_ts`` Integer A timestamp added by the resident
|
|
||||||
homeserver.
|
|
||||||
``prev_events`` List An event-reference list containing the
|
|
||||||
immediate predecessor events.
|
|
||||||
``room_id`` String The room ID of the room.
|
|
||||||
``sender`` String The user ID of the joining member.
|
|
||||||
``state_key`` String The user ID of the joining member.
|
|
||||||
======================== ============ =========================================
|
|
||||||
|
|
||||||
The ``content`` field itself must be an object, containing:
|
|
||||||
|
|
||||||
======================== ============ =========================================
|
|
||||||
Key Type Description
|
|
||||||
======================== ============ =========================================
|
|
||||||
``membership`` String The value ``join``.
|
|
||||||
======================== ============ =========================================
|
|
||||||
|
|
||||||
The joining server now has sufficient information to construct the real join
|
|
||||||
event from these protoevent fields. It copies the values of most of them,
|
|
||||||
adding (or replacing) the following fields:
|
|
||||||
|
|
||||||
======================== ============ =========================================
|
|
||||||
Key Type Description
|
|
||||||
======================== ============ =========================================
|
|
||||||
``event_id`` String A new event ID specified by the joining
|
|
||||||
homeserver.
|
|
||||||
``origin`` String The name of the joining homeserver.
|
|
||||||
``origin_server_ts`` Integer A timestamp added by the joining
|
|
||||||
homeserver.
|
|
||||||
======================== ============ =========================================
|
|
||||||
|
|
||||||
This will be a true event, so the joining server should apply the event-signing
|
|
||||||
algorithm to it, resulting in the addition of the ``hashes`` and ``signatures``
|
|
||||||
fields.
|
|
||||||
|
|
||||||
To complete the join handshake, the joining server must now submit this new
|
To complete the join handshake, the joining server must now submit this new
|
||||||
event to an resident homeserver, by using the ``send_join`` endpoint. This is
|
event to a resident homeserver, by using the ``PUT /send_join`` endpoint.
|
||||||
invoked using the room ID and the event ID of the new member event.
|
|
||||||
|
|
||||||
The resident homeserver then accepts this event into the room's event graph,
|
The resident homeserver then accepts this event into the room's event graph,
|
||||||
and responds to the joining server with the full set of state for the
|
and responds to the joining server with the full set of state for the
|
||||||
newly-joined room. This is returned as a two-element list, whose first element
|
newly-joined room. The resident server must also send the event to other servers
|
||||||
is the integer 200, and whose second element is an object which contains the
|
participating in the room.
|
||||||
following keys:
|
|
||||||
|
|
||||||
======================== ============ =========================================
|
{{joins_ss_http_api}}
|
||||||
Key Type Description
|
|
||||||
======================== ============ =========================================
|
|
||||||
``auth_chain`` List A list of events giving all of the events
|
|
||||||
in the auth chains for the join event and
|
|
||||||
the events in ``state``.
|
|
||||||
``state`` List A complete list of the prevailing state
|
|
||||||
events at the instant just before
|
|
||||||
accepting the new ``m.room.member``
|
|
||||||
event.
|
|
||||||
======================== ============ =========================================
|
|
||||||
|
|
||||||
.. TODO-spec
|
.. TODO-spec
|
||||||
- (paul) I don't really understand why the full auth_chain events are given
|
- (paul) I don't really understand why the full auth_chain events are given
|
||||||
|
|
@ -1228,6 +1165,9 @@ that are too long.
|
||||||
[[TODO(markjh) We might want to allow the server to omit the output of well
|
[[TODO(markjh) We might want to allow the server to omit the output of well
|
||||||
known hash functions like SHA-256 when none of the keys have been redacted]]
|
known hash functions like SHA-256 when none of the keys have been redacted]]
|
||||||
|
|
||||||
|
.. |/query/directory| replace:: ``/query/directory``
|
||||||
|
.. _/query/directory: #get-matrix-federation-v1-query-directory
|
||||||
|
|
||||||
.. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage
|
.. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage
|
||||||
.. _`Identity Service API`: ../identity_service/unstable.html
|
.. _`Identity Service API`: ../identity_service/unstable.html
|
||||||
.. _`Client-Server API`: ../client_server/unstable.html#m-room-member
|
.. _`Client-Server API`: ../client_server/unstable.html#m-room-member
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue