Drain plug to declare listener modules that will be notified of the received events. Listeners must implement the call/1 function, that will be invoked with a list of Routemaster.Drain.Event structures as argument.

The listeners’ call/1 function is invoked in a supervised Task, so all listeners are to be considered asynchronous and independent.

By default a listener module will be notified of all events in the current payload, but it’s possible to filter by topic. It’s also possible to subscribe multiple listeners at the same time. This is convenient when topic filters are applied, because the filtering function will be executed only once for all the listeners declared together.

Options

• :listener (or :listeners, plural): either the listener module or a list of listener modules.
• :only: either a binary or a list of binaries. The listener will only be notified of events for this topic or topics.
• :except: either a binary or a list of binaries. The opposite of :only.

If no events match the filters, listeners are not notified. This means that the listeners’ call/1 functions are never invoked with empty lists.

After notifying the listener(s), the full event payload is passed down in the pipeline unchanged, which means that multiple Notify drains can be configured together.

Examples

alias Routemaster.Drains.Notify

# listen to all events from all topics
drain Notify, listener: GlobalListener

# only listen to one or some topics
drain Notify, listener: BurgerListener, only: "burgers"
drain Notify, listener: FruitListener, only: ~w(apple orange)

# listen to all but some topics
drain Notify, listener: VeggieListener, except: "meat"
drain Notify, listener: NoFishListener, except: ~w(cod seabass)

# notify multiple listeners for a selection of topics
drain Notify,
  listeners: [DessertListener, SweetListener],
  only: ~w(pies cakes ice_creams)