Broker
******
.. contents::
The broker is the central elbus instance, which routes messages between
applications. Being the broker is the only way to exchange messages between
local threads, so usually the broker is embedded into the central heaviest
application, while all plug-ins, services and additional components talk with
the broker using inter-process communications (UNIX sockets or TCP).
elbus broker is currently implemented in Rust only.
Broker API
==========
When **rpc** feature is enabled, the following default RPC methods are
available at **.broker** after *broker.init_default_core_rpc* method is called:
* **test()** - broker test (ok: true)
* **info()** - broker info (author and version)
* **stats()** - broker statistics
* **client.list()** - list all connected clients
* **benchmark.test(payload)** - test method, returns the payload as-is
The payload exchange format (call params / replies) is MessagePack.
Stand-alone broker server
=========================
To build a stand-alone broker server, use the command:
.. code:: shell
cargo build --features server,rpc
The *rpc* feature is optional.
Embedded broker
===============
.. note::
If compiling for "musl" target, it is strongly recommended to replace the
default MUSL allocator with 3rd party, e.g. with `jemallocator
<https://crates.io/crates/jemallocator>`_ to keep the broker fast.
Example of a broker with inter-thread communications and external clients:
.. literalinclude:: ../examples/inter_thread.rs
:language: rust
Security model
--------------
An optional simple security model can be implemented in an embedded broker.
Note that any security model may slowdown communications, so it is usually a
good idea to move semi-trusted clients to a dedicated server socket, as a
broker can have multiple ones.
When a model is applied, only clients with the names listed in AAA map can
connect. The clients can be restricted to:
* connect only from specified hosts/networks
* exchange p2p messages with a specified list of peers only
* denied to publish
* denied to subscribe
* denied to broadcast
Important things to know:
* *elbus::broker::AaaMap* is a mutex-protected HashMap, which can be modified
on-the-flow
* when a client is connected, its AAA settings are CLONED and not affected with
any modifications, so it is usually a good idea to call
*Broker::force_disconnect* method when AAA settings are altered or removed
Example:
.. literalinclude:: ../examples/broker_aaa.rs
:language: rust