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

727 commits

Author SHA1 Message Date
Andrew Morgan 53137a3c53 c/p bug, fix operationIds, move rst docs to md 2018-07-30 11:09:50 +01:00
Andrew Morgan 3e4962f211 Document standardized extensions to OpenAPI v2 2018-07-30 11:09:50 +01:00
Andrew Morgan 273acb277c Change fields to use new extended query array syntax 2018-07-30 11:09:50 +01:00
Andrew Morgan 0ff882fb3b Field definitions for protocol metadata 2018-07-30 11:09:50 +01:00
Kitsune Ral 346db48588 Revert giving get() a default 
As per the PR review.

Signed-off-by: Alexey Rusakov <Alexey.Rusakov@pm.me>
 2018-07-29 14:04:07 +09:00
Kitsune Ral c6bfac41c5 Bypass jsonschema references resolver 
jsonschema's resolver doesn't work with local files on Windows.
resolve_references only works with the local files (on Windows as well)
but that's exactly what's needed for the case (as long as we don't have
remote references, that is).

Signed-off-by: Alexey Rusakov <Alexey.Rusakov@pm.me>
 2018-07-29 12:40:19 +09:00
Kitsune Ral d17ec7f184 Check that path starts with file://, not file:/// 
Because file:/// is not a thing on Windows.
 2018-07-29 12:40:18 +09:00
Kitsune Ral 2c9f00d37a Follow PEP 8 2018-07-29 12:40:17 +09:00
Kitsune Ral 31687608dc Factor out common code 2018-07-29 12:40:16 +09:00
Travis Ralston 73b0a03b9b Remove more padding 2018-07-27 08:39:15 -06:00
David Baker 5ddf5374db Missing comma 2018-07-27 12:24:29 +01:00
David Baker e4fd088fcc Fix room tags spec 2018-07-27 12:05:30 +01: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 797aca87bd Update the check_examples.py script to resolve references 
The script previously wasn't chasing down valid references in examples.
 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 05fb94e195 Merge remote-tracking branch 'matrix-org/master' into travis/better-errors 2018-07-18 08:28:16 -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 d2b0b1bbda
Merge pull request #1379 from turt2live/travis/preset-guests 
Document guest_access in /createRoom presets; Make presets a table
 2018-07-13 08:42:23 -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 1829589d23 Convert 3pn errors to new definition 2018-07-12 12:16:11 -06:00
Travis Ralston 197c36c520 Merge remote-tracking branch 'matrix-org/master' into travis/better-errors 2018-07-12 12:13:07 -06:00
Travis Ralston 91c59e7384
Merge pull request #1353 from matrix-org/anoa/as_thirdparty_lookup 
Thirdparty Entity Lookup API
 2018-07-12 11:19:12 -06:00
Andrew Morgan 291a4dfc76 Third party lookup module. Fix wording 2018-07-12 16:59:30 +01:00
Travis Ralston 6e3993effe Merge remote-tracking branch 'matrix-org/master' into travis/preset-guests 2018-07-12 09:48:52 -06:00
Travis Ralston 84e07a0c10 Convert errors in presence.yaml 2018-07-12 09:31:50 -06:00
Travis Ralston 16125f16f5 Spec retry_after_ms on ratelimit errors 2018-07-12 09:28:30 -06:00
Travis Ralston 8b513b9f8e Merge remote-tracking branch 'matrix-org/master' into travis/better-errors 2018-07-12 09:24:04 -06:00
Andrew Morgan 8999887245 Path -> query params 2018-07-12 14:44:48 +01:00
Andrew Morgan 9bde78ac28 $ref needs to be under a schema: 2018-07-12 14:41:24 +01:00
Andrew Morgan 114bcf1a2e Use $ref, clean up, fix errors, AS is now a C-S module. 2018-07-12 14:31:34 +01: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
Travis Ralston fbee83d5cf Clarify some of the properties on the search result 
Fixes https://github.com/matrix-org/matrix-doc/issues/773
 2018-07-10 15:08:28 -06:00
Travis Ralston d7a979da63 Merge remote-tracking branch 'matrix-org/master' into travis/all-the-auth 2018-07-06 11:33:24 -06:00
Travis Ralston 516000bdc3 Fix error reference in media repo 2018-07-06 08:53:04 -06:00
Travis Ralston ab75fc4b20 Merge remote-tracking branch 'matrix-org/master' into travis/better-errors 2018-07-06 08:46:50 -06:00
Travis Ralston e7a6ff1064
Merge branch 'master' into travis/spec-reason 2018-07-06 07:02:11 -06:00
Travis Ralston 1722734a51
Merge pull request #1364 from turt2live/travis/server-name-join 
Document the server_name query parameter on /join/{roomIdOrAlias}
 2018-07-06 07:00:24 -06:00
Will Hunt ff3c379339
Merge pull request #1189 from Half-Shot/hs/upload-limits 
GET media/config 🎉
 2018-07-06 11:37:35 +00:00
Will Hunt 77f4ac54aa
Wordy intro sentence for description 2018-07-06 10:36:17 +01:00
Will Hunt 2e6cc8045c
Better indent of description 2018-07-06 10:29:05 +01:00
Will Hunt d5ce87e956
Split summary up into description and summary 2018-07-06 10:27:03 +01:00
Travis Ralston bbf63d116c Fix reference to error.yaml in forget room API 2018-07-05 16:55:11 -06:00
Travis Ralston 55c27d6212
Merge branch 'master' into travis/better-errors 2018-07-05 13:40:17 -06:00
Travis Ralston 4485b2f025
Merge branch 'master' into travis/server-name-join 2018-07-05 11:23:13 -06:00
Travis Ralston c1c1f28c79
Merge branch 'master' into travis/dont-forget-to-leave 2018-07-05 10:55:48 -06:00
Travis Ralston 3935861445
Merge pull request #1380 from turt2live/travis/define-roomevent 
Define RoomEvent on /rooms/{roomId}/messages
 2018-07-05 10:54:54 -06:00
Andrew Morgan e81e0328c2 Fix single protocol metadata endpoint path, remove 500s 2018-07-05 17:50:34 +01:00
Travis Ralston 16860ddd22 De-quote 2018-07-05 10:46:53 -06:00
Andrew Morgan 4c38012122 I can spell 2018-07-05 12:58:42 +01:00
Andrew Morgan e6218b56ab Switch properties to schema 2018-07-05 11:59:10 +01:00
Andrew Morgan a6dad76c01 Fix indentation 2018-07-05 11:56:30 +01:00
Andrew Morgan cc3724b54a fix indentation, error messages. add rest of PR 2018-07-05 11:55:25 +01:00
Kitsune Ral dfdc5f9bef search.yaml: Rename some titles to avoid confusion between request and response schemas 
Signed-off-by: Alexey Rusakov <Alexey.Rusakov@pm.me>
 2018-07-04 20:11:08 -06:00
Travis Ralston 436b410698 Document the error code when someone tries to forget a room they are in 2018-07-04 20:02:30 -06:00
Travis Ralston 9b1f3a1f47 Document guest_access in /createRoom presets; Make presets a table 
Previously the presets ended up being rendered as one long string (the indentation was not respected). This was hard to read and wasn't very clear.

Now that there's a larger amount of information, it makes some sense to put it into a table. Tables don't work nicely when nested in another table, so the preset definitions have been moved into the general route description.

This commit also updates the documentation to reference `preset`, not `presets` given the param is singular.

Fixes https://github.com/matrix-org/matrix-doc/issues/881
 2018-07-04 18:16:24 -06:00
Travis Ralston 9e796192e4 Document that clients must leave before forgetting rooms 
Fixes https://github.com/matrix-org/matrix-doc/issues/1011
 2018-07-04 15:31:23 -06:00
Travis Ralston 05c85fd840 Spec the 403 on GET /presence/{userId}/status 2018-07-04 14:37:21 -06:00
Kitsune Ral 981d1004bc Add a missing $ref 2018-07-04 14:14:52 -06:00
Travis Ralston 442ad99727
Merge pull request #1273 from QMatrixClient/content-repo-use-default 
Add 'default' to formally enforce the description
 2018-07-04 14:01:36 -06:00
Travis Ralston caa6d4d9ad Give all errors a schema reference 
This just helps keep an overall structure
 2018-07-04 13:54:52 -06:00
Travis Ralston 7cd22f5690 Describe the rate limit error everywhere 
Fixes https://github.com/matrix-org/matrix-doc/issues/1153
 2018-07-04 13:45:34 -06:00
Travis Ralston 1f12637d3f Getting presence requires authentication 2018-07-04 12:23:51 -06:00
Travis Ralston a6b0125da6 Our swagger doesn't support explode yet 2018-07-03 16:19:31 -06:00
Travis Ralston d279fdafa6 Document the server_name query parameter on /join/{roomIdOrAlias} 
Fixes https://github.com/matrix-org/matrix-doc/issues/904
 2018-07-03 15:49:16 -06:00
Travis Ralston 7d94aaace8 Explicitly declare that the kick/ban reason will be on the membership event 
Fixes https://github.com/matrix-org/matrix-doc/issues/798
 2018-07-03 14:59:41 -06:00
Travis Ralston 2409c84968 Document the GET version of /login 
Fixes https://github.com/matrix-org/matrix-doc/issues/677
 2018-07-03 13:41:49 -06:00