Have removed the second clause about how the client interprets them:
I was trying to think how to rephrase it but I think in reality it's
probably just redundant.
Fixes https://github.com/matrix-org/matrix-doc/issues/1161
The IP address clarification is to add an explicit mention of how to handle the case. The prior documentation assumed that all servers would be resolvable with DNS, and does technically have a fallback to use the fallback port, however making it clear feels like a good idea.
This intentionally doesn't document the third party network aspect of the endpoint. This is scheduled for a later area for dealing with third party network/IDs and is reported as https://github.com/matrix-org/matrix-doc/issues/1476
The client-server response has been broken out to a shared file: both the client-server and server-server /publicRoom endpoints return the same thing, with slightly different inputs.
The inputs (and behaviour) are based upon the docstring here: 43ecfe0b10/synapse/federation/transport/server.py (L583-L612)
This also adds a previously-undocumented endpoint: /state_ids
Backfill is technically not part of this section, however it is being left untouched to make the merge with #1469 easier (which moves it out of the file).
Reference material:
* Some calls to synapse on these endpoints with a relatively simple private room.
The response is based upon various sections of the Synapse code in how it generates a response.
There are no new fields added to the transaction. Originally, `previous_ids` and `pdu_failures` were to be documented however neither of these are used in the real world.
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
Most of the text has been shuffled into the swagger definitions to bring it closer to where it matters.
This also attempts to clarify what is out in the wild. Most importantly, the first version of the key exchange is outright removed from the specification. Other research points/questions are:
* What is a "Key ID"?
* 1241156c82/synapse/rest/key/v2/local_key_resource.py (L81-L83)
* 1241156c82/synapse/rest/key/v2/local_key_resource.py (L88-L91)
* Returning a cached response if the server throws a 400, 500, or otherwise not-offline status code
* 1241156c82/synapse/rest/key/v2/remote_key_resource.py (L227-L229)
* `minimum_valid_until_ts` default
* This branch of the ladder: 1241156c82/synapse/rest/key/v2/remote_key_resource.py (L192)
* Returning empty arrays when querying offline/no servers
* Queried by hand against matrix.org as a notary server with a fake domain name to query
* Returning all keys even when querying for specific keys
* Queried by hand using matrix.org as a notary server against a server publishing multiple keys.
The examples and descriptions were also improved as part of this commit.
The whole section reads like a description for the endpoint, and has been replaced by the swagger definition now (rather than at a later stage). All the same information should be kept.
