Builtin routers

Vumi ships with a small set of generically useful routers:

SimpleDispatchRouter

class vumi.dispatchers.SimpleDispatchRouter(dispatcher, config)

Simple dispatch router that maps transports to apps.

Configuration options:

Parameters:

• route_mappings (dict) – A map of transport_names to exposed_names. Inbound messages and events received from a given transport are dispatched to the application attached to the corresponding exposed name.
• transport_mappings (dict) – An optional re-mapping of transport_names to transport_names. By default, outbound messages are dispatched to the transport attached to the endpoint with the same name as the transport name given in the message. If a transport name is present in this dictionary, the message is instead dispatched to the new transport name given by the re-mapping.

TransportToTransportRouter

class vumi.dispatchers.TransportToTransportRouter(dispatcher, config)

Simple dispatch router that connects transports to other transports.

Note

Connecting transports to one results in event messages being discarded since transports cannot receive events. Outbound messages never need to be dispatched because transports only send inbound messages.

Configuration options:

Parameters:route_mappings (dict) – A map of transport_names to transport_names. Inbound messages received from a transport are sent as outbound messages to the associated transport.

ToAddrRouter

class vumi.dispatchers.ToAddrRouter(dispatcher, config)

Router that dispatches based on msg to_addr.

Parameters:toaddr_mappings (dict) – Mapping from application transport names to regular expressions. If a message’s to_addr matches the given regular expression the message is sent to the applications listening on the given transport name.

FromAddrMultiplexRouter

class vumi.dispatchers.FromAddrMultiplexRouter(dispatcher, config)

Router that multiplexes multiple transports based on msg from_addr.

This router is intended to be used to multiplex a pool of transports that each only supports a single external address, and present them to applications (or downstream dispatchers) as a single transport that supports multiple external addresses. This is useful for multiplexing vumi.transports.xmpp.XMPPTransport instances, for example.

Note

This router rewrites transport_name in both directions. Also, only one exposed name is supported.

Configuration options:

Parameters:fromaddr_mappings (dict) – Mapping from message from_addr to transport_name.

UserGroupingRouter

class vumi.dispatchers.UserGroupingRouter(dispatcher, config)

Router that dispatches based on msg from_addr. Each unique from_addr is round-robin assigned to one of the defined groups in group_mappings. All messages from that from_addr are then routed to the app assigned to that group.

Useful for A/B testing.

Configuration options:

Parameters:

• group_mappings (dict) – Mapping of group names to transport_names. If a user is assigned to a given group the message is sent to the application listening on the given transport_name.
• dispatcher_name (str) – The name of the dispatcher, used internally as the prefix for Redis keys.

ContentKeywordRouter

class vumi.dispatchers.ContentKeywordRouter(dispatcher, config)

Router that dispatches based on the first word of the message content. In the context of SMSes the first word is sometimes called the ‘keyword’.

Parameters:

• keyword_mappings (dict) – Mapping from application transport names to simple keywords. This is purely a convenience for constructing simple routing rules. The rules generated from this option are appened to the of rules supplied via the rules option.
• rules (list) – A list of routing rules. A routing rule is a dictionary. It must have app and keyword keys and may contain to_addr and prefix keys. If a message’s first word matches a given keyword, the message is sent to the application listening on the transport name given by the value of app. If a ‘to_addr’ key is supplied, the message to_addr must also match the value of the ‘to_addr’ key. If a ‘prefix’ is supplied, the message from_addr must start with the value of the ‘prefix’ key.
• fallback_application (str) – Optional application transport name to forward inbound messages that match no rule to. If omitted, unrouted inbound messages are just logged.
• transport_mappings (dict) – Mapping from message from_addr values to transports names. If a message’s from_addr matches a given from_addr, the message is sent to the associated transport.
• expire_routing_memory (int) – Time in seconds before outbound message’s ids are expired from the redis routing store. Outbound message ids are stored along with the transport_name the message came in on and are used to route events such as acknowledgements and delivery reports back to the application that sent the outgoing message. Default is seven days.