matrix-org / matrix-org/complement
De-emphasise and reduce the usage of `/_synapse` endpoints
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 99
- Forks
- 72
- Avg merge
- 4d 1h
- Merged PRs (30d)
- 8
Description
This is something I noticed while working on conduit support (#513), where it seems that complement currently requires or emphasizes the usage of `/_synapse` endpoints.
Specifically, it uses them like so:
- Under ["Image Requirements"](https://github.com/matrix-org/complement#image-requirements) in README.md, it asks for `/_synapse/admin/v1/register` to be supported for "admin" registrations.
- This is then used in `RegisterUser` where isAdmin is `true`, which is used by the following tests:
- `TestCanRegisterAdmin`
- `TestServerNotices`
- `TestRegistration`, under some `t.Run`s
From a puritan perspective, these should not exist within complement, as they test Synapse-specific behaviour that other servers have to then copy uncritically, and without blessing or formalisation from the spec.
From such a perspective, the concept of "admins" is also dubious, as the spec (explicitly) makes no serious note of them, leaving server administration as an implementation detail. (See MSC3593 for some context reading on an attempt to broach/formalise this as well.)
----
For all of complement's current usage of this endpoint, there is one problem with a suggestion of removing all of them altogether; [Server Notices](https://spec.matrix.org/v1.4/client-server-api/#server-notices) are defined in the spec, and so the absence of a formal mechanism which empowers servers/users to send server notices is unfortunate, but this means complement has no "closed system" way of implementing this.
To make the rejection of a `/_synapse` specific API explicit, and to develop a better way of testing server notices, I'm suggesting to introduce a `/_complement` API space, which servers should enable only in their corresponding complement images, and (for now) be only used for sending server notices (exact API forthcoming), *not* to elevate individual users as a "server admin", as this concept does not properly exist from a matrix specification standpoint.
This API space should only perform individual elevated actions, such as sending a single server notice via a `POST` API.
Hopefully, this way, we can avoid biasing to a certain implementation, and help make complement more pure or agnostic when testing conformity.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing README.md's Image Requirements, RegisterUser, TestCanRegisterAdmin, TestServerNotices, and TestRegistration to map every current /_synapse usage. The proposal does not define the replacement API, so the work is not ready until the server-notice interface and migration scope are agreed; done would remove unnecessary Synapse-specific assumptions while preserving server-notice coverage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- api, backend-api-design, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100