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

api/server-server/joins.yaml

@@ -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: {}
+                      schema:
-                      # TODO: Verify schema
+                        $ref: "definitions/pdu.yaml"
                   state:
                     type: array
                     description: The room state.
                     items:
                       type: object
-                      properties: {}
+                      schema:
-                      # TODO: Verify schema
+                        $ref: "definitions/pdu.yaml"
                 required: ["auth_chain", "state"]
           examples:
             application/json: [
               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"}]
               }
             ]

specification/server_server_api.rst

@@ -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
+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
 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``
+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
-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
+The joining server is expected to add or replace the ``origin``, ``origin_server_ts``,
-algorithm to it, resulting in the addition of the ``hashes`` and ``signatures``
+and ``event_id`` on the templated event received by the resident server. This
-fields.
+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
+event to an 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,
 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
   - (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