sleekxmpp/plugins/xep_0030/static.py

   1 """
   2     SleekXMPP: The Sleek XMPP Library
   3     Copyright (C) 2010 Nathanael C. Fritz, Lance J.T. Stout
   4     This file is part of SleekXMPP.
   5
   6     See the file LICENSE for copying permission.
   7 """
   8
   9 import logging
  10 import threading
  11
  12 from sleekxmpp import Iq
  13 from sleekxmpp.exceptions import XMPPError, IqError, IqTimeout
  14 from sleekxmpp.xmlstream import JID
  15 from sleekxmpp.plugins.xep_0030 import DiscoInfo, DiscoItems
  16
  17
  18 log = logging.getLogger(__name__)
  19
  20
  21 class StaticDisco(object):
  22
  23     """
  24     While components will likely require fully dynamic handling
  25     of service discovery information, most clients and simple bots
  26     only need to manage a few disco nodes that will remain mostly
  27     static.
  28
  29     StaticDisco provides a set of node handlers that will store
  30     static sets of disco info and items in memory.
  31
  32     Attributes:
  33         nodes -- A dictionary mapping (JID, node) tuples to a dict
  34                  containing a disco#info and a disco#items stanza.
  35         xmpp  -- The main SleekXMPP object.
  36     """
  37
  38     def __init__(self, xmpp, disco):
  39         """
  40         Create a static disco interface. Sets of disco#info and
  41         disco#items are maintained for every given JID and node
  42         combination. These stanzas are used to store disco
  43         information in memory without any additional processing.
  44
  45         Arguments:
  46             xmpp -- The main SleekXMPP object.
  47         """
  48         self.nodes = {}
  49         self.xmpp = xmpp
  50         self.disco = disco
  51         self.lock = threading.RLock()
  52
  53     def add_node(self, jid=None, node=None, ifrom=None):
  54         """
  55         Create a new set of stanzas for the provided
  56         JID and node combination.
  57
  58         Arguments:
  59             jid  -- The JID that will own the new stanzas.
  60             node -- The node that will own the new stanzas.
  61         """
  62         with self.lock:
  63             if jid is None:
  64                 jid = self.xmpp.boundjid.full
  65             if node is None:
  66                 node = ''
  67             if ifrom is None:
  68                 ifrom = ''
  69             if isinstance(ifrom, JID):
  70                 ifrom = ifrom.full
  71             if (jid, node, ifrom) not in self.nodes:
  72                 self.nodes[(jid, node, ifrom)] = {'info': DiscoInfo(),
  73                                            'items': DiscoItems()}
  74                 self.nodes[(jid, node, ifrom)]['info']['node'] = node
  75                 self.nodes[(jid, node, ifrom)]['items']['node'] = node
  76
  77     def get_node(self, jid=None, node=None, ifrom=None):
  78         with self.lock:
  79             if jid is None:
  80                 jid = self.xmpp.boundjid.full
  81             if node is None:
  82                 node = ''
  83             if ifrom is None:
  84                 ifrom = ''
  85             if isinstance(ifrom, JID):
  86                 ifrom = ifrom.full
  87             if (jid, node, ifrom) not in self.nodes:
  88                 self.add_node(jid, node, ifrom)
  89             return self.nodes[(jid, node, ifrom)]
  90
  91     def node_exists(self, jid=None, node=None, ifrom=None):
  92         with self.lock:
  93             if jid is None:
  94                 jid = self.xmpp.boundjid.full
  95             if node is None:
  96                 node = ''
  97             if ifrom is None:
  98                 ifrom = ''
  99             if isinstance(ifrom, JID):
 100                 ifrom = ifrom.full
 101             if (jid, node, ifrom) not in self.nodes:
 102                 return False
 103             return True
 104
 105     # =================================================================
 106     # Node Handlers
 107     #
 108     # Each handler accepts four arguments: jid, node, ifrom, and data.
 109     # The jid and node parameters together determine the set of info
 110     # and items stanzas that will be retrieved or added. Additionally,
 111     # the ifrom value allows for cached results when results vary based
 112     # on the requester's JID. The data parameter is a dictionary with
 113     # additional parameters that will be passed to other calls.
 114     #
 115     # This implementation does not allow different responses based on
 116     # the requester's JID, except for cached results. To do that,
 117     # register a custom node handler.
 118
 119     def supports(self, jid, node, ifrom, data):
 120         """
 121         Check if a JID supports a given feature.
 122
 123         The data parameter may provide:
 124             feature  -- The feature to check for support.
 125             local    -- If true, then the query is for a JID/node
 126                         combination handled by this Sleek instance and
 127                         no stanzas need to be sent.
 128                         Otherwise, a disco stanza must be sent to the
 129                         remove JID to retrieve the info.
 130             cached   -- If true, then look for the disco info data from
 131                         the local cache system. If no results are found,
 132                         send the query as usual. The self.use_cache
 133                         setting must be set to true for this option to
 134                         be useful. If set to false, then the cache will
 135                         be skipped, even if a result has already been
 136                         cached. Defaults to false.
 137         """
 138         feature = data.get('feature', None)
 139
 140         data = {'local': data.get('local', False),
 141                 'cached': data.get('cached', True)}
 142
 143         if not feature:
 144             return False
 145
 146         try:
 147             info = self.disco.get_info(jid=jid, node=node,
 148                                        ifrom=ifrom, **data)
 149             info = self.disco._wrap(ifrom, jid, info, True)
 150             features = info['disco_info']['features']
 151             return feature in features
 152         except IqError:
 153             return False
 154         except IqTimeout:
 155             return None
 156
 157     def has_identity(self, jid, node, ifrom, data):
 158         """
 159         Check if a JID has a given identity.
 160
 161         The data parameter may provide:
 162             category -- The category of the identity to check.
 163             itype    -- The type of the identity to check.
 164             lang     -- The language of the identity to check.
 165             local    -- If true, then the query is for a JID/node
 166                         combination handled by this Sleek instance and
 167                         no stanzas need to be sent.
 168                         Otherwise, a disco stanza must be sent to the
 169                         remove JID to retrieve the info.
 170             cached   -- If true, then look for the disco info data from
 171                         the local cache system. If no results are found,
 172                         send the query as usual. The self.use_cache
 173                         setting must be set to true for this option to
 174                         be useful. If set to false, then the cache will
 175                         be skipped, even if a result has already been
 176                         cached. Defaults to false.
 177         """
 178         identity = (data.get('category', None),
 179                     data.get('itype', None),
 180                     data.get('lang', None))
 181
 182         data = {'local': data.get('local', False),
 183                 'cached': data.get('cached', True)}
 184
 185         try:
 186             info = self.disco.get_info(jid=jid, node=node,
 187                                        ifrom=ifrom, **data)
 188             info = self.disco._wrap(ifrom, jid, info, True)
 189             trunc = lambda i: (i[0], i[1], i[2])
 190             return identity in map(trunc, info['disco_info']['identities'])
 191         except IqError:
 192             return False
 193         except IqTimeout:
 194             return None
 195
 196     def get_info(self, jid, node, ifrom, data):
 197         """
 198         Return the stored info data for the requested JID/node combination.
 199
 200         The data parameter is not used.
 201         """
 202         with self.lock:
 203             if not self.node_exists(jid, node):
 204                 if not node:
 205                     return DiscoInfo()
 206                 else:
 207                     raise XMPPError(condition='item-not-found')
 208             else:
 209                 return self.get_node(jid, node)['info']
 210
 211     def set_info(self, jid, node, ifrom, data):
 212         """
 213         Set the entire info stanza for a JID/node at once.
 214
 215         The data parameter is a disco#info substanza.
 216         """
 217         with self.lock:
 218             self.add_node(jid, node)
 219             self.get_node(jid, node)['info'] = data
 220
 221     def del_info(self, jid, node, ifrom, data):
 222         """
 223         Reset the info stanza for a given JID/node combination.
 224
 225         The data parameter is not used.
 226         """
 227         with self.lock:
 228             if self.node_exists(jid, node):
 229                 self.get_node(jid, node)['info'] = DiscoInfo()
 230
 231     def get_items(self, jid, node, ifrom, data):
 232         """
 233         Return the stored items data for the requested JID/node combination.
 234
 235         The data parameter is not used.
 236         """
 237         with self.lock:
 238             if not self.node_exists(jid, node):
 239                 if not node:
 240                     return DiscoItems()
 241                 else:
 242                     raise XMPPError(condition='item-not-found')
 243             else:
 244                 return self.get_node(jid, node)['items']
 245
 246     def set_items(self, jid, node, ifrom, data):
 247         """
 248         Replace the stored items data for a JID/node combination.
 249
 250         The data parameter may provide:
 251             items -- A set of items in tuple format.
 252         """
 253         with self.lock:
 254             items = data.get('items', set())
 255             self.add_node(jid, node)
 256             self.get_node(jid, node)['items']['items'] = items
 257
 258     def del_items(self, jid, node, ifrom, data):
 259         """
 260         Reset the items stanza for a given JID/node combination.
 261
 262         The data parameter is not used.
 263         """
 264         with self.lock:
 265             if self.node_exists(jid, node):
 266                 self.get_node(jid, node)['items'] = DiscoItems()
 267
 268     def add_identity(self, jid, node, ifrom, data):
 269         """
 270         Add a new identity to te JID/node combination.
 271
 272         The data parameter may provide:
 273             category -- The general category to which the agent belongs.
 274             itype    -- A more specific designation with the category.
 275             name     -- Optional human readable name for this identity.
 276             lang     -- Optional standard xml:lang value.
 277         """
 278         with self.lock:
 279             self.add_node(jid, node)
 280             self.get_node(jid, node)['info'].add_identity(
 281                     data.get('category', ''),
 282                     data.get('itype', ''),
 283                     data.get('name', None),
 284                     data.get('lang', None))
 285
 286     def set_identities(self, jid, node, ifrom, data):
 287         """
 288         Add or replace all identities for a JID/node combination.
 289
 290         The data parameter should include:
 291             identities -- A list of identities in tuple form:
 292                             (category, type, name, lang)
 293         """
 294         with self.lock:
 295             identities = data.get('identities', set())
 296             self.add_node(jid, node)
 297             self.get_node(jid, node)['info']['identities'] = identities
 298
 299     def del_identity(self, jid, node, ifrom, data):
 300         """
 301         Remove an identity from a JID/node combination.
 302
 303         The data parameter may provide:
 304             category -- The general category to which the agent belonged.
 305             itype    -- A more specific designation with the category.
 306             name     -- Optional human readable name for this identity.
 307             lang     -- Optional, standard xml:lang value.
 308         """
 309         with self.lock:
 310             if self.node_exists(jid, node):
 311                 self.get_node(jid, node)['info'].del_identity(
 312                         data.get('category', ''),
 313                         data.get('itype', ''),
 314                         data.get('name', None),
 315                         data.get('lang', None))
 316
 317     def del_identities(self, jid, node, ifrom, data):
 318         """
 319         Remove all identities from a JID/node combination.
 320
 321         The data parameter is not used.
 322         """
 323         with self.lock:
 324             if self.node_exists(jid, node):
 325                 del self.get_node(jid, node)['info']['identities']
 326
 327     def add_feature(self, jid, node, ifrom, data):
 328         """
 329         Add a feature to a JID/node combination.
 330
 331         The data parameter should include:
 332             feature -- The namespace of the supported feature.
 333         """
 334         with self.lock:
 335             self.add_node(jid, node)
 336             self.get_node(jid, node)['info'].add_feature(
 337                     data.get('feature', ''))
 338
 339     def set_features(self, jid, node, ifrom, data):
 340         """
 341         Add or replace all features for a JID/node combination.
 342
 343         The data parameter should include:
 344             features -- The new set of supported features.
 345         """
 346         with self.lock:
 347             features = data.get('features', set())
 348             self.add_node(jid, node)
 349             self.get_node(jid, node)['info']['features'] = features
 350
 351     def del_feature(self, jid, node, ifrom, data):
 352         """
 353         Remove a feature from a JID/node combination.
 354
 355         The data parameter should include:
 356             feature -- The namespace of the removed feature.
 357         """
 358         with self.lock:
 359             if self.node_exists(jid, node):
 360                 self.get_node(jid, node)['info'].del_feature(
 361                         data.get('feature', ''))
 362
 363     def del_features(self, jid, node, ifrom, data):
 364         """
 365         Remove all features from a JID/node combination.
 366
 367         The data parameter is not used.
 368         """
 369         with self.lock:
 370             if not self.node_exists(jid, node):
 371                 return
 372             del self.get_node(jid, node)['info']['features']
 373
 374     def add_item(self, jid, node, ifrom, data):
 375         """
 376         Add an item to a JID/node combination.
 377
 378         The data parameter may include:
 379             ijid  -- The JID for the item.
 380             inode -- Optional additional information to reference
 381                      non-addressable items.
 382             name  -- Optional human readable name for the item.
 383         """
 384         with self.lock:
 385             self.add_node(jid, node)
 386             self.get_node(jid, node)['items'].add_item(
 387                     data.get('ijid', ''),
 388                     node=data.get('inode', ''),
 389                     name=data.get('name', ''))
 390
 391     def del_item(self, jid, node, ifrom, data):
 392         """
 393         Remove an item from a JID/node combination.
 394
 395         The data parameter may include:
 396             ijid  -- JID of the item to remove.
 397             inode -- Optional extra identifying information.
 398         """
 399         with self.lock:
 400             if self.node_exists(jid, node):
 401                 self.get_node(jid, node)['items'].del_item(
 402                         data.get('ijid', ''),
 403                         node=data.get('inode', None))
 404
 405     def cache_info(self, jid, node, ifrom, data):
 406         """
 407         Cache disco information for an external JID.
 408
 409         The data parameter is the Iq result stanza
 410         containing the disco info to cache, or
 411         the disco#info substanza itself.
 412         """
 413         with self.lock:
 414             if isinstance(data, Iq):
 415                 data = data['disco_info']
 416
 417             self.add_node(jid, node, ifrom)
 418             self.get_node(jid, node, ifrom)['info'] = data
 419
 420     def get_cached_info(self, jid, node, ifrom, data):
 421         """
 422         Retrieve cached disco info data.
 423
 424         The data parameter is not used.
 425         """
 426         with self.lock:
 427             if not self.node_exists(jid, node, ifrom):
 428                 return None
 429             else:
 430                 return self.get_node(jid, node, ifrom)['info']