########################################################################
# File name: service.py
# This file is part of: aioxmpp
#
# LICENSE
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this program. If not, see
# <http://www.gnu.org/licenses/>.
#
########################################################################
import asyncio
import aioxmpp
import aioxmpp.callbacks as callbacks
import aioxmpp.service as service
import aioxmpp.private_xml as private_xml
from . import xso as bookmark_xso
# TODO: use private storage in pubsub where available.
# TODO: sync bookmarks between pubsub and private xml storage
# TODO: do we need merge-capabilities to reconcile the bookmarks
# from different sources (local bookmark storage, pubsub, private xml
# storage)
[docs]class BookmarkClient(service.Service):
"""
Supports retrieval and storage of bookmarks on the server.
It currently only supports :xep:`Private XML Storage <49>` as
backend.
There is the general rule *never* to modify the bookmark instances
retrieved from this class (either by :meth:`get_bookmarks` or as
an argument to one of the signals). If you need to modify a bookmark
for use with :meth:`update_bookmark` use :func:`copy.copy` to create
a copy.
.. automethod:: sync
.. automethod:: get_bookmarks
.. automethod:: set_bookmarks
The following methods change the bookmark list in a get-modify-set
pattern, to mitigate the danger of race conditions and should be
used in most circumstances:
.. automethod:: add_bookmark
.. automethod:: discard_bookmark
.. automethod:: update_bookmark
The following signals are provided that allow tracking the changes to
the bookmark list:
.. signal:: on_bookmark_added(added_bookmark)
Fires when a new bookmark is added.
.. signal:: on_bookmark_removed(removed_bookmark)
Fires when a bookmark is removed.
.. signal:: on_bookmark_changed(old_bookmark, new_bookmark)
Fires when a bookmark is changed.
.. note:: A heuristic is used to determine the change of bookmarks
and the reported changes may not directly reflect the
used methods, but it will always be possible to
construct the list of bookmarks from the events. For
example, when using :meth:`update_bookmark` to change
the JID of a :class:`Conference` bookmark a removed and
a added signal will fire.
.. note:: The bookmark protocol is prone to race conditions if
several clients access it concurrently. Be careful to
use a get-modify-set pattern or the provided highlevel
interface.
.. note:: Some other clients extend the bookmark format. For now
those extensions are silently dropped by our XSOs, and
therefore are lost, when changing the bookmarks with
aioxmpp. This is considered a bug to be fixed in the future.
"""
ORDER_AFTER = [
private_xml.PrivateXMLService,
]
on_bookmark_added = callbacks.Signal()
on_bookmark_removed = callbacks.Signal()
on_bookmark_changed = callbacks.Signal()
def __init__(self, client, **kwargs):
super().__init__(client, **kwargs)
self._private_xml = self.dependencies[private_xml.PrivateXMLService]
self._bookmark_cache = []
self._lock = asyncio.Lock()
@service.depsignal(aioxmpp.Client, "on_stream_established", defer=True)
async def _stream_established(self):
await self.sync()
async def _get_bookmarks(self):
"""
Get the stored bookmarks from the server.
:returns: a list of bookmarks
"""
res = await self._private_xml.get_private_xml(
bookmark_xso.Storage()
)
return res.registered_payload.bookmarks
async def _set_bookmarks(self, bookmarks):
"""
Set the bookmarks stored on the server.
"""
storage = bookmark_xso.Storage()
storage.bookmarks[:] = bookmarks
await self._private_xml.set_private_xml(storage)
def _diff_emit_update(self, new_bookmarks):
"""
Diff the bookmark cache and the new bookmark state, emit signals as
needed and set the bookmark cache to the new data.
"""
self.logger.debug("diffing %s, %s", self._bookmark_cache,
new_bookmarks)
def subdivide(level, old, new):
"""
Subdivide the bookmarks according to the data item
``bookmark.secondary[level]`` and emit the appropriate
events.
"""
if len(old) == len(new) == 1:
old_entry = old.pop()
new_entry = new.pop()
if old_entry == new_entry:
pass
else:
self.on_bookmark_changed(old_entry, new_entry)
return ([], [])
elif len(old) == 0:
return ([], new)
elif len(new) == 0:
return (old, [])
else:
try:
groups = {}
for entry in old:
group = groups.setdefault(
entry.secondary[level],
([], [])
)
group[0].append(entry)
for entry in new:
group = groups.setdefault(
entry.secondary[level],
([], [])
)
group[1].append(entry)
except IndexError:
# the classification is exhausted, this means
# all entries in this bin are equal by the
# defininition of bookmark equivalence!
common = min(len(old), len(new))
assert old[:common] == new[:common]
return (old[common:], new[common:])
old_unhandled, new_unhandled = [], []
for old, new in groups.values():
unhandled = subdivide(level+1, old, new)
old_unhandled += unhandled[0]
new_unhandled += unhandled[1]
# match up unhandleds as changes as early as possible
i = -1
for i, (old_entry, new_entry) in enumerate(
zip(old_unhandled, new_unhandled)):
self.logger.debug("changed %s -> %s", old_entry, new_entry)
self.on_bookmark_changed(old_entry, new_entry)
i += 1
return old_unhandled[i:], new_unhandled[i:]
# group the bookmarks into groups whose elements may transform
# among one another by on_bookmark_changed events. This information
# is given by the type of the bookmark and the .primary property
changable_groups = {}
for item in self._bookmark_cache:
group = changable_groups.setdefault(
(type(item), item.primary),
([], [])
)
group[0].append(item)
for item in new_bookmarks:
group = changable_groups.setdefault(
(type(item), item.primary),
([], [])
)
group[1].append(item)
for old, new in changable_groups.values():
# the first branches are fast paths which should catch
# most cases – especially all cases where each bare jid of
# a conference bookmark or each url of an url bookmark is
# only used in one bookmark
if len(old) == len(new) == 1:
old_entry = old.pop()
new_entry = new.pop()
if old_entry == new_entry:
# the bookmark is unchanged, do not emit an event
pass
else:
self.logger.debug("changed %s -> %s", old_entry, new_entry)
self.on_bookmark_changed(old_entry, new_entry)
elif len(new) == 0:
for removed in old:
self.logger.debug("removed %s", removed)
self.on_bookmark_removed(removed)
elif len(old) == 0:
for added in new:
self.logger.debug("added %s", added)
self.on_bookmark_added(added)
else:
old, new = subdivide(0, old, new)
assert len(old) == 0 or len(new) == 0
for removed in old:
self.logger.debug("removed %s", removed)
self.on_bookmark_removed(removed)
for added in new:
self.logger.debug("added %s", added)
self.on_bookmark_added(added)
self._bookmark_cache = new_bookmarks
[docs] async def get_bookmarks(self):
"""
Get the stored bookmarks from the server. Causes signals to be
fired to reflect the changes.
:returns: a list of bookmarks
"""
async with self._lock:
bookmarks = await self._get_bookmarks()
self._diff_emit_update(bookmarks)
return bookmarks
[docs] async def set_bookmarks(self, bookmarks):
"""
Store the sequence of bookmarks `bookmarks`.
Causes signals to be fired to reflect the changes.
.. note:: This should normally not be used. It does not
mitigate the race condition between clients
concurrently modifying the bookmarks and may lead to
data loss. Use :meth:`add_bookmark`,
:meth:`discard_bookmark` and :meth:`update_bookmark`
instead. This method still has use-cases (modifying
the bookmarklist at large, e.g. by syncing the
remote store with local data).
"""
async with self._lock:
await self._set_bookmarks(bookmarks)
self._diff_emit_update(bookmarks)
[docs] async def sync(self):
"""
Sync the bookmarks between the local representation and the
server.
This must be called periodically to assure that the signals
are fired.
"""
await self.get_bookmarks()
[docs] async def add_bookmark(self, new_bookmark, *, max_retries=3):
"""
Add a bookmark and check whether it was successfully added to the
bookmark list. Already existant bookmarks are not added twice.
:param new_bookmark: the bookmark to add
:type new_bookmark: an instance of :class:`~bookmark_xso.Bookmark`
:param max_retries: the number of retries if setting the bookmark
fails
:type max_retries: :class:`int`
:raises RuntimeError: if the bookmark is not in the bookmark list
after `max_retries` retries.
After setting the bookmark it is checked, whether the bookmark
is in the online storage, if it is not it is tried again at most
`max_retries` times to add the bookmark. A :class:`RuntimeError`
is raised if the bookmark could not be added successfully after
`max_retries`.
"""
async with self._lock:
bookmarks = await self._get_bookmarks()
try:
modified_bookmarks = list(bookmarks)
if new_bookmark not in bookmarks:
modified_bookmarks.append(new_bookmark)
await self._set_bookmarks(modified_bookmarks)
retries = 0
bookmarks = await self._get_bookmarks()
while retries < max_retries:
if new_bookmark in bookmarks:
break
modified_bookmarks = list(bookmarks)
modified_bookmarks.append(new_bookmark)
await self._set_bookmarks(modified_bookmarks)
bookmarks = await self._get_bookmarks()
retries += 1
if new_bookmark not in bookmarks:
raise RuntimeError("Could not add bookmark")
finally:
self._diff_emit_update(bookmarks)
[docs] async def discard_bookmark(self, bookmark_to_remove, *, max_retries=3):
"""
Remove a bookmark and check it has been removed.
:param bookmark_to_remove: the bookmark to remove
:type bookmark_to_remove: a :class:`~bookmark_xso.Bookmark` subclass.
:param max_retries: the number of retries of removing the bookmark
fails.
:type max_retries: :class:`int`
:raises RuntimeError: if the bookmark is not removed from
bookmark list after `max_retries`
retries.
If there are multiple occurences of the same bookmark exactly
one is removed.
This does nothing if the bookmarks does not match an existing
bookmark according to bookmark-equality.
After setting the bookmark it is checked, whether the bookmark
is removed in the online storage, if it is not it is tried
again at most `max_retries` times to remove the bookmark. A
:class:`RuntimeError` is raised if the bookmark could not be
removed successfully after `max_retries`.
"""
async with self._lock:
bookmarks = await self._get_bookmarks()
occurences = bookmarks.count(bookmark_to_remove)
try:
if not occurences:
return
modified_bookmarks = list(bookmarks)
modified_bookmarks.remove(bookmark_to_remove)
await self._set_bookmarks(modified_bookmarks)
retries = 0
bookmarks = await self._get_bookmarks()
new_occurences = bookmarks.count(bookmark_to_remove)
while retries < max_retries:
if new_occurences < occurences:
break
modified_bookmarks = list(bookmarks)
modified_bookmarks.remove(bookmark_to_remove)
await self._set_bookmarks(modified_bookmarks)
bookmarks = await self._get_bookmarks()
new_occurences = bookmarks.count(bookmark_to_remove)
retries += 1
if new_occurences >= occurences:
raise RuntimeError("Could not remove bookmark")
finally:
self._diff_emit_update(bookmarks)
[docs] async def update_bookmark(self, old, new, *, max_retries=3):
"""
Update a bookmark and check it was successful.
The bookmark matches an existing bookmark `old` according to
bookmark equalitiy and replaces it by `new`. The bookmark
`new` is added if no bookmark matching `old` exists.
:param old: the bookmark to replace
:type bookmark_to_remove: a :class:`~bookmark_xso.Bookmark` subclass.
:param new: the replacement bookmark
:type bookmark_to_remove: a :class:`~bookmark_xso.Bookmark` subclass.
:param max_retries: the number of retries of removing the bookmark
fails.
:type max_retries: :class:`int`
:raises RuntimeError: if the bookmark is not in the bookmark list
after `max_retries` retries.
After replacing the bookmark it is checked, whether the
bookmark `new` is in the online storage, if it is not it is
tried again at most `max_retries` times to replace the
bookmark. A :class:`RuntimeError` is raised if the bookmark
could not be replaced successfully after `max_retries`.
.. note:: Do not modify a bookmark retrieved from the signals
or from :meth:`get_bookmarks` to obtain the bookmark
`new`, this will lead to data corruption as they are
passed by reference. Instead use :func:`copy.copy`
and modify the copy.
"""
def replace_bookmark(bookmarks, old, new):
modified_bookmarks = list(bookmarks)
try:
i = bookmarks.index(old)
modified_bookmarks[i] = new
except ValueError:
modified_bookmarks.append(new)
return modified_bookmarks
async with self._lock:
bookmarks = await self._get_bookmarks()
try:
await self._set_bookmarks(
replace_bookmark(bookmarks, old, new)
)
retries = 0
bookmarks = await self._get_bookmarks()
while retries < max_retries:
if new in bookmarks:
break
await self._set_bookmarks(
replace_bookmark(bookmarks, old, new)
)
bookmarks = await self._get_bookmarks()
retries += 1
if new not in bookmarks:
raise RuntimeError("Cold not update bookmark")
finally:
self._diff_emit_update(bookmarks)