Pub/sub subscribers

• Subscribers are pub/sub endpoints that receive messages that were previously sent (published) by publishers.
• To receive messages, subscribers first create a subscription. Each subscription has a unique subscription key which serves as its identifier.
• Subscribers can be of several types: Python or REST.
• REST subscribers use Basic Auth to identify themselves with the message broker.
• Pattern-based permissions are assigned to each subscriber. If, during the publication of a message, a particular subscriber does not have permissions to receive messages from the topic the message is sent to, that subscriber will not receive the message. Python subscribers (Zato services) are always allowed to receive their own messages, i.e. each service can always receive messages from a topic that points to this service.
• It is possible to create more than one subscriber for a given application, e.g. to represent different permissions assigned to different parts of the same application. Each subscriber will use a different subscription key.

Subscriptions

Provided that there are correct permission patterns and that relevant topics already exist, each REST or Python (service) endpoint may subscribe to one or more topics.

Note that services can subscribe to two kinds of topics:

• Explicitly created ones, such as customer.new in the screenshot above
• Topics created for each service implicitly on demand - whenever a message is published to a service by its name, a topic for that service will be created and the service will subscribe to it automatically, unless such a topic already exists. All such topics have a prefix of "zato.s.to." followed by the service's name. For instance, if your service is called my.api.customer.new, its implicit topic's name will be zato.s.to.my.api.customer.new.

Messages can be sent on a notify or pull basis. The former means that Zato itself will be invoking the endpoint with new messages whereas pull means that Zato will queue messages up and the recipient itself will periodically read the contents of its queue.

Each endpoint may subscribe to topics multiple types and each time it is given a new subscription key - this is a secret that must be known only to the participant to whom it was issued.

Handling push messages in Python services

When Zato pushes a message to a subscribing service, the service's handle method is invoked with the message data available through self.request.input.

Simple service (no data model)

A service without a declared input model receives the raw published data as a dictionary:

from zato.server.service import Service

class MySubscriber(Service):

    def handle(self):

        # .. the published data is available as a dictionary ..
        data = self.request.input['data']

        customer_name = data['customer_name']
        customer_id = data['customer_id']

        self.logger.info('Received customer: %s (%s)', customer_name, customer_id)

Service with a data model

If the subscribing service declares an IO.input data model, the published data is automatically parsed against the model. The self.request.input attribute becomes an instance of the model class with typed fields:

from dataclasses import dataclass
from zato.server.service import Model, Service

@dataclass(init=False)
class CustomerEvent(Model):
    customer_name: str = ''
    customer_id: int = 0

class MySubscriber(Service):

    class IO:
        input = CustomerEvent

    def handle(self):

        # .. self.request.input is a CustomerEvent instance ..
        customer_name = self.request.input.customer_name
        customer_id = self.request.input.customer_id

        self.logger.info('Received customer: %s (%s)', customer_name, customer_id)

Quick links