class AvatarService(service.Service): """ Access and publish User Avatars (:xep:`84`). Fallback to vCard based avatars (:xep:`153`) if no PEP avatar is available. This service provides an interface for accessing the avatar of other entities in the network, getting notifications on avatar changes and publishing an avatar for this entity. .. versionchanged:: 0.10 Support for :xep:`vCard-Based Avatars <153>` was added. Observing avatars: .. note:: :class:`AvatarService` only caches the metadata, not the actual image data. This is the job of the caller. .. signal:: on_metadata_changed(jid, metadata) Fires when avatar metadata changes. :param jid: The JID which the avatar belongs to. :param metadata: The new metadata descriptors. :type metadata: a sequence of :class:`~aioxmpp.avatar.service.AbstractAvatarDescriptor` instances .. automethod:: get_avatar_metadata .. automethod:: subscribe Publishing avatars: .. automethod:: publish_avatar_set .. automethod:: disable_avatar .. automethod:: wipe_avatar Configuration: .. autoattribute:: synchronize_vcard .. autoattribute:: advertise_vcard .. attribute:: avatar_pep The PEP descriptor for claiming the avatar metadata namespace. The value is a :class:`~aioxmpp.pep.service.RegisteredPEPNode`, whose :attr:`~aioxmpp.pep.service.RegisteredPEPNode.notify` property can be used to disable or enable the notification feature. .. autoattribute:: metadata_cache_size :annotation: = 200 """ ORDER_AFTER = [ disco.DiscoClient, disco.DiscoServer, pubsub.PubSubClient, pep.PEPClient, vcard.VCardService, presence.PresenceClient, presence.PresenceServer, ] avatar_pep = pep.register_pep_node( namespaces.xep0084_metadata, notify=True, ) on_metadata_changed = callbacks.Signal() def __init__(self, client, **kwargs): super().__init__(client, **kwargs) self._has_pep_avatar = set() self._metadata_cache = LRUDict() self._metadata_cache.maxsize = 200 self._pubsub = self.dependencies[pubsub.PubSubClient] self._pep = self.dependencies[pep.PEPClient] self._presence_server = self.dependencies[presence.PresenceServer] self._disco = self.dependencies[disco.DiscoClient] self._vcard = self.dependencies[vcard.VCardService] # we use this lock to prevent race conditions between different # calls of the methods by one client. # XXX: Other, independent clients may still cause inconsistent # data by race conditions, this should be fixed by at least # checking for consistent data after an update. self._publish_lock = asyncio.Lock() self._synchronize_vcard = False self._advertise_vcard = True self._vcard_resource_interference = set() self._vcard_id = None self._vcard_rehashing_for = None self._vcard_rehash_task = None @property def metadata_cache_size(self): """ Maximum number of cache entries in the avatar metadata cache. This is mostly a measure to prevent malicious peers from exhausting memory by spamming vCard based avatar metadata for different resources. .. versionadded:: 0.10 """ return self._metadata_cache.maxsize @metadata_cache_size.setter def metadata_cache_size(self, value): self._metadata_cache.maxsize = value @property def synchronize_vcard(self): """ Set this property to true to enable publishing the a vCard avatar. This property defaults to false. For the setting true to have effect, you have to publish your avatar with :meth:`publish_avatar_set` or :meth:`disable_avatar` *after* this switch has been set to true. """ return self._synchronize_vcard @synchronize_vcard.setter def synchronize_vcard(self, value): self._synchronize_vcard = bool(value) @property def advertise_vcard(self): """ Set this property to false to disable advertisement of the vCard avatar via presence broadcast. Note, that this reduces traffic, since it makes the presence stanzas smaller and we no longer have to recalculate the hash, this also disables vCard advertisement for all other ressources of the bare local jid, by the business rules of :xep:`0153`. Note that, when enabling this feature again the vCard has to be fetched from the server to recalculate the hash. """ return self._advertise_vcard @advertise_vcard.setter def advertise_vcard(self, value): self._advertise_vcard = bool(value) if self._advertise_vcard: self._vcard_id = None self._start_rehash_task() @service.depfilter(aioxmpp.stream.StanzaStream, "service_outbound_presence_filter") def _attach_vcard_notify_to_presence(self, stanza): if self._advertise_vcard: if self._vcard_resource_interference: # do not advertise the hash if there is resource interference stanza.xep0153_x = avatar_xso.VCardTempUpdate() else: stanza.xep0153_x = avatar_xso.VCardTempUpdate(self._vcard_id) return stanza def _update_metadata(self, cache_jid, metadata): try: cached_metadata = self._metadata_cache[cache_jid] except KeyError: pass else: if cached_metadata == metadata: return self._metadata_cache[cache_jid] = metadata self.on_metadata_changed(cache_jid, metadata) def _handle_notify(self, full_jid, stanza): # handle resource interference as per XEP-153 business rules, # we go along with this tracking even if vcard advertisement # is off if (full_jid.bare() == self.client.local_jid.bare() and full_jid != self.client.local_jid): if stanza.xep0153_x is None: self._vcard_resource_interference.add(full_jid) else: if self._vcard_resource_interference: self._vcard_resource_interference.discard(full_jid) if not self._vcard_resource_interference: self._vcard_id = None # otherwise ignore stanzas without xep0153_x payload, or # no photo tag. if stanza.xep0153_x is None: return if stanza.xep0153_x.photo is None: return # special case MUC presence – otherwise the vcard is retrieved # for the bare jid if stanza.xep0045_muc_user is not None: cache_jid = full_jid else: cache_jid = full_jid.bare() if cache_jid not in self._has_pep_avatar: metadata = self._cook_vcard_notify(cache_jid, stanza) self._update_metadata(cache_jid, metadata) # trigger the download of the vCard and calculation of the # vCard avatar hash, if some other resource of our bare jid # reported a hash distinct from ours! # don't do this if there is a non-compliant resource, we don't # send the hash in that case anyway if (full_jid.bare() == self.client.local_jid.bare() and full_jid != self.client.local_jid and self._advertise_vcard and not self._vcard_resource_interference): if (self._vcard_id is None or stanza.xep0153_x.photo.lower() != self._vcard_id.lower()): # do not rehash if we alread have a rehash task that # was triggered by an update with the same hash if (self._vcard_rehashing_for is None or self._vcard_rehashing_for != stanza.xep0153_x.photo.lower()): self._vcard_rehashing_for = stanza.xep0153_x.photo.lower() self._start_rehash_task() def _start_rehash_task(self): if self._vcard_rehash_task is not None: self._vcard_rehash_task.cancel() self._vcard_id = None # as per XEP immediately resend the presence with empty update # element, as this is not synchronous it might already contaiin # the new hash, but this is okay as well (as it makes the cached # presence stanzas coherent as well). self._presence_server.resend_presence() self._vcard_rehash_task = asyncio.ensure_future( self._calculate_vcard_id()) def set_new_vcard_id(fut): self._vcard_rehashing_for = None if not fut.cancelled(): self._vcard_id = fut.result() self._vcard_rehash_task.add_done_callback(set_new_vcard_id) async def _calculate_vcard_id(self): self.logger.debug("updating vcard hash") vcard = await self._vcard.get_vcard() self.logger.debug("got vcard for hash update: %s", vcard) photo = vcard.get_photo_data() # if no photo is set in the vcard, set an empty <photo> element # in the update; according to the spec this means the avatar # is disabled if photo is None: self.logger.debug("no photo in vcard, advertising as such") return "" sha1 = hashlib.sha1() sha1.update(photo) new_hash = sha1.hexdigest().lower() self.logger.debug("updated hash to %s", new_hash) return new_hash @service.depsignal(presence.PresenceClient, "on_available") def _handle_on_available(self, full_jid, stanza): self._handle_notify(full_jid, stanza) @service.depsignal(presence.PresenceClient, "on_changed") def _handle_on_changed(self, full_jid, stanza): self._handle_notify(full_jid, stanza) @service.depsignal(presence.PresenceClient, "on_unavailable") def _handle_on_unavailable(self, full_jid, stanza): if full_jid.bare() == self.client.local_jid.bare(): if self._vcard_resource_interference: self._vcard_resource_interference.discard(full_jid) if not self._vcard_resource_interference: self._start_rehash_task() # correctly handle MUC avatars if stanza.xep0045_muc_user is not None: self._metadata_cache.pop(full_jid, None) def _cook_vcard_notify(self, jid, stanza): result = [] # note: an empty photo element correctly # results in an empty avatar metadata list if stanza.xep0153_x.photo: result.append( VCardAvatarDescriptor( remote_jid=jid, id_=stanza.xep0153_x.photo, mime_type=None, vcard=self._vcard, nbytes=None, )) return result def _cook_metadata(self, jid, items): def iter_metadata_info_nodes(items): for item in items: yield from item.registered_payload.iter_info_nodes() result = [] for info_node in iter_metadata_info_nodes(items): if info_node.url is not None: descriptor = HttpAvatarDescriptor( remote_jid=jid, id_=info_node.id_, mime_type=info_node.mime_type, nbytes=info_node.nbytes, width=info_node.width, height=info_node.height, url=info_node.url, ) else: descriptor = PubsubAvatarDescriptor( remote_jid=jid, id_=info_node.id_, mime_type=info_node.mime_type, nbytes=info_node.nbytes, width=info_node.width, height=info_node.height, pubsub=self._pubsub, ) result.append(descriptor) return result @service.attrsignal(avatar_pep, "on_item_publish") def _handle_pubsub_publish(self, jid, node, item, *, message=None): # update the metadata cache metadata = self._cook_metadata(jid, [item]) self._has_pep_avatar.add(jid) self._update_metadata(jid, metadata) async def _get_avatar_metadata_vcard(self, jid): logger.debug("trying vCard avatar as fallback for %s", jid) vcard = await self._vcard.get_vcard(jid) photo = vcard.get_photo_data() mime_type = vcard.get_photo_mime_type() if photo is None: return [] logger.debug("success vCard avatar as fallback for %s", jid) sha1 = hashlib.sha1() sha1.update(photo) return [ VCardAvatarDescriptor( remote_jid=jid, id_=sha1.hexdigest(), mime_type=mime_type, nbytes=len(photo), vcard=self._vcard, image_bytes=photo, ) ] async def _get_avatar_metadata_pep(self, jid): try: metadata_raw = await self._pubsub.get_items( jid, namespaces.xep0084_metadata, max_items=1) except aioxmpp.XMPPCancelError as e: # transparently map feature-not-implemented and # item-not-found to be equivalent unset avatar if e.condition in (aioxmpp.ErrorCondition.FEATURE_NOT_IMPLEMENTED, aioxmpp.ErrorCondition.ITEM_NOT_FOUND): return [] raise self._has_pep_avatar.add(jid) return self._cook_metadata(jid, metadata_raw.payload.items) async def get_avatar_metadata(self, jid, *, require_fresh=False, disable_pep=False): """ Retrieve a list of avatar descriptors. :param jid: the JID for which to retrieve the avatar metadata. :type jid: :class:`aioxmpp.JID` :param require_fresh: if true, do not return results from the avatar metadata chache, but retrieve them again from the server. :type require_fresh: :class:`bool` :param disable_pep: if true, do not try to retrieve the avatar via pep, only try the vCard fallback. This usually only useful when querying avatars via MUC, where the PEP request would be invalid (since it would be for a full jid). :type disable_pep: :class:`bool` :returns: an iterable of avatar descriptors. :rtype: a :class:`list` of :class:`~aioxmpp.avatar.service.AbstractAvatarDescriptor` instances Returning an empty list means that the avatar not set. We mask a :class:`XMPPCancelError` in the case that it is ``feature-not-implemented`` or ``item-not-found`` and return an empty list of avatar descriptors, since this is semantically equivalent to not having an avatar. .. note:: It is usually an error to get the avatar for a full jid, normally, the avatar is set for the bare jid of a user. The exception are vCard avatars over MUC, where the IQ requests for the vCard may be translated by the MUC server. It is recommended to use the `disable_pep` option in that case. """ if require_fresh: self._metadata_cache.pop(jid, None) else: try: return self._metadata_cache[jid] except KeyError: pass if disable_pep: metadata = [] else: metadata = await self._get_avatar_metadata_pep(jid) # try the vcard fallback, note: we don't try this # if the PEP avatar is disabled! if not metadata and jid not in self._has_pep_avatar: metadata = await self._get_avatar_metadata_vcard(jid) # if a notify was fired while we waited for the results, then # use the version in the cache, this will mitigate the race # condition because if our version is actually newer we will # soon get another notify for this version change! if jid not in self._metadata_cache: self._update_metadata(jid, metadata) return self._metadata_cache[jid] async def subscribe(self, jid): """ Explicitly subscribe to metadata change notifications for `jid`. """ await self._pubsub.subscribe(jid, namespaces.xep0084_metadata) @aioxmpp.service.depsignal(aioxmpp.stream.StanzaStream, "on_stream_destroyed") def handle_stream_destroyed(self, reason): self._metadata_cache.clear() self._vcard_resource_interference.clear() self._has_pep_avatar.clear() async def publish_avatar_set(self, avatar_set): """ Make `avatar_set` the current avatar of the jid associated with this connection. If :attr:`synchronize_vcard` is true and PEP is available the vCard is only synchronized if the PEP update is successful. This means publishing the ``image/png`` avatar data and the avatar metadata set in pubsub. The `avatar_set` must be an instance of :class:`AvatarSet`. If :attr:`synchronize_vcard` is true the avatar is additionally published in the user vCard. """ id_ = avatar_set.png_id done = False async with self._publish_lock: if await self._pep.available(): await self._pep.publish(namespaces.xep0084_data, avatar_xso.Data( avatar_set.image_bytes), id_=id_) await self._pep.publish(namespaces.xep0084_metadata, avatar_set.metadata, id_=id_) done = True if self._synchronize_vcard: my_vcard = await self._vcard.get_vcard() my_vcard.set_photo_data("image/png", avatar_set.image_bytes) self._vcard_id = avatar_set.png_id await self._vcard.set_vcard(my_vcard) self._presence_server.resend_presence() done = True if not done: raise RuntimeError( "failed to publish avatar: no protocol available") async def _disable_vcard_avatar(self): my_vcard = await self._vcard.get_vcard() my_vcard.clear_photo_data() self._vcard_id = "" await self._vcard.set_vcard(my_vcard) self._presence_server.resend_presence() async def disable_avatar(self): """ Temporarily disable the avatar. If :attr:`synchronize_vcard` is true, the vCard avatar is disabled (even if disabling the PEP avatar fails). This is done by setting the avatar metadata node empty and if :attr:`synchronize_vcard` is true, downloading the vCard, removing the avatar data and re-uploading the vCard. This method does not error if neither protocol is active. :raises aioxmpp.errors.GatherError: if an exception is raised by the spawned tasks. """ async with self._publish_lock: todo = [] if self._synchronize_vcard: todo.append(self._disable_vcard_avatar()) if await self._pep.available(): todo.append( self._pep.publish(namespaces.xep0084_metadata, avatar_xso.Metadata())) await gather_reraise_multi(*todo, message="disable_avatar") async def wipe_avatar(self): """ Remove all avatar data stored on the server. If :attr:`synchronize_vcard` is true, the vCard avatar is disabled even if disabling the PEP avatar fails. This is equivalent to :meth:`disable_avatar` for vCard-based avatars, but will also remove the data PubSub node for PEP avatars. This method does not error if neither protocol is active. :raises aioxmpp.errors.GatherError: if an exception is raised by the spawned tasks. """ async def _wipe_pep_avatar(): await self._pep.publish(namespaces.xep0084_metadata, avatar_xso.Metadata()) await self._pep.publish(namespaces.xep0084_data, avatar_xso.Data(b'')) async with self._publish_lock: todo = [] if self._synchronize_vcard: todo.append(self._disable_vcard_avatar()) if await self._pep.available(): todo.append(_wipe_pep_avatar()) await gather_reraise_multi(*todo, message="wipe_avatar")
class AvatarService(service.Service): """ Access and publish User Avatars (:xep:`84`). This service provides an interface for accessing the avatar of other entities in the network, getting notifications on avatar changes and publishing an avatar for this entity. Observing avatars: .. note:: :class:`AvatarService` only caches the metadata, not the actual image data. This is the job of the caller. .. signal:: on_metadata_changed(jid, metadata) Fires when avatar metadata changes. :param jid: The JID which the avatar belongs to. :param metadata: The new metadata descriptors. :type metadata: a sequence of :class:`~aioxmpp.avatar.service.AbstractAvatarDescriptor` instances .. automethod:: get_avatar_metadata .. automethod:: subscribe Publishing avatars: .. automethod:: publish_avatar_set .. automethod:: disable_avatar """ ORDER_AFTER = [ disco.DiscoClient, disco.DiscoServer, pubsub.PubSubClient, pep.PEPClient, ] avatar_pep = pep.register_pep_node( namespaces.xep0084_metadata, notify=True, ) on_metadata_changed = callbacks.Signal() def __init__(self, client, **kwargs): super().__init__(client, **kwargs) self._has_pep = None self._metadata_cache = {} self._pubsub = self.dependencies[pubsub.PubSubClient] self._notify_lock = asyncio.Lock() self._disco = self.dependencies[disco.DiscoClient] # we use this lock to prevent race conditions between different # calls of the methods by one client. # XXX: Other, independent clients may still cause inconsistent # data by race conditions, this should be fixed by at least # checking for consistent data after an update. self._publish_lock = asyncio.Lock() def _cook_metadata(self, jid, items): def iter_metadata_info_nodes(items): for item in items: yield from item.registered_payload.iter_info_nodes() result = collections.defaultdict(lambda: []) for info_node in iter_metadata_info_nodes(items): if info_node.url is not None: descriptor = HttpAvatarDescriptor( remote_jid=jid, mime_type=info_node.mime_type, id_=info_node.id_, nbytes=info_node.nbytes, width=info_node.width, height=info_node.height, url=info_node.url, ) else: descriptor = PubsubAvatarDescriptor( remote_jid=jid, mime_type=info_node.mime_type, id_=info_node.id_, nbytes=info_node.nbytes, width=info_node.width, height=info_node.height, pubsub=self._pubsub, ) result[info_node.mime_type].append(descriptor) return result @service.attrsignal(avatar_pep, "on_item_publish") def handle_pubsub_publish(self, jid, node, item, *, message=None): # update the metadata cache metadata = self._cook_metadata(jid, [item]) self._metadata_cache[jid] = metadata self.on_metadata_changed(jid, metadata) @asyncio.coroutine def get_avatar_metadata(self, jid, *, require_fresh=False): """ Retrieve a list of avatar descriptors for `jid`. The avatar descriptors are returned as a list of instances of :class:`~aioxmpp.avatar.service.AbstractAvatarDescriptor`. An empty list means that the avatar is unset. If `require_fresh` is true, we will not lookup the avatar metadata from the cache, but make a new pubsub request. We mask a :class:`XMPPCancelError` in the case that it is ``feature-not-implemented`` or ``item-not-found`` and return an empty list of avatar descriptors, since this is semantically equivalent to not having an avatar. """ if not require_fresh: try: return self._metadata_cache[jid] except KeyError: pass with (yield from self._notify_lock): if jid in self._metadata_cache: if require_fresh: del self._metadata_cache[jid] else: return self._metadata_cache[jid] try: metadata_raw = yield from self._pubsub.get_items( jid, namespaces.xep0084_metadata, max_items=1) except aioxmpp.XMPPCancelError as e: # transparently map feature-not-implemente and # item-not-found to be equivalent unset avatar if e.condition in ((namespaces.stanzas, "feature-not-implemented"), (namespaces.stanzas, "item-not-found")): metadata = collections.defaultdict(lambda: []) else: raise else: metadata = self._cook_metadata(jid, metadata_raw.payload.items) self._metadata_cache[jid] = metadata return metadata @asyncio.coroutine def subscribe(self, jid): """ Explicitly subscribe to metadata change notifications for `jid`. """ yield from self._pubsub.subscribe(jid, namespaces.xep0084_metadata) @asyncio.coroutine def _check_for_pep(self): # determine support for PEP as specified in XEP-0163 section 6 # XXX: fix this by implementing a PEPService that is derived from # pubsub and checks for the server capability and simplifies the # handling def raise_exception(): raise NotImplementedError( "Server does not support PEP and we do not support " "surrogating for lack of PEP support") if self._has_pep is not None: if self._has_pep: return else: raise_exception() disco_info = yield from self._disco.query_info( self.client.local_jid.bare()) for item in disco_info.identities.filter(attrs={"category": "pubsub"}): if item.type_ == "pep": self._has_pep = True break else: self._has_pep = False raise_exception() @aioxmpp.service.depsignal(aioxmpp.stream.StanzaStream, "on_stream_destroyed") def handle_stream_destroyed(self, reason): # invalidate the cache self._has_pep = None @asyncio.coroutine def publish_avatar_set(self, avatar_set): """ Make `avatar_set` the current avatar of the jid associated with this connection. This means publishing the ``image/png`` avatar data and the avatar metadata set in pubsub. The `avatar_set` must be an instance of :class:`AvatarSet`. """ yield from self._check_for_pep() id_ = avatar_set.png_id with (yield from self._publish_lock): yield from self._pubsub.publish(None, namespaces.xep0084_data, avatar_xso.Data( avatar_set.image_bytes), id_=id_) yield from self._pubsub.publish(None, namespaces.xep0084_metadata, avatar_set.metadata, id_=id_) @asyncio.coroutine def disable_avatar(self): """ Temporarily disable the avatar. This is done by setting the avatar metadata node empty. """ yield from self._check_for_pep() with (yield from self._publish_lock): yield from self._pubsub.publish(None, namespaces.xep0084_metadata, avatar_xso.Metadata())