archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1428 from turt2live/travis/s2s/joining-rooms

Browse Source 
Improve the documentation for joining rooms
pull/977/head
Travis Ralston 6 years ago committed by GitHub
parent b96ee3e393 a9258ed195
commit 48972addbf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 40 additions and 91 deletions
Show Stats Download Patch File Download Diff File

31
api/server-server/joins.yaml
Unescape Escape View File

@ -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
required: ["auth_chain", "state"]
schema:
$ref: "definitions/pdu.yaml"
required: ["auth_chain", "state", "origin"]
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"}]
}
]

100
specification/server_server_api.rst
Unescape Escape View File

@ -610,9 +610,6 @@ All these URLs are name-spaced within a prefix of::
{{query_general_ss_http_api}}
{{joins_ss_http_api}}
Joining Rooms
-------------
@ -664,94 +661,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.
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.
======================== ============ =========================================
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.
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 a 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
@ -1228,6 +1165,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

Write Preview
Loading…
Cancel
Save