araldo / README.rst


araldo provides a simple, extensible communication relay (based on gevent and WebSockets) between multiple endpoints

Use cases

  • Push notification from server to Browser
  • Bidirectional communication between browsers
  • Bidirectional communication between browsers and a backend
  • Interoperability between different message-oriented middleware products


araldo is a central server component that provides an arbitrary amount of endpoints to which clients may connect, or which connect to other servers.


araldo uses the concept of routes for setting up communication. Rather than relying on clients subscribing/publishing to/from particular channels, the channel setup and routing between endpoints is done inside araldo.


araldo uses gevent, a corouting-based networking library. gevent uses green threads (greenlets) and asynchronous IO. Therefore, the araldo server is single-threaded with respect to native threads, but highly concurrent with respect to green threads.


Available Plugins

araldo consists of a core that is run as a server process, and several plugins. Available plugins are loaded automatically. Out of the box, araldo provides a WebSocket server that allows multiple clients to communicate with each other via routes.

Currently the following plugins are available:

Name Description Link
araldo-redis Communication via Redis PubSub
araldo-websocket Communication with an HTML5 WebSocket server


araldo uses the Python entry-point mechanism for plugin discovery.


To install araldo along with some plugins, type:

pip install araldo


Configuration File

The configuration file in YAML format mainly contains

  • global settings
  • plugin instances, with plugin-specific settings
  • routes (connections between endpoints)

The standard configuration file is araldo.yaml in the current directory.

Global parameters

Parameter Type Description
server-port int TCP port of web (WebSocket) server
log-level str One of debug, info, warning, error, fatal. Verbosity of logging

Plugin-Specific parameters

Plugins are configured under the toplevel configuration key plugins.

All plugins

Parameter Type Description
name str Unique name for the plugin instance
id str Identifier for the plugin type


Routes map messages from an inbound source to multiple outbound endpoints. Routing is configured under the toplevel configuration key routes. Each route consists of a key that references a name of an endpoint. The value is a list of names referencing other endpoints.

Sample configuration:

    server-port: 54321
    log-level: debug

    - name: marshal-json
      id: marshal-json
    - name: mock_1
      id: endpoint-mock
      channel: channel_1
    - name: redis_2
      id: endpoint-mock
      channel: channel_2
    - name: redis_3
      id: endpoint-mock
      channel: channel_3

    - redis_2
    - redis_3