MSC4255 Initial commit

proposals/4255-bulk-profile-updates.md

@@ -0,0 +1,180 @@
+# MSC4255: Bulk Profile Updates Per-User
+
+This proposal builds upon [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133)
+(Extending User Profile API with Custom Key:Value Pairs) to introduce two additional endpoints to
+the Matrix Client-Server API that enable efficient bulk updates of user profiles. These endpoints
+are particularly valuable for bridge applications (AppServices) that need to manage profiles for
+many bridged users simultaneously.
+
+## Problem Statement
+
+When users interact with Matrix through bridges, they expect their profile information to stay
+consistent with the bridged platform. However, the current Matrix specification only provides
+single-field update endpoints, making it difficult for bridges to efficiently maintain this
+consistency at scale.
+
+Currently, bridges must make individual API calls for each field they want to update in a user's
+profile. For instance, when a Discord user changes their avatar, username, and status
+simultaneously, the bridge must make three separate API calls to reflect these changes in Matrix.
+This becomes a significant bottleneck when managing thousands of bridged users, leading to delayed
+updates and increased server load.
+
+Some commercial bridge providers, such as Beeper, have already implemented proprietary solutions
+for this problem. This proposal aims to standardise this functionality, allowing both commercial
+and self-hosted bridge deployments to benefit from similar, efficient client functionality.
+
+## Current Specification
+
+The Matrix specification currently defines a read-only endpoint for retrieving all profile fields:
+[`GET /_matrix/client/v3/profile/{userId}`](https://spec.matrix.org/v1.13/client-server-api/#get_matrixclientv3profileuserid).
+
+However, there is no equivalent endpoint for updating multiple profile fields simultaneously.
+Instead, clients must use individual PUT requests for each field they want to update.
+
+## Proposal
+
+This MSC introduces two new endpoints that allow updating multiple profile fields in a single
+request:
+
+### PUT Endpoint - Replace Profile
+
+- **Endpoint**: `PUT /_matrix/client/v3/profile/{userId}`
+- **Description**: Replace the entire profile with the provided fields, removing any fields not
+  included in the request.
+- **Rate Limiting**: Servers SHOULD apply appropriate rate limits based on their policies
+- **Authentication**: Requires valid access token with permission to modify the requested userId's
+  profile
+- **Request Body**:
+
+```json
+{
+    "avatar_url": "mxc://matrix.org/MyNewAvatar",
+    "displayname": "John Doe",
+    "m.example_field": "new_value1",
+    "org.example.job_title": "Software Engineer"
+}
+```
+
+### PATCH Endpoint - Merge Profile Updates
+
+- **Endpoint**: `PATCH /_matrix/client/v3/profile/{userId}`
+- **Description**: Merge the provided fields into the existing profile, only modifying specified
+  fields.
+- **Rate Limiting**: Servers SHOULD apply appropriate rate limits based on their policies
+- **Authentication**: Requires valid access token with permission to modify the requested userId's
+  profile
+- **Request Body**:
+
+```json
+{
+    "avatar_url": "mxc://matrix.org/MyNewAvatar",
+    "m.example_field": "new_value1"
+}
+```
+
+### Behaviour
+
+- The `PUT` endpoint replaces the entire profile, removing any fields not included in the request
+- The `PATCH` endpoint only updates the fields provided, leaving other fields unchanged
+- Both endpoints MUST respect the same size limits as individual field updates (64 KiB total
+  profile size)
+- Both endpoints MUST follow the same field naming requirements as individual updates
+- Authentication and permissions follow the same rules as individual field updates
+- Servers MUST process these requests atomically to prevent partial updates
+- Servers MUST validate all fields in the request before applying any changes
+
+## Use Cases
+
+### Bridge Profile Synchronisation
+
+When bridging platforms that support rich profiles (such as Discord, Slack, or IRC services),
+bridges need to synchronise multiple profile fields simultaneously. For example:
+
+1. Avatar URL changes
+2. Display name updates
+3. Custom status fields
+4. Platform-specific metadata (roles, badges, etc.)
+
+Currently, each field requires a separate API call, which is inefficient when managing thousands of
+bridged users. These new endpoints allow bridges to update all relevant fields in a single request,
+reducing server load and improving synchronisation speed.
+
+## Security Considerations
+
+1. **Authentication and Authorization**
+   - All requests MUST be authenticated
+   - Servers MUST verify the access token has permission to modify the requested userId's profile
+   - Rate limiting SHOULD be applied as per the homeserver's normal profile endpoint limits
+
+2. **Data Validation**
+   - Servers MUST validate all fields before applying any changes
+   - The total profile size MUST NOT exceed 64 KiB
+   - Field names MUST follow the [Common Namespaced Identifier Grammar](https://spec.matrix.org/v1.13/appendices/#common-namespaced-identifier-grammar)
+
+3. **Atomic Updates**
+   - Servers MUST ensure updates are atomic to prevent inconsistent profile states
+   - If any field update fails validation, the entire request MUST be rejected
+
+## Error Codes
+
+All error codes from individual profile field updates apply, plus:
+
+- **`M_LIMIT_EXCEEDED`**: Too many fields are updated at once (server-defined limit)
+
+  ```json
+  {
+    "errcode": "M_LIMIT_EXCEEDED",
+    "error": "Too many profile fields in request"
+  }
+  ```
+
+- **`M_BAD_JSON`**: Request body is malformed
+
+  ```json
+  {
+    "errcode": "M_BAD_JSON",
+    "error": "Request must be valid JSON"
+  }
+  ```
+
+- **`M_FORBIDDEN`**: User lacks permission for requested changes
+
+  ```json
+  {
+    "errcode": "M_FORBIDDEN",
+    "error": "You do not have permission to modify this profile"
+  }
+  ```
+
+- **`M_PROFILE_TOO_LARGE`**: Resulting profile would exceed 64 KiB
+
+  ```json
+  {
+    "errcode": "M_PROFILE_TOO_LARGE",
+    "error": "Profile exceeds maximum size of 64 KiB"
+  }
+  ```
+
+## Unstable Prefix
+
+Until this proposal is stable, implementations SHOULD use these endpoints:
+
+- `PUT /_matrix/client/unstable/uk.tcpip.msc4255/profile/{userId}`
+- `PATCH /_matrix/client/unstable/uk.tcpip.msc4255/profile/{userId}`
+
+The client feature `uk.tcpip.msc4255` SHOULD be advertised on the `/versions` endpoint when these
+endpoints are supported.
+
+## Relationship to Other MSCs
+
+This proposal builds on [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133)
+which introduces extensible profiles. While [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133)
+focuses on the core functionality of custom profile fields, this MSC adds efficient bulk update
+capabilities specifically to support bridge use cases.
+
+## Alternatives
+
+1. Continue using individual field updates, accepting the performance impact on bridges
+2. Create a new batch endpoint instead of following REST conventions with PUT/PATCH
+3. Restrict these endpoints to only AppServices, limiting potential use cases
+4. Wait for proprietary solutions to become more widespread, risking fragmentation