Skip to content

Commit f8f2b47

Browse files
tcpipuktcpipuk
committed
MSC4255 Initial commit
1 parent 03197ed commit f8f2b47

File tree

1 file changed

+180
-0
lines changed

1 file changed

+180
-0
lines changed

‎proposals/4255-bulk-profile-updates.md

+180
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# MSC0000: Bulk Profile Updates Per-User
2+
3+
This proposal builds upon [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133)
4+
(Extending User Profile API with Custom Key:Value Pairs) to introduce two additional endpoints to
5+
the Matrix Client-Server API that enable efficient bulk updates of user profiles. These endpoints
6+
are particularly valuable for bridge applications (AppServices) that need to manage profiles for
7+
many bridged users simultaneously.
8+
9+
## Problem Statement
10+
11+
When users interact with Matrix through bridges, they expect their profile information to stay
12+
consistent with the bridged platform. However, the current Matrix specification only provides
13+
single-field update endpoints, making it difficult for bridges to efficiently maintain this
14+
consistency at scale.
15+
16+
Currently, bridges must make individual API calls for each field they want to update in a user's
17+
profile. For instance, when a Discord user changes their avatar, username, and status
18+
simultaneously, the bridge must make three separate API calls to reflect these changes in Matrix.
19+
This becomes a significant bottleneck when managing thousands of bridged users, leading to delayed
20+
updates and increased server load.
21+
22+
Some commercial bridge providers, such as Beeper, have already implemented proprietary solutions
23+
for this problem. This proposal aims to standardise this functionality, allowing both commercial
24+
and self-hosted bridge deployments to benefit from similar, efficient client functionality.
25+
26+
## Current Specification
27+
28+
The Matrix specification currently defines a read-only endpoint for retrieving all profile fields:
29+
[`GET /_matrix/client/v3/profile/{userId}`](https://spec.matrix.org/v1.13/client-server-api/#get_matrixclientv3profileuserid).
30+
31+
However, there is no equivalent endpoint for updating multiple profile fields simultaneously.
32+
Instead, clients must use individual PUT requests for each field they want to update.
33+
34+
## Proposal
35+
36+
This MSC introduces two new endpoints that allow updating multiple profile fields in a single
37+
request:
38+
39+
### PUT Endpoint - Replace Profile
40+
41+
- **Endpoint**: `PUT /_matrix/client/v3/profile/{userId}`
42+
- **Description**: Replace the entire profile with the provided fields, removing any fields not
43+
included in the request.
44+
- **Rate Limiting**: Servers SHOULD apply appropriate rate limits based on their policies
45+
- **Authentication**: Requires valid access token with permission to modify the requested userId's
46+
profile
47+
- **Request Body**:
48+
49+
```json
50+
{
51+
"avatar_url": "mxc://matrix.org/MyNewAvatar",
52+
"displayname": "John Doe",
53+
"m.example_field": "new_value1",
54+
"org.example.job_title": "Software Engineer"
55+
}
56+
```
57+
58+
### PATCH Endpoint - Merge Profile Updates
59+
60+
- **Endpoint**: `PATCH /_matrix/client/v3/profile/{userId}`
61+
- **Description**: Merge the provided fields into the existing profile, only modifying specified
62+
fields.
63+
- **Rate Limiting**: Servers SHOULD apply appropriate rate limits based on their policies
64+
- **Authentication**: Requires valid access token with permission to modify the requested userId's
65+
profile
66+
- **Request Body**:
67+
68+
```json
69+
{
70+
"avatar_url": "mxc://matrix.org/MyNewAvatar",
71+
"m.example_field": "new_value1"
72+
}
73+
```
74+
75+
### Behaviour
76+
77+
- The `PUT` endpoint replaces the entire profile, removing any fields not included in the request
78+
- The `PATCH` endpoint only updates the fields provided, leaving other fields unchanged
79+
- Both endpoints MUST respect the same size limits as individual field updates (64 KiB total
80+
profile size)
81+
- Both endpoints MUST follow the same field naming requirements as individual updates
82+
- Authentication and permissions follow the same rules as individual field updates
83+
- Servers MUST process these requests atomically to prevent partial updates
84+
- Servers MUST validate all fields in the request before applying any changes
85+
86+
## Use Cases
87+
88+
### Bridge Profile Synchronisation
89+
90+
When bridging platforms that support rich profiles (such as Discord, Slack, or IRC services),
91+
bridges need to synchronise multiple profile fields simultaneously. For example:
92+
93+
1. Avatar URL changes
94+
2. Display name updates
95+
3. Custom status fields
96+
4. Platform-specific metadata (roles, badges, etc.)
97+
98+
Currently, each field requires a separate API call, which is inefficient when managing thousands of
99+
bridged users. These new endpoints allow bridges to update all relevant fields in a single request,
100+
reducing server load and improving synchronisation speed.
101+
102+
## Security Considerations
103+
104+
1. **Authentication and Authorization**
105+
- All requests MUST be authenticated
106+
- Servers MUST verify the access token has permission to modify the requested userId's profile
107+
- Rate limiting SHOULD be applied as per the homeserver's normal profile endpoint limits
108+
109+
2. **Data Validation**
110+
- Servers MUST validate all fields before applying any changes
111+
- The total profile size MUST NOT exceed 64 KiB
112+
- Field names MUST follow the [Common Namespaced Identifier Grammar](https://spec.matrix.org/v1.13/appendices/#common-namespaced-identifier-grammar)
113+
114+
3. **Atomic Updates**
115+
- Servers MUST ensure updates are atomic to prevent inconsistent profile states
116+
- If any field update fails validation, the entire request MUST be rejected
117+
118+
## Error Codes
119+
120+
All error codes from individual profile field updates apply, plus:
121+
122+
- **`M_LIMIT_EXCEEDED`**: Too many fields are updated at once (server-defined limit)
123+
124+
```json
125+
{
126+
"errcode": "M_LIMIT_EXCEEDED",
127+
"error": "Too many profile fields in request"
128+
}
129+
```
130+
131+
- **`M_BAD_JSON`**: Request body is malformed
132+
133+
```json
134+
{
135+
"errcode": "M_BAD_JSON",
136+
"error": "Request must be valid JSON"
137+
}
138+
```
139+
140+
- **`M_FORBIDDEN`**: User lacks permission for requested changes
141+
142+
```json
143+
{
144+
"errcode": "M_FORBIDDEN",
145+
"error": "You do not have permission to modify this profile"
146+
}
147+
```
148+
149+
- **`M_PROFILE_TOO_LARGE`**: Resulting profile would exceed 64 KiB
150+
151+
```json
152+
{
153+
"errcode": "M_PROFILE_TOO_LARGE",
154+
"error": "Profile exceeds maximum size of 64 KiB"
155+
}
156+
```
157+
158+
## Unstable Prefix
159+
160+
Until this proposal is stable, implementations SHOULD use these endpoints:
161+
162+
- `PUT /_matrix/client/unstable/uk.tcpip.msc5000/profile/{userId}`
163+
- `PATCH /_matrix/client/unstable/uk.tcpip.msc5000/profile/{userId}`
164+
165+
The client feature `uk.tcpip.msc5000` SHOULD be advertised on the `/versions` endpoint when these
166+
endpoints are supported.
167+
168+
## Relationship to Other MSCs
169+
170+
This proposal builds on [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133)
171+
which introduces extensible profiles. While [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133)
172+
focuses on the core functionality of custom profile fields, this MSC adds efficient bulk update
173+
capabilities specifically to support bridge use cases.
174+
175+
## Alternatives
176+
177+
1. Continue using individual field updates, accepting the performance impact on bridges
178+
2. Create a new batch endpoint instead of following REST conventions with PUT/PATCH
179+
3. Restrict these endpoints to only AppServices, limiting potential use cases
180+
4. Wait for proprietary solutions to become more widespread, risking fragmentation

0 commit comments

Comments
 (0)