Fetch MUC occupant avatars via occupant vCard (XEP-0045/XEP-0153) #7

Merged
skunky merged 1 commit from muc-occupant-avatars into main 2026-11-08 22:54:13 +00:00
Owner

Problem

Avatars of XMPP users never appeared on the Matrix side, while regular XMPP clients show them fine. In semi-anonymous MUCs the bridge ghosts have room-qualified IDs (room@service/nick), and GetUserInfo returned early with just the nick for those - no PEP, no vCard, no avatar was ever fetched.

Fix

Regular XMPP clients display occupant avatars by querying the vCard of room@service/<nick> and by reading the vcard-temp:x:update (XEP-0153) photo hash from occupant presence. The bridge now uses exactly the same two sources:

  • GetUserInfo: for occupant ghosts, fetch the vCard of the full occupant JID (room@service/nick) - the MUC service answers with the occupant real vCard. Nick stays the display name.
  • fetchRemoteAvatar: skip the PEP (XEP-0084) pubsub query for full JIDs - occupant JIDs have no PEP node, so it was a wasted IQ.
  • Occupant presence with an XEP-0153 photo hash now triggers a deduplicated, asynchronous ghost avatar refresh (maybeRefreshOccupantAvatar -> refreshOccupantGhost), so avatar changes propagate without waiting for the next message.
  • avatarIDFor: avatar IDs are now derived from a SHA-1 of the content instead of the byte length, so a changed avatar of the same size is still re-uploaded.
  • AGENTS.md: the old claim that avatars cannot work in semi-anonymous rooms was wrong and is replaced with the actual mechanism.

Tests

Unit tests for the occupant avatar path: cache hit delivery, negative caching on failure, XEP-0153 hash deduplication (nick- and real-JID ghosts), and skipping our own puppet occupants.

Verified with the existing fake-component-server reaction tests: outgoing Matrix reactions (XEP-0444) still send the correct stanza - reactions Matrix->XMPP are fully wired in main (see reactions_out_test.go), so if a deployment still shows no reactions, it is running a build from before #6.

## Problem Avatars of XMPP users never appeared on the Matrix side, while regular XMPP clients show them fine. In semi-anonymous MUCs the bridge ghosts have room-qualified IDs (`room@service/nick`), and `GetUserInfo` returned early with just the nick for those - no PEP, no vCard, no avatar was ever fetched. ## Fix Regular XMPP clients display occupant avatars by querying the vCard of `room@service/<nick>` and by reading the `vcard-temp:x:update` (XEP-0153) photo hash from occupant presence. The bridge now uses exactly the same two sources: - `GetUserInfo`: for occupant ghosts, fetch the vCard of the full occupant JID (`room@service/nick`) - the MUC service answers with the occupant real vCard. Nick stays the display name. - `fetchRemoteAvatar`: skip the PEP (XEP-0084) pubsub query for full JIDs - occupant JIDs have no PEP node, so it was a wasted IQ. - Occupant presence with an XEP-0153 photo hash now triggers a deduplicated, asynchronous ghost avatar refresh (`maybeRefreshOccupantAvatar` -> `refreshOccupantGhost`), so avatar changes propagate without waiting for the next message. - `avatarIDFor`: avatar IDs are now derived from a SHA-1 of the content instead of the byte length, so a changed avatar of the same size is still re-uploaded. - AGENTS.md: the old claim that avatars cannot work in semi-anonymous rooms was wrong and is replaced with the actual mechanism. ## Tests Unit tests for the occupant avatar path: cache hit delivery, negative caching on failure, XEP-0153 hash deduplication (nick- and real-JID ghosts), and skipping our own puppet occupants. Verified with the existing fake-component-server reaction tests: outgoing Matrix reactions (XEP-0444) still send the correct stanza - reactions Matrix->XMPP are fully wired in `main` (see `reactions_out_test.go`), so if a deployment still shows no reactions, it is running a build from before #6.
Fetch MUC occupant avatars via occupant vCard (XEP-0045/XEP-0153)
Some checks failed
CI / test (pull_request) Has been cancelled
ff6e956cfb
Semi-anonymous MUCs hide occupants' real JIDs, so ghost IDs are
room-qualified (<room>/<nick>) and GetUserInfo used to return only the
nick: no avatar was ever fetched, even though regular XMPP clients show
the same occupants' avatars. The MUC service answers vCard queries
addressed to <room JID>/<nick> with the occupant's real vCard - the
same lookup regular clients perform.

- GetUserInfo: fetch the occupant vCard avatar for room-qualified ghost
  IDs instead of returning early with just the nick.
- fetchRemoteAvatar: skip the PEP (XEP-0084) pubsub query for full JIDs;
  occupant JIDs have no PEP node.
- Occupant presence with vcard-temp❌update (XEP-0153) now triggers a
  deduplicated asynchronous ghost avatar refresh when the advertised
  photo hash is new or changed.
- avatarIDFor: derive the avatar ID from a SHA-1 of the content instead
  of the byte length, so changed avatars of equal size still re-upload.

Update AGENTS.md: the old claim that avatars cannot work in
semi-anonymous rooms was wrong - regular clients prove otherwise.

Add unit tests for the occupant avatar path (cache hit, negative
caching, hash dedup, puppet skip).
skunky merged commit 70bc1c65d0 into main 2026-11-08 22:54:13 +00:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
xmpp-bridge/mautrix-xmpp!7
No description provided.