Semantics

Before you are able to connect an emitter to the Frontend or a worker to the Backend, you’ll need to understand the xbus broker semantics.

The most important terms are:

• event
• event type
• event node
• emitter
• emitter profile
• item
• worker
• consumer
• service
• role
• envelope
• immediate reply

Event

In the Xbus semantics the core of what we transfer between actors of the IT infrastructure are considered as events. Events are arbitrary collections of data structures. An event will be received by the Frontend and propagated to all the consumers that have registered to receive it.

Event Type

Each and every event in xbus needs only one thing: an event type. This is only a name, but this means a lot: Xbus does not try by itself to assert anything about the datastructure it transports and forwards. But at the same time it is necessary for the consumers (receivers) to know what kind of data they will receive and how to treat it. The event type is that contract. IE: if I say to the bus that I emit new_clients the consumers may rely on the bus to make sure that the same kind of datastructure will be served to them each time.

Envelope

Any event sent into the bus must be enclosed into an envelope. This is important because the evelope is a transactional unit that permits to rollback operations at the envelope level if your consumers are transaction aware.

This really depends on your application layout but you can easily imagine a simple network that handles invoices and a final consumer that will write accounting lines into accounting books. If for any reason the envelope failed in the middle you would want that NO single line was written in your books. Putting all the invoice lines in a single envelope you ensure that everything in the same envelope will be part of the same transaction.

Event Node

Internally we use the term event node to describe a node in our graph that will handle an event. This is specifically used in the Backend part of the broker and refers to eitheir a worker or a consumer.

Emitter

An emitter is an independant program in your IT infrastructure that needs to send information about a change, a new item or whatever. In the internal Xbus database each emitter is assigned an emitter row that contains its login / password pair. An emitter is just that, it does not directly declare what it wants to emit.

This is declared by the Xbus administrator using emitter profiles

The emitter however declares what profile it is using.

Emitter Profile

A profile is used to link one or more emitters to a list of allowed event types

An emitter can only emit the type of events that are linked to its profile. Xbus will refuse any other event type.

Item

An event contain one or more items.

When sending, an event_id and data (JSON or msgpack) are needed.

Worker

A worker is an independant program that connects to the xbus Backend and declares itself ready to handle events as they are emitted in the network.

It is important to understand that a worker is not intended to be used as a final node of a graph but instead as an intermediate node that will process data, transform or enrich it and then return it back to the broker.

The contract between a worker and the xbus backend is that the bus will send all items of an event down to a worker and that the worker must send back a list of items.

Consumer

A consumer as a worker node is still an independant program that connects to the xbus backend, but it is considered as a final node that will not return data for each item received.

On the contrary it will wait for the end of an envelope to give some kind of answer to the Backend.

Recipient

Nodes that form the actual execution path for an ongoing event.

Service

An abstract representation of one or more event nodes be it a worker or consumer. The service is the link between an event node and one or more concrete workers.

Attached to the service we will find a role, which is the concrete distinct instance of a worker or consumer.

Role

The individual worker or consumer. There is a separation between service and role because you can connect many different roles to your bus that will provide the same service.

In effect, once you have described your work graph using a tree of event nodes, each one attached to a distinct service, you’ll be able to spawn as many real workers (programs that provide a service) that will attach to one service.

The bus will automatically distribute the work between all the roles that provide the same service.

Immediate reply

Emitters of events marked as wanting an “immediate reply” will wait for a reply from the consumer once they have called the “end_event” RPC call.

The reply will be sent via the return value of the “end_event” call.

The “immediate reply” flag is an attribute of event types.

Restrictions:

• Immediate replies are disallowed when more than one consumer is available to the emitter wishing to send events with that flag.
• The consumer MUST announce support for the “Immediate reply” feature (see the documentation about the Xbus recipient API for details).