This fixes a number of formatting issues alongside a few documentation problems:
* The push gateway can actually expect less parameters than previously advertised. This is for user privacy.
* Introduction of the `m.email` pusher for email-capable homeservers.
* Fields not being flagged as required on some endpoints.
* Document the `event_id_only` format
Note: this does not attempt to document push rules, just pushers.
Fixes https://github.com/matrix-org/matrix-doc/issues/1374
Fixes https://github.com/matrix-org/matrix-doc/issues/1087
It's worth noting that Synapse does not make use of the `poll` or `unpoll` fields, and therefore the wording has been updated to permit servers to reject users. In the case of synapse, it would automatically reject everyone in the list by nature of ignoring it.
We might want to consider promoting the media repo to it's own API, and maybe consider calling it the Media Repo rather than Content Repo.
Source of information: experience.
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.
There's two kinds of transactions currently: one with EDUs and one without. The one with EDUs is only used on /send, however the schema is still somewhat worth splitting out for simplicity.
The examples are brought apart to make them slightly more reusable for when they get dumped into the relevant sections of the spec (see TODO in server_server_api.rst)
Further, the Transactions stuff introduces tuples to the spec. The units.py has been updated to support this.
In practice this was confusing for people, so instead we should encourage people to create new issues and reference the existing ones.
Signed-off-by: Travis Ralston <travpc@gmail.com>
Travis Ralston