Routing¶
When the Consumer
receives a message from RabbitMQ, it prepares an
Envelope
object of that message, for the handler. However, the prepared
envelope somehow needs to be routed to its handler, where it’s actually consumed.
The envelope may be routed based on the message type, payload, or any other criteria;
It depends on the routing logic. For this reason, the consumer doesn’t make the
routing decisions itself, it delegates the routing to a router. The router sits
between the consumer and handlers. Its responsibility is, to route each incoming
envelope to its handler, returning the handler to the consumer for execution.
Router¶
-
class
rabbitleap.routing.
Router
(**kwargs)[source] Base class for routers.
Subclasses MUST implement
find_handler()
Rule Router¶
-
class
rabbitleap.routing.
RuleRouter
(consumer, default_rule=None)[source] Bases:
rabbitleap.routing.Router
Rule router.
Rule Router is an implementation of the base class
Router
. It uses routing rules to route envelopes to handlers. The rule router maintains a list routing rules, through which it goes sequentially to find a handler for a given envelope. Rules added to the router are appended to the end of its rules list, and since the router goes through the routing rules sequentially in the order they’re added, more specific rules should be added first, then the general ones later.A routing rule is an instance of the class
Rule
. It has 3 fields, aMatcher
, target, and target arguments field. The matcher is used to determines whether the target can handle the envelope. The target can be aHandler
class or aRouter
instance (sub-router). The target arguments is a dictionary passed to the newly created handler for initialization.When the target is a
Handler
class, the router creates an instance of it, then returns the instance to the caller. However, if the target is aRouter
instance, it would act as a sub-router (child router). The parent router delegates finding the handler to the child router. The sub-router doesn’t have to be of the same type, it can be anyRouter
implementation. Chained routers let one router delegates the routing to the next one.The rule router returns
None
when the given envelope is unroutable (no handler can handle it). However, the rule router may be configured with a default routing rule which catches all unroutable envelopes, checkset_default_rule()
.Rule router always creates a new handler instance when its
find_handler()
is called, even for the same envelope, except when the rule’s target is aRouter
instance, which may have different implementation and may not return a new instance.Actually, the
Consumer
itself is a Rule Router. It implements extra stuff to communicate with RabbitMQ.
-
RuleRouter.
add_rule
(rule)[source] Add a routing rule to the routing rules list.
A routing rule is added to the end of routing rules list, just before the default rule which is always the last one.
A routing rule is an instance of the class
Rule
. It has 3 fields, aMatcher
, target, and target arguments field. The matcher is used to determines whether the target can handler the envelope. The target can be aHandler
class or aRouter
instance (sub-router). The target arguments is a dictionary passed to the newly created handler for initialization.Since the rules of the Rule Router are checked sequentially in the order they added, more specific rules should be added first, then generic ones later.
Parameters: rule (Rule) – routing rule instance.
-
RuleRouter.
set_default_rule
(rule)[source] Set default rule.
Default rule, when set, it catches all unroutable envelopes.
Parameters: rule (Rule) – default routing rule which catches all unmatched messages. None
will unset default rule
-
RuleRouter.
find_handler
(envelope)[source] Find and return a handler
The router goes through the routing rules list sequentially to find a handler for the given envelope.
When the target, in matched
Rule
, is aHandler
class, an instance of it is created and returned. However, if the target is aRouter
instance, it would act as a sub-router. The sub-router’sfind_handler()
is invoked to get aHandler
instance.None
is returned when the given envelope is unroutable (no handler can handle it). However, if a default rule is set, its handler instance will be returnedNOTE: The router always creates a new handler instance for each find handler call, even for the same message.
Parameters: envelope (Envelope) – Message envelope Return Handler: Handler
instance
Routing Rule¶
-
class
rabbitleap.routing.
Rule
(matcher, target, target_kwargs=None)[source] A matching rule.
A rule (routing rule) is an object that links a matcher (
Matcher
) instance, to a target.The matcher is used to determines whether the target can handler the envelope. The target can be a
Handler
class or aRouter
instance (sub-router). The target arguments is a dictionary passed to the newly created handler for initialization.
Matchers¶
-
class
rabbitleap.routing.
Matcher
[source] Base class for matchers
This is the base class for matcher. Matcher is used by
Rule
to check if its target can handle the givenEnvelope
or notSubclasses MUST implement
match()
method.
-
Matcher.
match
(envelope)[source] Return
True
orFalse
indicating the target can handle the message.This method accepts an
Envelope
object as an argument and returns boolean, indicating whether the target can handle the envelope or not.Subclasses MUST implement this method
Parameters: envelope (Envelope) – Message envelope Returns: can handle or not Return type: bool
-
class
rabbitleap.routing.
AnyMatches
[source] Bases:
rabbitleap.routing.Matcher
Match all messages macher
This matcher matches nothing. It always returns
False
. It’s used inRuleRouter
when a default rule is set to catch all unroutable envelopes
-
AnyMatches.
match
(envelope)[source] Always return
True
-
class
rabbitleap.routing.
NoneMatches
[source] Bases:
rabbitleap.routing.Matcher
Match noting macher
This matcher matches nothing. It always returns
False
.
-
NoneMatches.
match
(envelope)[source] Always return
False
-
class
rabbitleap.routing.
MessageTypeMatches
(message_type_pattern)[source] Bases:
rabbitleap.routing.Matcher
Match messages based on message type macher
This matcher does match based on the message type.
The message type is provided as a regular expression string or a compiled
re.Pattern
The matcher returns
True
when find a match in the message type, orFalse
otherwise.
-
MessageTypeMatches.
match
(envelope)[source] Return
True
orFalse
indicating the target can handle the message.This method accepts an
Envelope
object as an argument and returns boolean, indicating whether the target can handle the envelope or not.Subclasses MUST implement this method
Parameters: envelope (Envelope) – Message envelope Returns: can handle or not Return type: bool