Improve the joining rooms handshake documentation
There isn't a whole lot to this section that needed work. The section overall lost the table schema in favour of having the endpoints close by. The directory query is improved in https://github.com/matrix-org/matrix-doc/pull/1443
This commit is contained in:
Travis Ralston
parent
b0744aa1e9
commit
c2f1c6e78d
2 changed files with 39 additions and 90 deletions
|
|
@ -29,7 +29,6 @@ paths:
|
|||
description: |-
|
||||
Asks the receiving server to return information that the sending
|
||||
server will need to prepare a join event to get into the room.
|
||||
This is part of the `Joining Rooms`_ handshake.
|
||||
operationId: makeJoin
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -95,7 +94,9 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
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:
|
||||
type: array
|
||||
maxItems: 2
|
||||
|
|
@ -128,7 +129,12 @@ paths:
|
|||
"state_key": "@someone:example.org",
|
||||
"content": {
|
||||
"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}":
|
||||
put:
|
||||
|
|
@ -250,27 +256,30 @@ paths:
|
|||
title: Room State
|
||||
description: The state for the room.
|
||||
properties:
|
||||
origin:
|
||||
type: string
|
||||
description: The resident server's DNS name.
|
||||
auth_chain:
|
||||
type: array
|
||||
description: The auth chain.
|
||||
items:
|
||||
type: object
|
||||
properties: {}
|
||||
# TODO: Verify schema
|
||||
schema:
|
||||
$ref: "definitions/pdu.yaml"
|
||||
state:
|
||||
type: array
|
||||
description: The room state.
|
||||
items:
|
||||
type: object
|
||||
properties: {}
|
||||
# TODO: Verify schema
|
||||
schema:
|
||||
$ref: "definitions/pdu.yaml"
|
||||
required: ["auth_chain", "state"]
|
||||
examples:
|
||||
application/json: [
|
||||
200,
|
||||
{
|
||||
# TODO: Use the appropriate refs (see TODOs in schema)
|
||||
"auth_chain": [],
|
||||
"state": []
|
||||
"origin": "matrix.org",
|
||||
"auth_chain": [{"$ref": "examples/pdu.json"}],
|
||||
"state": [{"$ref": "examples/pdu.json"}]
|
||||
}
|
||||
]
|
||||
|
|
|
|||
|
|
@ -688,9 +688,6 @@ All these URLs are name-spaced within a prefix of::
|
|||
|
||||
{{query_general_ss_http_api}}
|
||||
|
||||
|
||||
{{joins_ss_http_api}}
|
||||
|
||||
Joining Rooms
|
||||
-------------
|
||||
|
||||
|
|
@ -742,94 +739,34 @@ homeservers, though most in practice will use just two.
|
|||
<---------- join response
|
||||
|
||||
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
|
||||
directory server documentation, below. In the case of a new user joining a
|
||||
room as a result of a received invite, the joining user's homeserver could
|
||||
optimise this step away by picking the origin server of that invite message as
|
||||
the join candidate. However, the joining server should be aware that the origin
|
||||
server of the invite might since have left the room, so should be prepared to
|
||||
fall back on the regular join flow if this optimisation fails.
|
||||
request the room ID and join candidates through the |/query/directory|_
|
||||
API endpoint. In the case of a new user joining a room as a result of a received
|
||||
invite, the joining user's homeserver could optimise this step away by picking
|
||||
the origin server of that invite message as the join candidate. However, the
|
||||
joining server should be aware that the origin server of the invite might since
|
||||
have left the room, so should be prepared to fall back on the regular join flow
|
||||
if this optimisation fails.
|
||||
|
||||
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
|
||||
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``
|
||||
request, specifying the room ID and the user ID of the new member who is
|
||||
attempting to join.
|
||||
candidate list, and using the ``GET /make_join`` endpoint. The resident server
|
||||
will then reply with enough information for the joining server to fill in the
|
||||
event.
|
||||
|
||||
The resident server replies to this request with a JSON-encoded object having a
|
||||
single key called ``event``; within this is an object whose fields contain some
|
||||
of the information that the joining server will need. Despite its name, this
|
||||
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.
|
||||
The joining server is expected to add or replace the ``origin``, ``origin_server_ts``,
|
||||
and ``event_id`` on the templated event received by the resident server. This
|
||||
event is then signed by the joining server.
|
||||
|
||||
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
|
||||
invoked using the room ID and the event ID of the new member event.
|
||||
event to an resident homeserver, by using the ``PUT /send_join`` endpoint.
|
||||
|
||||
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
|
||||
newly-joined room. This is returned as a two-element list, whose first element
|
||||
is the integer 200, and whose second element is an object which contains the
|
||||
following keys:
|
||||
newly-joined room. The resident server must also send the event to other servers
|
||||
participating in the room.
|
||||
|
||||
======================== ============ =========================================
|
||||
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.
|
||||
======================== ============ =========================================
|
||||
{{joins_ss_http_api}}
|
||||
|
||||
.. TODO-spec
|
||||
- (paul) I don't really understand why the full auth_chain events are given
|
||||
|
|
@ -1306,6 +1243,9 @@ that are too long.
|
|||
[[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]]
|
||||
|
||||
.. |/query/directory| replace:: ``/query/directory``
|
||||
.. _/query/directory: #get-matrix-federation-v1-query-directory
|
||||
|
||||
.. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage
|
||||
.. _`Identity Service API`: ../identity_service/unstable.html
|
||||
.. _`Client-Server API`: ../client_server/unstable.html#m-room-member
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue