element-hq / element-hq/synapse

Remove the unspecced, "legacy" account validity endpoints

Open
#15,271 0 comments 0 reactions 0 assignees View on GitHub
A-Spec-Compliance O-Occasional S-Minor T-Task X-Consult-Clients
Dominant language
Python
Stars
4.6k
Forks
600
Avg merge
5d 22h
Merged PRs (30d)
51

Description

This issue has been migrated from [#15271](https://github.com/matrix-org/synapse/issues/15271).

---

We have an undocumented and unspecced Account Validity feature currently implemented in Synapse. This was originally written for DINUM. Since then, all of the functionality has been moved into the module API (https://github.com/matrix-org/synapse/pull/9884), and can be implemented by modules. https://github.com/matrix-org/synapse-email-account-validity is the only known implementation of this API.

Synapse still has an implementation of account validity however, gated behind an undocumented [account_validity config option](https://github.com/matrix-org/synapse/blob/b71b41c7bd0dd7510182621ab4bc8267388c0cce/synapse/config/account_validity.py#L31). Completely removing the account validity feature out of Synapse's main codebase is not what this issue is about though.

In the original implementation of account validity (https://github.com/matrix-org/synapse/pull/5047/files#diff-6fc5658389633ef773a5c9ed669e5273eecff1c01311d7ac2c0721119a9ad21b, https://github.com/matrix-org/synapse/pull/5073/files#diff-6fc5658389633ef773a5c9ed669e5273eecff1c01311d7ac2c0721119a9ad21b), the following endpoints were registered:

- [`GET /_matrix/client/{unstable,r0,v3}/account_validity/renew`](https://github.com/matrix-org/synapse/blob/2af6d31b78109a989e27128ac655990c35b29d62/synapse/rest/client/account_validity.py#L34)
- [`POST /_matrix/client/{unstable,r0,v3}/account_validity/send_mail`](https://github.com/matrix-org/synapse/blob/2af6d31b78109a989e27128ac655990c35b29d62/synapse/rest/client/account_validity.py#L77)

plus one [Admin API endpoint](https://matrix-org.github.io/synapse/latest/admin_api/account_validity.html#renew-account):

- [`POST /_synapse/admin/v1/account_validity/validity`](https://github.com/matrix-org/synapse/blob/53680ae148b4f35d69f5c6bbf779b6cec49a7c04/synapse/rest/admin/users.py#L683)

In the effort to move towards a module in April 2021, account validity module API callbacks were created which were tied to these "legacy" endpoints. If one of the legacy endpoints were called, then these callbacks would fire.

https://github.com/matrix-org/synapse/blob/a00462dd9927558532b030593f8914ade53b7214/synapse/handlers/account_validity.py#L36-L40

At the same time, modules were also given the ability to register their own endpoints under `/_synapse/client/`, which is what [synapse-email-account-validity does](https://github.com/matrix-org/synapse-email-account-validity#routes) does. Client implementations were encouraged to move to these `/_synapse/client/email_account_validity/...` endpoints instead.

https://github.com/matrix-org/synapse-email-account-validity still implements these legacy callbacks though: in case a client still uses them, or a user clicks on an email still containing an old `GET /_matrix/client/v3/account_validity/renew` link.

However, it has been sufficiently long since https://github.com/matrix-org/synapse/pull/9884 (April 2021), that I think we can remove the legacy endpoints and module API callbacks. The legacy module API callbacks are also [not documented](https://matrix-org.github.io/synapse/latest/modules/account_validity_callbacks.html), so it's unlikely their usage has spread much.

~~I will ask DINUM if they are still using the unspecced `/_matrix/client/...` endpoints in any form.~~ According to @giomfo, DINUM are not currently using the feature at all, but plan to again in the future. While Tchap clients have not yet been updated to point to the new endpoint, they're just going to use a proxy to rewrite the request path to ensure clients switch immediately.

Therefore I suggest we just rip out the "legacy" endpoints and module API callbacks without a deprecation period.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the legacy routes in synapse/rest/client/account_validity.py and the Admin API entry in synapse/rest/admin/users.py, then inspect the related callbacks in synapse/handlers/account_validity.py. Check how the account-validity module API is registered and keep the newer module-owned endpoints intact. Done means the three legacy endpoints and their callbacks are no longer registered, with no remaining references to them.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.