Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-21 17:08:36 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
5116 commits 30 branches 42 tags 32 MiB
Commit graph

217 commits

Author SHA1 Message Date
Travis Ralston 73958ecbff Document /event_auth and /query_auth 
/event_auth is a fairly easy endpoint to determine the use case of. /query_auth is a little harder to investigate and has a fairly interesting purpose: it appears to be used for the sending server to admit defeat and shop around for the right auth chain, correcting it's own perspective as it goes.

/query_auth is based off the following research points in synapse:
* 43ecfe0b10/synapse/handlers/federation.py (L1947-L1990)
* 43ecfe0b10/synapse/handlers/federation.py (L2049-L2187)
* 43ecfe0b10/synapse/handlers/federation.py (L1716-L1761)
* 43ecfe0b10/synapse/federation/federation_server.py (L393-L446)
* https://github.com/matrix-org/synapse/blob/master/synapse/federation/transport/server.py#L482-L487
 2018-08-03 09:27:19 -06:00
Travis Ralston 6b67d501e4
Merge branch 'master' into travis/s2s/query 2018-08-03 08:55:21 -06:00
Travis Ralston 3a9fb11c9b
Merge branch 'master' into travis/s2s/backfill 2018-08-03 08:54:40 -06:00
Travis Ralston 1578da453b
Merge branch 'master' into travis/s2s/get-event 2018-08-03 08:01:43 -06:00
Travis Ralston 86d7f42173
Merge pull request #1455 from turt2live/travis/s2s/leaving-rooms 
Document how leaving rooms/rejecting invites over federation works
 2018-08-03 08:00:56 -06:00
Travis Ralston d48f1e1713
Merge pull request #1461 from turt2live/travis/s2s/transactions 
Improve documentation on how Transactions work
 2018-08-03 07:38:45 -06:00
Travis Ralston cda88f3b3d Document /get_missing_events 
Fixes https://github.com/matrix-org/matrix-doc/issues/1385
 2018-08-02 23:18:08 -06:00
Travis Ralston e766606f24 join -> leave 2018-08-02 18:54:12 -06:00
Travis Ralston 0b313dbdd9 Don't explain what a 400 Bad Request is 2018-08-02 18:47:17 -06:00
Travis Ralston 05bb7e1050 Spelling and word choice 2018-08-02 18:45:59 -06:00
Travis Ralston 53d4003d3a manual merge of master into travis/s2s/query 2018-08-02 16:48:32 -06:00
Travis Ralston 48972addbf
Merge pull request #1428 from turt2live/travis/s2s/joining-rooms 
Improve the documentation for joining rooms
 2018-08-02 16:44:31 -06:00
Travis Ralston 5596243add origin is required 2018-08-02 16:43:24 -06:00
Travis Ralston 8b7bc60367 list -> array 2018-08-02 16:42:03 -06:00
Travis Ralston 9d474bb819 Document event retrieval endpoints in more detail 
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.
 2018-08-02 12:44:54 -06:00
Travis Ralston 4b1955f395 Clarify what the auth_events on a PDU are 2018-08-02 12:06:43 -06:00
Travis Ralston 5aef545128 Improve documentation for backfilling rooms 
There's not a whole lot to improve here - most of the changes are about reorganization and minor clarifications.
 2018-08-01 13:31:23 -06:00
Travis Ralston d0e8df8f3f prev_content is an object 2018-07-31 14:02:04 -06:00
Travis Ralston 5027a9a59a Improve documentation around EDUs and PDUs 
Clarify fields, improve examples, and make the tables in the spec be generated rather than duplicated.
 2018-07-31 13:58:23 -06:00
Travis Ralston 7679b4f1d1 Improve documentation on how Transactions work 
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.
 2018-07-30 16:58:13 -06:00
Travis Ralston 73b0a03b9b Remove more padding 2018-07-27 08:39:15 -06:00
Travis Ralston cafd1a9ab3 Use more modern timestamps 2018-07-26 16:46:33 -06:00
Travis Ralston e27f4a69a0 Key versions must be [0-9a-zA-Z_] 2018-07-26 16:46:13 -06:00
Travis Ralston bdccfca726 Timestamps should be in milliseconds 2018-07-26 16:43:43 -06:00
Travis Ralston cad1db2a14 Unpadded means unpadded 2018-07-26 16:43:16 -06:00
Travis Ralston 9dbb627d7b Undo accidental changes to the operation ID 2018-07-26 16:42:40 -06:00
Travis Ralston 2f71703427 Deprecate key ID querying 2018-07-26 16:42:21 -06:00
Travis Ralston 9fdd8a6f96 Document how leaving rooms/rejecting invites over federation works 
Fixes https://github.com/matrix-org/matrix-doc/issues/1401

This is very similar to the joining rooms handshake, and much of it is a near copy/paste of the make_join and send_join API. The major difference is the send_leave API doesn't return anything.

References:
* Handling of make_leave: d69decd5c7/synapse/handlers/federation.py (L1285-L1310)
* send_leave route: d69decd5c7/synapse/federation/transport/client.py (L267)
* make_leave route: d69decd5c7/synapse/federation/transport/server.py (L396)
* send_leave returning nothing: d69decd5c7/synapse/handlers/federation.py (L1346)
 2018-07-26 14:59:43 -06:00
Travis Ralston fcaa299f81 Include information on how invite_room_state works 
This is completely optional, and the events included are up to the sender. 

Sources:
* Structure: d69decd5c7/synapse/handlers/message.py (L896-L904)
* What events are recommended: d69decd5c7/synapse/config/api.py (L30-L40)
 2018-07-26 08:44:10 -06:00
Travis Ralston f873bae0cc Improve documentation for how non-third party invites work 
The details are fairly straightforward. An `event` has been added to the response body because that's what Synapse returns, despite the spec saying otherwise until now: d69decd5c7/synapse/federation/federation_server.py (L339)
 2018-07-26 08:44:10 -06:00
Travis Ralston c2f1c6e78d 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
 2018-07-26 08:43:08 -06:00
Travis Ralston 8e97b0ca81 Improve the server key exchange portion of the s2s specification 
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.
 2018-07-26 08:41:00 -06:00
Travis Ralston d914c402e2 Improve the profile query to have more sane responses 
This is a mix of Synapse and Dendrite behaviour, mostly Dendrite. Synapse returns `null` for field values that aren't set, however Dendrite just doesn't return them and instead opts for an empty object.

Further, synapse is lacking in error codes in this area. Dendrite does some additional validation on this API which introduces more errors for bad requests, instead of defaulting to empty objects/200 OK responses.

Likewise, Dendrite returns a 404 when the user is not found while Synapse returns 200 OK/empty object.
 2018-07-26 08:40:39 -06:00
Travis Ralston 0ddf578b61 Combine all queries into their own section 
This removes the Directory and Profile sections, instead opting to document them as Queries. 

The behaviour of profile queries is based on Synapse's behaviour. A few issues have been opened to improve the behaviour:
* https://github.com/matrix-org/matrix-doc/issues/1434
* https://github.com/matrix-org/matrix-doc/issues/1435
* https://github.com/matrix-org/matrix-doc/issues/1436
* https://github.com/matrix-org/matrix-doc/issues/1437

This fixes https://github.com/matrix-org/matrix-doc/issues/1404
 2018-07-26 08:40:39 -06:00
Travis Ralston b0744aa1e9
Merge pull request #1413 from turt2live/travis/s2s/join-swagger 
Convert joins/invites to swagger
 2018-07-26 08:39:26 -06:00
Travis Ralston af0629a520 Full stop 2018-07-26 08:36:12 -06:00
Travis Ralston 9f399a08fe Full stops 
I'm never going to remember these
 2018-07-24 14:41:42 -06:00
Travis Ralston 0d1b82a601 Add the event_id to unsigned PDUs 
This went missing in the swagger conversion. The example already has an event_id.
 2018-07-24 14:40:32 -06:00
Travis Ralston eaf175056f Full stops 2018-07-24 10:58:15 -06:00
Travis Ralston 7314405904 Update comment 2018-07-24 10:58:15 -06:00
Travis Ralston 45ec8269e6 Fill out the required fields in all the examples 2018-07-24 10:58:15 -06:00
Travis Ralston 9c1c541a38 Remove extra "required" declarations 
"required" is something that is handled as an array, and these are invalid. The `type` in both cases is covered by a required array elsewhere
 2018-07-24 10:58:15 -06:00
Travis Ralston 004998b98f Convert invites to swagger 
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.
 2018-07-24 10:58:15 -06:00
Travis Ralston f09c4fd286 Convert joins to swagger 2018-07-24 10:58:15 -06:00
Travis Ralston cb4fcd1d09 Merge remote-tracking branch 'matrix-org/master' into travis/s2s/transactions-swagger 2018-07-24 09:15:36 -06:00
Travis Ralston 88beaf4ad8 Completely remove /pull 
It's not been in use for years - we can safely let it disappear
 2018-07-24 09:13:46 -06:00
Travis Ralston 21c4af70a9 Fix schema definitions (spelling, attributes) 2018-07-24 09:13:15 -06:00
Travis Ralston 2aafde4549
Merge pull request #1419 from turt2live/travis/s2s/3pinvites-swagger 
Convert third party invite exchange to swagger
 2018-07-23 10:33:00 -06:00
Travis Ralston 89384c96c1 Full stops, language. 2018-07-18 11:06:23 -06:00
Travis Ralston e226b60c7f Merge remote-tracking branch 'matrix-org/master' into travis/s2s/transactions-swagger 2018-07-18 10:59:39 -06:00
Travis Ralston bafdcf3640 Full stops, spelling, and operation IDs. 2018-07-18 10:37:56 -06:00
Travis Ralston 7cb918407d Merge remote-tracking branch 'matrix-org/master' into travis/s2s/keys-swagger 2018-07-18 10:32:46 -06:00
Travis Ralston 272f3d8432 Fix documentation link 2018-07-13 15:49:49 -06:00
Travis Ralston cf93c88337 Convert third party invite exchange to swagger 2018-07-13 15:44:33 -06:00
Travis Ralston e5da1e1741 Improve upon the transaction schema and examples 
Reduces data duplication and makes the objects more reusable for other areas of the spec
 2018-07-12 21:34:52 -06:00
Travis Ralston 51faf8ed2e Convert the general query API to swagger 
Includes "moving" the directory query API into the same area. This will make more sense once the other query types are specified.
 2018-07-12 13:46:42 -06:00
Travis Ralston 374ec00046 Convert things that mention "Transaction" to swagger 
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.
 2018-07-11 16:52:27 -06:00
Travis Ralston 3e13ec2841 Fix required properties in POST /query 2018-07-11 13:43:15 -06:00
Travis Ralston 96889f16e9 Split out and fix the /server and /query key APIs 2018-07-11 13:20:44 -06:00
Travis Ralston bd2c0b7c98 Convert server keys to swagger 2018-07-11 13:09:19 -06:00
user 5ab5fe08d1 Small grammatical and stylistic fixes 2018-06-17 15:49:39 +01:00
Maxime Dor 9d2e18cca1 Adapt paths as per feedback 2017-11-15 18:46:27 +01:00
Maxime Dor d1e64daa10 Fix yaml title for directory api 2017-11-15 18:43:16 +01:00
Maxime Dor 28c09aed62 Properly mark required response keys to pass tests 2017-11-15 13:57:52 +01:00
Maxime Dor 8a6103798e Fix for tests 2017-11-15 13:54:55 +01:00
Maxime Dor bb50ec2e88 Document directory query endpoint 2017-11-15 13:40:55 +01:00
Maxime Dor 1045bc721d Document federation version endpoint 2017-11-15 04:16:30 +01:00