This document is for Kombu's development version, which can be significantly different from previous releases. Get the stable docs here: 5.0.
Source code for kombu.transport.azureservicebus
"""Azure Service Bus Message Queue transport module for kombu.
Note that the Shared Access Policy used to connect to Azure Service Bus
requires Manage, Send and Listen claims since the broker will create new
queues and delete old queues as required.
Notes when using with Celery if you are experiencing issues with programs not
terminating properly. The Azure Service Bus SDK uses the Azure uAMQP library
which in turn creates some threads. If the AzureServiceBus Channel is closed,
said threads will be closed properly, but it seems there are times when Celery
does not do this so these threads will be left running. As the uAMQP threads
are not marked as Daemon threads, they will not be killed when the main thread
exits. Setting the ``uamqp_keep_alive_interval`` transport option to 0 will
prevent the keep_alive thread from starting
More information about Azure Service Bus:
https://azure.microsoft.com/en-us/services/service-bus/
Features
========
* Type: Virtual
* Supports Direct: *Unreviewed*
* Supports Topic: *Unreviewed*
* Supports Fanout: *Unreviewed*
* Supports Priority: *Unreviewed*
* Supports TTL: *Unreviewed*
Connection String
=================
Connection string has the following format:
.. code-block::
azureservicebus://SAS_POLICY_NAME:SAS_KEY@SERVICE_BUSNAMESPACE
Transport Options
=================
* ``queue_name_prefix`` - String prefix to prepend to queue names in a
service bus namespace.
* ``wait_time_seconds`` - Number of seconds to wait to receive messages.
Default ``5``
* ``peek_lock_seconds`` - Number of seconds the message is visible for before
it is requeued and sent to another consumer. Default ``60``
* ``uamqp_keep_alive_interval`` - Interval in seconds the Azure uAMQP library
should send keepalive messages. Default ``30``
* ``retry_total`` - Azure SDK retry total. Default ``3``
* ``retry_backoff_factor`` - Azure SDK exponential backoff factor.
Default ``0.8``
* ``retry_backoff_max`` - Azure SDK retry total time. Default ``120``
"""
import string
from queue import Empty
from typing import Any, Dict, Optional, Set, Tuple, Union
import azure.core.exceptions
import azure.servicebus.exceptions
import isodate
from azure.servicebus import (ServiceBusClient, ServiceBusMessage,
ServiceBusReceiveMode, ServiceBusReceiver,
ServiceBusSender)
from azure.servicebus.management import ServiceBusAdministrationClient
from kombu.utils.encoding import bytes_to_str, safe_str
from kombu.utils.json import dumps, loads
from kombu.utils.objects import cached_property
from . import virtual
# dots are replaced by dash, all other punctuation replaced by underscore.
PUNCTUATIONS_TO_REPLACE = set(string.punctuation) - {'_', '.', '-'}
CHARS_REPLACE_TABLE = {
ord('.'): ord('-'),
**{ord(c): ord('_') for c in PUNCTUATIONS_TO_REPLACE}
}
class SendReceive:
"""Container for Sender and Receiver."""
def __init__(self,
receiver: Optional[ServiceBusReceiver] = None,
sender: Optional[ServiceBusSender] = None):
self.receiver = receiver # type: ServiceBusReceiver
self.sender = sender # type: ServiceBusSender
def close(self) -> None:
if self.receiver:
self.receiver.close()
self.receiver = None
if self.sender:
self.sender.close()
self.sender = None
[docs]class Channel(virtual.Channel):
"""Azure Service Bus channel."""
default_wait_time_seconds = 5 # in seconds
default_peek_lock_seconds = 60 # in seconds (default 60, max 300)
# in seconds (is the default from service bus repo)
default_uamqp_keep_alive_interval = 30
# number of retries (is the default from service bus repo)
default_retry_total = 3
# exponential backoff factor (is the default from service bus repo)
default_retry_backoff_factor = 0.8
# Max time to backoff (is the default from service bus repo)
default_retry_backoff_max = 120
domain_format = 'kombu%(vhost)s'
_queue_service = None # type: ServiceBusClient
_queue_mgmt_service = None # type: ServiceBusAdministrationClient
_queue_cache = {} # type: Dict[str, SendReceive]
_noack_queues = set() # type: Set[str]
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self._namespace = None
self._policy = None
self._sas_key = None
self._connection_string = None
self._try_parse_connection_string()
self.qos.restore_at_shutdown = False
def _try_parse_connection_string(self) -> None:
self._namespace, self._policy, self._sas_key = Transport.parse_uri(
self.conninfo.hostname)
# Convert
endpoint = 'sb://' + self._namespace
if not endpoint.endswith('.net'):
endpoint += '.servicebus.windows.net'
conn_dict = {
'Endpoint': endpoint,
'SharedAccessKeyName': self._policy,
'SharedAccessKey': self._sas_key,
}
self._connection_string = ';'.join(
[key + '=' + value for key, value in conn_dict.items()])
[docs] def basic_consume(self, queue, no_ack, *args, **kwargs):
if no_ack:
self._noack_queues.add(queue)
return super().basic_consume(
queue, no_ack, *args, **kwargs
)
[docs] def basic_cancel(self, consumer_tag):
if consumer_tag in self._consumers:
queue = self._tag_to_queue[consumer_tag]
self._noack_queues.discard(queue)
return super().basic_cancel(consumer_tag)
def _add_queue_to_cache(
self, name: str,
receiver: Optional[ServiceBusReceiver] = None,
sender: Optional[ServiceBusSender] = None
) -> SendReceive:
if name in self._queue_cache:
obj = self._queue_cache[name]
obj.sender = obj.sender or sender
obj.receiver = obj.receiver or receiver
else:
obj = SendReceive(receiver, sender)
self._queue_cache[name] = obj
return obj
def _get_asb_sender(self, queue: str) -> SendReceive:
queue_obj = self._queue_cache.get(queue, None)
if queue_obj is None or queue_obj.sender is None:
sender = self.queue_service.get_queue_sender(
queue, keep_alive=self.uamqp_keep_alive_interval)
queue_obj = self._add_queue_to_cache(queue, sender=sender)
return queue_obj
def _get_asb_receiver(
self, queue: str,
recv_mode: ServiceBusReceiveMode = ServiceBusReceiveMode.PEEK_LOCK,
queue_cache_key: Optional[str] = None) -> SendReceive:
cache_key = queue_cache_key or queue
queue_obj = self._queue_cache.get(cache_key, None)
if queue_obj is None or queue_obj.receiver is None:
receiver = self.queue_service.get_queue_receiver(
queue_name=queue, receive_mode=recv_mode,
keep_alive=self.uamqp_keep_alive_interval)
queue_obj = self._add_queue_to_cache(cache_key, receiver=receiver)
return queue_obj
[docs] def entity_name(
self, name: str, table: Optional[Dict[int, int]] = None) -> str:
"""Format AMQP queue name into a valid ServiceBus queue name."""
return str(safe_str(name)).translate(table or CHARS_REPLACE_TABLE)
def _restore(self, message: virtual.base.Message) -> None:
# Not be needed as ASB handles unacked messages
# Remove 'azure_message' as its not JSON serializable
# message.delivery_info.pop('azure_message', None)
# super()._restore(message)
pass
def _new_queue(self, queue: str, **kwargs) -> SendReceive:
"""Ensure a queue exists in ServiceBus."""
queue = self.entity_name(self.queue_name_prefix + queue)
try:
return self._queue_cache[queue]
except KeyError:
# Converts seconds into ISO8601 duration format
# ie 66seconds = P1M6S
lock_duration = isodate.duration_isoformat(
isodate.Duration(seconds=self.peek_lock_seconds))
try:
self.queue_mgmt_service.create_queue(
queue_name=queue, lock_duration=lock_duration)
except azure.core.exceptions.ResourceExistsError:
pass
return self._add_queue_to_cache(queue)
def _delete(self, queue: str, *args, **kwargs) -> None:
"""Delete queue by name."""
queue = self.entity_name(self.queue_name_prefix + queue)
self._queue_mgmt_service.delete_queue(queue)
send_receive_obj = self._queue_cache.pop(queue, None)
if send_receive_obj:
send_receive_obj.close()
def _put(self, queue: str, message, **kwargs) -> None:
"""Put message onto queue."""
queue = self.entity_name(self.queue_name_prefix + queue)
msg = ServiceBusMessage(dumps(message))
queue_obj = self._get_asb_sender(queue)
queue_obj.sender.send_messages(msg)
def _get(
self, queue: str,
timeout: Optional[Union[float, int]] = None
) -> Dict[str, Any]:
"""Try to retrieve a single message off ``queue``."""
# If we're not ack'ing for this queue, just change receive_mode
recv_mode = ServiceBusReceiveMode.RECEIVE_AND_DELETE \
if queue in self._noack_queues else ServiceBusReceiveMode.PEEK_LOCK
queue = self.entity_name(self.queue_name_prefix + queue)
queue_obj = self._get_asb_receiver(queue, recv_mode)
messages = queue_obj.receiver.receive_messages(
max_message_count=1,
max_wait_time=timeout or self.wait_time_seconds)
if not messages:
raise Empty()
# message.body is either byte or generator[bytes]
message = messages[0]
if not isinstance(message.body, bytes):
body = b''.join(message.body)
else:
body = message.body
msg = loads(bytes_to_str(body))
msg['properties']['delivery_info']['azure_message'] = message
msg['properties']['delivery_info']['azure_queue_name'] = queue
return msg
[docs] def basic_ack(self, delivery_tag: str, multiple: bool = False) -> None:
delivery_info = self.qos.get(delivery_tag).delivery_info
if delivery_info['exchange'] in self._noack_queues:
return super().basic_ack(delivery_tag)
queue = delivery_info['azure_queue_name']
# recv_mode is PEEK_LOCK when ack'ing messages
queue_obj = self._get_asb_receiver(queue)
try:
queue_obj.receiver.complete_message(delivery_info['azure_message'])
except azure.servicebus.exceptions.MessageAlreadySettled:
super().basic_ack(delivery_tag)
except Exception:
super().basic_reject(delivery_tag)
else:
super().basic_ack(delivery_tag)
def _size(self, queue: str) -> int:
"""Return the number of messages in a queue."""
queue = self.entity_name(self.queue_name_prefix + queue)
props = self.queue_mgmt_service.get_queue_runtime_properties(queue)
return props.total_message_count
def _purge(self, queue):
"""Delete all current messages in a queue."""
# Azure doesn't provide a purge api yet
n = 0
max_purge_count = 10
queue = self.entity_name(self.queue_name_prefix + queue)
# By default all the receivers will be in PEEK_LOCK receive mode
queue_obj = self._queue_cache.get(queue, None)
if queue not in self._noack_queues or \
queue_obj is None or queue_obj.receiver is None:
queue_obj = self._get_asb_receiver(
queue,
ServiceBusReceiveMode.RECEIVE_AND_DELETE, 'purge_' + queue
)
while True:
messages = queue_obj.receiver.receive_messages(
max_message_count=max_purge_count,
max_wait_time=0.2
)
n += len(messages)
if len(messages) < max_purge_count:
break
return n
[docs] def close(self) -> None:
# receivers and senders spawn threads so clean them up
if not self.closed:
self.closed = True
for queue_obj in self._queue_cache.values():
queue_obj.close()
self._queue_cache.clear()
if self.connection is not None:
self.connection.close_channel(self)
@property
def queue_service(self) -> ServiceBusClient:
if self._queue_service is None:
self._queue_service = ServiceBusClient.from_connection_string(
self._connection_string,
retry_total=self.retry_total,
retry_backoff_factor=self.retry_backoff_factor,
retry_backoff_max=self.retry_backoff_max
)
return self._queue_service
@property
def queue_mgmt_service(self) -> ServiceBusAdministrationClient:
if self._queue_mgmt_service is None:
self._queue_mgmt_service = \
ServiceBusAdministrationClient.from_connection_string(
self._connection_string)
return self._queue_mgmt_service
@property
def conninfo(self):
return self.connection.client
@property
def transport_options(self):
return self.connection.client.transport_options
@cached_property
def queue_name_prefix(self) -> str:
return self.transport_options.get('queue_name_prefix', '')
@cached_property
def wait_time_seconds(self) -> int:
return self.transport_options.get('wait_time_seconds',
self.default_wait_time_seconds)
@cached_property
def peek_lock_seconds(self) -> int:
return min(self.transport_options.get('peek_lock_seconds',
self.default_peek_lock_seconds),
300) # Limit upper bounds to 300
@cached_property
def uamqp_keep_alive_interval(self) -> int:
return self.transport_options.get(
'uamqp_keep_alive_interval',
self.default_uamqp_keep_alive_interval
)
@cached_property
def retry_total(self) -> int:
return self.transport_options.get(
'retry_total', self.default_retry_total)
@cached_property
def retry_backoff_factor(self) -> float:
return self.transport_options.get(
'retry_backoff_factor', self.default_retry_backoff_factor)
@cached_property
def retry_backoff_max(self) -> int:
return self.transport_options.get(
'retry_backoff_max', self.default_retry_backoff_max)
[docs]class Transport(virtual.Transport):
"""Azure Service Bus transport."""
Channel = Channel
polling_interval = 1
default_port = None
can_parse_url = True
[docs] @staticmethod
def parse_uri(uri: str) -> Tuple[str, str, str]:
# URL like:
# azureservicebus://{SAS policy name}:{SAS key}@{ServiceBus Namespace}
# urllib parse does not work as the sas key could contain a slash
# e.g.: azureservicebus://rootpolicy:some/key@somenamespace
# > 'rootpolicy:some/key@somenamespace'
uri = uri.replace('azureservicebus://', '')
# > 'rootpolicy:some/key', 'somenamespace'
policykeypair, namespace = uri.rsplit('@', 1)
# > 'rootpolicy', 'some/key'
policy, sas_key = policykeypair.split(':', 1)
# Validate ASB connection string
if not all([namespace, policy, sas_key]):
raise ValueError(
'Need a URI like '
'azureservicebus://{SAS policy name}:{SAS key}@{ServiceBus Namespace} ' # noqa
'or the azure Endpoint connection string'
)
return namespace, policy, sas_key
[docs] @classmethod
def as_uri(cls, uri: str, include_password=False, mask='**') -> str:
namespace, policy, sas_key = cls.parse_uri(uri)
return 'azureservicebus://{}:{}@{}'.format(
policy,
sas_key if include_password else mask,
namespace
)
