araldo / README.rst

araldo

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

Architecture

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

Routes

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.

Implementation

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.

Plugins

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 https://bitbucket.org/ganymed/araldo-redis
araldo-websocket Communication with an HTML5 WebSocket server https://bitbucket.org/ganymed/araldo-websocket

Extensibility

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

Installation

To install araldo along with some plugins, type:

pip install araldo

Configuration

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

Routing

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:

global:
    server-port: 54321
    log-level: debug

plugins:
  araldo.marshalling:
    - name: marshal-json
      id: marshal-json
  araldo.endpoints.endpoint:
    - 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

routes:
  redis_1:
    - redis_2
    - redis_3
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.