Merge "oslo.messaging: notification-listener-pools"

specs/kilo/oslo.messaging-notification-listener-pools.rst

@@ -0,0 +1,135 @@
+
+===========================================
+oslo.messaging: Notification listener pools
+===========================================
+
+https://blueprints.launchpad.net/oslo.messaging/+spec/notification-listener-pools
+
+The idea is that you can have multiple groups/pools of listeners
+consuming notifications and that each group/pool only receives one
+copy of each notification.
+
+Problem description
+===================
+
+Currently if two applications use the oslo.messaging notification listener
+and want to subscribe to the same topic, they steal messages from each other.
+
+The current workaround is to configure the notifier part to publish the message
+twice on different topic. This confuses a lot of people and this is
+undocumented.
+
+Proposed change
+===============
+
+So part of the purpose of this BP is a bit hardcoded into oslo.messaging and
+have bad side effect. The proposal will fix that.
+
+We need to add a pool parameter for the messaging.get_notification_listener()
+API in order to support this.
+
+In all AMQP drivers, this is implemented by using the pool name as the queue
+name for consume from the topic. To keep backward compatibility, by default,
+the topic name will continue to be used as the pool/queue name.
+
+Alternatives
+------------
+
+Documents the workaround.
+
+Impact on Existing APIs
+-----------------------
+
+oslo.messaging.get_notification_listener will get a new parameter 'pool' to
+configure the pool name.
+
+Security impact
+---------------
+
+None.
+
+Performance Impact
+------------------
+
+None.
+
+Configuration Impact
+--------------------
+
+None.
+
+Developer Impact
+----------------
+
+None.
+
+Testing Impact
+--------------
+
+None.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  sileht
+
+Other contributors:
+  None
+
+Milestones
+----------
+
+K-1
+
+Work Items
+----------
+
+Works already done: https://review.openstack.org/125112
+
+Incubation
+==========
+
+None.
+
+Adoption
+--------
+
+None.
+
+Library
+-------
+
+None.
+
+Anticipated API Stabilization
+-----------------------------
+
+None.
+
+Documentation Impact
+====================
+
+The new pool parameter will be documented.
+
+Dependencies
+============
+
+None.
+
+References
+==========
+
+
+Code in review: https://review.openstack.org/#/c/125112/
+
+
+.. note::
+
+  This work is licensed under a Creative Commons Attribution 3.0
+  Unported License.
+  http://creativecommons.org/licenses/by/3.0/legalcode
+