Add get_media_upload_limits_for_user and on_media_upload_limit_exceeded callbacks to module API

docs/modules/media_repository_callbacks.md

@@ -70,21 +70,22 @@ implementations of this callback.
 _First introduced in Synapse v1.139.0_
 
 ```python
-async def get_media_upload_limits_for_user(user_id: str, size: int) -> Optional[List[MediaUploadLimit]]
+async def get_media_upload_limits_for_user(user_id: str, size: int) -> Optional[List[synapse.module_api.MediaUploadLimit]]
 ```
 
 **<span style="color:red">
 Caution: This callback is currently experimental. The method signature or behaviour
 may change without notice.
 </span>**
 
-Called when processing a request to store content in the media repository.
+Called when processing a request to store content in the media repository. This can be used to dynamically override
+the [media upload limits configuration](../usage/configuration/config_documentation.html#media_upload_limits).
 
 The arguments passed to this callback are:
 
 * `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`) making the request.
 
-If the callback returns a list then it will be used as the limits to be applied to the request.
+If the callback returns a list then it will be used as the limits instead of those in the configuration (if any).
 
 If an empty list is returned then no limits are applied (**warning:** users will be able
 to upload as much data as they desire).
@@ -96,27 +97,33 @@ any of the subsequent implementations of this callback.
 
 If there are no registered modules, or if all modules return `None`, then
 the default
-[media upload limits config](../usage/configuration/config_documentation.html#media_upload_limits)
+[media upload limits configuration](../usage/configuration/config_documentation.html#media_upload_limits)
 will be used.
 
 ### `on_media_upload_limit_exceeded`
 
 _First introduced in Synapse v1.139.0_
 
 ```python
-async def on_media_upload_limit_exceeded(user_id: str, limit: MediaUploadLimit, sent_bytes: int, attempted_bytes: int) -> None
+async def on_media_upload_limit_exceeded(user_id: str, limit: synapse.module_api.MediaUploadLimit, sent_bytes: int, attempted_bytes: int) -> None
 ```
 
 **<span style="color:red">
 Caution: This callback is currently experimental. The method signature or behaviour
 may change without notice.
 </span>**
 
-Called when a user attempts to upload media that would exceed a configured media upload limit.
+Called when a user attempts to upload media that would exceed a
+[configured media upload limit](../usage/configuration/config_documentation.html#media_upload_limits).
+
+This callback will only be called a media workers which handle [POST /_matrix/media/v3/upload](https://spec.matrix.org/v1.15/client-server-api/#post_matrixmediav3upload) requests.
+
+This could be used to inform the user that they have reached a media upload limit through through
+some external method.
 
 The arguments passed to this callback are:
 
 * `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`) making the request.
-* `limit`: The `MediaUploadLimit` that was reached.
+* `limit`: The `synapse.module_api.MediaUploadLimit` representing the limit that was reached.
 * `sent_bytes`: The number of bytes already sent during the period of the limit.
 * `attempted_bytes`: The number of bytes that the user attempted to send.

docs/usage/configuration/config_documentation.md

@@ -2168,9 +2168,12 @@ max_upload_size: 60M
 ### `media_upload_limits`
 
 *(array)* A list of media upload limits defining how much data a given user can upload in a given time period.
+This is applied in addition to the `max_upload_size` limit above, which applies to individual uploads.
 
 An empty list means no limits are applied.
 
+These settings can be overridden using the `get_media_upload_limits_for_user` module API [callback](../../modules/callbacks/media_repository_callbacks.html#get_media_upload_limits_for_user).
+
 Defaults to `[]`.
 
 Example configuration:

schema/synapse-config.schema.yaml

@@ -2415,8 +2415,15 @@ properties:
       A list of media upload limits defining how much data a given user can
       upload in a given time period.
 
+      This is applied in addition to the `max_upload_size` limit above, which
+      applies to individual uploads.
+
 
       An empty list means no limits are applied.
+
+
+      These settings can be overridden using the `get_media_upload_limits_for_user`
+      module API [callback](../../modules/callbacks/media_repository_callbacks.html#get_media_upload_limits_for_user).
     default: []
     items:
       time_period:

synapse/config/repository.py

@@ -120,11 +120,19 @@ def parse_thumbnail_requirements(
 
 @attr.s(auto_attribs=True, slots=True, frozen=True)
 class MediaUploadLimit:
-    """A limit on the amount of data a user can upload in a given time
-    period."""
+    """
+    Represents a limit on the amount of data a user can upload in a given time
+    period.
+
+    These can be configured through the `media_upload_limits` [config option](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#media_upload_limits)
+    or via the the `get_media_upload_limits_for_user` module API [callback](https://element-hq.github.io/synapse/latest/modules/callbacks/media_repository_callbacks.html#get_media_upload_limits_for_user).
+    """
 
     max_bytes: int
+    """The maximum number of bytes that can be uploaded in the given time period."""
+
     time_period_ms: int
+    """The time period in milliseconds."""
 
 
 class ContentRepositoryConfig(Config):