From 65ba987eb84f74b8883f7d82e47b3ae7011cb7ae Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 15 Oct 2025 11:19:59 +0200 Subject: [PATCH 1/2] MSC4368: Add limit_type to M_RESOURCE_LIMIT_EXCEEDED error code --- ...68-resource-limit-exceeded-extra-fields.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 proposals/4368-resource-limit-exceeded-extra-fields.md diff --git a/proposals/4368-resource-limit-exceeded-extra-fields.md b/proposals/4368-resource-limit-exceeded-extra-fields.md new file mode 100644 index 00000000000..239f4244b37 --- /dev/null +++ b/proposals/4368-resource-limit-exceeded-extra-fields.md @@ -0,0 +1,50 @@ +# MSC4368: Add limit_type to M_RESOURCE_LIMIT_EXCEEDED error code + +## Proposal + +1. Add an optional `limit_type` field to the body of the [`M_RESOURCE_LIMIT_EXCEEDED`] error response that has the same +definition as it does for [`m.server_notice`]: + +> The kind of usage limit the server has exceeded + +And on the possible values: + +> The specified values for `limit_type` are: +> `monthly_active_user` The server’s number of active users in the last 30 days has exceeded the maximum. New +> connections are being refused by the server. What defines “active” is left as an implementation detail, however +> servers are encouraged to treat syncing users as “active”. + +2. Update the description of `admin_contact` so that instead of "a place to reach out to" that it is the same definition +as the `admin_contact` field on the [`m.server_notice`] which says "a URI giving a contact method for the server +administrator". + +This amounts to unifying the representation of a server resource limit being exceeded in an error code and the server +notice. + +## Potential issues + +None anticipated. Optional extra fields on the error. + +## Alternatives + +None considered. + +## Security considerations + +None. + +## Unstable prefix + +Ideally implementations would use an unstable prefix of something like `io.element.mscXXX.limit_type` whilst the +MSC is in development. + +However, it is noted that the implementation in Synapse has existed since +[2018](https://github.com/matrix-org/synapse/pull/3707) and so the unprefixed `limit_type` is being used in the wild. +As such some clients also support this unprefixed version. + +## Dependencies + +None. + +[`M_RESOURCE_LIMIT_EXCEEDED`]: https://spec.matrix.org/v1.16/client-server-api/#other-error-codes +[`m.server_notice`]: https://spec.matrix.org/v1.16/client-server-api/#mroommessagemserver_notice From ff78bc5dea64590485b7bb5e00c3f225e2473915 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 16 Oct 2025 17:08:10 +0200 Subject: [PATCH 2/2] Make it clear that proposing to merge two definitions --- ...68-resource-limit-exceeded-extra-fields.md | 37 +++++++++++++------ 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/proposals/4368-resource-limit-exceeded-extra-fields.md b/proposals/4368-resource-limit-exceeded-extra-fields.md index 239f4244b37..fc57705bee6 100644 --- a/proposals/4368-resource-limit-exceeded-extra-fields.md +++ b/proposals/4368-resource-limit-exceeded-extra-fields.md @@ -1,9 +1,22 @@ -# MSC4368: Add limit_type to M_RESOURCE_LIMIT_EXCEEDED error code +# MSC4368: Combine definitions of M_RESOURCE_LIMIT_EXCEEDED error code and m.server_notice.usage_limit_reached server notice type + +When a homeserver has exceeded some kind of resource limit it can currently communicate the fact to the client and user +using two distinct mechanism: + +* the [`M_RESOURCE_LIMIT_EXCEEDED`] error code returned on the affected API endpoint +* the sending of a [`m.server_notice.usage_limit_reached`] [server notice] to the user + +The fields that are contained in the error response are currently a subset of that which is sent in the server notice. ## Proposal -1. Add an optional `limit_type` field to the body of the [`M_RESOURCE_LIMIT_EXCEEDED`] error response that has the same -definition as it does for [`m.server_notice`]: +The proposal is to standardise the information across the [`M_RESOURCE_LIMIT_EXCEEDED`] error code and +[`m.server_notice.usage_limit_reached`] server notice by: + +1. Add the optional `limit_type` field to the body of the [`M_RESOURCE_LIMIT_EXCEEDED`] error response that has the same +definition as it does for [`m.server_notice`]. + +Repeated here for convenience: > The kind of usage limit the server has exceeded @@ -11,19 +24,19 @@ And on the possible values: > The specified values for `limit_type` are: > `monthly_active_user` The server’s number of active users in the last 30 days has exceeded the maximum. New -> connections are being refused by the server. What defines “active” is left as an implementation detail, however -> servers are encouraged to treat syncing users as “active”. +> connections are being refused by the server. What defines "active" is left as an implementation detail, however +> servers are encouraged to treat syncing users as "active". 2. Update the description of `admin_contact` so that instead of "a place to reach out to" that it is the same definition -as the `admin_contact` field on the [`m.server_notice`] which says "a URI giving a contact method for the server -administrator". + as the `admin_contact` field on the [`m.server_notice`] which says "a URI giving a contact method for the server + administrator". -This amounts to unifying the representation of a server resource limit being exceeded in an error code and the server -notice. +3. Aside from the above, at a minimum make the two definitions reference one another if not merge the actual + descriptions. ## Potential issues -None anticipated. Optional extra fields on the error. +None anticipated ad adding an optional extra fields on the error. ## Alternatives @@ -35,7 +48,7 @@ None. ## Unstable prefix -Ideally implementations would use an unstable prefix of something like `io.element.mscXXX.limit_type` whilst the +Ideally implementations would use an unstable prefix of something like `io.element.msc4368.limit_type` whilst the MSC is in development. However, it is noted that the implementation in Synapse has existed since @@ -47,4 +60,6 @@ As such some clients also support this unprefixed version. None. [`M_RESOURCE_LIMIT_EXCEEDED`]: https://spec.matrix.org/v1.16/client-server-api/#other-error-codes +[`m.server_notice.usage_limit_reached`]: https://spec.matrix.org/v1.16/client-server-api/#events-20 [`m.server_notice`]: https://spec.matrix.org/v1.16/client-server-api/#mroommessagemserver_notice +[server notice]: https://spec.matrix.org/v1.16/client-server-api/#server-notices